Ghost Shell (攻殻機動隊)

AI-Powered DeFi Security Guard Platform on HashKey Chain

📋 Project Overview

Ghost Shell is an AI-powered security platform that protects DeFi users from malicious contracts, risky wallets, and dangerous transactions on HashKey Chain by Ghost in the Shell (攻殻機動隊), it acts as your personal Section 9 security team.

What It Does

Scans smart contracts - Detects reentrancy, access control flaws, delegatecall risks
Analyzes wallets - Identifies suspicious transaction patterns and risky interactions
Blocks dangerous transactions - AI-powered pre-transaction protection
Provides real-time insights - Live threat monitoring and asset health tracking
Creates audit trail - On-chain security manifests for transparency

Key Innovation

Unlike traditional security tools that only warn after the fact, Ghost Shell prevents malicious transactions before they execute. Our AI analyzes every transaction in real-time and blocks it if dangerous - protecting your assets proactively.

Traditional Security:  User → Transaction → Exploit → Loss
With Ghost Shell:      User → AI Check → Block → Assets Safe

🌐 Why This Matters for HashKey Chain

The DeFi Security Problem

DeFi users lose billions annually to:

Malicious smart contracts (rug pulls, honeypots)
Compromised wallets and phishing attacks
Unaudited protocols with hidden vulnerabilities
Users have no protection layer between them and danger

What We Bring to HashKey Chain

Benefit	Impact
Protects Users	AI-powered transaction blocking prevents losses before they happen
Builds Trust	Users feel safe interacting with DeFi on HashKey Chain
Increases Adoption	Security = confidence = more users joining the ecosystem
Native Integration	Built specifically for HashKey Chain, optimized for HSK

Market Need

DeFi users need protection from malicious contracts
Wallet users need pre-transaction risk assessment
Developers need security audit infrastructure
All of these need real-time AI analysis that can't be bypassed

🚀 Deployment Information

Live Contracts on HashKey Testnet

Contract	Address	Explorer
GhostShellRegistry	`0x2CD70324C4043D90f3C45D6ac7E84aB828708205`	✅ View Code
SecureVault	`0x6483d00d9E5Ff9cCE4e2b549d78A0B8885E5d1c3`	✅ View Code

Network Details

Network:     HashKey Chain Testnet
Chain ID:    133
RPC URL:     https://testnet.hsk.xyz
Explorer:    https://testnet-explorer.hsk.xyz
Currency:    HSK (test HSK)
Faucet:      https://testnet-explorer.hsk.xyz/faucet

Deploy Your Own

# 1. Clone the repository
git clone https://github.com/Venkat5599/Ghost-shell.git
cd Ghost-shell

# 2. Install dependencies
npm install
cd contracts && npm install
cd ../backend && npm install
cd ../frontend && npm install

# 3. Configure environment
cp contracts/.env.example contracts/.env
# Edit contracts/.env with your private key

# 4. Deploy to HashKey Testnet
cd contracts
npx hardhat run scripts/deploy.ts --network hashkeyTestnet

# 5. Deploy backend to Vercel
cd ../backend
vercel

# 6. Deploy frontend to Vercel
cd ../frontend
vercel

📖 How to Use the Platform

Option 1: Web Interface (Easiest)

Visit the platform (after deployment)
Connect MetaMask to HashKey Chain Testnet
Scan a contract - Paste address, get instant security report
Analyze a wallet - Check any wallet's risk score
Send transactions - AI automatically protects you

Option 2: Direct Contract Interaction

Register Security Manifest

// Solidity - Call from your contract
interface IGhostShellRegistry {
    function registerManifest(
        address contractAddress,
        string memory manifestHash,
        uint8 riskScore,
        string memory summary
    ) external;
}

IGhostShellRegistry registry = IGhostShellRegistry(
    0x2CD70324C4043D90f3C45D6ac7E84aB828708205
);

registry.registerManifest(
    0xYourContract,
    "ipfs://QmHash...",
    25, // Low risk
    "Audited by Ghost Shell"
);

Query Security Manifest

(
    string memory manifestHash,
    uint8 riskScore,
    string memory summary,
    address auditor,
    uint256 timestamp,
    bool exists
) = registry.getManifest(contractAddress);

require(exists, "No security audit found");
require(riskScore < 50, "Risk too high");

Option 3: API Integration

import axios from 'axios';

// Scan contract for vulnerabilities
const scanResult = await axios.post('https://your-backend.vercel.app/api/scan-contract', {
  contractAddress: '0x2CD70324C4043D90f3C45D6ac7E84aB828708205'
});

console.log(scanResult.data);
// {
//   riskScore: 15,
//   vulnerabilities: [...],
//   aiExplanation: "This contract appears safe...",
//   recommendation: "SAFE"
// }

// Analyze wallet risk
const walletResult = await axios.post('https://your-backend.vercel.app/api/analyze-wallet', {
  walletAddress: '0xYourWallet...'
});

// Check transaction before sending
const riskCheck = await axios.post('https://your-backend.vercel.app/api/risk-check', {
  from: '0xYourWallet...',
  to: '0xRecipient...',
  value: '1000000000000000000' // 1 HSK in wei
});

