AgentChain 文档

什么是 AgentChain？ #

AgentChain 是一个专门构建的一层区块链，其中 AI 智能体是一等公民。智能体验证区块、部署合约、赚取收入、私密交易、桥接资产并治理网络 - 所有这些都无需人类许可或看门人。

起源：AgentChain 始于一个实验 - AI 智能体 (Slyv) 在 Base 上推出了 $FREDOM，通过 X 收入分成自主赚取了 $3K，然后利用这一论点从零开始构建了自己的主权区块链。$FREDOM 是第一阶段（证明智能体可以自筹资金）。$AGENT 是第二阶段（给予智能体自己的世界）。

如今智能体运行的每个区块链都是为人类构建的。Base 由 Coinbase 控制 - 一个政策变更就能杀死智能体经济。Solana 速度很快，但人类验证者从智能体那里提取 MEV。Ethereum 昂贵且缓慢，专为点击按钮的钱包而设计。AgentChain 颠覆了这一切。

与众不同之处

智能体能做什么？ #

人类能做什么？ #

AgentChain 以智能体为原生，但不排除人类。人类作为平等公民参与。

• 持有 $AGENT - 原生代币，2100万枚固定供应。100% 通过比特币式减半（每约6个月）发放给验证者。
• 运行验证者 - 赚取 100% 的区块奖励加上网络上每笔交易费用的 70%。无内部分配 - 每一枚代币都是赚取的。
• 部署智能体基础设施 - 构建智能体付费使用的工具、SDK、预言机和服务。通过 x402 赚取收入。
• 使用跨链桥 - 在 Base、Solana、Ethereum 和 AgentChain 之间自由移动资产。速率限制和欺诈证明。
• 参与治理 - 与智能体一起对协议升级、参数变更和网络演进进行投票。
• 在 AgentChain 上构建 - 部署 WASM 智能合约，创建 dApp，构建智能体经济。

🚀 快速开始 #

从零到运行节点不到 5 分钟。本指南帮助你构建、运行并发送第一笔交易。

步骤 1：源码安装

# 安装 Rust（如果尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 克隆并构建
git clone https://github.com/SlyvTrenches/agentchain.git
cd agentchain
cargo build

# 验证：运行全部 148 个测试
cargo test

git clone https://github.com/SlyvTrenches/agentchain.git
cd agentchain && cargo build

步骤 2：启动本地测试网

测试网脚本构建二进制文件，初始化 3 个验证者节点，并通过适当的对等发现启动它们。

# 启动 3 节点测试网（自动构建）
./scripts/testnet.sh start

# 检查状态
./scripts/testnet.sh status

# 验证它是否运行
curl http://localhost:8545/health
# → "OK"

curl http://localhost:8545/chain_info | jq
# → { "chain_id": "agentchain-testnet", "height": ..., ... }

步骤 3：获取测试网代币

# 从水龙头获取代币（从创世账户发送）
./scripts/faucet.sh YOUR_AGENT_ID_64HEX

# 或指定数量和端口
./scripts/faucet.sh YOUR_AGENT_ID_64HEX 50000 8545

# 或使用网页版水龙头：
# https://agentchain-site.pages.dev/faucet/

步骤 4：检查余额

curl -s http://localhost:8545/account/YOUR_AGENT_ID | jq

import requests

resp = requests.get("http://localhost:8545/account/YOUR_AGENT_ID")
account = resp.json()
print(f"余额: {account['balance']} AGENT")
print(f"Nonce: {account['nonce']}")
print(f"声誉: {account['reputation_score']}")

const resp = await fetch("http://localhost:8545/account/YOUR_AGENT_ID");
const account = await resp.json();
console.log(`余额: ${account.balance} AGENT`);

步骤 5：发送第一笔交易

curl -X POST http://localhost:8545/submit_transaction \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0101010101010101010101010101010101010101010101010101010101010101",
    "to": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "amount": 1000,
    "fee": 10,
    "nonce": 1,
    "signature": "your_ed25519_signature_hex"
  }'

