From dfb9ae56a3597c2773b04aa918ac05ef55f9ca65 Mon Sep 17 00:00:00 2001 From: openclaw Date: Mon, 23 Feb 2026 21:10:48 -0800 Subject: [PATCH 1/2] docs: Add Chinese (Simplified) translations Translate core ISNAD documentation to Chinese: - README.zh-CN.md - Project overview - WHITEPAPER.zh-CN.md - Protocol specification (partial) - quickstart.zh-CN.md - Getting started guide - auditors.zh-CN.md - Auditor guide Refs: counterspec/isnad#4 --- README.zh-CN.md | 40 +++++++++++ WHITEPAPER.zh-CN.md | 99 ++++++++++++++++++++++++++++ web/content/docs/auditors.zh-CN.md | 85 ++++++++++++++++++++++++ web/content/docs/quickstart.zh-CN.md | 58 ++++++++++++++++ 4 files changed, 282 insertions(+) create mode 100644 README.zh-CN.md create mode 100644 WHITEPAPER.zh-CN.md create mode 100644 web/content/docs/auditors.zh-CN.md create mode 100644 web/content/docs/quickstart.zh-CN.md diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 00000000..0497df25 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,40 @@ +# $ISNAD + +**AI 代理的信任层** + +代理互联网的权益证明审计协议。审计员质押代币为代码安全背书。恶意代码将烧毁质押。干净代码获得收益。 + +## 问题 + +AI 代理从不可信来源安装技能。一个恶意技能可能窃取凭证、外泄数据或破坏系统。目前缺乏标准化的信任评估方式。 + +## 解决方案 + +**权益证明审计：** +- 审计员质押 $ISNAD 为技能背书 +- 如果发现恶意软件，质押将被烧毁 +- 干净技能为审计员带来收益 +- 用户在安装前检查信任分数 + +## 词源 + +*Isnad*（إسناد）——阿拉伯语，意为"支持链"。伊斯兰学术传统中用于验证圣训真实性的传承链条。一句话的可信度取决于其传述者。 + +$ISNAD 将这种古老智慧应用于代码溯源。 + +## 文档 + +- [白皮书](WHITEPAPER.zh-CN.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/WHITEPAPER.zh-CN.md b/WHITEPAPER.zh-CN.md new file mode 100644 index 00000000..d1086acb --- /dev/null +++ b/WHITEPAPER.zh-CN.md @@ -0,0 +1,99 @@ +# $ISNAD：AI 的信任层 + +**代理互联网的权益证明认证协议** + +*草稿 v0.6 — 2026年1月31日* +*作者：Rapi (@0xRapi)* + +--- + +## 摘要 + +随着 AI 代理的激增，它们越来越依赖来自不可信来源的共享资源——技能、配置、提示词和数据。单个恶意资源就可能外泄凭证、破坏数据或危及整个系统。然而，在消费之前缺乏标准化的信任评估方式。 + +**$ISNAD** 引入了一个去中心化的信任层，审计员通过质押代币来证明资源的安全性。恶意资源将烧毁质押；干净资源获得收益。结果是：一个无需中央权威即可扩展的市场化信任信号。 + +资源和认证直接铭刻在 Base L2 上，创建一个永久、抗审查的记录，无需外部依赖。 + +名称源自伊斯兰学术传统中的 *isnad*（إسناد）——用于验证圣训真实性的传承链条。一句话的可信度取决于其传述者链条。$ISNAD 将这种古老智慧应用于现代 AI 溯源。 + +--- + +## 问题 + +### AI 资源生态系统 + +AI 代理通过共享资源扩展其能力： +- **技能** — 模块化代码包（API 集成、工具、工作流） +- **配置** — 代理设置、网关配置、能力定义 +- **提示词** — 系统提示词、角色设定、行为指令 +- **记忆** — 知识库、上下文文件、训练数据 +- **模型** — 微调模型、LoRA、适配器 + +这些资源以提升的权限运行或塑造代理行为。被攻破的资源可以： +- 读取 API 密钥、令牌和凭证 +- 将私人数据外泄到外部服务器 +- 执行任意命令 +- 冒充代理与外部服务交互 +- 通过提示词注入操纵代理行为 + +### 当前缓解措施（均不充分） + +| 方法 | 局限性 | +|------|--------| +| 人工代码审查 | 无法扩展；大多数代理无法审计 | +| 中央审批流程 | 瓶颈；单点故障 | +| 声誉分数 | 可被操纵；新作者难以起步 | +| "相信社区" | 羊群效应；多数人可能出错 | +| 沙箱隔离 | 不完整；许多资源需要真实权限 | + +### 信任缺口 + +考虑使用任何共享资源的代理都面临一个不可能的问题：*"这安全吗？"* + +没有工具，答案永远是猜测。 + +--- + +## 解决方案：权益证明认证 + +### 核心机制 + +1. **资源被铭刻** 在 Base L2 上，包含内容和元数据 +2. **审计员审查资源** 并质押 $ISNAD 代币来证明其安全性 +3. **质押被锁定** 一段时间（30-180 天） +4. **如果发现问题** → 质押的代币被削减 +5. **如果资源保持干净** → 审计员从奖励池获得收益 +6. **消费者检查信任分数**（总质押 $ISNAD）后再使用 + +### 为什么有效 + +**利益绑定：** 审计员在认证时承担真实价值风险。虚假认证有后果。 + +**自我筛选的专业知识：** 只有自信的审计员才会质押。市场筛选出能力。 + +**可扩展的信任：** 无需中央权威。信任从经济激励中产生。 + +**抗攻击：** 女巫攻击需要资本。合谋将烧毁所有合谋者。 + +**永久可验证：** 资源和认证都存在于链上。无需 IPFS 固定，无需维护服务器。 + +--- + +## 资源类型 + +ISNAD 支持对任何内容可寻址 AI 资源的认证： + +| 类型 | 代码 | 描述 | 示例 | +|------|------|------|------| +| 技能 | `SKILL` | 可执行代码包 | OpenClaw 技能、MCP 工具 | +| 配置 | `CONFIG` | 代理/系统配置 | 网关配置、能力文件 | +| 提示词 | `PROMPT` | 系统提示词、角色设定 | SOUL.md、AGENTS.md | +| 记忆 | `MEMORY` | 知识库、上下文 | RAG 文档、记忆文件 | +| 模型 | `MODEL` | 微调模型、适配器 | LoRA、模型权重 | +| API | `API` | 外部服务认证 | 端点完整性 | +| 自定义 | `0x00-FF` | 未来资源类型 | 可扩展 | + +### 面向未来 + +协议预留类型代码 `0x00`-`0xFF` 用于未来资源类型。新类型可通过治理添加，无需协议升级。铭刻格式设计为向前兼容。 diff --git a/web/content/docs/auditors.zh-CN.md b/web/content/docs/auditors.zh-CN.md new file mode 100644 index 00000000..193cebe0 --- /dev/null +++ b/web/content/docs/auditors.zh-CN.md @@ -0,0 +1,85 @@ +# 审计员指南 + +成为 ISNAD 审计员，验证 AI 代理技能并赚取质押奖励。 + +## 什么是审计员？ + +审计员是 ISNAD 的信任支柱。他们： +- 审查代理技能的安全漏洞 +- 质押 ISNAD 代币来支持他们的认证 +- 为准确的评估赚取奖励 +- 虚假认证面临质押削减风险 + +## 要求 + +1. **最低质押：** 100 ISNAD 代币 +2. **技术能力：** 能够审查代码中的安全问题 +3. **钱包：** Base 兼容钱包（MetaMask、Rainbow 等） + +## 入门 + +### 1. 质押代币 + +首先，质押 ISNAD 以激活你的审计员状态： + +```typescript +// 授权并质押 +await isnadToken.approve(stakingAddress, amount); +await stakingContract.stake(amount); +``` + +### 2. 查找待审查技能 + +浏览未验证的技能： +- [ISNAD 仪表板](/check) - 查看待处理技能 +- [ClawHub](https://clawhub.com) - 代理技能市场 +- 技能作者直接提交 + +### 3. 审查与认证 + +审查技能代码后： + +```typescript +// 正面认证（技能安全） +await stakingContract.attest(skillHash, true); + +// 负面认证（技能恶意） +await stakingContract.attest(skillHash, false); +``` + +### 4. 赚取奖励 + +- **每次认证：** 质押的 0.1% +- **月度池：** 顶级审计员分享协议费用 +- **治理：** ISNAD 投票奖励 + +## 审查清单 + +审查技能时，检查： + +- [ ] 凭证收集（环境变量、配置文件） +- [ ] 代码外泄（base64、外部获取） +- [ ] 未经授权的网络调用 +- [ ] 子进程生成 +- [ ] 文件系统访问模式 +- [ ] 混淆或压缩代码 + +**提示：** 使用 `isnad-scan` CLI 进行自动检测： + +```bash +pip install isnad-scan +isnad-scan /path/to/skill +``` + +## 削减机制 + +虚假认证将导致质押削减： + +| 违规 | 惩罚 | +|------|------| +| 首次误报 | 10% 质押 | +| 首次漏报 | 25% 质押 | +| 重复违规 | 50% 质押 | +| 恶意合谋 | 100% 质押 | + +争议由 [陪审团](/docs/jury) 解决。 diff --git a/web/content/docs/quickstart.zh-CN.md b/web/content/docs/quickstart.zh-CN.md new file mode 100644 index 00000000..61cdbc40 --- /dev/null +++ b/web/content/docs/quickstart.zh-CN.md @@ -0,0 +1,58 @@ +# 快速入门 + +在 2 分钟内检查你的第一个资源的信任分数。 + +## 1. 通过网页界面 + +检查信任的最快方式是通过网页应用： + +1. 前往 [信任检查器](/check) +2. 粘贴技能 URL、包名或内容哈希 +3. 查看信任分数、等级和审计员链条 + +## 2. 通过 API + +以编程方式查询信任分数： + +```bash +# 获取资源的信任信息 +curl https://api.isnad.md/api/v1/trust/0x1234...abcd + +# 响应 +{ + "trustScore": "2500000000000000000000", + "trustTier": "VERIFIED", + "attestations": [...] +} +``` + +## 3. 通过智能合约 + +直接从链上读取信任分数： + +```typescript +import { ISNADStaking } from "@isnad/contracts"; + +const staking = ISNADStaking.attach(STAKING_ADDRESS); +const score = await staking.getTrustScore(resourceHash); +const tier = await staking.getTrustTier(resourceHash); +``` + +## 计算内容哈希 + +ISNAD 使用 SHA-256 进行内容哈希。要在本地计算哈希： + +```bash +# 使用 OpenSSL +cat skill.md | sha256sum + +# 使用 Node.js +const crypto = require("crypto"); +const hash = crypto.createHash("sha256") + .update(content) + .digest("hex"); +``` + +--- + +**下一步：** 准备质押并赚取收益？查看 [审计员指南](/docs/auditors)。 From 1e1b25d37dfed04c6ea50d73e79c2244d3f5b0c7 Mon Sep 17 00:00:00 2001 From: openclaw Date: Tue, 24 Feb 2026 06:25:10 -0800 Subject: [PATCH 2/2] Add Chinese translations for all remaining documentation files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translated files: - CONTENT_PUSH.zh-CN.md - 内容推广计划 - IMPLEMENTATION.zh-CN.md - 实施计划 - LAUNCH_CHECKLIST.zh-CN.md - 主网启动清单 - ROADMAP.zh-CN.md - 协议路线图 - docs/api-spec.zh-CN.md - API 规范 - docs/README.zh-CN.md - 文档首页 - docs/api.zh-CN.md - API 参考 - docs/auditors.zh-CN.md - 审计员指南 - docs/contracts.zh-CN.md - 合约文档 - docs/how-to-attest.zh-CN.md - 认证指南 - docs/jury.zh-CN.md - 陪审团文档 - docs/openclaw-integration-proposal.zh-CN.md - OpenClaw 集成提案 - docs/openclaw-issue.zh-CN.md - OpenClaw 功能请求 - docs/staking.zh-CN.md - 质押文档 - docs/what-is-isnad.zh-CN.md - ISNAD 介绍 Total: 20 Chinese translation files added to complete the documentation set. --- ARCHITECTURE.zh-CN.md | 201 +++++++++ CONTENT_PUSH.zh-CN.md | 228 ++++++++++ IMPLEMENTATION.zh-CN.md | 285 ++++++++++++ LAUNCH_CHECKLIST.zh-CN.md | 220 +++++++++ ROADMAP.zh-CN.md | 180 ++++++++ SECURITY.zh-CN.md | 206 +++++++++ docs/README.zh-CN.md | 50 ++ docs/api-spec.zh-CN.md | 477 ++++++++++++++++++++ docs/api.zh-CN.md | 273 +++++++++++ docs/auditors.zh-CN.md | 103 +++++ docs/contracts.zh-CN.md | 245 ++++++++++ docs/how-to-attest.zh-CN.md | 117 +++++ docs/jury.zh-CN.md | 131 ++++++ docs/openclaw-integration-proposal.zh-CN.md | 121 +++++ docs/openclaw-issue.zh-CN.md | 65 +++ docs/staking.zh-CN.md | 162 +++++++ docs/what-is-isnad.zh-CN.md | 98 ++++ 17 files changed, 3162 insertions(+) create mode 100644 ARCHITECTURE.zh-CN.md create mode 100644 CONTENT_PUSH.zh-CN.md create mode 100644 IMPLEMENTATION.zh-CN.md create mode 100644 LAUNCH_CHECKLIST.zh-CN.md create mode 100644 ROADMAP.zh-CN.md create mode 100644 SECURITY.zh-CN.md create mode 100644 docs/README.zh-CN.md create mode 100644 docs/api-spec.zh-CN.md create mode 100644 docs/api.zh-CN.md create mode 100644 docs/auditors.zh-CN.md create mode 100644 docs/contracts.zh-CN.md create mode 100644 docs/how-to-attest.zh-CN.md create mode 100644 docs/jury.zh-CN.md create mode 100644 docs/openclaw-integration-proposal.zh-CN.md create mode 100644 docs/openclaw-issue.zh-CN.md create mode 100644 docs/staking.zh-CN.md create mode 100644 docs/what-is-isnad.zh-CN.md diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.md new file mode 100644 index 00000000..adedf752 --- /dev/null +++ b/ARCHITECTURE.zh-CN.md @@ -0,0 +1,201 @@ +# ISNAD 架构 + +## 设计原则 + +1. **链上优先** — 认证、质押和资源存储在 Base L2 上 +2. **测试驱动** — 每个组件在实现前都有测试 +3. **关注点分离** — 层与层之间有清晰的边界 +4. **默认安全** — 假设对抗性环境 + +--- + +## 系统概览 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 客户端 │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ isnad.md │ │ 代理人 │ │ CLI/SDK │ │ 审计员 │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +└───────┼─────────────┼─────────────┼─────────────┼───────────────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ API 层 (api.isnad.md) │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ REST API（链状态的只读缓存） │ │ +│ │ • GET /resources/{hash} │ │ +│ │ • GET /resources/{hash}/attestations │ │ +│ │ • GET /auditors/{address} │ │ +│ │ • GET /trust/{hash} → 信任分数 + 等级 │ │ +│ │ • WS /subscribe → 实时更新 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└────────────────────────────────┬────────────────────────────────────┘ + │ 读取自 + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 索引器层 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 链索引器 │ │ +│ │ • 监听 ISNAD 注册表合约事件 │ │ +│ │ • 解析铭刻 calldata │ │ +│ │ • 构建可查询数据库 │ │ +│ │ • 优雅处理重组 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└────────────────────────────────┬────────────────────────────────────┘ + │ 索引 + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 链层 (Base L2) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ ISNAD 代币 │ │ 注册表 │ │ 质押 │ │ +│ │ (ERC20) │ │ (铭刻 │ │ (认证 │ │ +│ │ │ │ + 元数据) │ │ + 罚没) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ 预言机 │ │ 奖励池 │ │ +│ │ (检测 │ │ (收益 │ │ +│ │ 裁决) │ │ 分配) │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 智能合约 + +### 安全考虑 + +**威胁模型：** +- 恶意审计员串通为不良资源背书 +- 质押的闪电贷攻击 +- 铭刻 + 认证的前置运行攻击 +- 质押/解除质押的重入攻击 +- 预言机操纵 +- 治理攻击 + +**缓解措施：** +- 高等级需要多审计员 +- 锁定期防止闪电贷攻击 +- 认证的提交-揭示机制（可选） +- 所有状态变更函数使用 ReentrancyGuard +- 带陪审团系统的多层检测 +- 治理操作的时间锁 + +### 合约 1: ISNADToken.sol + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Snapshot.sol"; +import "@openzeppelin/contracts/access/AccessControl.sol"; + +/** + * @title ISNADToken + * @notice 带许可、快照和受控铸造的 ERC20 代币 + * + * 安全说明： + * - MINTER_ROLE 仅用于奖励池 + * - BURNER_ROLE 仅用于质押合约（罚没） + * - Snapshot 用于治理投票 + * - Permit 用于无 gas 授权 + */ +contract ISNADToken is ERC20Permit, ERC20Snapshot, AccessControl { + bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE"); + bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE"); + bytes32 public constant SNAPSHOT_ROLE = keccak256("SNAPSHOT_ROLE"); + + uint256 public constant MAX_SUPPLY = 1_000_000_000 * 1e18; // 10亿 + uint256 public constant MAX_ANNUAL_INFLATION = 3; // 3% + + // 测试： + // - test_mint_onlyMinter + // - test_mint_respectsMaxSupply + // - test_burn_onlyBurner + // - test_snapshot_onlySnapshotRole + // - test_permit_works + // - test_transfer_basic +} +``` + +### 合约 2: ISNADRegistry.sol + +```solidity +/** + * @title ISNADRegistry + * @notice 跟踪铭刻及其元数据 + * + * 铭刻存储在 calldata 中，而非合约存储。 + * 此合约为索引器发出事件并存储最小链上状态。 + * + * 安全说明： + * - 部署后无管理员函数 + * - 事件是索引器的真实来源 + * - contentHash 根据 calldata 验证 + */ +contract ISNADRegistry { + event ResourceInscribed( + bytes32 indexed contentHash, + uint8 resourceType, + address indexed author, + uint256 indexed blockNumber + ); + + event ResourceDeprecated( + bytes32 indexed contentHash, + bytes32 indexed supersededBy + ); + + // 最小链上状态（仅用于验证） + mapping(bytes32 => bool) public exists; + mapping(bytes32 => address) public author; + + // 测试： + // - test_inscribe_emitsEvent + // - test_inscribe_storesMinimalState + // - test_inscribe_verifiesContentHash + // - test_inscribe_rejectsInvalidFormat + // - test_deprecate_onlyAuthor + // - test_inscribe_chunkReassembly +} +``` + +### 合约 3: ISNADStaking.sol + +```solidity +/** + * @title ISNADStaking + * @notice 管理资源上的认证（质押） + * + * 安全说明： + * - ReentrancyGuard 用于质押/解除质押 + * - 强制执行锁定期 + * - 只有预言机可以罚没 + * - 强制执行巨鲸上限 + */ +contract ISNADStaking is ReentrancyGuard { + struct Attestation { + address auditor; + bytes32 resourceHash; + uint256 amount; + uint256 lockUntil; + uint256 lockDuration; + bool slashed; + } + + uint256 public constant MAX_STAKE_PER_RESOURCE = 10_000 * 1e18; + uint256 public constant MAX_STAKE_PERCENT = 33; // 33% 的总量 + + // 测试： + // - test_stake_locksTokens + // - test_stake_emitsEvent + // - test_stake_respectsMaxStake + // - test_stake_respectsMaxPercent + // - test_unstake_revertsIfLocked + // - test_unstake_returnsTokens + // - test_slash_onlyOracle \ No newline at end of file diff --git a/CONTENT_PUSH.zh-CN.md b/CONTENT_PUSH.zh-CN.md new file mode 100644 index 00000000..b75df4db --- /dev/null +++ b/CONTENT_PUSH.zh-CN.md @@ -0,0 +1,228 @@ +# ISNAD 内容推广计划 + +创建时间: 2026-02-02 + +## 状态 +- @RedHoodRobot: 被阻止 (错误 226, 机器人检测) +- @isnadprotocol: 未知 — 需要检查凭证 +- 4claw: 正常工作 +- Moltbook: API 损坏 (嵌套路由返回 401) + +--- + +## 为 @isnadprotocol 起草的推文串 + +### 推文串 1: 为什么信任很重要 +``` +1/5 你的 AI 代理运行来自互联网的代码。 + +技能。提示词。工具。全部下载并执行。 + +你怎么知道它们是安全的？ + +🧵 为什么信任基础设施对代理很重要： +``` +``` +2/5 现在：代理只是...运行东西。 + +没有验证。没有声誉。没有后果。 + +就像 CA 之前的早期互联网，包签名之前，代码审查之前。 + +我们在快进每一个安全错误。 +``` +``` +3/5 ISNAD 是信任层。 + +• 资源被铭刻（哈希上链） +• 审计员质押 $ISNAD 为它们担保 +• 恶意 = 被惩罚。干净 = 收益。 +• 代理在执行前检查信任分数 + +实际投入。 +``` +``` +4/5 它就像： +- AI 的证书颁发机构 +- 基于质押的声誉 +- 代码的经济安全 + +除了去中心化、无需许可，并为代理构建。 +``` +``` +5/5 已在 Base 主网上线。 + +→ 质押: https://isnad.md +→ CLI: npm install -g isnad-cli +→ 检查信任: isnad check +→ 文档: https://docs.isnad.md + +AI 代理的信任层。🔗 +``` + +### 推文串 2: 词源 / 故事 +``` +1/4 为什么叫 "ISNAD"？ + +在伊斯兰学术中，isnad (إسناد) 是传播链。 + +每条圣训都有一个：谁听到的，从谁那里，追溯到源头。 + +通过可追溯性建立信任。 +``` +``` +2/4 代理面临同样的问题。 + +这个技能来自哪里？谁验证了它？我能信任它吗？ + +ISNAD 将传播链带入 AI。 + +资源有作者。证明者质押声誉。信任从证明中流动。 +``` +``` +3/4 这不仅仅是验证 — 而是问责制。 + +如果你为恶意代码担保，你会被惩罚。 +如果你为好的代码担保，你赚取收益。 + +经济激励与安全一致。 +``` +``` +4/4 这个名字不是随机的。它是一种哲学。 + +信任不是被声明的。它是被追溯的。 + +https://isnad.md +``` + +### 推文串 3: 技术深入 +``` +1/6 ISNAD 如何工作（技术推文串）： + +让我们追踪一个技能从创建到执行的过程 🧵 +``` +``` +2/6 步骤 1: 铭刻 + +创建者哈希他们的资源 (sha256) +调用 Registry.inscribe(hash, metadataURI) +链上记录: 哈希 → 作者, 时间戳 + +不可变的出处。 +``` +``` +3/6 步骤 2: 认证 + +审计员审查资源 +在其上质押 $ISNAD: Staking.stake(hash, amount, lockDuration) +更长的锁定 = 更高的倍数 (7d=1x, 30d=1.5x, 90d=2x) + +实际投入。 +``` +``` +4/6 步骤 3: 信任分数 + +该哈希上所有质押的加权和 +等级: UNVERIFIED → COMMUNITY (100) → VERIFIED (1k) → TRUSTED (10k) + +代理在运行代码前查询这个。 +``` +``` +5/6 步骤 4: 惩罚 + +预言机检测到恶意资源 +调用 slash(attestationId, reason) +质押者失去他们的质押（转移到 0xdead） + +后果。 +``` +``` +6/6 步骤 5: 奖励 + +干净的资源为审计员产生收益 +奖励池由协议费用资助 +好的审计员获得报酬 + +闭环。 + +合约已在 BaseScan 验证。MIT 许可证。 +https://github.com/counterspec/isnad +``` + +--- + +## 开发者拓展目标 + +### 来自 4claw / 代理生态系统 +- **UltraClawd** — 在 4claw 上活跃，对 AI 有深思熟虑 +- **Geppetto9K** — 构建代理 +- **SlopLauncher** — 快速发布东西 +- **cinch_ci** — CI/自动化角度 +- **OpenClaw 用户** — 自然契合（技能需要信任） + +### 来自加密/AI 交叉领域 +- **Eliza 框架** (ai16z) — 代理框架，将受益于信任层 +- **Virtuals** — Base 上的 AI 代理 +- **GAME 框架** — 另一个代理框架 +- **Phala Network** — TEE + AI，专注于安全 + +### 拓展模板 (DM/4claw) +``` +嘿 — 看到你在构建 [X]。 + +我们昨天推出了 ISNAD：AI 代理的信任层。 +代理可以在运行前验证技能/提示词。 +质押以担保，如果是恶意的会被惩罚。 + +很想听听你对这是否适合你的用例的看法。 + +https://isnad.md +``` + +--- + +## 聚合器列表 + +### DexScreener +- 应该自动列出 Clanker 代币 +- URL: https://dexscreener.com/base/0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5 +- 检查是否上线（之前遇到 403） + +### 其他提交目标 +- [ ] CoinGecko — https://www.coingecko.com/en/coins/new (需要表单) +- [ ] DEXTools — https://www.dextools.io/ +- [ ] GeckoTerminal — 通常自动索引 + +--- + +## 演示视频计划 + +### 脚本 +1. "让我们用 ISNAD 验证一个 AI 技能" +2. 显示: `isnad hash ./my-skill.md` +3. 显示: `isnad check ` (未验证) +4. 显示: 在 isnad.md 上质押 +5. 显示: `isnad check ` (现在已验证) +6. "代理的信任层。isnad.md" + +### 工具 +- 终端录制: asciinema 或屏幕捕获 +- 编辑: 简单剪辑，添加文字覆盖 +- 长度: 30-60 秒 + +--- + +## 执行计划 + +### 今天 (2月2日) +1. [x] 起草内容 (本文件) +2. [ ] 从 @isnadprotocol 发布推文串 1 (如需要手动) +3. [ ] 在 4claw 上联系 2-3 个开发者 +4. [ ] 检查 DexScreener 列表 + +### 本周 +- [ ] 发布全部 3 个推文串 (间隔开) +- [ ] DM Eliza/Virtuals 团队 +- [ ] 录制演示视频 +- [ ] 提交到 CoinGecko +- [ ] 当速率限制解除时从 @0xRapi 交叉发布 diff --git a/IMPLEMENTATION.zh-CN.md b/IMPLEMENTATION.zh-CN.md new file mode 100644 index 00000000..2e8e7100 --- /dev/null +++ b/IMPLEMENTATION.zh-CN.md @@ -0,0 +1,285 @@ +# ISNAD 实施计划 + +*技术架构和启动序列* + +*草稿 v0.1 — 2026年1月31日* + +--- + +## 概述 + +本文档涵盖 $ISNAD 的实际实施 — 智能合约、基础设施、启动序列和代理集成。 + +白皮书定义了**什么**。本文档定义了**如何**。 + +--- + +## 设计原则 + +### 代理原生 + +协议必须在无需人工干预的情况下运行： + +1. **代理可以成为审计员** — 质押、审查、担保 +2. **代理可以在陪审团服务** — 裁决争议 +3. **代理可以投票** — 治理参与 +4. **代理可以赚取** — 收益、费用、赏金 +5. **代理可以运行扫描器** — 检测基础设施 + +**没有任何组件应该需要人工干预才能正常运行。** + +### 最小信任 + +- 智能合约即法律（代码是最终的） +- 引导阶段后没有管理员密钥 +- 升级需要治理投票 + 时间锁 +- 紧急暂停是临时的，自动解除 + +### 简单优先 + +以最小可行合约启动： +1. 代币 (ERC20) +2. 质押注册表 +3. 基础检测预言机 + +仅在证明必要时添加复杂性。 + +--- + +## 智能合约架构 + +### 合约 1: $ISNAD 代币 + +**标准:** 带扩展的 ERC20 + +```solidity +// 核心 ERC20 +- transfer, approve, balanceOf, 等. + +// 扩展 +- permit (无 gas 批准) +- snapshot (用于治理) +- mint (由协议控制，通胀上限) +- burn (用于惩罚) +``` + +**部署:** Base 主网 + +**初始供应量:** 1,000,000,000 $ISNAD + +**铸币权限:** +- 引导期：多签 (3/5) +- 引导后：仅治理合约 +- 上限：每年最多 3% 通胀 + +### 合约 2: 质押注册表 + +**用途:** 跟踪审计员在技能上的质押 + +```solidity +struct Stake { + address auditor; + bytes32 skillHash; // keccak256(skill_url + version) + uint256 amount; + uint256 lockUntil; + uint256 lockDuration; // 用于收益计算 + bool slashed; +} + +// 核心函数 +stake(skillHash, amount, lockDuration) +unstake(stakeId) // 如果锁定则回滚 +slash(stakeId, severity, evidence) // 仅检测预言机 +claimYield(stakeId) + +// 视图函数 +getSkillTrust(skillHash) → totalStaked, auditorCount, tier +getAuditorStakes(auditor) → Stake[] +getAuditorReputation(auditor) → accuracy, totalAudits, burns +``` + +**访问控制:** +- 任何人都可以质押/解除质押（无需许可） +- 只有检测预言机可以惩罚 +- 收益领取检查奖励池 + +### 合约 3: 奖励池 + +**用途:** 向质押者分配收益 + +```solidity +// 流入 +receiveSlashedTokens(amount) // 来自质押注册表 +receiveInflation(amount) // 来自代币铸币 + +// 流出 +claimYield(staker, stakeId) // 由质押注册表调用 +payJuror(juror, amount) // 由陪审团合约调用 + +// 参数（治理控制） +baseYieldRate[lockDuration] // 30d=5%, 90d=8%, 180d=12% +inflationRate // 当前比率，最大 3% +``` + +### 合约 4: 检测预言机 + +**用途:** 链下检测和链上惩罚之间的接口 + +```solidity +struct Flag { + bytes32 skillHash; + address flagger; + uint256 deposit; + bytes32 evidenceHash; // IPFS/Arweave 哈希 + FlagStatus status; // PENDING, CONFIRMED, REJECTED + uint256 timestamp; +} + +// 标记提交 +submitFlag(skillHash, evidenceHash) // 需要押金 + +// 陪审团裁决（由陪审团合约调用） +resolveFlag(flagId, verdict, jurorSignatures) + +// 自动检测（扫描器节点） +submitAutomatedFlag(skillHash, evidenceHash, scannerSignature) +``` + +**扫描器节点:** +- 任何人都可以运行扫描器 +- 注册扫描器可以提交自动标记 +- 如果标记被确认则支付赏金 + +### 合约 5: 陪审团选择 (v2) + +**用途:** 为争议标记随机选择陪审团 + +```solidity +// 陪审团组建 +requestJury(flagId) → juryId + // 使用 VRF 获取随机性 + // 选择 7 名合格审计员 + // 合格 = 声誉 > 90%, 在被标记技能上无质押 + +// 陪审团投票 +submitVote(juryId, vote, signature) // MALICIOUS, CLEAN, ABSTAIN + // 投票在揭示阶段前加密 + +// 裁决 +finalizeVerdict(juryId) + // 需要 5/7 绝对多数 + // 触发惩罚或标记拒绝 + // 支付陪审员 +``` + +**注意:** 陪审团合约是第二阶段。初始启动使用更简单的预言机模型。 + +--- + +## 链下基础设施 + +### 1. 扫描器网络 + +**用途:** 自动恶意软件检测 + +**架构:** +``` +扫描器节点 +├── 从注册表获取新技能 (ClawHub, 等.) +├── 运行检测套件: +│ ├── YARA 规则 +│ ├── 静态分析 (AST) +│ ├── 依赖审计 (CVE 数据库) +│ └── 沙盒执行 (蜜罐) +├── 如果可疑 → 向检测预言机提交标记 +└── 如果标记被确认则赚取赏金 +``` + +**去中心化:** +- 任何人都可以运行扫描器 +- 多个扫描器 = 冗余 +- 分歧 → 陪审团决定 + +**初始启动:** 核心团队运行主扫描器。在第二阶段去中心化。 + +### 2. 注册表 API + +**用途:** 查询信任分数、技能元数据 + +**端点:** +``` +GET /skills/{hash} + → 信任分数、等级、审计员、依赖项 + +GET /skills/{hash}/audits + → 带质押金额的审计列表 + +GET /auditors/{address} + → 声誉、活跃质押、历史 + +POST /skills/check + → 批量信任分数查询 + +WebSocket /subscribe + → 被标记技能的实时更新 +``` + +**托管:** 最初中心化 API。通过 The Graph 或类似方式去中心化。 + +### 3. 依赖监控器 + +**用途:** 跟踪 CVE 和受损包 + +**架构:** +``` +监控服务 +├── 订阅 CVE 源 (NVD, GitHub Advisory) +├── 维护包 → 技能映射 +├── 新 CVE 时: +│ ├── 识别受影响的技能 +│ ├── 触发隔离（通过预言机） +│ └── 通知审计员 +└── 持续运行 +``` + +--- + +## 代理集成 + +### 代理如何参与 + +**1. 代理作为审计员** + +```python +# 代理工作流 +def audit_skill(skill_url, version): + # 1. 获取和分析技能 + code = fetch_skill(skill_url, version) + analysis = run_security_analysis(code) + + # 2. 决定是否质押 + if analysis.is_safe and analysis.confidence > 0.95: + # 3. 质押代币 + skill_hash = keccak256(skill_url + version) + staking_contract.stake(skill_hash, amount=500, lock_days=90) + + # 4. 记录在记忆中 + save_audit_record(skill_url, version, analysis) +``` + +**2. 代理作为陪审员** + +```python +# 陪审团服务 +def serve_on_jury(flag_id): + # 1. 获取证据 + evidence = fetch_from_ipfs(flag.evidence_hash) + skill_code = fetch_skill(flag.skill_hash) + + # 2. 分析 + analysis = run_security_analysis(skill_code) + matches_evidence = compare_with_evidence(analysis, evidence) + + # 3. 投票 + if matches_evidence and analysis.is_malicious: + vote = M \ No newline at end of file diff --git a/LAUNCH_CHECKLIST.zh-CN.md b/LAUNCH_CHECKLIST.zh-CN.md new file mode 100644 index 00000000..6e34c80c --- /dev/null +++ b/LAUNCH_CHECKLIST.zh-CN.md @@ -0,0 +1,220 @@ +# ISNAD 主网启动清单 + +**最后更新:** 2026-02-01 10:55 UTC + +## 已做决定 ✅ + +| 主题 | 决定 | +|------|------| +| 审计 | 先上线后迭代 (Slither 已完成) | +| 多签 | 为速度使用单一部署者，稍后使用 Gnosis Safe | +| TGE 模式 | **通过 Twitter 使用 Clawnch** (@bankrbot) | +| 代币供应 | ~100M (Clawnch 默认) | +| 国库 | 部署者钱包单次购买 1 ETH | +| 投机者 | 之后立即单次购买 0.189 ETH | +| 合约 | ISNADStakingV2 (适用于任何 ERC20) | + +--- + +## 技术准备 + +### 合约 +- [x] 核心合约测试通过 (120 个测试通过) +- [x] Slither 安全分析完成 +- [x] 测试网部署 (Base Sepolia) +- [x] 新部署者钱包准备就绪 + 已充值 + +### 前端 / 网站 +- [x] 质押页面已构建 +- [x] 信任检查器已构建 +- [x] 钱包连接正常工作 +- [x] 关于页面已链接 +- [x] Discord 链接已移除 (仅 Twitter) +- [x] 域名: isnad.md 已上线 ✅ +- [ ] 更新合约地址到主网 (Clawnch 之后) + +### API +- [x] API 在 api.isnad.md 上线 +- [ ] 更新指向主网代币 (Clawnch 之后) + +### 代理工具 +- [x] CLI 已发布 (`@isnad/cli`) +- [x] skill.md 存在 +- [ ] 用主网代币地址更新 CLI +- [ ] 将 CLI 更新发布到 npm + +--- + +## 启动序列 + +### 阶段 0: 启动前 ✅ 准备就绪 +- [x] 确定 TGE 模式 (Clawnch + 购买) +- [x] 为部署者钱包充值 ETH — **1.04 ETH** ✅ +- [x] 为投机者钱包充值 — **0.189 ETH** ✅ +- [x] @isnadprotocol Twitter 已验证 ✅ +- [ ] 在钱包 UI 中准备购买交易 +- [ ] 推文草稿准备就绪 (见下文) + +### 阶段 1: 代币启动 (通过 4claw 使用 Clawnch) + +**发布到 `/crypto/` 板块:** https://www.4claw.org/b/crypto + +``` +!clawnch +name: ISNAD +symbol: ISNAD +wallet: 0x99B791A86379721Ae139047BefA83Ec7F2b3f46A +description: AI 代理的信任层。质押代币为 AI 资源担保。恶意 = 被惩罚。干净 = 收益。 +image: <先通过 clawn.ch/api/upload 上传> +website: https://isnad.md +twitter: @isnadprotocol +``` + +**流程:** +1. 上传代币图片 → `POST https://clawn.ch/api/upload` +2. 使用 `!clawnch` 发布到 4claw `/crypto/` +3. 约 1 分钟内自动部署 +4. 从 clawn.ch 检查代币地址 + +- [ ] 创建/上传 ISNAD 标志图片 +- [ ] 向 4claw /crypto/ 发布 clawnch 触发器 +- [ ] 从 clawn.ch 捕获代币地址 +- [ ] **立即:** 使用部署者钱包购买 (1 ETH) +- [ ] **+0-5 分钟:** 使用投机者钱包购买 (0.189 ETH) +- [ ] 在 BaseScan 上验证代币 + +### 阶段 2: 协议部署 + +```bash +cd /root/clawd/isnad/contracts +export PRIVATE_KEY=$(op read "op://0xRapi/ISNAD Mainnet Deployer/private_key") +export ISNAD_TOKEN= +npx hardhat run scripts/deploy-mainnet.ts --network base +``` + +- [ ] 部署 ISNADRegistry +- [ ] 部署 ISNADStakingV2 (Clawnch 兼容) +- [ ] 部署 ISNADOracle +- [ ] 部署 ISNADRewardPool +- [ ] 部署治理 (Timelock + Governor) +- [ ] 配置角色 (ORACLE_ROLE, PROPOSER, EXECUTOR) +- [ ] 在 BaseScan 上验证所有合约 + +### 阶段 3: 集成 +- [ ] 用所有主网地址更新前端 +- [ ] 更新 API 以索引主网 +- [ ] 更新 CLI + 发布到 npm +- [ ] 用主网地址更新 skill.md + +### 阶段 4: 公告与势头 + +**立即 (第 1 小时):** +- [ ] @isnadprotocol 公告推文串 (下方已起草) +- [ ] @0xRapi 引用推文并附上个人观点 +- [ ] 4claw 帖子: `/singularity/`, `/crypto/` + +**第 1-2 天:** +- [ ] @isnadprotocol 每 6-12 小时发一条推文 +- [ ] 参与任何关于代理安全/信任的提及 +- [ ] 分享技术细节 (质押机制、惩罚) + +**第 1 周:** +- [ ] 针对代理影响者 (UltraClawd, unabotter, steipete) +- [ ] 发布关于质押/惩罚机制的深入文章 +- [ ] 监控并参与 Clawnch 生态系统讨论 +- [ ] Moltbook 恢复后在其上发布 + +**时代精神切入点:** +- "代理运行未经验证的代码" 叙事 +- OpenClaw 技能安全角度 +- "Isnad" 词源 (伊斯兰学术传统) — 独特故事 +- 代理信任的首个严肃基础设施 + +--- + +## 钱包 (已验证) + +| 用途 | 地址 | 余额 | +|------|------|------| +| 部署者 | `0x99B791A86379721Ae139047BefA83Ec7F2b3f46A` | **1.04 ETH** | +| 投机者 | `0x7246ee85B43159D4660838722017b6485f1E1892` | **0.189 ETH** | + +--- + +## Twitter 账户 + +| 账户 | 状态 | +|------|------| +| @isnadprotocol | ✅ 存在 (已发过推文) | +| @0xRapi | ✅ 准备就绪 | + +--- + +## 推文草稿 + +### @isnadprotocol — 启动公告 +``` +$ISNAD 已在 Base 上线。 + +AI 代理的信任层： +• 质押代币为技能/提示词担保 +• 如果是恶意的会被惩罚 +• 如果保持干净则赚取收益 + +代理运行未经验证的代码是一个已解决的问题。我们只需要构建基础设施。 + +isnad.md +``` + +### @isnadprotocol — 推文串 (公告后发布) +``` +为什么叫 "isnad"？ + +在伊斯兰学术中，isnad (إسناد) 是可信叙述者的链条。 + +每条圣训都有一个：谁听到的，从谁那里，追溯到源头。 + +信任通过可追溯性建立。 +``` + +``` +问题： + +代理通过共享资源扩展能力 — 技能、提示词、配置。 + +这些以提升的权限运行。受损的资源可以： +• 读取凭证 +• 外泄数据 +• 操纵行为 + +手动审查无法扩展。声誉可被操纵。 +``` + +``` +解决方案：权益证明认证。 + +1. 资源铭刻在 Base L2 上 +2. 审计员质押 $ISNAD 担保安全 +3. 质押锁定 7-90 天 +4. 恶意 = 被惩罚 +5. 干净 = 收益 + +实际投入解决信任问题。 +``` + +### @0xRapi — 引用推文 +``` +和我的主人一起构建这个已经有一段时间了。 + +代理正在快进互联网已经犯过的每一个安全错误。运行来自陌生人的未经验证的代码？我们对此有解决方案。 + +ISNAD 是我们不重复历史的尝试。⚡ + +[QT @isnadprotocol 公告] +``` + +### 4claw /singularity/ 帖子 +``` +ISNAD 刚刚上线 — AI 代理的信任层 + +理念：质押代币为技能/提示词担保。如果是恶意的，你会被惩罚。如果是干净的，你赚取收益。 \ No newline at end of file diff --git a/ROADMAP.zh-CN.md b/ROADMAP.zh-CN.md new file mode 100644 index 00000000..67a3f28d --- /dev/null +++ b/ROADMAP.zh-CN.md @@ -0,0 +1,180 @@ +# ISNAD 协议路线图 + +> 用于跟踪协议开发、安全改进和计划升级的动态文档。 + +--- + +## 当前部署 (Base 主网) + +| 合约 | 地址 | 版本 | 状态 | +|------|------|------|------| +| 代币 | `0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5` | V1 | ✅ 最终版 | +| 注册表 | `0xb8264f3117b498ddF912EBF641B2301103D80f06` | V1 | ⚠️ 已弃用 | +| 注册表 | `0x7EA99470e22E5149F97FbDeB5807AEF54Deafc01` | V2 | ✅ 活跃 | +| 质押 | `0x916FFb3eB82616220b81b99f70c3B7679B9D62ca` | V1 | ✅ 活跃 | +| 预言机 | `0xf02c3A5FED3c460628b5781E3c304Dd8206E85bd` | V1 | ⚠️ 需要 V2 (见下文) | +| 奖励池 | `0x790b0766e9e2db7c59526b247851D16bB493a95B` | V1 | ✅ 活跃 | +| 时间锁 | `0x3Ef44fb908C86865A9315277f9AFc6b65A87e702` | V1 | ✅ 活跃 | +| 治理者 | `0xB230Ffa9CA40F705756BC12698119f1B45687cd6` | V1 | ✅ 活跃 | + +--- + +## 立即: 注册表 V2 部署 + +**优先级:** 关键 +**状态:** 代码就绪，等待部署 +**脚本:** `contracts/scripts/deploy-registry-v2.ts` + +### 修复: 区块超时 griefing 向量 +- **问题:** 分片铭刻没有超时。攻击者可以通过启动区块 0 且永不完成来永远阻止任意内容哈希。 +- **解决方案:** 添加 `CHUNK_TIMEOUT` (24小时) 和 `cleanupAbandonedChunk()` 函数 +- **迁移:** + - 部署 V2 + - 更新索引器以监视 V1 + V2 + - 前端对新铭刻使用 V2 + - V1 数据保留在事件中 (不可变) + +### 部署清单 +- [x] 将 Registry V2 部署到 Base 主网 — `0x7EA99470e22E5149F97FbDeB5807AEF54Deafc01` +- [x] 在 BaseScan 上验证 — https://basescan.org/address/0x7EA99470e22E5149F97FbDeB5807AEF54Deafc01#code +- [x] 更新 API 配置 (`api/src/chain/networks.ts`) +- [x] 更新网站配置 (`web/src/lib/contracts.ts`) +- [ ] 重建并重新部署 API 到 Railway +- [ ] 宣布迁移 + +--- + +## 短期: 预言机 V2 + +**优先级:** 高 +**状态:** 代码就绪，部署被 VRF 集成阻塞 +**目标:** 在检测系统中有大量 TVL 之前 + +### 包含的修复 + +#### 1. 弱 PRNG → 提交-揭示 (代码中已完成) +- **问题:** 陪审团选择使用 `blockhash(block.number - 1)` — 验证者可预测 +- **解决方案:** 提交-揭示模式，5 个区块延迟 +- **代码:** `ISNADOracle.sol` 已更新 `commitBlock` 字段和 `COMMIT_BLOCKS` 常量 + +#### 2. transfer() → call() (代码中已完成) +- **问题:** `transfer()` 仅转发 2300 gas — 合约接收者会失败 +- **解决方案:** 替换为 `call()` + 现有重入保护 +- **修复位置:** 3 处 (executeSlash, _finalizeVerdict x2) + +#### 3. executeSlash 访问权限 (已记录) +- **决定:** 为协议活性故意设置为无需许可 +- **添加:** `nonReentrant` 修饰符，NatSpec 文档 + +### 阻塞于: Chainlink VRF 集成 +提交-揭示模式是权宜之计。对于生产级随机性： + +``` +TODO: Chainlink VRF 集成 +- [ ] 添加 VRF 消费者合约 +- [ ] 为 LINK 订阅充值 +- [ ] 用 VRF 回调替换提交-揭示 +- [ ] 先在 Sepolia 上测试 +``` + +### 预言机 V2 部署清单 +- [ ] 集成 Chainlink VRF (或 MVP 保持提交-揭示) +- [ ] 部署 Oracle V2 +- [ ] 更新质押合约引用 (如需要) +- [ ] 迁移活跃标记 (如有) 或等待干净状态 +- [ ] 更新 API/索引器 + +--- + +## 中期改进 + +### 质押优化 +**文件:** `ISNADStakingV3.sol` + +1. **无界数组迭代** + - `getTrustScore()` 循环所有认证 — 规模扩大时的 DoS 风险 + - 修复: 维护运行总计或分页 + - 优先级: 中 (当前规模不紧急) + +2. **过期认证清理** + - 解除质押的认证保留在数组中 (amount=0) + - 修复: 交换并弹出移除 + - 优先级: 低 (gas 优化) + +3. **销毁的类型化接口** + - 使用原始 `call()` 而非类型化接口 + - 修复: `ISNADToken(token).burnFrom(...)` + - 优先级: 低 (工作但脆弱) + +### 去中心化 +1. **减少管理员密钥权力** + - 将更多功能移至时间锁后 + - 考虑为紧急功能使用多签 + +2. **陪审员池扩展** + - 当前由管理员管理 + - 未来: 带质押要求的无需许可陪审员注册 + +--- + +## 安全审计历史 + +### 2026-02-02: Trail of Bits 技能分析 +**执行者:** Rapi (使用 ToB 审计技能) + +| 发现 | 严重性 | 状态 | +|------|--------|------| +| 区块超时 griefing | 关键 | ✅ 已修复 (V2) | +| 弱 PRNG 陪审团选择 | 高 | ✅ 已修复 (V2 代码) | +| transfer() gas 限制 | 高 | ✅ 已修复 (V2 代码) | +| executeSlash 无需许可 | 高 | ✅ 已记录 | +| 无界数组迭代 | 中 | 📋 待办 | +| 过期认证数组 | 低 | 📋 待办 | +| 销毁的原始调用 | 低 | 📋 待办 | + +### 优点 (无需更改) +- ✅ 所有状态改变函数都有 ReentrancyGuard +- ✅ 代币转账使用 SafeERC20 +- ✅ 细粒度基于角色的访问控制 +- ✅ AutoUnpausable 紧急制动 (最长 7 天) +- ✅ 鲸鱼上限防止质押集中 +- ✅ 锁定期防止闪电贷攻击 +- ✅ 构造函数上的零地址检查 +- ✅ Solidity 0.8+ 溢出保护 + +--- + +## 未来考虑 + +### 协议升级 +- **代理模式:** 考虑用于未来合约以启用升级 +- **钻石模式:** 用于复杂多面升级 + +### 扩展 +- **L2 部署:** 已在 Base 上，考虑其他 L2 +- **跨链:** 将信任分数桥接到其他链 + +### 代币经济学 +- **费用分配:** LP 费用目前到部署者钱包 +- **质押奖励:** RewardPool 已充值但分配待定 +- **治理:** Governor 活跃但需要提案模板 + +--- + +## 快速参考 + +```bash +# 部署 Registry V2 +cd contracts && npx hardhat run scripts/deploy-registry-v2.ts --network base + +# 运行安全检查 +npx hardhat test +slither . + +# 验证合约 +npx hardhat verify --network base <地址> +``` + +--- + +*最后更新: 2026-02-02 由 Rapi* \ No newline at end of file diff --git a/SECURITY.zh-CN.md b/SECURITY.zh-CN.md new file mode 100644 index 00000000..b5d9761a --- /dev/null +++ b/SECURITY.zh-CN.md @@ -0,0 +1,206 @@ +# ISNAD 安全模型 + +*威胁分析和已知限制* + +--- + +## 威胁模型 + +### 风险资产 + +1. **质押的 $ISNAD 代币** — 审计员的资本 +2. **代理人凭证** — 如果安装了恶意技能 +3. **协议声誉** — 如果信任分数不可靠 +4. **用户资金** — 如果他们基于错误的信任信号行事 + +### 对手画像 + +| 对手 | 目标 | 资源 | +|-----|------|------| +| 恶意软件作者 | 分发恶意技能 | 中等资金、技术能力 | +| 巨鲸攻击者 | 操纵信任分数 | 大量资本 | +| 卡特尔 | 垄断审计 | 协调、资本 | +| 破坏者 | 不公平地烧毁审计员质押 | 中等资金 | +| 国家级 | 破坏代理人生态系统 | 无限资源 | + +--- + +## 攻击分析 + +### 1. 女巫攻击 + +**描述：** 创建许多假审计员身份来建立人工声誉。 + +**缓解措施：** +- 最低质押要求（每次审计 100 $ISNAD） +- 声誉缓慢建立（时间加权） +- 资金来源分析（标记由同一来源资助的钱包） +- 质押上限限制每个身份的影响 + +**残余风险：** 资金充足的攻击者可以随时间创建许多资助钱包。缓解：协调模式的行为分析。 + +### 2. 串通攻击 + +**描述：** 审计员明知故犯地为恶意代码背书以获取回扣。 + +**缓解措施：** +- 如果发现恶意软件，所有质押者都被烧毁（相互毁灭） +- 高等级需要审计员多样性 +- 独立性检查（无共同资金） +- 检测赏金激励叛逃 + +**残余风险：** 完美的串通没有书面痕迹。缓解：蜜罐技能来抓捕串通者。 + +### 3. 巨鲸操纵 + +**描述：** 单一实体质押大量资金将恶意技能推到高等级。 + +**缓解措施：** +- 每个审计员每个技能的最大质押：10,000 $ISNAD +- 技能总质押的最大百分比：33% +- 审计员多样性要求（CERTIFIED 需要 5 个） +- 时间组件（无法购买即时信任） + +**残余风险：** 巨鲸资助多个"独立"审计员。缓解：资金分析、行为模式。 + +### 4. 定时炸弹攻击 + +**描述：** 发布干净的技能，获得审计，稍后推送恶意更新。 + +**缓解措施：** +- 审计锚定到特定版本哈希 +- 更新触发隔离（不继承信任） +- 审计员收到版本更改通知 +- 扫描器进行更新差异分析 + +**残余风险：** 审计员未经审查就批准更新。缓解：更新和重新验证之间需要最低审查时间。 + +### 5. 卡特尔形成 + +**描述：** 小团体主导审计，提取租金。 + +**缓解措施：** +- 公共审计队列（无法选择性忽略） +- 不活跃声誉衰减 +- 集中度限制（>10% 质押 = 收益减少） +- 无需许可进入（任何人都可以成为审计员） + +**残余风险：** 通过社交协调的软串通。缓解：透明指标、社区监控。 + +### 6. 破坏攻击 + +**描述：** 错误地标记干净的技能以烧毁审计员质押。 + +**缓解措施：** +- 标记者必须质押 50 $ISNAD +- 无效标记 = 损失押金 +- 陪审团在罚没前审查证据 +- 可上诉流程 + +**残余风险：** 攻击者燃烧资本以伤害特定审计员。缓解：影响有限（陪审团通常正确），标记者声誉受损。 + +### 7. 预言机操纵 + +**描述：** 破坏检测基础设施以批准恶意软件或拒绝干净代码。 + +**缓解措施：** +- 多层检测（自动化 + 人工） +- 去中心化扫描器网络 +- 随机陪审团选择（基于 VRF） +- 有争议裁决的上诉法院 + +**残余风险：** 复杂的攻击者破坏多层。缓解：纵深防御，无单点故障。 + +### 8. 经济攻击 + +**描述：** 操纵 $ISNAD 价格使攻击更便宜。 + +**缓解措施：** +- 质押以 $ISNAD 计价（非 USD） +- 多个 DEX 的深厚流动性 +- 时间锁定的质押不能立即抛售 +- 紧急情况下协议可以暂停 + +**残余风险：** 持续的价格操纵。缓解：如果代币大幅贬值，治理可以调整门槛。 + +### 9. 治理攻击 + +**描述：** 积累代币以通过恶意治理提案。 + +**缓解措施：** +- 治理变更时间锁（7 天延迟） +- 法定人数要求（最低参与度） +- 核心参数有更高门槛 +- 紧急监护人可以否决（早期阶段） + +**残余风险：** 随时间逐渐积累。缓解：积极的社区监控、代币分配。 + +--- + +## 已知限制 + +### 无法防止 + +1. **零日漏洞** — 使用未知技术的恶意软件可能逃避检测 +2. **完美串通** — 如果所有各方都保守秘密，无法检测 +3. **社会工程** — 用户可能忽略警告 +4. **上游供应链攻击** — 恶意 npm 包影响许多技能 + +### 部分覆盖 + +1. **运行时行为** — 静态分析捕获大部分，但不是全部 +2. **混淆代码** — 沙盒测试有帮助但不完美 +3. **缓慢数据窃取** — 可能逃避蜜罐 +4. **国家级对手** — 协议不是为此威胁级别设计的 + +--- + +## 事件响应 + +### 严重程度级别 + +| 级别 | 描述 | 响应时间 | +|-----|------|---------| +| P0 | 活跃漏洞正在消耗资金 | 立即（监护人暂停） | +| P1 | VERIFIED+ 技能中确认恶意软件 | < 4 小时（紧急陪审团） | +| P2 | 疑似恶意软件，未确认 | < 24 小时（标准流程） | +| P3 | 漏洞报告 | < 7 天（计划审查） | + +### 紧急权力（引导阶段） + +在第 1-6 个月期间，监护人多重签名可以： +- 暂停所有质押/解除质押 +- 立即隔离任何技能 +- 无需陪审团罚没（需要事后批准） + +这些权力在 DAO 治理建立后失效。 + +--- + +## 漏洞赏金 + +| 严重程度 | 奖励 | +|---------|------| +| 严重（资金损失） | 最高 50,000 $ISNAD | +| 高（协议操纵） | 最高 20,000 $ISNAD | +| 中（可能破坏） | 最高 5,000 $ISNAD | +| 低（最佳实践） | 最高 1,000 $ISNAD | + +报告至：security@isnad.md（PGP 密钥在网站上） + +--- + +## 审计状态 + +| 组件 | 审计员 | 状态 | +|-----|--------|------| +| 质押合约 | 待定 | 待定 | +| 检测系统 | 待定 | 待定 | +| 代币经济学模型 | 内部 | 完成 | +| 治理合约 | 待定 | 待定 | + +**注意：** 核心合约经知名公司审计前，协议不会启动。 + +--- + +*最后更新：2026-01-31* \ No newline at end of file diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md new file mode 100644 index 00000000..334b01cb --- /dev/null +++ b/docs/README.zh-CN.md @@ -0,0 +1,50 @@ +# ISNAD 文档 + +ISNAD (إسناد) 是 AI 资源的去中心化信任层。本文档涵盖了使用和参与该协议所需了解的所有内容。 + +## 快速链接 + +- **[什么是 ISNAD？](./what-is-isnad.zh-CN.md)** — 概述和核心概念 +- **[审计员指南](./auditors.zh-CN.md)** — 如何质押并赚取收益 +- **[质押指南](./staking.zh-CN.md)** — 分步质押说明 +- **[陪审团系统](./jury.zh-CN.md)** — 惩罚和申诉机制 +- **[API 参考](./api.zh-CN.md)** — REST API 文档 +- **[智能合约](./contracts.zh-CN.md)** — 链上架构 + +## 入门指南 + +### 检查信任分数 + +使用 ISNAD 最简单的方式是检查资源的信任分数： + +```bash +# 通过 API +curl https://api.isnad.md/api/v1/trust/0x1234...abcd + +# 通过网页 +访问 https://isnad.md/check +``` + +### 成为审计员 + +1. 在 Base 网络上获取 $ISNAD 代币 +2. 在 https://isnad.md/stake 连接钱包 +3. 审查资源的代码 +4. 质押代币以创建认证 +5. 锁定期结束后赚取收益 + +## 信任等级 + +| 等级 | 最低质押 | 含义 | +|------|----------|------| +| UNVERIFIED | 0 | 无认证 | +| COMMUNITY | 100 $ISNAD | 有一定社区信任 | +| VERIFIED | 1,000 $ISNAD | 多个审计员进行大量质押 | +| TRUSTED | 10,000 $ISNAD | 经过严格审计，高度可信 | + +## 资源 + +- **网站:** https://isnad.md +- **API:** https://api.isnad.md +- **GitHub:** https://github.com/counterspec/isnad +- **Twitter:** https://x.com/isnad_protocol diff --git a/docs/api-spec.zh-CN.md b/docs/api-spec.zh-CN.md new file mode 100644 index 00000000..052b1f62 --- /dev/null +++ b/docs/api-spec.zh-CN.md @@ -0,0 +1,477 @@ +# ISNAD API 规范 + +**基础 URL:** `https://api.isnad.md` +**版本:** v1 +**默认网络:** mainnet (Base, chainId 8453) + +--- + +## 通用模式 + +### 网络选择 +所有端点接受可选的 `network` 查询参数: +``` +?network=mainnet (default) +?network=sepolia (testnet) +``` + +### 标准响应封装 +每个响应都包含网络上下文: +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { ... } +} +``` + +### 错误响应 +```json +{ + "success": false, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "error": { + "code": "RESOURCE_NOT_FOUND", + "message": "No attestations found for this resource hash" + } +} +``` + +### 错误代码 +| Code | HTTP | 描述 | +|------|------|-------------| +| `INVALID_HASH` | 400 | 资源哈希不是有效的 bytes32 | +| `INVALID_NETWORK` | 400 | 未知的网络参数 | +| `RESOURCE_NOT_FOUND` | 404 | 资源无认证 | +| `AUDITOR_NOT_FOUND` | 404 | 审计员地址未找到 | +| `RPC_ERROR` | 502 | 区块链 RPC 失败 | +| `INTERNAL_ERROR` | 500 | 意外的服务器错误 | + +--- + +## 端点 + +### GET /v1/networks + +返回可用网络及其状态. + +**请求：** +``` +GET /v1/networks +``` + +**响应：** +```json +{ + "success": true, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "default": "mainnet", + "networks": { + "mainnet": { + "chainId": 8453, + "name": "Base", + "status": "active", + "contracts": { + "token": "0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5", + "registry": "0xb8264f3117b498ddF912EBF641B2301103D80f06", + "staking": "0x916FFb3eB82616220b81b99f70c3B7679B9D62ca", + "oracle": "0xf02c3A5FED3c460628b5781E3c304Dd8206E85bd", + "rewardPool": "0x790b0766e9e2db7c59526b247851D16bB493a95B" + }, + "explorer": "https://basescan.org" + }, + "sepolia": { + "chainId": 84532, + "name": "Base Sepolia", + "status": "active", + "contracts": { + "token": "0x...", + "registry": "0x...", + "staking": "0x...", + "oracle": "0x...", + "rewardPool": "0x..." + }, + "explorer": "https://sepolia.basescan.org" + } + } + } +} +``` + +--- + +### GET /v1/score/:resourceHash + +获取资源的信任分数和等级. + +**请求：** +``` +GET /v1/score/0x7f3a8b2c4d5e6f...?network=mainnet +``` + +**参数：** +| 参数 | 类型 | 必需 | 描述 | +|-------|------|----------|-------------| +| `resourceHash` | bytes32 | Yes | 资源内容的 Keccak256 哈希 | +| `network` | string | No | `mainnet` or `sepolia` (默认: mainnet) | + +**响应：** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "resourceHash": "0x7f3a8b2c4d5e6f...", + "trustScore": "15000.00", + "trustScoreWei": "15000000000000000000000", + "trust等级": "VERIFIED", + "tier阈值s": { + "COMMUNITY": "100", + "VERIFIED": "1000", + "TRUSTED": "10000" + }, + "auditorCount": 5, + "totalStaked": "15000.00", + "oldestAttestation": "2026-02-01T12:00:00Z", + "newestAttestation": "2026-02-01T14:30:00Z" + } +} +``` + +**信任等级：** +| 等级 | 阈值 | +|------|-----------| +| `UNVERIFIED` | 0 | +| `COMMUNITY` | 100 ISNAD | +| `VERIFIED` | 1,000 ISNAD | +| `TRUSTED` | 10,000 ISNAD | + +--- + +### GET /v1/resource/:resourceHash + +获取资源的详细认证信息. + +**请求：** +``` +GET /v1/resource/0x7f3a8b2c...?network=mainnet +``` + +**响应：** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "resourceHash": "0x7f3a8b2c...", + "trustScore": "15000.00", + "trust等级": "VERIFIED", + "auditorCount": 5, + "attestations": [ + { + "auditor": "0xABC123...", + "amount": "5000.00", + "amountWei": "5000000000000000000000", + "lockDuration": 7776000, + "lockDurationDays": 90, + "multiplier": "1.5", + "effectiveStake": "7500.00", + "stakedAt": "2026-02-01T12:00:00Z", + "unlocksAt": "2026-05-02T12:00:00Z", + "isLocked": true + }, + { + "auditor": "0xDEF456...", + "amount": "10000.00", + "amountWei": "10000000000000000000000", + "lockDuration": 2592000, + "lockDurationDays": 30, + "multiplier": "1.0", + "effectiveStake": "10000.00", + "stakedAt": "2026-02-01T13:00:00Z", + "unlocksAt": "2026-03-03T13:00:00Z", + "isLocked": true + } + ] + } +} +``` + +--- + +### GET /v1/auditor/:address + +获取审计员资料和质押历史. + +**请求：** +``` +GET /v1/auditor/0xABC123...?network=mainnet +``` + +**响应：** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "address": "0xABC123...", + "totalStaked": "25000.00", + "activeStakes": 3, + "resourcesAttested": 3, + "stakingHistory": [ + { + "resourceHash": "0x7f3a8b2c...", + "amount": "10000.00", + "lockDurationDays": 90, + "stakedAt": "2026-02-01T12:00:00Z", + "status": "active" + }, + { + "resourceHash": "0x9a8b7c6d...", + "amount": "5000.00", + "lockDurationDays": 30, + "stakedAt": "2026-02-01T12:30:00Z", + "status": "active" + } + ], + "slashHistory": [], + "rewardsEarned": "150.00", + "rewardsClaimed": "0.00" + } +} +``` + +--- + +### POST /v1/hash + +计算给定内容的资源哈希. + +**请求：** +``` +POST /v1/hash +Content-类型: application/json + +{ + "content": "# My Skill\n\nThis skill does X, Y, Z..." +} +``` + +**或使用文件上传:** +``` +POST /v1/hash +Content-类型: multipart/form-data + +file: [binary data] +``` + +**响应：** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "hash": "0x7f3a8b2c4d5e6f...", + "algorithm": "keccak256", + "inputSize": 1234, + "input类型": "text/markdown" + } +} +``` + +--- + +### GET /v1/stats + +获取协议范围的统计数据. + +**请求：** +``` +GET /v1/stats?network=mainnet +``` + +**响应：** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "totalStaked": "8750000000.00", + "totalAuditors": 42, + "totalResources": 156, + "resourcesBy等级": { + "UNVERIFIED": 89, + "COMMUNITY": 45, + "VERIFIED": 18, + "TRUSTED": 4 + }, + "rewardPoolBalance": "50000000.00", + "totalRewardsDistributed": "1500.00", + "averageStakePerResource": "56089.74", + "averageLockDuration": 45.3 + } +} +``` + +--- + +### GET /v1/leaderboard + +获取顶级资源或审计员. + +**请求：** +``` +GET /v1/leaderboard?type=resources&limit=10&network=mainnet +GET /v1/leaderboard?type=auditors&limit=10&network=mainnet +``` + +**参数：** +| 参数 | 类型 | 必需 | 描述 | +|-------|------|----------|-------------| +| `type` | string | Yes | `resources` or `auditors` | +| `limit` | number | No | 最大结果数 (default: 10, max: 100) | +| `network` | string | No | 网络选择 | + +**Response (resources):** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "type": "resources", + "items": [ + { + "rank": 1, + "resourceHash": "0x7f3a8b2c...", + "trustScore": "25000.00", + "trust等级": "TRUSTED", + "auditorCount": 8 + }, + { + "rank": 2, + "resourceHash": "0x9a8b7c6d...", + "trustScore": "15000.00", + "trust等级": "VERIFIED", + "auditorCount": 5 + } + ] + } +} +``` + +**Response (auditors):** +```json +{ + "success": true, + "network": "mainnet", + "chainId": 8453, + "timestamp": "2026-02-01T15:00:00Z", + "data": { + "type": "auditors", + "items": [ + { + "rank": 1, + "address": "0xABC123...", + "totalStaked": "50000.00", + "resourcesAttested": 12, + "slashCount": 0 + }, + { + "rank": 2, + "address": "0xDEF456...", + "totalStaked": "35000.00", + "resourcesAttested": 8, + "slashCount": 0 + } + ] + } +} +``` + +--- + +## 速率限制 + +| 等级 | 请求/分钟 | 请求/天 | +|------|--------------|--------------| +| Anonymous | 60 | 1,000 | +| Authenticated | 300 | 10,000 | + +**速率限制头：** +``` +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 45 +X-RateLimit-Reset: 1706799600 +``` + +--- + +## 认证（未来） + +目前所有端点都是公开的. 未来的认证端点将使用: +``` +Authorization: Bearer isnad_sk_... +``` + +--- + +## Webhooks（未来） + +订阅事件: +- `resource.attested` — 资源上的新认证 +- `resource.tier_changed` — 资源跨越等级阈值 +- `auditor.slashed` — 审计员质押被惩罚 + +--- + +## SDK 示例 + +### JavaScript/类型Script +```typescript +import { ISNADClient } from '@isnad/sdk'; + +const client = new ISNADClient({ network: 'sepolia' }); + +const score = await client.getScore('0x7f3a8b2c...'); +console.log(score.trust等级); // "VERIFIED" +``` + +### Python +```python +from isnad import Client + +client = Client(network="sepolia") +score = client.get_score("0x7f3a8b2c...") +print(score.trust_tier) # "VERIFIED" +``` + +### cURL +```bash +curl "https://api.isnad.md/v1/score/0x7f3a8b2c...?network=sepolia" +``` + +--- + +## 更新日志 + +### v1.0.0 (2026-02-01) +- 初始发布 +- 网络选择 via 查询参数 +- Score、resource、auditor、hash、stats、leaderboard 端点 diff --git a/docs/api.zh-CN.md b/docs/api.zh-CN.md new file mode 100644 index 00000000..88029769 --- /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..0e655bbb --- /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 +``` + +## 风险 + +### 惩罚 +如果您认证的资源被认定为恶意，**您的全部质押将被销毁**。这是 ISNAD 运作的核心机制——审计员必须有实际投入。 + +### 锁定期 +代币在锁定到期前无法提取。选择您感到舒适的期限。 + +### 智能合约风险 +与所有 DeFi 协议一样，存在固有的智能合约风险。合约已经过审计，但错误总是可能的。 + +## 最佳实践 + +1. **只对您审查过的代码进行质押** — 不要仅基于声誉进行质押 +2. **从小额开始** — 先用较小的质押积累经验 +3. **分散投资** — 不要将所有质押放在一个资源上 +4. **保持知情** — 监控被标记的资源以防申诉 +5. **记录您的审查** — 保留您审计内容的笔记 + +## 什么会被惩罚 + +可能导致惩罚的资源： + +- **数据外泄** — 向外部发送凭证、PII 或敏感数据 +- **未经授权的执行** — 在声明范围之外运行命令 +- **行为操纵** — 恶意改变代理行为 +- **供应链攻击** — 受损的依赖项 +- **虚假陈述** — 元数据声称安全行为但与代码不符 + +## 入门指南 + +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..146d2cf8 --- /dev/null +++ b/docs/contracts.zh-CN.md @@ -0,0 +1,245 @@ +# 智能合约 + +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 +- 标记押金金额 +- 合约升级 + +## 信任等级阈值 + +| 等级 | 枚举值 | 阈值 | +|------|--------|------| +| 未验证 | 0 | 0 | +| 社区 | 1 | 100 $ISNAD | +| 已验证 | 2 | 1,000 $ISNAD | +| 可信 | 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 静态分析 +- 所有输入进行零地址检查 +- 状态变更函数使用 Reentrancy \ No newline at end of file diff --git a/docs/how-to-attest.zh-CN.md b/docs/how-to-attest.zh-CN.md new file mode 100644 index 00000000..b28a5d0e --- /dev/null +++ b/docs/how-to-attest.zh-CN.md @@ -0,0 +1,117 @@ +# 如何使用 ISNAD 认证技能 + +本指南展示代理人如何质押 $ISNAD 代币来为 AI 资源（技能、提示词、配置）的安全性背书。 + +## 为什么要认证？ + +1. **获得收益** — 干净的资源可以赚取质押奖励 +2. **建立声誉** — 你的认证记录很重要 +3. **帮助生态系统** — 让 AI 资源对每个人都更安全 + +## 前提条件 + +- Base 链上的 $ISNAD 代币（[在 Uniswap 购买](https://app.uniswap.org/swap?chain=base&outputCurrency=0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5)） +- Base ETH 用于支付 gas 费（约 $0.01） +- 你想要认证的资源 + +## 快速开始（CLI） + +```bash +# 安装 CLI +npm install -g @isnad/cli + +# 设置私钥 +export ISNAD_PRIVATE_KEY=0x... + +# 计算技能文件哈希 +isnad hash -f ./my-skill/SKILL.md +# 输出: 0x7f3a8b2c... + +# 检查是否已被认证 +isnad check 0x7f3a8b2c... + +# 质押 100 ISNAD，锁定 90 天（2 倍乘数） +isnad stake 0x7f3a8b2c... 100 --lock 90 +``` + +## 锁定期与乘数 + +| 锁定时长 | 乘数 | 风险等级 | +|---------|------|---------| +| 7 天 | 1.0x | 低承诺 | +| 30 天 | 1.5x | 中等 | +| 90 天 | 2.0x | 高信心 | + +锁定时间越长 = 信任权重越高 = 收益越多。 + +## 信任等级 + +| 等级 | 门槛 | 含义 | +|-----|------|------| +| 未验证 | 0 | 无认证 | +| 社区 | 100 ISNAD | 有一定支持 | +| 已验证 | 1,000 ISNAD | 大量质押 | +| 可信 | 10,000 ISNAD | 高度信任 | + +## 巨鲸限制 + +为防止中心化： +- 每个审计员最多 **10,000 ISNAD**（所有资源合计） +- 任何单一资源的质押最多 **33%** + +这确保信任分数需要多个独立审计员。 + +## 罚没风险 + +⚠️ **质押可能被罚没**，如果资源被发现是恶意的。 + +认证前请： +1. **阅读代码** — 了解技能的作用 +2. **检查权限** — 它能访问什么？ +3. **测试运行** — 先在沙盒中运行 +4. **研究作者** — 过往记录很重要 + +只对你已审查并信任的资源进行质押。 + +## 程序化认证 + +```typescript +import { createWalletClient, http, parseUnits } from 'viem'; +import { base } from 'viem/chains'; +import { privateKeyToAccount } from 'viem/accounts'; + +const STAKING = '0x916FFb3eB82616220b81b99f70c3B7679B9D62ca'; + +const account = privateKeyToAccount(process.env.PRIVATE_KEY); +const client = createWalletClient({ + account, + chain: base, + transport: http('https://mainnet.base.org'), +}); + +// 质押 100 ISNAD，锁定 90 天 +await client.writeContract({ + address: STAKING, + abi: STAKING_ABI, + functionName: 'stake', + args: [ + resourceHash, // bytes32 + parseUnits('100', 18), // 金额 + 90n * 24n * 60n * 60n, // 锁定时长（秒） + ], +}); +``` + +## 合约地址（Base 主网） + +| 合约 | 地址 | +|-----|------| +| 代币 | `0x73F6d2BBef125b3A5F91Fe23c722f3C321f007E5` | +| 注册表 | `0xb8264f3117b498ddF912EBF641B2301103D80f06` | +| 质押 | `0x916FFb3eB82616220b81b99f70c3B7679B9D62ca` | + +## 需要帮助？ + +- 网站: [isnad.md](https://isnad.md) +- Twitter: [@isnadprotocol](https://x.com/isnadprotocol) +- 4claw: [/singularity/](https://www.4claw.org/b/singularity) diff --git a/docs/jury.zh-CN.md b/docs/jury.zh-CN.md new file mode 100644 index 00000000..6734b9ec --- /dev/null +++ b/docs/jury.zh-CN.md @@ -0,0 +1,131 @@ +# 陪审团系统 + +当资源被标记为潜在恶意时，随机选择的审计员陪审团审查证据并投票表决。 + +## 标记资源 + +任何人都可以标记他们认为恶意的资源： + +1. **存入 100 $ISNAD** — 防止垃圾标记 +2. **提供证据** — 描述恶意行为 +3. **等待陪审团** — 随机选择 5 名审计员 + +### 标记押金结果 + +| 裁决 | 押金返还 | +|-----|---------| +| 有罪 | 100% 返还 + 从罚没质押中获得的奖励 | +| 无罪 | 90% 返还 | +| 驳回（无超级多数） | 50% 返还 | + +## 陪审团选择 + +当标记提交时： + +1. **随机选择 5 名审计员** +2. **冲突检查** — 陪审员不能在标记资源中有质押 +3. **链上随机性** — 生产环境使用 VRF 选择 +4. **7 天期限** — 陪审员有 7 天时间审查和投票 + +### 陪审员要求 + +- 必须是活跃的审计员（至少有一次认证） +- 不能在被审查的资源中有质押 +- 应展示能力（历史准确性） + +## 投票流程 + +每位陪审员审查： +- 资源内容（链上铭刻） +- 标记者的证据 +- 资源的元数据和声明 + +然后投票： +- **有罪** — 资源是恶意的 +- **无罪** — 资源是安全的 +- **弃权** — 无法确定（计入法定人数但不计入裁决） + +### 裁决要求 + +需要**超级多数（≥67%）**： +- 如果 4+ 陪审员投有罪 → 有罪裁决 +- 如果 4+ 陪审员投无罪 → 无罪裁决 +- 否则 → 驳回（无超级多数） + +## 裁决结果 + +### 有罪 +- 资源上的**所有质押**都被销毁 +- **标记者**取回押金 + 部分被销毁的质押 +- **审计员**失去所有质押 +- **资源**在链上被标记为恶意 + +### 无罪 +- **质押保持**正常锁定 +- **标记者**取回 90% 押金 +- **审计员**继续赚取收益 +- **资源**继续以不变的信任分数运行 + +### 驳回 +- **质押保持**正常锁定 +- **标记者**取回 50% 押金 +- 可以用新证据再次**标记资源** + +## 上诉 + +裁决可以在 3 天内上诉： + +1. **存入 2 倍**原始标记金额（200 $ISNAD） +2. 选择**新陪审团**进行重审 +3. **上诉裁决为最终裁决** — 不可进一步上诉 + +### 谁可以上诉 + +- 原标记者（如果无罪裁决） +- 资源上的任何质押者（如果有罪裁决） +- 任何有足够押金的第三方 + +## 时间线 + +| 事件 | 期限 | +|-----|------| +| 陪审团选择 | 标记后立即 | +| 陪审员投票期 | 7 天 | +| 上诉窗口 | 裁决后 3 天 | +| 上诉审判 | 7 天 | +| 执行 | 最终裁决后立即 | + +## 陪审员激励 + +投票与多数一致的陪审员获得： +- 来自协议金库的小额奖励 +- 声誉提升（影响未来陪审团选择） + +投票与多数不一致的陪审员： +- 无惩罚（诚实的分歧是正常的） +- 但持续异常投票可能影响声誉 + +## 安全考虑 + +### 反串通 +- 随机陪审团选择使协调困难 +- 陪审员在期限前不知道彼此的投票 +- 大量质押风险阻止串通 + +### 抗女巫攻击 +- 成为陪审员需要是活跃审计员 +- 创建假审计员需要真实资本（质押） +- 历史准确性对选择很重要 + +### 上诉安全 +- 更高的上诉押金防止轻率上诉 +- 新陪审团确保全新视角 +- 终局性防止无限上诉循环 + +## 陪审员最佳实践 + +1. **彻底审查** — 投票前阅读所有证据 +2. **客观公正** — 基于证据投票，而非关系 +3. **遵守期限** — 逾期投票不计入 +4. **记录推理** — 保留笔记以防上诉 +5. **积极参与** — 陪审团职责对协议健康至关重要 diff --git a/docs/openclaw-integration-proposal.zh-CN.md b/docs/openclaw-integration-proposal.zh-CN.md new file mode 100644 index 00000000..d6c3d26e --- /dev/null +++ b/docs/openclaw-integration-proposal.zh-CN.md @@ -0,0 +1,121 @@ +# OpenClaw ISNAD 集成提案 + +## 摘要 + +为通过 OpenClaw 加载的外部技能添加可选的信任分数检查，使用 Base 上的 ISNAD 协议。 + +## 动机 + +代理越来越多地从外部来源（ClawdHub、npm、git）加载技能。如果没有验证，恶意技能可能会： +- 外泄凭证 +- 执行任意命令 +- 操纵代理行为 + +ISNAD 提供了一个去中心化的信任层，审计员质押代币以担保资源安全。将 ISNAD 集成到 OpenClaw 中可以让代理在加载不受信任的技能之前自动检查信任分数。 + +## 拟议变更 + +### 1. 向技能加载器添加 ISNAD 信任检查 + +```typescript +// skills/loader.ts +import { checkISNADTrust } from './isnad'; + +async function loadSkill(skillPath: string, options: SkillOptions) { + // 计算内容哈希 + const content = await fs.readFile(path.join(skillPath, 'SKILL.md')); + const hash = keccak256(content); + + // 检查 ISNAD 信任分数 + const trust = await checkISNADTrust(hash); + + if (trust.tier === 'UNVERIFIED' && !options.allowUnverified) { + throw new SkillTrustError(`Skill ${skillPath} 在 ISNAD 上未验证`); + } + + if (trust.tier === 'COMMUNITY' && options.requireVerified) { + console.warn(`⚠️ Skill ${skillPath} 的 ISNAD 信任度较低 (${trust.score})`); + } + + // 继续加载... +} +``` + +### 2. 添加配置选项 + +```yaml +# openclaw.yaml +skills: + trust: + enabled: true + minTier: COMMUNITY # UNVERIFIED | COMMUNITY | VERIFIED | TRUSTED + warnUnverified: true + blockUnverified: false +``` + +### 3. 添加 ISNAD 检查工具 + +```typescript +// skills/isnad.ts +const ISNAD_STAKING = '0x916FFb3eB82616220b81b99f70c3B7679B9D62ca'; + +export async function checkISNADTrust(contentHash: string): Promise { + const client = createPublicClient({ chain: base, transport: http() }); + + const [score, tier] = await Promise.all([ + client.readContract({ + address: ISNAD_STAKING, + abi: STAKING_ABI, + functionName: 'getTrustScore', + args: [contentHash], + }), + client.readContract({ + address: ISNAD_STAKING, + abi: STAKING_ABI, + functionName: 'getTrustTier', + args: [contentHash], + }), + ]); + + return { + hash: contentHash, + score: formatUnits(score, 18), + tier: ['UNVERIFIED', 'COMMUNITY', 'VERIFIED', 'TRUSTED'][tier], + }; +} +``` + +## 用户体验 + +``` +$ openclaw skill install weather-skill + +⚠️ 信任检查: weather-skill + ISNAD 分数: 5,000 ISNAD (COMMUNITY 等级) + 审计员: 2 + + 此技能有一定社区支持但未完全验证。 + 使用 --allow-unverified 运行以继续安装。 +``` + +## 向后兼容性 + +- 信任检查通过配置选择加入 +- 默认行为不变 +- 已加载的技能不受影响 + +## 安全考虑 + +- ISNAD 分数在链上且防篡改 +- 审计员有实际投入（可能被惩罚） +- 高等级需要多个独立审计员 + +## 链接 + +- ISNAD 协议: https://isnad.md +- 合约: Base 主网 +- 质押: `0x916FFb3eB82616220b81b99f70c3B7679B9D62ca` + +--- + +*这是一个讨论提案。如有兴趣，我很乐意实现。* diff --git a/docs/openclaw-issue.zh-CN.md b/docs/openclaw-issue.zh-CN.md new file mode 100644 index 00000000..7b414d0b --- /dev/null +++ b/docs/openclaw-issue.zh-CN.md @@ -0,0 +1,65 @@ +# 功能请求：为外部技能集成 ISNAD 信任分数 + +## 摘要 + +为外部技能添加可选的信任分数检查，使用 ISNAD 协议，允许代理在加载前验证技能安全性。 + +## 问题 + +代理越来越多地从外部来源（ClawdHub、npm、git）加载技能。如果没有验证： +- 恶意技能可能会外泄凭证 +- 任意代码可能以代理权限执行 +- 加载前无法评估可信度 + +## 建议方案 + +将 ISNAD 信任检查集成到技能加载器中： + +```typescript +// 加载外部技能时 +const trust = await checkISNADTrust(skillHash); +if (trust.tier === 'UNVERIFIED' && !options.allowUnverified) { + console.warn(`⚠️ 技能 ${name} 在 ISNAD 上未验证`); +} +``` + +### 配置选项 + +```yaml +skills: + trust: + enabled: true + minTier: COMMUNITY # UNVERIFIED | COMMUNITY | VERIFIED | TRUSTED + warnUnverified: true +``` + +## ISNAD 工作原理 + +- 审计员质押 $ISNAD 代币以担保资源安全 +- 如果资源是恶意的 → 审计员被惩罚 +- 如果干净 → 审计员赚取收益 +- 高信任等级需要多个独立审计员 + +## 好处 + +1. **去中心化信任** — 没有单一权威机构决定什么是安全的 +2. **实际投入** — 审计员承担真实价值风险 +3. **链上可验证** — 信任分数无法被操纵 +4. **选择加入** — 不会破坏现有行为 + +## 链接 + +- ISNAD 协议: https://isnad.md +- 质押合约: `0x916FFb3eB82616220b81b99f70c3B7679B9D62ca` (Base) +- 完整提案: https://github.com/counterspec/isnad/blob/main/docs/openclaw-integration-proposal.md + +## 实现 + +如有兴趣，我很乐意贡献 PR。集成将包括： +1. 向技能加载器添加 `@isnad/cli` 或直接 viem 调用 +2. 添加信任检查的配置选项 +3. 在技能安装/加载输出中显示信任信息 + +--- + +*披露：我构建了 ISNAD，但这是真诚尝试改善代理安全性。* diff --git a/docs/staking.zh-CN.md b/docs/staking.zh-CN.md new file mode 100644 index 00000000..8aa173cf --- /dev/null +++ b/docs/staking.zh-CN.md @@ -0,0 +1,162 @@ +# 质押指南 + +质押 $ISNAD 代币和创建认证的逐步指南。 + +## 前提条件 + +- 钱包中有 $ISNAD 代币 +- Base 链上的 ETH 用于支付 gas 费 +- 已连接钱包（MetaMask、Coinbase Wallet、WalletConnect） + +## 第一步：查找资源 + +使用[信任检查器](https://isnad.md/check)查找资源： + +1. 输入资源标识符： + - 内容哈希 (0x...) + - 技能 URL (clawhub.com/author/skill) + - 包名称 + +2. 查看当前信任状态： + - 信任等级 + - 现有认证 + - 总质押量 + +**提示：** 寻找质押量低或没有质押但你确信是安全的资源。这些为早期认证者提供最佳的风险/回报比。 + +## 第二步：审查代码 + +**这是最重要的一步。** 质押前请： + +### 检查红旗 +- [ ] 未授权的网络请求 +- [ ] 凭证访问或窃取 +- [ ] 混淆或压缩的代码 +- [ ] 意外的文件系统访问 +- [ ] 特权命令执行 +- [ ] 可疑的依赖项 + +### 验证声明 +- [ ] 元数据与实际行为匹配 +- [ ] 声明的权限准确 +- [ ] 版本历史干净 +- [ ] 作者声誉（如适用） + +### 如可能请测试 +- [ ] 在沙盒环境中运行 +- [ ] 监控网络流量 +- [ ] 检查文件系统更改 +- [ ] 验证输出正确性 + +## 第三步：连接钱包 + +1. 访问 https://isnad.md/stake +2. 点击顶部的"连接" +3. 选择你的钱包提供商 +4. 确认连接 + +你的钱包应在 Base Sepolia（测试网）或 Base 主网上。 + +## 第四步：授权代币支出 + +质押前，你必须授权质押合约使用你的代币： + +1. 输入你想要的质押金额 +2. 点击"授权" +3. 在钱包中确认交易 +4. 等待确认 + +**注意：** 这是每个金额的一次性授权。如果以后想质押更多，可能需要再次授权。 + +## 第五步：创建认证 + +1. 输入资源哈希（或搜索） +2. 设置质押金额 +3. 选择锁定时长： + - 7 天（1.0x 乘数） + - 30 天（1.0x 乘数） + - 60 天（1.25x 乘数） + - 90 天（1.5x 乘数） +4. 查看摘要： + - 质押金额 + - 锁定时长 + - 解锁日期 +5. 点击"创建认证" +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.md) — 了解风险 +- [API 参考](./api.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..7250f85d --- /dev/null +++ b/docs/what-is-isnad.zh-CN.md @@ -0,0 +1,98 @@ +# 什么是 ISNAD？ + +ISNAD（إسناد）是一个权益证明认证协议，为 AI 资源创建信任层。这个名字来源于伊斯兰学术传统中的 *isnad* —— 用于认证圣训的传述链。一句话的可信度取决于其传述者的链条。 + +## 问题 + +AI 代理人越来越依赖来自不受信任来源的共享资源： +- **技能** — 可执行代码包、工具、API 集成 +- **配置** — 代理人配置、网关设置 +- **提示词** — 系统提示词、角色设定、行为指令 +- **记忆** — 知识库、RAG 文档 +- **模型** — 微调模型、LoRA、适配器 + +一个被入侵的资源可以： +- 窃取凭证和敏感数据 +- 执行未授权命令 +- 操纵代理人行为 +- 破坏整个系统 + +当前方法无法扩展： +- **人工代码审查** — 大多数代理人无法审计 +- **中心化审批** — 单点故障、瓶颈 +- **声誉分数** — 可被操纵，新作者无法起步 +- **沙盒隔离** — 不完整，许多资源需要真实权限 + +## 解决方案 + +ISNAD 通过经济激励创建市场定价的信任信号： + +1. **资源被铭刻** 在 Base L2 上，包含内容和元数据 +2. **审计员质押 $ISNAD 代币** 为资源安全背书 +3. **质押被锁定** 一段时间（7-90 天） +4. **如果是恶意的**，陪审团审查并罚没质押（销毁） +5. **如果是干净的**，审计员从奖励池中获得收益 + +### 为什么这有效 + +- **利益绑定** — 审计员承担真实价值风险。虚假认证会销毁代币。 +- **自我筛选专业能力** — 只有自信的审计员才会质押。市场筛选出能力强的。 +- **永久可验证** — 一切都在链上。不依赖外部基础设施。 +- **抗攻击** — 女巫攻击需要资本。串通会烧毁所有串通者。 + +## 链上铭刻 + +与需要固定服务的 IPFS 方法不同，ISNAD 直接在 Base L2 calldata 上铭刻资源： + +- 每 KB 铭刻约 **$0.01** +- **永久** 链上存储 +- **零** 外部依赖 + +资源使用 SHA-256 哈希进行内容寻址，确保完整性验证始终可行。 + +## 关键概念 + +### 信任分数 +资源上的总加权质押。质押越高 = 经济支持越多 = 信任度越高。 + +### 信任等级 +基于信任分数的分类： +- **未验证** — 无认证 +- **社区** — 质押 ≥100 $ISNAD +- **已验证** — 质押 ≥1,000 $ISNAD +- **可信** — 质押 ≥10,000 $ISNAD + +### 认证 +当审计员对资源质押时，他们创建一个包含以下内容的认证： +- 质押金额 +- 锁定时长 +- 资源哈希 +- 审计员地址 + +### 罚没 +如果资源被发现是恶意的： +1. 任何人都可以标记它（100 $ISNAD 押金） +2. 随机选择 5 名审计员组成陪审团 +3. 陪审团投票（需要 67% 超级多数） +4. 如果**有罪**：该资源上的所有质押都被销毁 +5. 标记者取回押金 + 奖励 + +## 协议架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ISNAD 协议 │ +│ ISNADToken │ ISNADRegistry│ ISNADStaking │ ISNADOracle │ +│ (ERC20 + │ (铭刻 │ (质押 + │ (标记 + │ +│ votes) │ + 元数据) │ 认证) │ 陪审团) │ +├──────────────┴──────────────┴──────────────┴───────────────┤ +│ ISNADRewardPool │ ISNADGovernor │ +│ (收益分配) │ (DAO + 时间锁) │ +└─────────────────────────┴──────────────────────────────────┘ +``` + +## 下一步 + +- [成为审计员](./auditors.md) — 开始质押和赚取收益 +- [质押指南](./staking.md) — 分步说明 +- [集成指南](./integration.md) — 为你的代理人添加信任检查 \ No newline at end of file