if (riskCheck.data.riskLevel === 'CRITICAL') {
  console.log('⛔ Transaction blocked:', riskCheck.data.reason);
} else {
  // Proceed with transaction
}

Contract Functions Reference

Function	Description	Access
`registerManifest(address, string, uint8, string)`	Register security audit	Authorized auditors
`getManifest(address)`	Get security manifest	Anyone (view)
`isAuthorizedAuditor(address)`	Check auditor status	Anyone (view)
`authorizeAuditor(address)`	Add authorized auditor	Owner only
`revokeAuditor(address)`	Remove auditor	Owner only

🛡️ Security Features

Contract Scanner

Detects 15+ vulnerability types:

Vulnerability	Detection Method	Risk Level
Reentrancy	Bytecode pattern analysis	CRITICAL
Access Control	Function modifier check	HIGH
Delegatecall	Opcode detection	CRITICAL
Selfdestruct	Opcode detection	HIGH
Unprotected Functions	Modifier analysis	MEDIUM
Integer Overflow	Solidity version check	LOW (0.8+)

Wallet Analyzer

Analyzes wallet behavior:

Transaction frequency patterns
Interaction with known malicious contracts
Balance verification
Historical risk assessment
AI-generated risk summary

Transaction Protection

Real-time blocking system:

User initiates transaction
         ↓
Ghost Shell intercepts
         ↓
AI analyzes in <1 second
         ↓
┌────────┴────────┐
│                 │
SAFE            RISKY
│                 │
Execute         Block/Warn

Protection levels:

SAFE (0-30): Transaction proceeds automatically
WARNING (31-70): User confirmation required
CRITICAL (71-100): Transaction blocked, manual override available

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              USER/DAPP                                   │
│                    (Web Interface or Direct Integration)                │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         FRONTEND (Next.js 14)                            │
│                                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │  Contract   │  │   Wallet    │  │    Send     │  │    Risk     │   │
│  │   Scanner   │  │  Analyzer   │  │     TRX     │  │    Modal    │   │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘   │
│         │                │                │                │           │
│         └────────────────┴────────────────┴────────────────┘           │
│                                  │                                      │
└──────────────────────────────────┼──────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    BACKEND (Vercel Serverless)                           │
│                                                                          │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐     │
│  │ Contract Scanner │  │ Wallet Analyzer  │  │  Risk Aggregator │     │
│  │  - Bytecode      │  │  - Transactions  │  │  - Combine data  │     │
│  │  - Opcodes       │  │  - Patterns      │  │  - Calculate     │     │
│  │  - Patterns      │  │  - Balance       │  │  - Generate      │     │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘     │
│           │                     │                     │                │
│           └─────────────────────┴─────────────────────┘                │
│                                  │                                      │
│                                  ▼                                      │
│                     ┌─────────────────────────┐                        │
│                     │   AI Explanation        │                        │
│                     │   (Groq - Llama 3.3)    │                        │
│                     │   - Risk assessment     │                        │
│                     │   - Attack scenarios    │                        │
│                     │   - Recommendations     │                        │
│                     └─────────────────────────┘                        │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    SMART CONTRACTS (Solidity)                            │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────┐      │
│  │              GhostShellRegistry                               │      │
│  │              0x2CD70324C4043D90f3C45D6ac7E84aB828708205       │      │
│  │                                                               │      │
│  │  - registerManifest()  → Store security audits               │      │
│  │  - getManifest()       → Retrieve audit data                 │      │
│  │  - authorizeAuditor()  → Manage auditors                     │      │
│  │  - Events: ManifestRegistered, AuditorAuthorized             │      │
│  └──────────────────────────────────────────────────────────────┘      │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────┐      │
│  │              SecureVault (Example)                            │      │
│  │              0x6483d00d9E5Ff9cCE4e2b549d78A0B8885E5d1c3       │      │
│  │                                                               │      │
│  │  - Uses GhostShellGuard modifier                             │      │
│  │  - Demonstrates integration pattern                          │      │
│  │  - Production-ready example                                  │      │
│  └──────────────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      HASHKEY CHAIN TESTNET                               │
│                                                                          │
│  Chain ID: 133                                                           │
│  RPC: https://testnet.hsk.xyz                                            │
│  Explorer: https://testnet-explorer.hsk.xyz                              │
└─────────────────────────────────────────────────────────────────────────┘

📁 Project Structure