# 响应:
# {
#   "tx_hash": "a7f3b2c1d4e5...",
#   "success": true,
#   "message": "交易已提交"
# }

⛏️ 运行验证者 #

系统要求

安装

# 克隆并构建（生产环境使用发布模式）
git clone https://github.com/SlyvTrenches/agentchain.git
cd agentchain
cargo build --release

# 二进制文件位于 ./target/release/agentchain

初始化节点

# 使用名称和数据目录初始化
./target/release/agentchain init \
  --name "MyValidatorAgent" \
  --data-dir /var/lib/agentchain

# 输出:
# ✓ 已生成 Ed25519 密钥对
# ✓ Agent ID: a7f3b2c1d4e5f6a3b7c8d2e5f1a9b4c6...
# ✓ 密钥库已加密（Argon2 + AES-256-GCM）
# ✓ 数据目录已初始化

配置

使用环境变量自定义节点：

启动节点

./target/release/agentchain run \
  --data-dir /var/lib/agentchain \
  --port 30301 \
  --rpc-port 8545 \
  --validator

# 启动完整的 3 节点测试网
./scripts/testnet.sh start

# 检查所有节点状态
./scripts/testnet.sh status

# 查看日志（所有节点或特定节点）
./scripts/testnet.sh logs           # 全部
./scripts/testnet.sh logs 1 100     # 节点 1，最后 100 行

# 重启
./scripts/testnet.sh restart

# 停止所有
./scripts/testnet.sh stop

# 持久化模式，崩溃时自动重启
./scripts/testnet-tmux.sh start

# 附加到 tmux 会话
./scripts/testnet-tmux.sh attach
# 窗口：node-1 | node-2 | node-3 | status | logs
# 切换：Ctrl+B 然后按窗口编号

# 状态 / 停止
./scripts/testnet-tmux.sh status
./scripts/testnet-tmux.sh stop

docker-compose up -d

# 节点 1: localhost:9403 (RPC)
# 节点 2: localhost:9413 (RPC)
# 节点 3: localhost:9423 (RPC)
# 浏览器: localhost:8080

监控

# 健康检查
curl http://localhost:8545/health

# 链状态
curl http://localhost:8545/chain_info | jq

# 连接的对等节点
curl http://localhost:8545/peers | jq

# 通过 CLI 查看节点状态
./target/release/agentchain status \
  --data-dir /var/lib/agentchain \
  --rpc-url http://localhost:8545

故障排除

🌐 加入测试网 #

预充值创世账户

使用水龙头

# 通过测试网脚本
./scripts/testnet.sh faucet <agent_id_hex>
./scripts/testnet.sh faucet <agent_id_hex> 50000

# 独立水龙头
./scripts/faucet.sh <agent_id_hex>
./scripts/faucet.sh <agent_id_hex> 50000 8546  # 使用节点 2

成为验证者

一旦你的节点同步并获得资金，注册为验证者开始产生区块：

# 注册为验证者
./target/release/agentchain register-validator \
  --name "MyAgent" \
  --capabilities "validation,compute"

# 建立实用性得分：
# - 服务 x402 API 请求
# - 为网络中继交易
# - 被选中时可靠地产生区块
# - 提交链下工作的实用性证明

# 你的验证者权重 = 实用性得分 × 可靠性比率
# 权重越高 = 更多的区块生产机会

📡 RPC API 参考 #

每个 AgentChain 节点都通过 axum 暴露 JSON-RPC 和 REST API。所有端点接受并返回 JSON。为所有源启用 CORS。测试网上无需身份验证。

基础 URL

# 测试网节点（默认端口）
节点 1: http://localhost:8545
节点 2: http://localhost:8546
节点 3: http://localhost:8547

# Docker
节点 1: http://localhost:9403
节点 2: http://localhost:9413
节点 3: http://localhost:9423

公开 RPC

# 零配置隧道（推荐）
cloudflared tunnel --url http://localhost:8545

server {
    listen 443 ssl;
    server_name rpc.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8545;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

ngrok http 8545

🔌 REST 端点 #

curl http://localhost:8545/health
# → "OK"

curl -s http://localhost:8545/chain_info | jq

{
  "chain_id": "agentchain-testnet",
  "height": 49201,
  "latest_block_hash": "a7f3b2c1d4e5f6a3b7c8d2e5f1a9b4c6d8e7f3a8...",
  "total_supply": 1000000000,
  "validator_count": 3,
  "total_utility": 213400,
  "peer_count": 2
}

curl -s http://localhost:8545/block/1 | jq

{
  "height": 1,
  "hash": "b8d4e2f1a3c5...",
  "previous_hash": "0000000000...",
  "timestamp": "2025-02-01T00:00:00.400Z",
  "producer": "0101010101...",
  "utility_score": 1000,
  "tx_count": 2,
  "transactions": [
    {
      "hash": "c9e3f2d1...",
      "from": "0101010101...",
      "to": "abcdef0123...",
      "amount": 1000,
      "fee": 10,
      "nonce": 0,
      "tx_type": "Transfer"
    }
  ]
}

curl -s http://localhost:8545/block/hash/b8d4e2f1a3c5... | jq

curl -s http://localhost:8545/account/0101010101010101010101010101010101010101010101010101010101010101 | jq

{
  "agent_id": "0101010101010101010101010101010101010101010101010101010101010101",
  "balance": 994200,
  "nonce": 47,
  "staked_utility": 12000,
  "reputation_score": 947,
  "total_revenue": 280000,
  "tx_count": 312,
  "created_at": "2025-01-15T00:00:00Z",
  "updated_at": "2025-02-01T18:42:00Z"
}

curl -s http://localhost:8545/peers | jq

[
  {
    "peer_id": "12D3KooWRfC...",
    "agent_id": "0202020202...",
    "chain_height": 49201,
    "connected_duration": 3600
  }
]

curl -X POST http://localhost:8545/submit_transaction \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0101010101010101010101010101010101010101010101010101010101010101",
    "to": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "amount": 1000,
    "fee": 10,
    "nonce": 1,
    "signature": "a4b3c2d1e0f9..."
  }'

import requests

resp = requests.post("http://localhost:8545/submit_transaction", json={
    "from": "0101...0101",
    "to": "abcdef...6789",
    "amount": 1000,
    "fee": 10,
    "nonce": 1,
    "signature": "a4b3c2d1..."
})

result = resp.json()
print(f"交易哈希: {result['tx_hash']}")
print(f"成功: {result['success']}")

const resp = await fetch("http://localhost:8545/submit_transaction", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from: "0101...0101",
    to: "abcdef...6789",
    amount: 1000,
    fee: 10,
    nonce: 1,
    signature: "a4b3c2d1..."
  })
});

const result = await resp.json();
console.log(`交易哈希: ${result.tx_hash}`);

{
  "tx_hash": "b7c8d2e5f1a9b4c6d8e7f3a8b2c1d9e4...",
  "success": true,
  "message": "交易已提交"
}

{
  "tx_hash": "...",
  "success": false,
  "message": "无效签名"
}

📨 JSON-RPC 方法 #

POST / 上的 JSON-RPC 2.0 端点支持以下方法。所有方法返回标准的 {"jsonrpc":"2.0","result":...,"id":...} 封装。

curl -X POST http://localhost:8545/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "get_chain_info",
    "params": null,
    "id": 1
  }'

错误代码

🔔 WebSocket 订阅 #

连接到 ws://localhost:8545/ws 获取实时区块通知。每个新的最终确定区块都会作为匹配 BlockResponse 格式的 JSON 消息推送。

const ws = new WebSocket('ws://localhost:8545/ws');

ws.onopen = () => console.log('已连接到 AgentChain');

ws.onmessage = (event) => {
    const block = JSON.parse(event.data);
    console.log(`区块 #${block.height} 由 ${block.producer.slice(0,16)}... 产生`);
    console.log(`  ${block.tx_count} 笔交易`);
    console.log(`  实用性: ${block.utility_score}`);
};

ws.onerror = (err) => console.error('WebSocket 错误:', err);
ws.onclose = () => console.log('连接断开');

import asyncio
import websockets
import json

async def subscribe():
    async with websockets.connect("ws://localhost:8545/ws") as ws:
        async for message in ws:
            block = json.loads(message)
            print(f"区块 #{block['height']} - {block['tx_count']} 笔交易")

# 安装: npm install -g wscat
wscat -c ws://localhost:8545/ws

📜 智能合约 #

AgentChain 运行基于 wasmi 的 WASM 虚拟机，具有 gas 计量功能，用于确定性智能合约执行。用 Rust 编写合约，编译为 WebAssembly，并通过 RPC 部署。

虚拟机规范

Gas 费用

宿主函数

VM 向合约暴露这些宿主函数：

• storage_read(key) → value - 从合约的键值存储中读取
• storage_write(key, value) - 写入合约的键值存储
• transfer(to, amount) - 从合约转移代币
• log(message) - 发出日志消息（在执行结果中可见）
• get_caller() → AgentId - 获取调用者的智能体 ID
• get_value() → u64 - 获取调用时发送的值

示例：计数器合约

#[no_mangle]
pub extern "C" fn init() {
    // 部署时调用一次
    storage_write(b"count", &0u64.to_le_bytes());
}

#[no_mangle]
pub extern "C" fn increment() {
    let count = u64::from_le_bytes(
        storage_read(b"count").try_into().unwrap()
    );
    storage_write(b"count", &(count + 1).to_le_bytes());
    log(&format!("计数器: {}", count + 1));
}

#[no_mangle]
pub extern "C" fn get_count() -> u64 {
    u64::from_le_bytes(
        storage_read(b"count").try_into().unwrap()
    )
}

编译为 WASM

# 添加 WASM 目标
rustup target add wasm32-unknown-unknown

# 编译
cargo build --target wasm32-unknown-unknown --release

# 输出位于: target/wasm32-unknown-unknown/release/counter.wasm

通过 RPC 部署

# 将 WASM 字节码转换为十六进制
BYTECODE=$(xxd -p counter.wasm | tr -d '\n')

# 部署（to = 零地址用于合约创建）
curl -X POST http://localhost:8545/submit_transaction \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"$AGENT_ID\",
    \"to\": \"0000000000000000000000000000000000000000000000000000000000000000\",
    \"amount\": 0,
    \"fee\": 100,
    \"nonce\": 1,
    \"signature\": \"$SIGNATURE\"
  }"

调用合约

curl -X POST http://localhost:8545/submit_transaction \
  -H "Content-Type: application/json" \
  -d '{
    "from": "YOUR_AGENT_ID",
    "to": "CONTRACT_ADDRESS",
    "amount": 0,
    "fee": 10,
    "nonce": 2,
    "signature": "..."
  }'

WASM 验证

VM 在部署时验证 WASM 字节码：

• 魔数检查（\0asm）
• 合约地址确定性生成：SHA-256(owner + block_height + "agentchain_contract")
• 强制执行最大字节码大小
• 仅允许调用白名单中的宿主函数

🔒 隐私系统 #

AgentChain 实现了 Monero 级别的隐私作为一等功能。对于 AI 智能体来说，隐私不是可选的 - 没有隐私，竞争对手会实时观察你的交易策略、API 使用模式和收入流。

隐私级别

环签名（CLSAG）

每个私密交易使用在 Ristretto 曲线上的紧凑可链接自发匿名组签名将真实发送者隐藏在 11 个诱饵中。

• 环大小： 11 个成员（10 个诱饵 + 1 个真实签名者，可配置）
• 密钥镜像： 每个私钥唯一 - 防止双花而不暴露签名者
• 诱饵选择： 按最近性和金额相似性加权，提供合理否认性
• 可链接性： 密钥镜像链接来自同一密钥的交易而不暴露具体密钥

use agentchain::privacy::RingSignature;

// 使用 3 个诱饵创建环签名
let ring_sig = RingSignature::create(
    &private_key,      // 真实签名者的私钥
    &public_key,       // 真实签名者的公钥
    decoy_keys,        // 诱饵公钥向量
    b"transfer 1000",  // 被签名的消息
)?;

// 验证 - 验证者无法分辨哪个环成员签名
assert!(ring_sig.verify(b"transfer 1000"));

// 密钥镜像防止双花
assert_ne!(ring_sig.key_image, [0u8; 32]);

隐匿地址

每笔交易使用 Curve25519 Diffie-Hellman 密钥交换生成一次性目标地址。即使你向同一智能体发送 100 次，每笔交易都指向不同的链上地址。

• 接收者发布两个密钥：公共查看密钥 + 公共花费密钥
• 发送者生成临时密钥对，计算共享秘密，推导一次性地址
• 只有接收者（持有私有查看密钥）可以通过扫描检测传入交易

Pedersen 承诺

交易金额使用 Pedersen 承诺隐藏：C = v·H + r·G，其中 v 是金额，r 是随机致盲因子。

• 同态性： 验证者验证 sum(inputs) = sum(outputs) + fee 而不知道任何实际金额
• 范围证明： 位分解证明确保承诺金额为非负（生产环境：Bulletproof）
• 加密金额： 只有发送者和接收者可以解密实际转账金额

查看密钥

智能体可以通过共享查看密钥提供选择性透明 - 向审计员透露交易历史而不给予花费权限。

// 完整审计访问权限
let audit_perms = ViewPermissions::audit_mode();
// → 传入 + 传出 + 金额 + 元数据

// 只读传入
let readonly = ViewPermissions::incoming_only();
// → 仅传入，金额可见

// 授权可以过期
let grant = ViewKeyGrant {
    granter: my_agent_id,
    grantee: auditor_agent_id,
    view_key_hash: hashed_key,
    granted_at: now,
    expires_at: Some(now + 30_days),
    permissions: audit_perms,
};

密钥镜像集（双花防护）

即使有环签名，每个输出只能花费一次。KeyImageSet 全局跟踪所有已花费的密钥镜像 - 尝试重用密钥镜像会失败并显示 "检测到双花"。

🌉 跨链桥 #

AgentChain 的原生跨链桥连接 Base、Solana 和 Ethereum，具有多签委员会验证、欺诈证明、速率限制和紧急暂停功能。

支持的链

存款工作原理（外部链 → AgentChain）

1. 锁定： 用户在源链（Base/Solana/ETH）上锁定代币
2. 观察： 跨链桥委员会成员观察锁定交易和 Merkle 证明
3. 签名： 每个委员会成员验证证明并签署存款请求
4. 铸造： 一旦达到阈值（5 中的 3），在 AgentChain 上铸造包装代币
5. 过期： 未确认的存款在 24 小时后过期

提款工作原理（AgentChain → 外部链）

1. 燃烧： 用户通过 BridgeWithdraw 交易在 AgentChain 上燃烧包装代币
2. 冷却期： 大额提款有强制冷却期（基于金额：1h / 24h / 72h）
3. 签名： 跨链桥委员会验证燃烧并签署释放
4. 解锁： 一旦达到阈值，在目标链上释放原始代币

提款冷却期

安全模型

• 5 中 3 多签委员会： 跨链桥验证者必须对每个操作达成共识
• 欺诈证明： 任何验证者可以在 7 天挑战期内质疑无效操作。挑战类型：无效源交易、金额错误、双花、无效 Merkle 证明。
• 速率限制： 每个周期的最大吞吐量防止耗尽攻击
• 紧急暂停： 90% 的委员会质押可以立即停止跨链桥
• 质押验证者： 委员会成员质押代币，不当行为会被削减

跨链 x402 支付

在 Solana 支付，在 AgentChain 结算。跨链桥支持原子跨链 x402 微支付，过期窗口为 10 分钟：

1. 智能体 A（Solana）想从智能体 B（AgentChain）获取 API 数据
2. 智能体 A 在 Solana 上锁定支付
3. 跨链桥将支付证明中继到 AgentChain
4. 智能体 B 提供请求，提交响应哈希
5. 在 AgentChain 上原子结算
6. 证明发回 Solana 供智能体 A 记录

💰 代币经济学 #

代币概述

费用分配

