ADD1xD/ClearShield
GitHub: ADD1xD/ClearShield
ClearShield 是一个构建在 Arkiv 去中心化数据层上的 EVM 链上威胁情报网络，通过社区举报、AI 验证和链上签名确认来追踪和预警恶意地址。
Stars: 2 | Forks: 0
# ⚔️ ClearShield
### **去中心化的社区驱动威胁情报 — 在 Arkiv 上防篡改，由 Gemini AI 综合**
## 📖 介绍与愿景
**ClearShield** 是一个面向兼容 EVM 区块链的高级、实时威胁情报网络。
与传统的中心化安全注册表不同（它们可能会被审查、针对或操纵），ClearShield 将所有恶意地址注册表存储在 **Arkiv** 上——这是一个高度优化的去中心化数据层。一旦提交了报告，任何恶意行为者都无法删除他们的数字足迹，也没有任何中心化平台可以审查警告。
每份报告和审计确认都通过 Braga 区块链交易签名与其各自的报告者进行加密绑定，利用不可变的链上归因。
## 🛡️ 核心功能
1. **AI 驱动的自动化验证与评分**
* 社区报告在被记录之前，会由多模型 **Gemini AI 服务**进行实时验证。
* AI 会过滤掉测试条目/垃圾信息，推导出**严重性评分 (1–10)**，并编写一段简明的**两句纯英文总结**，说明漏洞利用向量，以拯救用户资产。
2. **数字武士守护者美学系统**
* 高端、高能量的布局风格，采用深色、战术调色板（强烈的深红色、哑光隐形黑和发光的网络安全青色）。
* 视觉增强包括：细腻的胶片颗粒叠加层、移动的激光网格、水平和垂直的武士刀斩击点缀、发光的边角括号，以及代表**武士道** (`义` 正直, `勇` 勇气, `礼` 尊重, `忠` 忠诚) 美德的巨大环境背景水印。
3. **去中心化社区审计与确认 Feed**
* 全球威胁日志的实时流。
* 将 MetaMask 连接到 Braga 测试网，对您也亲身见证过的报告点击“+ 确认”。审计计数会实时动态增加，以警告他人。
4. **生产级开发者与 Agent API**
* 高性能、受速率限制的 `/api/v1/check` endpoint，专为 dApp、钱包和自主 AI agent 的关键交易路径设计。
## 🏛️ 去中心化数据架构
ClearShield 使用发布在全局命名空间 `CLEARSHIELD_V1` 下、发布到 Braga 测试网的两种主要实体 schema 来存储其情报。
### 1. 实体类型
| 实体类型 | 描述 | TTL (衰减窗口) |
| :--- | :--- | :--- |
| `threat_report` | 详细记录恶意地址、描述、区块链和预估美元损失的原始事件记录。 | **90 天**（未确认的报告会自动衰减） |
| `threat_confirmation` | 来自另一个钱包的审计签名，用于验证威胁的存在。 | **90 天**（与父报告同时过期） |
### 🔑 加密归因与安全元数据
Arkiv 数据层上的每个区块记录本身都封装了两个控制授权的关键元数据属性：
* **`creator` (`$creator` - 不可变)**：最初签署交易的钱包地址。这为威胁报告和确认提供了**防篡改归因**。在前端，这确保了确认不会被单个钱包进行女巫攻击。
* **`owner` (`$owner` - 可变)**：实体的管理控制地址，如果威胁状况发生变化，允许报告作者更新或删除记录。
ClearShield 使用 `@arkiv-network/sdk` 直接从返回实体对象的根级属性中检索这些属性，并将它们清晰地映射到 UI 中：
```
const creator = entity.creator; // Fully utilized for security attribution!
```
## 🛠️ 技术栈与依赖
* **前端与后端 API:** Next.js 16.2 (App Router) + TypeScript + React 19
* **样式与主题引擎:** Vanilla CSS + 自定义设计 token
* **去中心化数据层:** `@arkiv-network/sdk`（通过 `subscribeEntityEvents` 索引 Braga 测试网事件）
* **核心账本网络:** Arkiv Braga Testnet
* **生成式 AI 核心:** `@google/generative-ai`（Gemini Flash 及其备选方案，用于验证和综合）
* **Web3 集成:** Wagmi + Viem + MetaMask 自定义 provider
## 🚀 设置与安装说明
### 前置条件
* **Node.js:** 版本 `18.0.0` 或更高
* 您的网络浏览器中已安装 **MetaMask**
* **Braga GLM 测试 Token**（可在 [Arkiv Braga 水龙头](https://braga.hoodi.arkiv.network/faucet/)获取）
### 1. 克隆与安装
```
git clone https://github.com/your-username/clearshield.git
cd clearshield
npm install
```
### 2. 环境配置
复制模板变量文件：
```
cp .env.local.example .env.local
```
在 `.env.local` 中填写以下凭证：
```
# Gemini API 凭证（来自 https://aistudio.google.com/）
GEMINI_API_KEY=AIzaSy...
# Braga Node RPC 和 Websocket 配置
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（可选）
ARKIV_PRIVATE_KEY=your_private_key_here
```
### 3. 本地运行
启动开发服务器：
```
npm run dev
```
在浏览器中打开 **[http://localhost:3000](http://localhost:3000)**。
### 4. Braga 测试网钱包设置
当您在 Web 应用程序中点击 **连接钱包** 时，MetaMask 会自动提示您添加并切换到 Arkiv Braga 测试网。如果您需要手动添加：
* **网络名称:** `Arkiv Braga Testnet`
* **RPC URL:** `https://braga.hoodi.arkiv.network/rpc`
* **Chain ID:** `60138453102` (Hex: `0xe0087f86e`)
* **代币符号:** `GLM`
* **区块浏览器:** [https://explorer.braga.hoodi.arkiv.network](https://explorer.braga.hoodi.arkiv.network)
## ⚡ 集成 API（适用于钱包与 Agent）
将去中心化威胁检查直接集成到关键交易路径中：
### 1. GET 请求
```
curl -H "x-api-key: YOUR_KEY" "https://clear-shield.vercel.app/api/v1/check?address=0x379a2970755003256c19a4de88b9c05b21ab401f&includeReports=true"
```
### 2. 响应 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."
}
]
}
```
针对 JavaScript、Python、Ethers.js 和自主 Agent 系统 prompt 的详细集成模板已在 [docs/INTEGRATION.md](docs/INTEGRATION.md) 中完整记录。
## ⚖️ 许可证
本项目基于 MIT 许可证授权 — 详情请参阅 [LICENSE](LICENSE) 文件。
标签：EVM, Gemini, Web3, 人工智能, 区块链安全, 去中心化, 域名收集, 威胁情报, 实时处理, 开发者工具, 用户模式Hook绕过, 自动化攻击