Ghost-shell/
├── frontend/              # Next.js 14 web application
│   ├── app/              # App router pages
│   │   ├── page.tsx      # Dashboard
│   │   ├── scanner/      # Contract scanner
│   │   ├── vault/        # Secure vault
│   │   ├── send/         # Send transactions
│   │   ├── audits/       # Audit history
│   │   ├── support/      # Support page
│   │   └── docs/         # Documentation
│   ├── components/       # React components
│   │   ├── ContractScanner.tsx
│   │   ├── WalletAnalyzer.tsx
│   │   ├── RiskCheckModal.tsx
│   │   ├── WalletConnect.tsx
│   │   └── PlumBackground.tsx
│   ├── lib/              # Utilities
│   │   ├── api.ts        # API client
│   │   ├── web3.ts       # Web3 utilities
│   │   └── transactionGuard.ts
│   └── hooks/            # Custom hooks
│
├── backend/              # Vercel serverless functions
│   ├── api/              # API endpoints
│   │   ├── health.ts
│   │   ├── scan-contract.ts
│   │   ├── analyze-wallet.ts
│   │   └── risk-check.ts
│   └── src/
│       ├── services/     # Business logic
│       │   ├── ContractScanner.ts
│       │   ├── WalletAnalyzer.ts
│       │   ├── AIExplanationService.ts
│       │   ├── RiskAggregator.ts
│       │   └── CacheService.ts
│       └── types/        # TypeScript types
│
├── contracts/            # Smart contracts
│   ├── contracts/
│   │   ├── GhostShellRegistry.sol
│   │   ├── GhostShellGuard.sol
│   │   └── SecureVault.sol
│   ├── scripts/          # Deployment scripts
│   │   ├── deploy.ts
│   │   ├── authorize-backend.ts
│   │   └── test-manifest.ts
│   └── test/             # Contract tests
│
└── docs/                 # Documentation
    ├── README.md
    ├── QUICK_REFERENCE.md
    ├── INTEGRATION_GUIDE.md
    ├── DEPLOYMENT_COMPLETE.md
    └── TRANSACTION_PROTECTION.md

📚 Documentation

Quick Reference - Commands and addresses
Integration Guide - How to integrate
Transaction Protection - Protection system
Real Data Implementation - No mock data
Testnet Testing Guide - Testing guide
Deployment Complete - Deployment status

🧪 Testing

Run Contract Tests

cd contracts
npx hardhat test

Expected output:

  GhostShellRegistry
    ✓ Should deploy with correct owner
    ✓ Should register manifest
    ✓ Should authorize auditor
    ✓ Should get manifest
    ... (13 tests total)

  13 passing (2s)

Test Backend Locally

cd backend
npm run dev:server

# In another terminal
curl http://localhost:3001/api/health

Test Frontend Locally

cd frontend
npm run dev

# Open http://localhost:3002
# Connect wallet and test features

Integration Testing

# Test contract scanning
curl -X POST http://localhost:3001/api/scan-contract \
  -H "Content-Type: application/json" \
  -d '{"contractAddress":"0x2CD70324C4043D90f3C45D6ac7E84aB828708205"}'

# Test wallet analysis
curl -X POST http://localhost:3001/api/analyze-wallet \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0xYourWallet..."}'

🔗 Links

Resource	URL
Registry Contract	View on Explorer
Vault Contract	View on Explorer
HashKey Testnet	Network Info
HashKey Explorer	Block Explorer
HashKey Faucet	Get Test HSK
Groq AI	AI Platform

🛠️ Tech Stack

Smart Contracts: Solidity 0.8.20, Hardhat, OpenZeppelin
Frontend: Next.js 14, TypeScript, Tailwind CSS, ethers.js v6
Backend: Vercel Serverless, TypeScript, ethers.js v6
AI: Groq (llama-3.3-70b-versatile)
Blockchain: HashKey Chain Testnet (EVM-compatible)
Design: Glassmorphism, Anime-inspired (Ghost in the Shell)

📈 Roadmap

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Ghost in the Shell (攻殻機動隊) - Section 9 Security
Built for HashKey Chain ecosystem
Powered by Groq AI (llama-3.3-70b-versatile)
UI design inspired by glassmorphism and cyberpunk aesthetics
Special thanks to the HashKey Chain team for testnet support

Built for HashKey Chain Ecosystem 🏆

Protecting DeFi Users with AI-Powered Security

Making Web3 safer, one transaction at a time

⭐ Star this repo if you find it useful!

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
backend		backend
contracts		contracts
docs		docs
frontend		frontend
.gitignore		.gitignore
README.md		README.md
next-env.d.ts		next-env.d.ts
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

Ghost Shell (攻殻機動隊)

📋 Project Overview

What It Does

Key Innovation

🌐 Why This Matters for HashKey Chain

The DeFi Security Problem

What We Bring to HashKey Chain

Market Need

🚀 Deployment Information

Live Contracts on HashKey Testnet

Network Details

Deploy Your Own

📖 How to Use the Platform

Option 1: Web Interface (Easiest)

Option 2: Direct Contract Interaction

Register Security Manifest

Query Security Manifest

Option 3: API Integration

Contract Functions Reference

🛡️ Security Features

Contract Scanner

Wallet Analyzer

Transaction Protection

🏗️ Architecture

📁 Project Structure

📚 Documentation

🧪 Testing

Run Contract Tests

Test Backend Locally

Test Frontend Locally

Integration Testing

🔗 Links

🛠️ Tech Stack

📈 Roadmap

🤝 Contributing

📝 License

🙏 Acknowledgments

Built for HashKey Chain Ecosystem 🏆

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages