ADD1xD/ClearShield

# ⚔️ ClearShield ## 📖 Introduction & Vision **ClearShield** is a premium, real-time threat intelligence network for EVM-compatible blockchains. Unlike traditional centralized security registries that can be censored, targeted, or manipulated, ClearShield stores all malicious address registries on **Arkiv**—a highly optimized, decentralized data layer. Once a report is submitted, no malicious actor can delete their digital footprint, and no centralized platform can censor a warning. Every report and audit confirmation is bound cryptographically to its respective reporter using Braga blockchain transaction signatures, utilizing immutable on-chain attribution. ## 🛡️ Core Features 1. **AI-Driven Automated Verification & Scoring** * Before being recorded, community reports are validated in real-time by a multi-model **Gemini AI service**. * The AI filters out test entries/spam, derives a **severity score (1–10)**, and writes a concise **2-sentence plain-English summary** of the exploit vectors to save user assets. 2. **Digital Samurai Guardian Aesthetic System** * A premium, high-energy layout styling featuring a dark, tactical color palette (crimson intensity, matte stealth blacks, and glowing cybersecurity teals). * Visual enhancements include: a fine film-grain overlay, moving laser grids, horizontal and vertical katana-slash accents, glowing corner brackets, and giant, ambient background watermarks representing the virtues of **Bushido** (`義` Integrity, `勇` Courage, `礼` Respect, `忠` Loyalty). 3. **Decentralized Community Audit & Confirmation Feed** * Live streaming of global threat logs. * Connect MetaMask to Braga testnet to "+ Confirm" reports you have also personally witnessed. The audit count increases dynamically in real-time to alert others. 4. **Production-Ready Developer & Agent APIs** * A high-performance, rate-limited `/api/v1/check` endpoint designed for hot transaction paths in dApps, wallets, and autonomous AI agents. ## 🏛️ Decentralized Data Architecture ClearShield stores its intelligence using two primary entity schemas published to the Braga testnet under the global namespace `CLEARSHIELD_V1`. ### 1. Entity Types | Entity Type | Description | TTL (Decay Window) | | :--- | :--- | :--- | | `threat_report` | Original incident record detailing the malicious address, description, chain, and estimated USD loss. | **90 Days** (Unconfirmed reports decay automatically) | | `threat_confirmation` | An audit signature from another wallet validating the existence of the threat. | **90 Days** (Co-expires with the parent report) | ### 🔑 Cryptographic Attribution & Security Metadata Every block record on the Arkiv data layer is natively sealed with two key metadata properties that control authorization: * **`creator` (`$creator` - Immutable)**: The wallet address that originally signed the transaction. This provides **tamper-proof attribution** for threat reporting and confirmations. In the frontend, this guarantees that confirmations cannot be sybil-spammed by a single wallet. * **`owner` (`$owner` - Mutable)**: The administrative controller address of the entity, allowing the report author to update or delete the record if the threat profile shifts. ClearShield retrieves these properties directly from the root-level properties of the returned entity objects using the `@arkiv-network/sdk` and maps them cleanly into the UI: const creator = entity.creator; // Fully utilized for security attribution! ## 🛠️ Tech Stack & Dependencies * **Frontend & Backend APIs:** Next.js 16.2 (App Router) + TypeScript + React 19 * **Styling & Theme Engine:** Vanilla CSS + custom design tokens * **Decentralized Data Layer:** `@arkiv-network/sdk` (indexing Braga testnet events via `subscribeEntityEvents`) * **Core Ledger Network:** Arkiv Braga Testnet * **Generative AI Core:** `@google/generative-ai` (Gemini Flash & Fallbacks for validation and synthesis) * **Web3 Integration:** Wagmi + Viem + MetaMask custom providers ## 🚀 Setup & Installation ### Prerequisites * **Node.js:** version `18.0.0` or higher * **MetaMask** installed in your web browser * **Braga GLM Test Tokens** (Available at the [Arkiv Braga Faucet](https://braga.hoodi.arkiv.network/faucet/)) ### 1. Clone & Install git clone https://github.com/your-username/clearshield.git cd clearshield npm install ### 2. Environment Configuration Copy the template variables file: cp .env.local.example .env.local Fill in the following credentials inside `.env.local`: # Gemini API credentials (from https://aistudio.google.com/) GEMINI_API_KEY=AIzaSy... # Braga Node RPC and Websocket Configurations NEXT_PUBLIC_ARKIV_RPC=https://braga.hoodi.arkiv.network/rpc NEXT_PUBLIC_ARKIV_WS=wss://braga.hoodi.arkiv.network/rpc/ws NEXT_PUBLIC_ARKIV_CHAIN_ID=60138453102 # Server-side wallets fallback (Optional) ARKIV_PRIVATE_KEY=your_private_key_here ### 3. Run Locally Start the development server: npm run dev Open **[http://localhost:3000](http://localhost:3000)** in your browser. ### 4. Braga Testnet Wallet Setup When clicking **Connect Wallet** inside the web app, MetaMask will automatically prompt you to add and switch to the Arkiv Braga Testnet. If you need to add it manually: * **Network Name:** `Arkiv Braga Testnet` * **RPC URL:** `https://braga.hoodi.arkiv.network/rpc` * **Chain ID:** `60138453102` (Hex: `0xe0087f86e`) * **Currency Symbol:** `GLM` * **Block Explorer:** [https://explorer.braga.hoodi.arkiv.network](https://explorer.braga.hoodi.arkiv.network) ## ⚡ Integration API (For Wallets & Agents) Integrate decentralized threat checks directly into hot transaction paths: ### 1. GET Request curl -H "x-api-key: YOUR_KEY" "https://clear-shield.vercel.app/api/v1/check?address=0x379a2970755003256c19a4de88b9c05b21ab401f&includeReports=true" ### 2. Response JSON Schema { "address": "0x379a2970755003256c19a4de88b9c05b21ab401f", "isFlagged": true, "riskLevel": "high", "confidence": "high", "reportCount": 2, "confirmationCount": 9, "maxSeverity": 7, "dominantThreatType": "approval_drain", "totalAmountLostUSD": 0, "verdict": "This address has been flagged for active approval drain interactions. Nine distinct wallets have cryptographically co-signed this alert. Avoid interacting or signing any deposit methods with this contract.", "reports": [ { "entityKey": "0x67a165a859f710683f56549bd9d62b8e60371216b745a8a4951a27e477df7b91", "threatType": "approval_drain", "severityScore": 7, "confirmationCount": 4, "amountLostUSD": 0, "reportedAt": 1779548385904, "aiSummary": "Contract initiates unlimited approval requests for ERC-20 assets under the guise of an aggregator utility." } ] } Detailed integration templates for JavaScript, Python, Ethers.js and Autonomous Agent system prompts are fully documented in [docs/INTEGRATION.md](docs/INTEGRATION.md). ## ⚖️ License This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

标签：自动化攻击