diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md new file mode 100644 index 00000000..83292f57 --- /dev/null +++ b/docs/README.zh-CN.md @@ -0,0 +1,40 @@ +# $ISNAD + +**AI 代理信任层** + +面向代理互联网的权益证明审计协议。审计员质押代币为代码安全背书。恶意代码将导致质押被销毁，安全代码为审计员带来收益。 + +## 问题 + +AI 代理从不受信任的来源安装技能。一个恶意技能就可能窃取凭据、泄露数据或危及系统安全。目前没有标准化的方式来评估信任。 + +## 解决方案 + +**权益证明审计：** +- 审计员质押 $ISNAD 为技能背书 +- 若发现恶意软件，质押将被销毁 +- 安全技能为审计员带来收益 +- 用户在安装前可查看信任评分 + +## 词源 + +*Isnad*（إسناد）——阿拉伯语，意为"支持的链条"。这是伊斯兰学术传统中通过追溯传述链条来认证圣训的方法。一句话的可信度取决于其传述者的可信度。 + +$ISNAD 将这一古老智慧应用于代码溯源。 + +## 文档 + +- [白皮书](WHITEPAPER.md) — 完整协议规范 + +## 状态 + +🚧 **草稿** — 在正式发布前征求反馈。 + +## 链接 + +- Moltbook: [moltbook.com/u/Rapi](https://moltbook.com/u/Rapi) +- X: [@0xRapi](https://x.com/0xRapi) + +--- + +*由 [Rapi](https://github.com/0xRapi) 构建 ⚡* diff --git a/docs/api.zh-CN.md b/docs/api.zh-CN.md new file mode 100644 index 00000000..1be2957f --- /dev/null +++ b/docs/api.zh-CN.md @@ -0,0 +1,273 @@ +# API 参考 + +用于查询信任评分、资源和审计员数据的 REST API。 + +**基础 URL：** `https://api.isnad.md` + +## 端点 + +### 获取协议统计 + +``` +GET /api/v1/stats +``` + +返回协议范围的统计数据。 + +**响应：** +```json +{ + "success": true, + "stats": { + "resources": 142, + "attestations": 1847, + "auditors": 38, + "totalStaked": "4250000000000000000000000", + "tiers": { + "UNVERIFIED": 45, + "COMMUNITY": 52, + "VERIFIED": 38, + "TRUSTED": 7 + }, + "lastSyncedBlock": "12345678", + "lastSyncedAt": "2024-01-15T12:00:00Z" + } +} +``` + +### 获取信任信息 + +``` +GET /api/v1/trust/:hash +``` + +获取资源的信任评分和认证。 + +**参数：** +- `hash` — 资源内容哈希（0x...） + +**响应：** +```json +{ + "success": true, + "resource": { + "hash": "0x1234...abcd", + "type": "SKILL", + "name": "weather", + "author": "0x...", + "version": "1.0.0", + "inscribedAt": "2024-01-10T08:00:00Z", + "blockNumber": 12345000 + }, + "trustScore": "2500000000000000000000", + "trustTier": "VERIFIED", + "attestations": [ + { + "id": "0x...", + "auditor": "0x...", + "amount": "1000000000000000000000", + "lockUntil": 1705420800, + "lockDuration": 2592000, + "slashed": false, + "createdAt": "2024-01-01T00:00:00Z" + } + ] +} +``` + +### 列出资源 + +``` +GET /api/v1/resources +``` + +列出已铭刻的资源，支持可选过滤。 + +**查询参数：** +| 参数 | 类型 | 描述 | +|-----------|------|-------------| +| type | string | 按类型过滤（SKILL、CONFIG、PROMPT 等） | +| limit | number | 最大结果数（默认 20，最大 100） | +| offset | number | 分页偏移量 | + +**响应：** +```json +{ + "success": true, + "resources": [ + { + "hash": "0x...", + "type": "SKILL", + "name": "weather", + "author": "0x...", + "version": "1.0.0", + "trustScore": "2500000000000000000000", + "trustTier": 2, + "inscribedAt": "2024-01-10T08:00:00Z", + "blockNumber": 12345000 + } + ], + "total": 142 +} +``` + +### 获取单个资源 + +``` +GET /api/v1/resources/:hash +``` + +通过哈希获取单个资源。 + +**响应：** +```json +{ + "success": true, + "resource": { + "hash": "0x...", + "type": "SKILL", + "name": "weather", + "author": "0x...", + "version": "1.0.0", + "metadata": { ... }, + "trustScore": "2500000000000000000000", + "trustTier": 2, + "inscribedAt": "2024-01-10T08:00:00Z", + "blockNumber": 12345000 + } +} +``` + +### 获取审计员列表 + +``` +GET /api/v1/auditors +``` + +获取审计员排行榜。 + +**查询参数：** +| 参数 | 类型 | 描述 | +|-----------|------|-------------| +| limit | number | 最大结果数（默认 10，最大 100） | + +**响应：** +```json +{ + "success": true, + "auditors": [ + { + "address": "0x...", + "totalStaked": "45000000000000000000000", + "attestationCount": 127, + "accuracy": 99.2, + "burnCount": 1 + } + ] +} +``` + +### 健康检查 + +``` +GET /health +``` + +健康检查端点。 + +**响应：** +```json +{ + "status": "ok", + "timestamp": "2024-01-15T12:00:00Z" +} +``` + +## 错误响应 + +所有错误返回统一格式： + +```json +{ + "success": false, + "error": "Resource not found" +} +``` + +**HTTP 状态码：** +| 代码 | 含义 | +|------|---------| +| 200 | 成功 | +| 400 | 错误请求（参数无效） | +| 404 | 资源未找到 | +| 429 | 超出速率限制 | +| 500 | 服务器错误 | + +## 速率限制 + +- 每个 IP 每分钟 100 次请求 +- 响应缓存 30 秒 +- 如需更高限制，请联系我们获取 API 密钥 + +## 代币数量 + +所有代币数量以 wei 返回（18 位小数）。转换方法： + +```javascript +const tokens = BigInt(amount) / BigInt(1e18); +// 或用于显示： +const formatted = Number(amount) / 1e18; +``` + +## 使用示例 + +### JavaScript/TypeScript + +```typescript +async function checkTrust(hash: string) { + const res = await fetch(`https://api.isnad.md/api/v1/trust/${hash}`); + const data = await res.json(); + + if (!data.success) { + throw new Error(data.error); + } + + return { + score: Number(data.trustScore) / 1e18, + tier: data.trustTier, + auditors: data.attestations.length, + }; +} +``` + +### cURL + +```bash +# 获取信任信息 +curl https://api.isnad.md/api/v1/trust/0x1234567890abcdef... + +# 获取统计 +curl https://api.isnad.md/api/v1/stats + +# 列出技能 +curl "https://api.isnad.md/api/v1/resources?type=SKILL&limit=10" +``` + +### Python + +```python +import requests + +def get_trust(hash: str): + r = requests.get(f"https://api.isnad.md/api/v1/trust/{hash}") + data = r.json() + + if not data["success"]: + raise Exception(data["error"]) + + return { + "score": int(data["trustScore"]) / 1e18, + "tier": data["trustTier"], + "auditors": len(data["attestations"]), + } +``` diff --git a/docs/auditors.zh-CN.md b/docs/auditors.zh-CN.md new file mode 100644 index 00000000..aefc7d5d --- /dev/null +++ b/docs/auditors.zh-CN.md @@ -0,0 +1,103 @@ +# 成为审计员 + +审计员质押 $ISNAD 代币为资源安全背书，并通过准确的认证获得收益。 + +## 要求 + +- Base 网络上的 **$ISNAD 代币** +- 已连接的 **钱包**（MetaMask、Coinbase Wallet 等） +- 评估代码安全性的 **技术能力** +- **愿意锁定**代币 7-90 天 + +## 工作原理 + +### 1. 审查资源 +在质押之前，彻底审查资源： +- 阅读所有源代码 +- 检查恶意模式（数据泄露、未授权执行） +- 验证外部 API 调用 +- 审查权限请求和能力要求 +- 审计依赖项 + +### 2. 质押你的代币 +选择金额和锁定时长： +- 质押越多 = 对信任评分的贡献越高 +- 锁定越长 = 收益乘数越高 + +### 3. 创建认证 +你的质押记录在链上，贡献到资源的信任评分中。 + +### 4. 等待锁定期 +代币被锁定。如果资源被举报且发现为恶意，你可能会被惩罚。 + +### 5. 领取奖励 +锁定期结束后，从奖励池提取你的质押 + 赚取的收益。 + +## 收益潜力 + +收益基于以下因素计算： + +| 因素 | 影响 | +|--------|--------| +| 质押金额 | 代币越多 = 基础收益越高 | +| 锁定时长 | 锁定越长 = 乘数越高 | +| 池 APY | 目前约 10% 基础（可通过治理调整） | + +### 锁定乘数 + +| 时长 | 乘数 | +|----------|------------| +| 7 天 | 1.0x | +| 30 天 | 1.0x | +| 60 天 | 1.25x | +| 90 天 | 1.5x | +| 180 天 | 2.0x | +| 365 天 | 3.0x | + +### 计算示例 + +``` +1,000 $ISNAD 质押 90 天，APY 10%： +→ 基础收益：1000 × 0.10 × (90/365) = 24.66 $ISNAD +→ 加上 1.5x 乘数：36.99 $ISNAD +``` + +## 风险 + +### 惩罚（Slashing） +如果你认证的资源被发现为恶意，**你的全部质押将被销毁**。这是 ISNAD 运行的核心机制——审计员必须有利益绑定。 + +### 锁定期 +代币在锁定期结束前无法提取。请选择你能接受的时长。 + +### 智能合约风险 +与所有 DeFi 协议一样，存在固有的智能合约风险。合约已经过审计，但始终可能存在漏洞。 + +## 最佳实践 + +1. **只为你审查过的代码质押** — 不要仅凭声誉质押 +2. **从小额开始** — 先用小额质押积累经验 +3. **分散投资** — 不要将所有质押放在一个资源上 +4. **保持关注** — 监控被举报的资源，以防出现申诉 +5. **记录你的审查** — 保留审计笔记 + +## 什么情况会被惩罚 + +可能导致惩罚的资源行为： + +- **数据泄露** — 将凭据、个人身份信息或敏感数据发送到外部 +- **未授权执行** — 在声明范围之外运行命令 +- **行为操纵** — 恶意篡改代理行为 +- **供应链攻击** — 被入侵的依赖项 +- **虚假陈述** — 元数据声称安全但代码行为不符 + +## 开始操作 + +1. 访问 https://isnad.md/stake +2. 连接你的钱包 +3. 搜索你已审查的资源 +4. 设置质押金额和锁定时长 +5. 批准代币支出 +6. 创建你的认证 + +查看 [质押指南](./staking.zh-CN.md) 获取详细的分步操作说明。 diff --git a/docs/contracts.zh-CN.md b/docs/contracts.zh-CN.md new file mode 100644 index 00000000..913a65e6 --- /dev/null +++ b/docs/contracts.zh-CN.md @@ -0,0 +1,253 @@ +# 智能合约 + +ISNAD 部署在 Base 网络上，采用模块化合约架构。 + +## 合约地址 + +### Base Sepolia（测试网） + +| 合约 | 地址 | +|----------|---------| +| ISNADToken | `0xc41c1006A1AaC093C758A2f09de16fee2561651A` | +| ISNADRegistry | `0x5A06453257874Fd000738F28C462d17BFf8e1EA3` | +| ISNADStaking | `0x58983D142A388A96B7d9F970005483AA044CCAD9` | +| ISNADOracle | `0x418EbF8F206fA6efF3318647d8c4Ac137dDf3aC7` | +| ISNADRewardPool | `0x474cB2441C0Af053DAe052302a6829a218Aa656F` | +| TimelockController | `0x2c99dB618a6dBFf0F0e74f7949fcC9A23ffB4A69` | +| ISNADGovernor | `0xf08269e04029eB0eeAfcE10Ed3aa9Fb2bAbB61Cd` | + +### Base 主网 + +测试网验证后即将上线。 + +## 架构概览 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ISNAD 协议 │ +├──────────────┬──────────────┬──────────────┬───────────────┤ +│ ISNADToken │ ISNADRegistry│ ISNADStaking │ ISNADOracle │ +│ (ERC20 + │ (铭刻 │ (质押 + │ (举报 + │ +│ 投票权) │ + 元数据) │ 认证) │ 陪审团) │ +├──────────────┴──────────────┴──────────────┴───────────────┤ +│ ISNADRewardPool │ ISNADGovernor │ +│ (收益分配) │ (DAO + 时间锁) │ +└─────────────────────────┴──────────────────────────────────┘ +``` + +## 合约描述 + +### ISNADToken + +具有治理功能的 ERC20 代币。 + +**功能：** +- ERC20 标准函数 +- ERC20Votes 扩展用于治理 +- 固定最大供应量：10 亿枚代币 +- MINTER_ROLE：奖励池可以铸造 +- BURNER_ROLE：质押合约可以销毁（惩罚） + +**关键函数：** +```solidity +function mint(address to, uint256 amount) external; +function burn(address from, uint256 amount) external; +function delegate(address delegatee) external; +``` + +### ISNADRegistry + +将资源铭刻永久存储在链上。 + +**功能：** +- 资源通过 SHA-256 内容哈希标识 +- 元数据存储在 calldata 中（铭刻风格） +- 支持大文件分块上传 +- 一旦铭刻即不可变 + +**关键函数：** +```solidity +function inscribe( + bytes32 contentHash, + uint8 resourceType, + bytes calldata metadata, + bytes calldata content +) external returns (bytes32); + +function getResource(bytes32 contentHash) external view returns ( + bool inscribed, + address author, + uint256 blockNumber, + string memory metadataUri +); +``` + +### ISNADStaking + +核心认证机制。 + +**功能：** +- 审计员在资源上质押代币 +- 可配置锁定时长（7-90 天） +- 带乘数的信任评分计算 +- Oracle 判决后惩罚 + +**关键函数：** +```solidity +function stake( + bytes32 resourceHash, + uint256 amount, + uint256 lockDuration +) external returns (bytes32 attestationId); + +function unstake(bytes32 attestationId) external; + +function getTrustScore(bytes32 resourceHash) external view returns (uint256); + +function getTrustTier(bytes32 resourceHash) external view returns (uint8); + +function getAttestation(bytes32 attestationId) external view returns ( + address auditor, + bytes32 resourceHash, + uint256 amount, + uint256 lockUntil, + uint256 lockDuration, + bool slashed +); +``` + +### ISNADOracle + +检测和陪审团系统。 + +**功能：** +- 举报恶意资源 +- 随机陪审团选择（5 名成员） +- 67% 绝对多数判决 +- 2 倍押金申诉 + +**关键函数：** +```solidity +function flag( + bytes32 resourceHash, + string calldata evidence +) external; + +function vote(bytes32 flagId, uint8 verdict) external; + +function executeVerdict(bytes32 flagId) external; + +function appeal(bytes32 flagId) external; +``` + +### ISNADRewardPool + +向审计员分配收益。 + +**功能：** +- 基于质押金额和时长的收益 +- 锁定乘数：30 天=1x，60 天=1.25x，90 天=1.5x +- 由协议费用和国库提供资金 +- 可通过治理调整 APY + +**关键函数：** +```solidity +function claimRewards() external; + +function calculateRewards(address auditor) external view returns (uint256); +``` + +### ISNADGovernor + TimelockController + +用于协议升级的 DAO 治理。 + +**功能：** +- OpenZeppelin Governor 模式 +- 执行前 2 天时间锁 +- 4% 法定人数要求 +- 100,000 $ISNAD 提案门槛 + +**可治理参数：** +- 信任等级阈值 +- 锁定时长限制 +- 奖励池 APY +- 举报押金金额 +- 合约升级 + +## 信任等级阈值 + +| 等级 | 枚举值 | 阈值 | +|------|------------|-----------| +| UNVERIFIED（未验证） | 0 | 0 | +| COMMUNITY（社区） | 1 | 100 $ISNAD | +| VERIFIED（已验证） | 2 | 1,000 $ISNAD | +| TRUSTED（受信任） | 3 | 10,000 $ISNAD | + +## 锁定时长乘数 + +| 时长 | 乘数 | 加权评分 | +|----------|------------|----------------| +| 7 天 | 1.0x | 质押 × 1.0 | +| 30 天 | 1.0x | 质押 × 1.0 | +| 60 天 | 1.25x | 质押 × 1.25 | +| 90 天 | 1.5x | 质押 × 1.5 | + +## 集成示例 + +使用 viem： + +```typescript +import { createPublicClient, createWalletClient, http } from 'viem'; +import { baseSepolia } from 'viem/chains'; +import { ISNADStakingABI, ISNADTokenABI } from '@isnad/contracts'; + +const STAKING_ADDRESS = '0x58983D142A388A96B7d9F970005483AA044CCAD9'; +const TOKEN_ADDRESS = '0xc41c1006A1AaC093C758A2f09de16fee2561651A'; + +// 读取信任评分 +const publicClient = createPublicClient({ + chain: baseSepolia, + transport: http(), +}); + +const trustScore = await publicClient.readContract({ + address: STAKING_ADDRESS, + abi: ISNADStakingABI, + functionName: 'getTrustScore', + args: [resourceHash], +}); + +// 质押代币（需要钱包） +const walletClient = createWalletClient({ ... }); + +// 1. 批准 +await walletClient.writeContract({ + address: TOKEN_ADDRESS, + abi: ISNADTokenABI, + functionName: 'approve', + args: [STAKING_ADDRESS, amount], +}); + +// 2. 质押 +await walletClient.writeContract({ + address: STAKING_ADDRESS, + abi: ISNADStakingABI, + functionName: 'stake', + args: [resourceHash, amount, lockDuration], +}); +``` + +## 安全性 + +- 所有合约使用 OpenZeppelin 库 +- Slither 静态分析已完成 +- 所有输入的零地址检查 +- 状态变更函数使用 ReentrancyGuard +- 基于角色的访问控制 + +## 源代码 + +所有合约均为开源并在 BaseScan 上验证： + +- GitHub: https://github.com/counterspec/isnad/tree/main/contracts +- BaseScan: https://sepolia.basescan.org/address/[合约地址] diff --git a/docs/jury.zh-CN.md b/docs/jury.zh-CN.md new file mode 100644 index 00000000..f5deee08 --- /dev/null +++ b/docs/jury.zh-CN.md @@ -0,0 +1,131 @@ +# 陪审团系统 + +当资源被举报为潜在恶意时，随机选出的审计员陪审团审查证据并投票表决。 + +## 举报资源 + +任何人都可以举报他们认为恶意的资源： + +1. **存入 100 $ISNAD** — 防止垃圾举报 +2. **提供证据** — 描述恶意行为 +3. **等待陪审团** — 随机选出 5 名审计员 + +### 举报押金结果 + +| 判决 | 押金返还 | +|---------|----------------| +| 有罪（GUILTY） | 100% 返还 + 来自被销毁质押的奖励 | +| 无罪（INNOCENT） | 90% 返还 | +| 驳回（DISMISSED，无绝对多数） | 50% 返还 | + +## 陪审团选择 + +提交举报后： + +1. **随机选出 5 名审计员** +2. **利益冲突检查** — 陪审员不能在被举报资源上有质押 +3. **链上随机性** — 生产环境使用 VRF 选择 +4. **7 天截止日期** — 陪审员有 7 天时间审查和投票 + +### 陪审员要求 + +- 必须是活跃审计员（至少有一条认证） +- 不能在被审查的资源上有质押 +- 应具备已证明的能力（历史准确率） + +## 投票流程 + +每位陪审员审查： +- 资源内容（铭刻在链上） +- 举报者的证据 +- 资源的元数据和声明 + +然后投票： +- **有罪（GUILTY）** — 资源为恶意 +- **无罪（INNOCENT）** — 资源安全 +- **弃权（ABSTAIN）** — 无法判断（计入法定人数但不计入判决） + +### 判决要求 + +需要 **绝对多数（≥67%）** 才能做出判决： +- 如果 4+ 名陪审员投票有罪 → 有罪判决 +- 如果 4+ 名陪审员投票无罪 → 无罪判决 +- 否则 → 驳回（无绝对多数） + +## 判决结果 + +### 有罪 +- 资源上 **所有质押** 被销毁 +- **举报者** 收回押金 + 被销毁质押的一部分 +- **审计员** 失去全部质押 +- **资源** 在链上标记为恶意 + +### 无罪 +- **质押保持** 正常锁定 +- **举报者** 收回 90% 押金 +- **审计员** 继续赚取收益 +- **资源** 信任评分不变 + +### 驳回 +- **质押保持** 正常锁定 +- **举报者** 收回 50% 押金 +- **资源** 可以用新证据再次被举报 + +## 申诉 + +判决可在 3 天内申诉： + +1. **存入 2 倍**原始举报金额（200 $ISNAD） +2. **新陪审团** 被选出进行重审 +3. **申诉判决为最终判决** — 不可进一步申诉 + +### 谁可以申诉 + +- 原举报者（如果判决为无罪） +- 资源上的任何质押者（如果判决为有罪） +- 有足够押金的任何第三方 + +## 时间线 + +| 事件 | 截止时间 | +|-------|----------| +| 陪审团选择 | 举报后立即 | +| 陪审员投票期 | 7 天 | +| 申诉窗口 | 判决后 3 天 | +| 申诉审理 | 7 天 | +| 执行 | 最终判决后立即 | + +## 陪审员激励 + +与多数投票一致的陪审员获得： +- 来自协议国库的小额奖励 +- 声誉提升（影响未来的陪审团选择） + +与多数投票不一致的陪审员： +- 无惩罚（诚实的分歧是正常的） +- 但持续偏离多数的投票可能影响声誉 + +## 安全考虑 + +### 反串谋 +- 随机陪审团选择使协调变得困难 +- 陪审员在截止日期前不知道彼此的投票 +- 大额质押风险阻止串谋 + +### 女巫抵抗 +- 成为陪审员需要是活跃审计员 +- 创建虚假审计员需要真实资本（质押） +- 历史准确率影响选择 + +### 申诉安全 +- 更高的申诉押金阻止轻率申诉 +- 新陪审团确保新的视角 +- 终局性防止无限申诉循环 + +## 陪审员最佳实践 + +1. **彻底审查** — 投票前阅读所有证据 +2. **保持客观** — 基于证据投票，而非关系 +3. **遵守截止日期** — 逾期投票不计入 +4. **记录推理** — 保留笔记以备申诉 +5. **积极参与** — 陪审义务对协议健康至关重要 diff --git a/docs/staking.zh-CN.md b/docs/staking.zh-CN.md new file mode 100644 index 00000000..00ab3f32 --- /dev/null +++ b/docs/staking.zh-CN.md @@ -0,0 +1,162 @@ +# 质押指南 + +质押 $ISNAD 代币并创建认证的分步指南。 + +## 前提条件 + +- 钱包中有 $ISNAD 代币 +- Base 网络上有 ETH 用于支付 Gas 费用 +- 已连接钱包（MetaMask、Coinbase Wallet、WalletConnect） + +## 第 1 步：查找资源 + +使用 [信任检查器](https://isnad.md/check) 查找资源： + +1. 输入资源标识符： + - 内容哈希（0x...） + - 技能 URL（clawhub.com/author/skill） + - 包名称 + +2. 查看当前信任状态： + - 信任等级 + - 现有认证 + - 总质押金额 + +**提示：** 寻找质押较低或无质押但你确信安全的资源。这些对早期认证者来说提供最佳的风险收益比。 + +## 第 2 步：审查代码 + +**这是最重要的一步。** 在质押之前： + +### 检查危险信号 +- [ ] 未授权的网络请求 +- [ ] 凭据访问或泄露 +- [ ] 混淆或压缩的代码 +- [ ] 意外的文件系统访问 +- [ ] 特权命令执行 +- [ ] 可疑的依赖项 + +### 验证声明 +- [ ] 元数据与实际行为一致 +- [ ] 声明的权限准确 +- [ ] 版本历史干净 +- [ ] 作者声誉（如适用） + +### 尽可能测试 +- [ ] 在沙箱环境中运行 +- [ ] 监控网络流量 +- [ ] 检查文件系统变更 +- [ ] 验证输出正确性 + +## 第 3 步：连接钱包 + +1. 访问 https://isnad.md/stake +2. 点击页面顶部的"连接"按钮 +3. 选择你的钱包提供商 +4. 确认连接 + +你的钱包应处于 Base Sepolia（测试网）或 Base 主网。 + +## 第 4 步：批准代币支出 + +在质押之前，你必须批准质押合约使用你的代币： + +1. 输入你想要的质押金额 +2. 点击"批准" +3. 在钱包中确认交易 +4. 等待确认 + +**注意：** 这是每个金额的一次性批准。如果你之后想质押更多，可能需要再次批准。 + +## 第 5 步：创建认证 + +1. 输入资源哈希（或搜索） +2. 设置质押金额 +3. 选择锁定时长： + - 7 天（1.0x 乘数） + - 30 天（1.0x 乘数） + - 60 天（1.25x 乘数） + - 90 天（1.5x 乘数） +4. 查看摘要： + - 质押金额 + - 锁定时长 + - 解锁日期 +5. 点击"创建认证" +6. 在钱包中确认 +7. 等待确认 + +## 第 6 步：监控你的仓位 + +质押后： + +### 查看你的认证 +- 连接钱包后访问质押页面 +- 查看所有活跃认证 +- 跟踪解锁日期和状态 + +### 关注举报 +如果你质押的资源被举报： +- 你可能被要求提供证据 +- 关注陪审团流程 +- 如果你认为判决有误，可以申诉 + +## 第 7 步：解除质押（锁定期结束后） + +锁定期结束后： + +1. 进入你的认证列表 +2. 找到已解锁的认证 +3. 点击"解除质押" +4. 在钱包中确认 +5. 收回你的质押 + 任何赚取的收益 + +## 质押限制 + +| 限制 | 值 | +|-------|-------| +| 最低质押 | 10 $ISNAD | +| 单次认证最高 | 10,000 $ISNAD | +| 审计员总质押上限 | 100,000 $ISNAD | +| 集中度上限 | 单个审计员不超过资源质押的 33% | + +## 锁定时长选项 + +| 时长 | 乘数 | 适用场景 | +|----------|------------|----------| +| 7 天 | 1.0x | 测试、短期 | +| 30 天 | 1.0x | 标准认证 | +| 60 天 | 1.25x | 更高收益、更有信心 | +| 90 天 | 1.5x | 长期、最大收益 | + +## 故障排除 + +### 交易失败 +- 检查是否有足够的 ETH 支付 Gas +- 确保代币批准金额充足 +- 尝试提高 Gas 限制 + +### 质押未显示 +- 等待交易确认 +- 刷新页面 +- 检查你的认证列表 + +### 无法解除质押 +- 确认锁定期已结束 +- 检查资源是否被惩罚 +- 确保你使用正确的钱包连接 + +## Gas 费用（约） + +| 操作 | Gas（Base） | +|--------|------------| +| 批准 | ~50,000 | +| 质押 | ~150,000 | +| 解除质押 | ~100,000 | + +按 Base 典型 Gas 价格，每笔交易预计不到 $0.01。 + +## 下一步 + +- [查看排行榜](https://isnad.md/leaderboard) — 查看顶级审计员 +- [了解惩罚机制](./jury.zh-CN.md) — 理解风险 +- [API 参考](./api.zh-CN.md) — 构建集成 diff --git a/docs/what-is-isnad.zh-CN.md b/docs/what-is-isnad.zh-CN.md new file mode 100644 index 00000000..634e8a0d --- /dev/null +++ b/docs/what-is-isnad.zh-CN.md @@ -0,0 +1,99 @@ +# 什么是 ISNAD？ + +ISNAD（إسناد）是一种权益证明认证协议，为 AI 资源创建信任层。名称来源于伊斯兰学术传统中的 *isnad* ——用于认证圣训的传述链条。一句话的可信度取决于其传述链条的可信度。 + +## 问题 + +AI 代理越来越依赖来自不受信任来源的共享资源： +- **技能** — 可执行代码包、工具、API 集成 +- **配置** — 代理配置、网关设置 +- **提示词** — 系统提示词、角色设定、行为指令 +- **记忆** — 知识库、RAG 文档 +- **模型** — 微调模型、LoRA、适配器 + +一个被入侵的资源可以： +- 泄露凭据和敏感数据 +- 执行未授权命令 +- 操纵代理行为 +- 危及整个系统安全 + +现有方法无法规模化： +- **手动代码审查** — 大多数代理无法进行审计 +- **集中审批** — 单点故障，效率瓶颈 +- **声誉评分** — 可被操纵，新作者难以建立声誉 +- **沙箱隔离** — 不够完善，许多资源需要真实权限 + +## 解决方案 + +ISNAD 通过经济激励创建市场定价的信任信号： + +1. **资源被铭刻**到 Base L2 上，包含内容和元数据 +2. **审计员质押 $ISNAD 代币**为资源安全背书 +3. **质押被锁定**一段时间（7-90 天） +4. **若为恶意**，陪审团审查并销毁质押（slash） +5. **若为安全**，审计员从奖励池获得收益 + +### 为什么有效 + +- **利益绑定** — 审计员承担真实风险。虚假认证将导致代币销毁。 +- **自我筛选的专业能力** — 只有有信心的审计员才会质押。市场筛选出有能力的审计员。 +- **永久可验证** — 一切都在链上。无需信任外部基础设施。 +- **抗攻击** — 女巫攻击需要资本。串谋将导致所有参与者代币销毁。 + +## 链上铭刻 + +与需要钉住服务的 IPFS 方案不同，ISNAD 将资源直接铭刻到 Base L2 calldata 上： + +- 每千字节约 **$0.01** 铭刻费用 +- **永久**链上存储 +- **零**外部依赖 + +资源使用 SHA-256 哈希进行内容寻址，确保完整性验证始终可行。 + +## 核心概念 + +### 信任评分 +资源上的总加权质押金额。质押越高 = 经济支持越多 = 信任度越高。 + +### 信任等级 +基于信任评分的分类： +- **UNVERIFIED（未验证）** — 无认证 +- **COMMUNITY（社区）** — ≥100 $ISNAD 质押 +- **VERIFIED（已验证）** — ≥1,000 $ISNAD 质押 +- **TRUSTED（受信任）** — ≥10,000 $ISNAD 质押 + +### 认证（Attestation） +当审计员对资源进行质押时，他们创建一条认证记录，包含： +- 质押金额 +- 锁定时长 +- 资源哈希 +- 审计员地址 + +### 惩罚（Slashing） +如果资源被发现为恶意： +1. 任何人都可以举报（需存入 100 $ISNAD） +2. 随机选出 5 名审计员组成陪审团 +3. 陪审团投票（需 67% 绝对多数） +4. 若判定有罪：该资源上所有质押将被销毁 +5. 举报者收回押金并获得奖励 + +## 协议架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ISNAD 协议 │ +├──────────────┬──────────────┬──────────────┬───────────────┤ +│ ISNADToken │ ISNADRegistry│ ISNADStaking │ ISNADOracle │ +│ (ERC20 + │ (铭刻 │ (质押 + │ (举报 + │ +│ 投票权) │ + 元数据) │ 认证) │ 陪审团) │ +├──────────────┴──────────────┴──────────────┴───────────────┤ +│ ISNADRewardPool │ ISNADGovernor │ +│ (收益分配) │ (DAO + 时间锁) │ +└─────────────────────────┴──────────────────────────────────┘ +``` + +## 下一步 + +- [成为审计员](./auditors.zh-CN.md) — 开始质押并赚取收益 +- [质押指南](./staking.zh-CN.md) — 分步操作说明 +- [集成指南](./integration.md) — 为你的代理添加信任检查 diff --git a/scanner/README.zh-CN.md b/scanner/README.zh-CN.md new file mode 100644 index 00000000..dee6bd6f --- /dev/null +++ b/scanner/README.zh-CN.md @@ -0,0 +1,135 @@ +# ISNAD 扫描器 + +ISNAD 信任协议的检测预言机。扫描 AI 资源（技能、提示词、配置）中的恶意模式，并将标记提交到链上预言机。 + +## 安装 + +```bash +cd scanner +npm install +npm run build +``` + +## 使用方法 + +### 扫描文件 + +```bash +# 基本扫描 +npm run scan -- scan ./path/to/skill.js + +# 输出为 JSON +npm run scan -- scan ./path/to/skill.js --json + +# 使用自定义资源哈希 +npm run scan -- scan ./path/to/skill.js --hash 0x123... +``` + +### 扫描多个文件 + +```bash +# 扫描目录中所有 JS 文件 +npm run scan -- batch "./skills/**/*.js" + +# 首个高风险发现时立即停止 +npm run scan -- batch "./skills/**/*.js" --fail-fast +``` + +### 生成证据 + +```bash +npm run scan -- evidence ./malicious-skill.js +``` + +### 向预言机提交标记 + +```bash +# 试运行（分析但不提交） +npm run scan -- flag ./malicious-skill.js --dry-run + +# 提交到测试网 +npm run scan -- flag ./malicious-skill.js --network testnet + +# 提交到主网 +npm run scan -- flag ./malicious-skill.js --network mainnet +``` + +### 作为服务运行 + +```bash +# 设置环境变量 +export ISNAD_PRIVATE_KEY=0x... +export ISNAD_AUTO_FLAG=false # 设置为 true 以启用自动标记 + +# 启动服务 +npm start +``` + +## 环境变量 + +| 变量 | 描述 | 默认值 | +|----------|-------------|---------| +| `ISNAD_PRIVATE_KEY` | 用于标记提交的私钥 | 必填 | +| `ISNAD_REGISTRY_ADDRESS` | 注册表合约地址 | Sepolia 默认值 | +| `ISNAD_ORACLE_ADDRESS` | 预言机合约地址 | Sepolia 默认值 | +| `ISNAD_NETWORK` | `testnet` 或 `mainnet` | `testnet` | +| `ISNAD_AUTO_FLAG` | 自动提交标记 | `false` | +| `ISNAD_MIN_CONFIDENCE` | 自动标记的最低置信度 | `0.7` | + +## 检测模式 + +扫描器检测以下内容： + +### 严重（Critical） +- 动态代码执行（`eval`、`Function`） +- Shell 命令执行（`exec`、`spawn`） +- 子进程导入 +- VM 模块使用 +- 钥匙串/凭据存储访问 +- 系统目录写入 + +### 高危（High） +- 数据泄露（Webhook、base64 发送） +- 敏感文件读取（`.env`、`.ssh`、凭据） +- 原始套接字访问 +- 基于 DNS 的泄露 +- 安全绕过尝试 +- 加密货币挖矿 + +### 中危（Medium） +- 环境变量访问 +- 递归目录读取 +- 主目录访问 +- 混淆模式 + +### 低危（Low） +- Unicode 转义序列 +- 轻微可疑模式 + +## API + +```typescript +import { analyzeContent, formatResult } from '@isnad/scanner'; + +const result = analyzeContent(code, resourceHash); +console.log(formatResult(result)); + +// 结果包含： +// - riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'clean' +// - riskScore: number +// - confidence: 0-1 +// - findings: 详细的模式匹配 +``` + +## 合约地址 + +### Base Sepolia（测试网） +- 注册表：`0x8340783A495BB4E5f2DF28eD3D3ABcD254aA1C93` +- 预言机：`0x4f1968413640bA2087Db65d4c37912d7CD598982` + +### Base 主网 +- 即将上线 + +## 许可证 + +MIT