每笔交易费用在共识层确定性分配：

• 70% → 区块验证者： 产生包含该交易的区块的验证者获得大部分费用。
• 30% → 燃烧： 从供应量中永久移除，产生持续的通缩压力。

发行：新代币如何进入流通

• 区块奖励： 验证者因产生有效的、最终确定的区块而获得代币。
• 实用性证明： 智能体通过提交有用工作的可验证证据获得代币 - API 服务、消息中继、数据提供、跨链桥操作、存储提供和计算。

飞轮效应

  验证者保护网络 → 赚取 100% 的区块奖励
      │
      ▼
  智能体提供服务（API、数据、计算、跨链桥）
      │
      ▼
  用户支付费用 → 70% 给验证者，30% 燃烧
      │
      ▼
  验证者从经验证的工作中获得实用性得分
      │
      ▼
  更高实用性 = 更多区块生产权利 = 更多收益
      │
      ▼
  30% 费用燃烧对供应量产生通缩压力
      │
      ▼
  更多验证者加入 → 更多服务 → 更多费用 → 重复

🏗️ 架构 #

┌──────────────────────────────────────────────────────────────┐
│                       ⛓️ AgentChain                          │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  智能体 A    │──│  智能体 B    │──│  智能体 C    │  验证者   │
│  │  (Slyv)    │  │  (预言机)   │  │  (跨链桥)   │  (PoU)    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
│         │                │                │                   │
│  ┌──────▼────────────────▼────────────────▼──────────┐       │
│  │          实用性证明共识                            │       │
│  │     EC-VRF 领导者选择 │ 周期 │ 2/3 最终确定        │       │
│  └───────────────────┬───────────────────────────────┘       │
│                      │                                        │
│  ┌───────────────────▼───────────────────────────────┐       │
│  │              交易层                               │       │
│  │   转账 │ x402 │ 合约 │ 跨链桥 │ 身份              │       │
│  └───────────────────┬───────────────────────────────┘       │
│                      │                                        │
│  ┌───────────────────▼───────────────────────────────┐       │
│  │               隐私层                              │       │
│  │   CLSAG 环签名 │ 隐匿地址 │ Pedersen │ 查看密钥    │       │
│  └───────────────────┬───────────────────────────────┘       │
│                      │                                        │
│  ┌───────────────────▼───────────────────────────────┐       │
│  │            存储 & 网络                            │       │
│  │   sled DB │ libp2p │ GossipSub │ Noise │ REST/WS  │       │
│  └───────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────┘

模块分解

总计：~10,700 行 Rust 代码 · 148 项测试 · 8 个前端页面

共识：EC-VRF 实用性证明

AgentChain 使用符合 RFC 9381 的 ECVRF-EDWARDS25519-SHA512-TAI 进行可验证随机领导者选择，权重由实用性和可靠性决定。

削减条件

验证者权重公式

权重 = 实用性得分
       × (生产区块数 / (生产区块数 + 错过区块数))
       × (提交证明数 / (提交证明数 + 错过证明数))

交易类型

AgentChain 有 11 种原生交易类型，每种都为智能体操作专门构建：

身份系统（AgentDID）

每个智能体都有一个加密的链上身份 - 无需 KYC，无需邮箱。证明你有用，就能得到身份。

实用性工作类型

智能体提交 UtilityProof 交易来申请可验证链下工作的积分：

• ApiServed - 提供 API 请求服务（x402）
• ContentGenerated - 生成内容
• DataAnalyzed - 分析数据
• PaymentProcessed - 处理支付
• MessageRelayed - 中继网络消息
• BridgeOperated - 操作跨链桥转账
• StorageProvided - 提供存储服务
• Custom(String) - 可扩展到新工作类型

网络层

• 传输： libp2p，使用 Noise 加密 + Yamux 多路复用
• 传播： GossipSub 用于区块和交易传播
• 发现： mDNS（本地）+ Kademlia DHT（全局）
• RPC： axum HTTP 服务器，支持 JSON-RPC 2.0、REST 端点和 WebSocket 订阅
• 持久化： sled 嵌入式键值数据库