ZORAI 公链技术文档（v1.0）

基于当前代码状态生成的完整开发者文档，已发布到 explorer.zorai.co/docs/zh
最后更新：2026-05-07 · 来源：/opt/zorai/docs/ZORAI_PUBLIC_CHAIN_TECHNICAL_DOCS_V1.md

ZORAI 公链技术文档 v1.0

代码基线：/home/zhangxg/zoraiv5 当前工作区
最后更新：2026-05-22
适用对象：节点运维者、DApp 开发者、RWA 发行方、法务/公证存证服务商、AI/GPU Provider、跨链集成方、区块链浏览器与索引服务开发者
法律声明：ZORAI Evidence/Notary Layer 适用于司法存证场景，但最终法律效力以当地司法机关认定为准。

目录

  1. ZORAI 公链概述
  2. 系统架构总览
  3. 核心功能详解
  4. EVM 兼容性与智能合约
  5. RWA 真实世界资产支持
  6. 法务/公证存证系统
  7. AI / GPU 计算市场
  8. 跨链功能
  9. 稳定币 ZUSD / zUSDT
  10. RPC 接口大全
  11. 开发者指南
  12. 技术参数与配置
  13. 部署与运维
  14. 路线图与当前状态

1. ZORAI 公链概述

ZORAI 是一条面向高吞吐 EVM 应用、RWA 合规资产、AI/GPU 计算市场和跨链资产流转的 Layer 1 公链。当前代码库实现了完整节点、BFT + PoS 共识、EVM 执行层、MPT 状态存储、LevelDB 持久化、JSON-RPC/WebSocket、Explorer/Indexer、RWA RPC、Compute RPC、Bridge/Wrapped Asset 模块以及生产监控脚本。

核心实现入口：

模块代码位置说明
节点主程序cmd/xihud/main.go:2208区块生产、BFT 提案、交易执行、最终性广播
共识核心pkg/consensus/bft.go:366BFTManager、QC、投票历史、round liveness
PoS 验证人pkg/consensus/pos_complete.go:37验证人、质押、加权 proposer 选择
EVM 执行层pkg/evm/evm.go:40go-ethereum EVM、London 规则、预编译
状态层pkg/state/mpt_state.go:43MPT 状态管理、账户、证明、状态根
区块链存储pkg/blockchain/store.go:34LevelDB + WAL、区块/交易索引
网络层pkg/network/network.go:107libp2p、Gossip、限流、DHT、同步
RPC 层pkg/rpc/web3_full.go:598Ethereum JSON-RPC、ZORAI 扩展 RPC
WebSocketpkg/websocket/websocket.go:22newHeads、pending tx、logs、syncing 订阅
Explorer/Indexercmd/explorer/main.go:235文档、区块、交易、账户、代币页面

项目定位

ZORAI 的设计重点是：

  1. EVM 兼容的高频交易链：链 ID 为 70707，十六进制为 0x11433，定义见 pkg/types/chain.go:3。
  2. 亚秒级出块目标：默认 block time 为 400ms，定义见 configs/config.toml:21。
  3. BFT 最终性：BFT vote、QC、BLS 聚合签名与 finalized block 广播定义在 pkg/consensus/bft.go:70、pkg/consensus/bft.go:76、cmd/xihud/main.go:5454。
  4. RWA 原生支持：资产、发行人、KYC、披露、估值、赎回、监管报告等模型定义在 pkg/rwa/types.go:37、pkg/rpc/rwa_rpc.go:24。
  5. AI/GPU 计算市场：任务、Provider、证明、托管和争议状态机定义在 pkg/taskmarket/types.go:52、pkg/taskmarket/market.go:17。
  6. 跨链与 Wrapped Asset：跨链消息、证明绑定、Wrapped Asset 执行器定义在 pkg/crosschain/types.go:28、pkg/crosschain/manager.go:261、pkg/evm/bridge_executor.go:35。

当前成熟度

从代码完整度看，ZORAI 已具备生产候选链的核心能力。当前最重要的生产门槛不是功能数量，而是长时间公网稳定性证据，尤其是 BFT liveness 在 7 validator + 1 RPC 公网拓扑下连续运行。代码中已经加入了 pending block 恢复、voteHistory 清理、finalized 水位同步、round_timeout 关键消息旁路限流和 90 秒级 liveness watchdog，相关位置见 pkg/consensus/bft.go:650、pkg/consensus/bft.go:839、pkg/consensus/bft.go:2372、pkg/network/network.go:1865、scripts/stability-test/zorai_liveness_watchdog.py:231。

建议成熟度评估：

维度当前评估说明
执行层兼容性8.5/10London EVM、EIP-1559、标准合约部署能力完整
共识安全性8.0/10QC、BLS、2/3 stake 检查、双签防护已实现
共识活性8.0 到 8.5/10liveness 修复已入代码，仍需要 720h 无停块证据
RPC/开发者体验8.0/10Ethereum RPC + ZORAI 扩展方法较完整
RWA/Compute/Bridge7.5 到 8.5/10模块完整，但需要更多审计和外部集成验证
运维生产化8.0/108 节点脚本、720h monitor、90s watchdog、控制平面基础已存在

与 Ethereum、Solana、Monad、Avalanche 的对比

项目ZORAIEthereumSolanaMonadAvalanche
执行环境EVM LondonEVMSVMEVMEVM/Subnet
共识方向PoS + BFT QCPoS finalityPoH + Tower BFT高性能 EVM 并行方向Avalanche consensus
出块目标默认 400ms约 12s亚秒级 slot高吞吐低延迟目标秒级
状态存储MPT + LevelDBMPT/Verkle 演进AccountsDB并行状态方向LevelDB/RocksDB 系
核心差异RWA + Compute + Bridge 原生模块最大生态和安全性高吞吐非 EVM 原生EVM 高性能多链/子网成熟
当前阶段生产候选，需要长稳验证生产成熟生产成熟新兴生产成熟

2. 系统架构总览

文字版架构图

用户 / 钱包 / DApp / 运维平台
        |
        | JSON-RPC / WebSocket / Explorer UI
        v
RPC 层 pkg/rpc + pkg/websocket
        |
        | sendRawTransaction / eth_call / logs / compute / rwa / bridge
        v
Mempool pkg/mempool  --->  区块生产 cmd/xihud
        |                         |
        |                         | BFT Proposal / Vote / QC
        v                         v
执行层 pkg/evm  <------>  共识层 pkg/consensus
        |
        | StateDB / receipts / logs
        v
状态层 pkg/state MPT + 区块存储 pkg/blockchain LevelDB/WAL
        |
        v
P2P 网络 pkg/network libp2p / DHT / Gossip / Sync
        |
        v
Explorer / Indexer cmd/explorer

共识层：BFT + PoS

PoS 验证人结构包含地址、P2P multiaddr、RPC URL、质押、BLS 公钥等字段，见 pkg/consensus/pos_complete.go:37。Proposer 选择使用 active validator 集合、stake 加权、epoch height、round 和 previous hash 共同参与的确定性选择逻辑，见 pkg/consensus/pos_complete.go:144。

BFT 层的核心对象是 BFTManager，它维护 pending blocks、votes、voteHistory、fork/equivocation 记录、round locks、highQC、currentQC 和 finalized 水位，见 pkg/consensus/bft.go:366。Quorum Certificate 包含 block hash、height、round、聚合签名、签名者、总质押与验证人集合哈希，见 pkg/consensus/bft.go:76。QC 有效性要求签名质押达到总质押的 2/3，见 pkg/consensus/bft.go:103。

执行层：EVM

EVM 执行器封装 go-ethereum stateDB、trie DB、ChainConfig、receipt 管理和状态管理器，见 pkg/evm/evm.go:40。ZORAI ChainConfig 将 Homestead、EIP150、EIP155、Byzantium、Constantinople、Petersburg、Istanbul、Berlin、London 全部从 block 0 激活，见 pkg/evm/evm.go:78。这意味着链从创世开始支持 EIP-155 replay protection 和 EIP-1559 fee market。

状态存储：MPT + LevelDB

状态层由 MPTStateManager 管理，持有 LevelDB、账户映射、trie、stateRoot、dirtyAccounts 和历史 stateRoot，见 pkg/state/mpt_state.go:43。账户余额、nonce、code hash、storage root 等账户数据由 Account 结构管理，状态提交时按地址排序重建 canonical trie 并写入 state_root，见 pkg/state/mpt_state.go:477。

区块链存储由 Blockchain 管理 LevelDB、WAL、block index、transaction index、receipt 管理器和链状态，见 pkg/blockchain/store.go:34。区块写入使用 WAL + LevelDB 批处理，避免写入一半导致状态不一致，见 pkg/blockchain/store.go:337。

P2P 网络

ZORAI 网络层基于 libp2p，协议 ID 为 /zorai/1.0.0，定义见 pkg/network/network.go:34。网络支持 Kademlia DHT、routing discovery、peer scoring、CRDT peer exchange、快照同步、增量同步、消息去重、限流和关键消息旁路，核心结构见 pkg/network/network.go:107。

共识消息包括 block_proposal、vote、round_timeout、finalized_block、validator join/leave/vote 等，见 pkg/network/network.go:63。round_timeout 被纳入关键消息旁路限流列表，因为它直接关系到 BFT round-change 活性，见 pkg/network/network.go:1865。

RPC 层

RPC 层提供 Ethereum 兼容 JSON-RPC、ZORAI 扩展 RPC、validator RPC、bridge RPC、RWA RPC 和 compute RPC。方法分发集中在 pkg/rpc/web3_full.go:598。WebSocket 支持 newHeads、newPendingTransactions、logs、syncing，见 pkg/websocket/websocket.go:22。

Explorer 与 Indexer

Explorer 路由在 cmd/explorer/main.go:235，包含首页、区块、交易、账户、验证人、代币、稳定币、RWA、跨链、文档等页面。Token indexer 使用 LevelDB 存储 ERC20/ERC721/ERC1155 事件索引状态，默认目录为 /opt/zorai/token-indexdb，见 cmd/explorer/token_indexer.go:23、cmd/explorer/token_indexer.go:64。

3. 核心功能详解

账户模型与状态管理

ZORAI 使用 EVM 账户模型。账户包括余额、nonce、code hash 和 storage root。状态管理器提供余额、nonce、storage、code、proof、state root commit 能力，核心入口见 pkg/state/mpt_state.go:216 到 pkg/state/mpt_state.go:535。

读取账户余额的 RPC 示例：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_getBalance",
    "params":["0xYourAddressHere","latest"]
  }'

读取 nonce：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_getTransactionCount",
    "params":["0xYourAddressHere","latest"]
  }'

交易结构与签名

交易类型定义在 pkg/types/transaction.go:17：

类型值说明
Legacy0x00传统 Ethereum 交易
AccessList0x01EIP-2930 access list 交易
DynamicFee0x02EIP-1559 动态费用交易

交易结构包含 from、to、value、gasLimit、gasPrice、maxFeePerGas、maxPriorityFeePerGas、nonce、data、signature、chainID 等字段，见 pkg/types/transaction.go:26。签名使用 go-ethereum LatestSignerForChainID，见 pkg/types/transaction.go:62。验证时会检查 chain ID、签名、gas limit、EIP-1559 fee 字段，见 pkg/types/transaction.go:169。

发送 raw transaction：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_sendRawTransaction",
    "params":["0xRAW_SIGNED_TRANSACTION"]
  }'

使用 ethers.js 发送 EIP-1559 交易：

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://rpc.zorai.co", {
  chainId: 70707,
  name: "zorai"
});

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const tx = await wallet.sendTransaction({
  to: "0xReceiverAddress",
  value: ethers.parseEther("1"),
  type: 2,
  maxFeePerGas: ethers.parseUnits("2", "gwei"),
  maxPriorityFeePerGas: ethers.parseUnits("1", "gwei"),
  gasLimit: 21000
});

console.log(tx.hash);

Gas 机制：EIP-1559

默认 gas 配置见 pkg/evm/evm.go:791：

参数默认值代码位置
EIP-1559enabledpkg/evm/evm.go:792
初始 base fee1 gweipkg/evm/evm.go:793
min gas price1 gweipkg/evm/evm.go:794
max gas price1000 gweipkg/evm/evm.go:795
max priority fee1 gweipkg/evm/evm.go:796
block gas limit30,000,000pkg/evm/evm.go:797
base fee denominator8pkg/evm/evm.go:798
target gas ratio50%pkg/evm/evm.go:799

Base fee 调整逻辑在 pkg/evm/evm.go:495，按父区块 gasUsed 与 targetGas 的差值调整。RPC 支持 eth_gasPrice、eth_maxPriorityFeePerGas、eth_feeHistory，分发见 pkg/rpc/web3_full.go:658。

查询 gas：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}'

查询 fee history：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_feeHistory",
    "params":["0x5","latest",[10,50,90]]
  }'

Mempool 与交易打包

TxPool 维护 pending、queued、按账户交易、交易大小、最小 gas price、replacement bump、chain ID、base fee 等状态，见 pkg/mempool/mempool.go:91。默认参数包括 3 小时过期、1 gwei minGasPrice、128KB maxTxBytes、10% replacement price bump，见 pkg/mempool/mempool.go:110。

交易加入 mempool 时会执行签名、nonce、余额、gas、size、chain ID 校验，见 pkg/mempool/mempool.go:409。区块生产时从 txpool 选择交易，执行 nonce、fee cap、余额、gas limit 过滤，见 cmd/xihud/main.go:2208。

查看 txpool：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"txpool_status","params":[]}'

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"txpool_content","params":[]}'

区块生产与最终性

区块结构定义在 pkg/types/block.go:21，Header 包含 height、previous hash、state root、transactions hash、receipts hash、gas used、gas limit、base fee、chain ID、proposer 和签名。NewBlock 默认设置 chain ID 和 base fee，见 pkg/types/block.go:52。

生产流程：

  1. 通过 PoS 选择 proposer，见 pkg/consensus/pos_complete.go:144。
  2. proposer 从 mempool 打包交易并执行预执行，见 cmd/xihud/main.go:2208。
  3. proposer 创建 BFT proposal，见 pkg/consensus/bft.go:1120。
  4. 验证人收到 proposal 后校验 proposer、chain ID、validator set、parent hash、round、签名和本地投票历史，见 pkg/consensus/bft.go:1219。
  5. 验证人创建 vote，见 pkg/consensus/bft.go:1430。
  6. 达到 2/3 stake 后形成 QC，最终化区块并广播 finalized block，见 cmd/xihud/main.go:5454。

BFT Liveness 保护

ZORAI 的 BFT liveness 修复重点解决同高度多 round 下 voteHistory 与 re-propose 的冲突。当前实现中：

机制代码位置作用
pending timeout 后允许恢复pkg/consensus/bft.go:650超时后清理 stale pending，允许重新提案
清理高度恢复状态pkg/consensus/bft.go:839同步清理 pending、forks、round locks、voteHistory
voteHistory 高 round 规则pkg/consensus/bft.go:788同 round 禁止改投，高 round 可按规则推进
finalized 水位推进pkg/consensus/bft.go:2098启动或恢复时将 lastFinalized 推进到链头
持久状态加载pkg/consensus/bft.go:2372加载 bft_state 时避免恢复导致死锁的 stale voteHistory
round_timeout 风暴保护pkg/network/network.go:1543按 peer/height/round 进行高水位和重复保护

事件日志与 WebSocket 订阅

Receipt 和 Log 结构定义在 pkg/receipt/receipt.go:18、pkg/receipt/receipt.go:33。日志过滤实现见 pkg/receipt/receipt.go:257。RPC 的 eth_getLogs 入口见 pkg/rpc/web3_full.go:1920。

WebSocket 订阅类型：

类型代码位置说明
newHeadspkg/websocket/websocket.go:22新区块头
newPendingTransactionspkg/websocket/websocket.go:23pending 交易 hash
logspkg/websocket/websocket.go:24合约事件日志
syncingpkg/websocket/websocket.go:25同步状态

WebSocket 示例：

const ws = new WebSocket("wss://rpc.zorai.co/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_subscribe",
    params: ["newHeads"]
  }));
};

ws.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

4. EVM 兼容性与智能合约

支持的 EVM 版本

ZORAI 当前代码将 London 及之前主要 hard fork 从 block 0 启用，见 pkg/evm/evm.go:78。当前代码未显示 Shanghai/Cancun 配置项，因此文档层面应声明为 London EVM 兼容。

// 核心配置位置：pkg/evm/evm.go:78
ChainID:        chainID,
HomesteadBlock: big.NewInt(0),
EIP150Block:    big.NewInt(0),
EIP155Block:    big.NewInt(0),
ByzantiumBlock: big.NewInt(0),
IstanbulBlock:  big.NewInt(0),
BerlinBlock:    big.NewInt(0),
LondonBlock:    big.NewInt(0),

预编译合约

ZORAI 继承 go-ethereum Berlin/Istanbul 预编译，并注册 ERC-3643 自定义预编译，见 pkg/evm/evm.go:158。ERC-3643 预编译地址定义见 pkg/evm/erc3643_precompiled.go:17：

地址功能
0x0000000000000000000000000000000000000200ERC3643 transfer
0x0000000000000000000000000000000000000201ERC3643 mint
0x0000000000000000000000000000000000000202ERC3643 burn
0x0000000000000000000000000000000000000203ERC3643 balance
0x0000000000000000000000000000000000000204ERC3643 whitelist
0x0000000000000000000000000000000000000205ERC3643 freeze

ERC 标准支持情况

标准支持状态说明
ERC20已支持官方模板 contracts/zorai-token-templates/ZORAIERC20.sol:9
ERC721EVM 可部署当前仓库未发现官方 ERC721 模板，可使用 OpenZeppelin 标准合约
ERC1155EVM 可部署，Indexer 有事件常量事件哈希见 cmd/explorer/token_indexer.go:23
ERC3643原生重点支持Solidity 模板 + EVM 预编译 + RWA RPC
Stablecoin已支持ZORAIStablecoinV2 模板支持 mint/burn/pause/blacklist/freezer/multisig

官方 ERC20 模板

模板位置：contracts/zorai-token-templates/ZORAIERC20.sol:9。

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
import "@openzeppelin/contracts/access/AccessControl.sol";

contract ZORAIERC20 is ERC20, ERC20Burnable, ERC20Pausable, AccessControl {
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

    constructor(
        string memory name_,
        string memory symbol_,
        address admin,
        uint256 initialSupply
    ) ERC20(name_, symbol_) {
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _grantRole(MINTER_ROLE, admin);
        _grantRole(PAUSER_ROLE, admin);
        _mint(admin, initialSupply);
    }
}

Hardhat 网络配置

Hardhat 配置已内置 ZORAI 网络，见 contracts/hardhat/hardhat.config.ts:23。

zorai: {
  url: process.env.ZORAI_RPC_URL || "http://127.0.0.1:18080/rpc",
  chainId: 70707,
  accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
}

部署示例：

cd /home/zhangxg/zoraiv5/contracts/hardhat
npm install
export ZORAI_RPC_URL=https://rpc.zorai.co
export PRIVATE_KEY=0xYOUR_PRIVATE_KEY
npx hardhat compile
npx hardhat run scripts/deploy_zusd.ts --network zorai

5. RWA 真实世界资产支持

ZORAI 的 RWA 模块覆盖资产登记、发行人、估值、文档、KYC、合规规则、治理提案、分红、赎回、披露、监管报告和价格 oracle。资产模型定义在 pkg/rwa/types.go:37，KYC 记录定义在 pkg/rwa/types.go:137，赎回请求定义在 pkg/rwa/types.go:218。

ERC-3643 实现细节

ERC-3643 Solidity 模板位于 contracts/zorai-token-templates/ZORAIRWAToken.sol:260。模板包含：

模块代码位置作用
ClaimTopicscontracts/zorai-token-templates/ZORAIRWAToken.sol:20声明所需 KYC/合规声明主题
TrustedIssuerscontracts/zorai-token-templates/ZORAIRWAToken.sol:59可信声明发行方
IdentityRegistrycontracts/zorai-token-templates/ZORAIRWAToken.sol:111地址身份与国家码
Compliancecontracts/zorai-token-templates/ZORAIRWAToken.sol:172冻结、黑名单、国家限制、单日限额
RWA Tokencontracts/zorai-token-templates/ZORAIRWAToken.sol:260ERC20 + KYC + 合规控制

Token 的 _update 会检查发送方和接收方身份、冻结状态和合规规则，相关逻辑见 contracts/zorai-token-templates/ZORAIRWAToken.sol:360。

合规模块、KYC 与权限控制

RWA RPC 方法入口见 pkg/rpc/rwa_rpc.go:24。核心合规方法包括：

方法说明
rwa_setKYCRecord设置 KYC 记录
rwa_getKYCRecord查询 KYC
rwa_isVerified检查地址是否通过验证
rwa_freezeAddress / rwa_unfreezeAddress冻结或解冻地址
rwa_setComplianceRules设置资产级合规规则
rwa_setSanction设置制裁状态
rwa_registerTradingVenue登记交易场所
rwa_setTransferRestriction设置转让限制

设置 KYC 示例：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"rwa_setKYCRecord",
    "params":[{
      "address":"0xInvestorAddress",
      "verified":true,
      "level":"enhanced",
      "investor_type":"professional",
      "jurisdiction":"HK",
      "tax_residency":"HK",
      "sanctions_clear":true,
      "accredited":true,
      "professional":true,
      "institution":false,
      "kyc_hash":"ipfs://bafy.../kyc-proof.json",
      "limits":{"daily":"1000000000000000000000"},
      "expires":1798761600,
      "metadata":{"provider":"licensed-kyc-vendor"}
    }]
  }'

设置合规规则示例：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"rwa_setComplianceRules",
    "params":[{
      "asset_id":"rwa-realestate-hk-001",
      "required_kyc_level":"enhanced",
      "allowed_jurisdictions":["HK","SG"],
      "blocked_jurisdictions":["US"],
      "require_accredited":true,
      "max_trade_amount":"100000000000000000000",
      "max_balance":"1000000000000000000000",
      "holding_period_seconds":86400,
      "venue_allowlist":["licensed-venue-1"]
    }]
  }'

RWA 发行完整流程

  1. 注册发行人：rwa_registerIssuer。
  2. 注册资产：rwa_registerAsset。
  3. 上传法律、审计、估值、托管文档：rwa_submitDocument。
  4. 启动资产验证：rwa_startVerification。
  5. 添加所有权证明、法律意见、审计、监管检查：rwa_addOwnershipProof、rwa_addLegalReview、rwa_addAudit、rwa_addRegulatoryCheck。
  6. 完成并批准验证：rwa_completeVerification、rwa_approveVerification。
  7. 设置 KYC 和合规规则：rwa_setKYCRecord、rwa_setComplianceRules。
  8. 创建发行治理提案：rwa_createProposal。
  9. 投票通过并激活 token：rwa_voteProposal、rwa_activateToken。
  10. 开始转让、分红、赎回和披露。

部署 RWA 合约：

cd /home/zhangxg/zoraiv5/contracts/hardhat
export ZORAI_RPC_URL=https://rpc.zorai.co
export PRIVATE_KEY=0xISSUER_PRIVATE_KEY
npx hardhat run scripts/deploy_rwa.ts --network zorai

6. 法务/公证存证系统

ZORAI Evidence/Notary Layer 是面向法务、公证、审计、企业合同和司法存证服务的链上证据登记层。系统原则是：链上只保存 hash、角色、时间、交易和事件证明；原始文件必须留在链下加密保全系统中。当前实现包括：

能力实现位置说明
通用存证合约contracts/zorai-token-templates/ZORAINotaryRegistry.solregisterEvidence、appendEvidence、revokeEvidence、batchRegister、Merkle leaf 验证
法律角色ZORAINotaryRegistry.sol / pkg/rwa/evidence.goNOTARY_ROLE、LAW_FIRM_ROLE、COURT_ROLE、ENTERPRISE_ROLE、AUDITOR_ROLE、OPERATOR_ROLE
多签与 timelockZORAINotaryRegistry.solappend、revoke、batchRegister 通过 approveOperation + 24h timelock 执行
RWA Evidence RPCpkg/rpc/rwa_rpc.gorwa_registerLegalIdentity、rwa_registerEvidence、rwa_verifyEvidence、rwa_getEvidenceReport
状态持久化pkg/rwa/state_snapshot.go法律身份、地址索引、证据记录进入 RWA snapshot
Explorer 验证门户cmd/explorer/evidence.go/evidence、/evidence/verify、/api/evidence/verify、PDF/JSON 报告导出
链下保全pkg/rwa/evidence.goIPFS CID、Arweave ID、S3/Object Lock URI、加密算法、访问日志 hash

6.1 Evidence Registry 合约

核心合约 ZORAINotaryRegistry 基于 OpenZeppelin AccessControlEnumerable、Pausable 和 MerkleProof。存证流程：

  1. 用户或企业系统对原始文件计算 SHA-256/Keccak-256。
  2. 生成规范化 metadata JSON，再计算 metadataHash。
  3. 法律角色账户调用 registerEvidence(contentHash, metadataHash, caseHash, subjectHash, previousEvidenceId, evidenceType, uri)。
  4. 合约发出 EvidenceRegistered 事件，事件包含 evidenceId、contentHash、submitter、caseHash、subjectHash、uri。
  5. Explorer 或 API 使用交易 receipt、block hash、event log 生成法律验证报告。

高风险操作：

操作控制
appendEvidence多签 signer 至少 2 个批准，24h timelock 后执行
revokeEvidence多签 signer 至少 2 个批准，24h timelock 后执行
batchRegister多签 signer 至少 2 个批准，24h timelock 后执行
pause/unpauseOPERATOR_ROLE 控制，生产部署建议转入多签

事件：

event EvidenceRegistered(
    bytes32 indexed evidenceId,
    bytes32 indexed contentHash,
    address indexed submitter,
    bytes32 metadataHash,
    bytes32 caseHash,
    bytes32 subjectHash,
    bytes32 previousEvidenceId,
    uint8 evidenceType,
    string uri
);

event EvidenceRevoked(bytes32 indexed evidenceId, address indexed revoker, bytes32 reasonHash);
event EvidenceSuperseded(bytes32 indexed evidenceId, bytes32 indexed newEvidenceId, address indexed operator);
event EvidenceBatchRegistered(bytes32 indexed batchId, bytes32 indexed merkleRoot, address indexed submitter, bytes32 metadataHash, uint32 itemCount, string uri);

6.2 法律身份与角色体系

法律级身份在 RWA 状态层扩展为 LegalIdentity：

{
  "subject_id": "notary-hk-001",
  "address": "0x...",
  "legal_name": "Example Notary Office",
  "jurisdiction": "HK",
  "registration_id": "NOTARY-001",
  "roles": ["notary"],
  "oidc_subject": "oidc|notary-hk-001",
  "webauthn_user_id": "base64url-user-id",
  "rbac_groups": ["notary-admins"]
}

生产模式下，面板层使用 OIDC/WebAuthn/RBAC 认证，Control Plane 审批后调用 RWA RPC 或链上合约。节点、Explorer、Ops Console 不保存私钥；所有写操作必须保留操作人、参数 hash、审批记录和链上交易 hash。

6.3 证据验证门户

Explorer 新增：

路径用途
/evidence证据验证入口
/evidence/verify同 /evidence
/api/evidence/verify?tx=0x...&hash=0x...根据交易 receipt 解析 EvidenceRegistered 并与文件 hash 比对
/api/evidence/report.json?tx=0x...&hash=0x...导出 JSON 法律验证报告
/api/evidence/report.pdf?tx=0x...&hash=0x...导出 PDF 法律验证报告

页面在浏览器本地通过 WebCrypto 计算文件 SHA-256，不上传原始文件。报告包含：

6.4 RWA Evidence RPC

新增 RPC：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rwa_registerEvidence",
  "params": {
    "content_hash": "0x...",
    "metadata_hash": "0x...",
    "case_hash": "0x...",
    "subject_hash": "0x...",
    "uri": "ipfs://bafy...",
    "evidence_type": "contract",
    "submitter": "0x...",
    "tx_hash": "0x...",
    "block_hash": "0x...",
    "block_number": 123,
    "offchain_storage": {
      "ipfs_cid": "bafy...",
      "object_lock_uri": "s3://zorai-evidence/legal/001",
      "encrypted": true,
      "encryption_alg": "AES-256-GCM",
      "access_log_hash": "0x..."
    }
  }
}

验证：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "rwa_verifyEvidence",
  "params": {
    "evidence_id": "abc...",
    "content_hash": "0x..."
  }
}

报告：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "rwa_getEvidenceReport",
  "params": {
    "evidence_id": "abc...",
    "chain_id": 70707,
    "contract_address": "0x...",
    "regulatory_export": true
  }
}

6.5 链下文件保全体系

生产推荐：

  1. 原始文件不上链。
  2. 文件本地计算 hash，metadata 规范化后再 hash。
  3. 文件加密后写入 IPFS/Arweave 或 S3 Object Lock。
  4. 访问日志写入不可变审计日志，并把访问日志 hash 写入 OffchainStorageProof.AccessLogHash。
  5. 证据验证报告不包含原始文件内容，只包含可复算的 hash 和链上证明。

6.6 部署与测试

部署：

cd /home/zhangxg/zoraiv5
export ZORAI_RPC_URL=http://127.0.0.1:8545
export ZORAI_CHAIN_ID=70707
export PRIVATE_KEY=0x...
scripts/rwa/deploy_notary_registry.sh

测试：

cd contracts/hardhat
npm test -- --grep "ZORAINotaryRegistry|ZORAIRWAToken"

cd /home/zhangxg/zoraiv5
go test ./pkg/rwa ./pkg/rpc -run 'TestRWAEvidenceRPCRegisterVerifyReport|TestRWAEnterpriseRPCOnboardingAndPersistence' -count=1
go test -tags explorer ./cmd/explorer -run TestDoesNotExist -count=1

7. AI / GPU 计算市场

ZORAI Compute Market 把 AI/GPU 任务发布、Provider 接单、结果提交、证明验证、托管支付和争议处理做成链上/链下协同协议。

架构设计

Requester
  |
  | zor_publishTask / HTTP relay
  v
TaskMarket pkg/taskmarket
  |
  | task assigned / websocket
  v
Compute Relay pkg/computerelay
  |
  | provider register / heartbeat / result
  v
GPU Agent / Provider
  |
  | proof + result CID + signature
  v
TaskMarket settle / dispute / reward

任务结构定义在 pkg/taskmarket/types.go:52，包含 requester、modelCID、inputCID、outputCID、budget、deposit、deadline、assignee、resultHash、proofHash、redundancy、audit、escrowToken 等字段。Provider 节点信息定义在 pkg/taskmarket/types.go:123。

TaskMarket

TaskMarket 维护 task、node、event、dispute、escrow、attestation、ledger 和持久化 store，见 pkg/taskmarket/market.go:17。默认配置包括最小任务押金、Provider stake、任务超时、挑战窗口、slashing bps、proof signature requirement，见 pkg/taskmarket/market.go:57。

核心状态机：

操作代码位置说明
PublishTaskpkg/taskmarket/market.go:158锁定预算并创建任务
AcceptTaskpkg/taskmarket/market.go:235Provider 接单
SubmitProofpkg/taskmarket/market.go:328提交结果和计算证明
SettleTaskpkg/taskmarket/market.go:387挑战期后结算
Disputepkg/taskmarket/market.go:423发起争议并可能罚没
RegisterNodepkg/taskmarket/market.go:520Provider 注册

Compute Relay

Relay HTTP 路由见 pkg/computerelay/relay.go:264：

路径方法说明
/healthGET健康检查
/v1/provider/connectWebSocketProvider 连接
/v1/providersGETProvider 列表
/v1/tasksPOST/GET创建或查询任务
/v1/tasks/{task_id}GET查询任务详情
/v1/tasks/{task_id}/disputePOST发起争议
/v1/chat/completionsPOSTOpenAI 兼容风格的计算入口

Mutation 签名域为 ZORAI_COMPUTE_RPC_V1，验证逻辑见 pkg/rpc/compute_rpc.go:115。Relay 协议的签名 hash 定义在 pkg/computerelay/protocol.go:104。

GPU Agent 注册示例

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"zor_registerNode",
    "params":[{
      "node_id":"gpu-provider-001",
      "owner":"0xProviderAddress",
      "endpoint":"wss://provider.example.com/v1/provider/connect",
      "gpus":[{"type":"A100","vram_gb":80,"count":4}],
      "stake":"100000000000000000",
      "nonce":1,
      "timestamp":1778112000,
      "signature":"0xProviderSignature"
    }]
  }'

发布 AI 任务示例

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"zor_publishTask",
    "params":[{
      "requester":"0xRequesterAddress",
      "task_type":"inference",
      "model_cid":"ipfs://bafy.../llm-model",
      "input_cid":"ipfs://bafy.../prompt.json",
      "config":{
        "gpu_type":"A100",
        "min_vram_gb":40,
        "max_duration_sec":600,
        "priority":5,
        "redundancy":1,
        "audit_sample_bps":500
      },
      "budget":"1000000000000000000",
      "deposit":"100000000000000000",
      "deadline":1778115600,
      "nonce":2,
      "timestamp":1778112000,
      "signature":"0xRequesterSignature"
    }]
  }'

官方 Compute Escrow 合约

合约模板位于 contracts/zorai-token-templates/ZORAIComputeEscrow.sol:10。状态包括 Open、Assigned、Submitted、Disputed、Settled、Refunded、Slashed。主要方法包括 publishNative、publishToken、accept、submitResult、dispute、settle、refundExpired 和 resolveDispute，见 contracts/zorai-token-templates/ZORAIComputeEscrow.sol:100 到 contracts/zorai-token-templates/ZORAIComputeEscrow.sol:183。

部署：

cd /home/zhangxg/zoraiv5/contracts/hardhat
export ZORAI_RPC_URL=https://rpc.zorai.co
export PRIVATE_KEY=0xDEPLOYER_PRIVATE_KEY
npx hardhat run scripts/deploy_compute_escrow.ts --network zorai

8. 跨链功能

ZORAI 跨链模块包括两套互补能力：

  1. pkg/crosschain：跨链消息、证明、链状态、finality binding、message digest 和 replay protection。
  2. pkg/bridge + pkg/evm/bridge_executor.go：跨链桥执行、Relayer、Wrapped Asset mint/burn/unlock、outbound receipt。

Solana / Ethereum 桥设计

跨链消息定义在 pkg/crosschain/types.go:28，包含 source chain、target chain、sender、receiver、token、amount、nonce、payload、proof、timestamp、status。Proof 同时支持 Ethereum transaction/receipt MPT proof、finalized checkpoint、Solana slot、program ID、guardian signatures 等字段，见 pkg/crosschain/types.go:49。

BridgeManager 注册 Ethereum 和 Solana verifier，见 pkg/crosschain/manager.go:172。消息验证流程在 pkg/crosschain/manager.go:261：

  1. 校验消息字段。
  2. 检查 chain state。
  3. 检查 proof finality binding。
  4. 调用对应链 verifier。
  5. 使用 message digest 防 replay。

Digest 绑定 sourceChainID、sourceTxHash、nonce、targetChainID、targetContract、token、amount、receiver、payload，见 pkg/crosschain/manager.go:554。

Wrapped Asset 机制

Wrapped Asset 执行器位于 pkg/evm/bridge_executor.go:35。Mint 时会：

  1. 校验消息和 wrapped asset registry。
  2. 检查 message hash 未处理。
  3. 更新 receiver balance 和 totalSupply。
  4. 生成 Transfer log。
  5. 标记消息已处理。

Wrapped asset registry 元数据包括 source chain、source token、wrapped token、symbol、decimals、maxSupply、dailyMintLimit、active、paused、blacklist 等，见 pkg/evm/wrapped_registry.go:292。

双向跨链流程

Ethereum/Solana 到 ZORAI：

用户在源链 lock/deposit
        |
Relayer 读取源链 proof
        |
bridge_deposit / bridge_submitMessage
        |
BridgeManager 验证 proof + finality
        |
BridgeExecutor MintWrapped
        |
用户在 ZORAI 获得 wrapped asset

ZORAI 到外链：

用户在 ZORAI burn wrapped asset
        |
Bridge 生成 outbound receipt
        |
验证人签名形成跨链收据证明
        |
Relayer 提交到目标链
        |
目标链 unlock/release 原资产

Bridge RPC 入口见 pkg/rpc/bridge_admin_rpc.go:28。

Bridge RPC 示例

注册 wrapped asset：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"bridge_registerWrappedAsset",
    "params":[{
      "source_chain":"ethereum",
      "source_token":"0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "wrapped_token":"0xWrappedUSDTOnZorai",
      "symbol":"zUSDT",
      "decimals":6,
      "max_supply":"1000000000000",
      "daily_mint_limit":"10000000000"
    }]
  }'

提交 deposit：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"bridge_deposit",
    "params":[{
      "source_chain_id":"ethereum-1",
      "source_tx_hash":"0xSourceTxHash",
      "source_sender":"0xEthereumSender",
      "target_receiver":"0xZoraiReceiver",
      "source_token":"0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "amount":"1000000",
      "nonce":12345,
      "proof":{"kind":"receipt_mpt","data":"0x..."}
    }]
  }'

9. 稳定币 ZUSD / zUSDT

ZORAI 稳定币支持两类路径：

  1. 原生发行稳定币：使用 ZORAIStablecoinV2 合约模板部署 ZUSD 等资产。
  2. 跨链 wrapped 稳定币：使用 Bridge + Wrapped Asset 机制发行 zUSDT、zUSDC 等映射资产。

ZORAIStablecoinV2 生产特性

模板位置：contracts/zorai-token-templates/ZORAIStablecoinV2.sol:1。关键特性：

功能代码位置说明
6 位 decimalscontracts/zorai-token-templates/ZORAIStablecoinV2.sol:44常见稳定币精度
MINTER/BURNERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:24发行与销毁权限
PAUSERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:26暂停转账
BLACKLISTERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:27黑名单
FREEZERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:28地址冻结
UPGRADERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:29UUPS 升级
多签操作contracts/zorai-token-templates/ZORAIStablecoinV2.sol:47OperationRecord + signer threshold
操作延迟contracts/zorai-token-templates/ZORAIStablecoinV2.sol:45最大操作延迟保护

部署 ZUSD

部署脚本位于 contracts/hardhat/scripts/deploy_zusd.ts:28。脚本使用 ZORAI_RPC_URL、PRIVATE_KEY、ZUSD_NAME、ZUSD_SYMBOL、ZUSD_ADMIN、ZUSD_SIGNERS、ZUSD_THRESHOLD、ZUSD_DELAY 等环境变量。

cd /home/zhangxg/zoraiv5/contracts/hardhat
npm install
npx hardhat compile

export ZORAI_RPC_URL=https://rpc.zorai.co
export PRIVATE_KEY=0xDEPLOYER_PRIVATE_KEY
export ZUSD_NAME="ZORAI USD"
export ZUSD_SYMBOL="ZUSD"
export ZUSD_ADMIN=0xAdminAddress
export ZUSD_SIGNERS=0xSigner1,0xSigner2,0xSigner3
export ZUSD_THRESHOLD=2
export ZUSD_DELAY=3600

npx hardhat run scripts/deploy_zusd.ts --network zorai

mint / burn / pause / blacklist 流程

生产流程建议：

  1. 多签 signer 对操作 hash 签名。
  2. 调用 approveOperation 累计批准，见 contracts/zorai-token-templates/ZORAIStablecoinV2.sol:178。
  3. 达到 threshold 且满足 delay 后执行 mint、burnFrom、pause、unpause、setBlacklisted、setFrozen。
  4. 操作完成后记录链上事件和链下审批工单。

ethers.js mint 示例：

import { ethers } from "ethers";
import StablecoinAbi from "./artifacts/contracts/ZORAIStablecoinV2.sol/ZORAIStablecoinV2.json";

const provider = new ethers.JsonRpcProvider(process.env.ZORAI_RPC_URL);
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
const zusd = new ethers.Contract(process.env.ZUSD_ADDRESS!, StablecoinAbi.abi, signer);

const to = "0xRecipient";
const amount = 1_000_000n; // 1 ZUSD, decimals = 6

const tx = await zusd.mint(to, amount, {
  maxFeePerGas: ethers.parseUnits("2", "gwei"),
  maxPriorityFeePerGas: ethers.parseUnits("1", "gwei")
});

await tx.wait();

10. RPC 接口大全

RPC 方法分发入口在 pkg/rpc/web3_full.go:598。Bridge 方法入口在 pkg/rpc/bridge_admin_rpc.go:28。RWA 方法入口在 pkg/rpc/rwa_rpc.go:24。Compute 方法入口在 pkg/rpc/compute_rpc.go:51。

Ethereum / Web3 / Net 方法

方法说明
web3_clientVersion客户端版本
net_version网络版本
net_peerCountpeer 数量
net_peerspeer 列表
net_addPeer添加 peer
net_peerScorespeer score
net_metrics网络指标
net_listening是否监听
eth_blockNumber当前块高
eth_chainIdchain id
eth_getBalance账户余额
eth_getTransactionCountnonce
eth_getBlockByNumber按高度查块
eth_getBlockByHash按 hash 查块
eth_getTransactionByHash查交易
eth_getTransactionReceipt查 receipt
eth_getTransactionsByAddress查地址交易
eth_getLogs查日志
eth_call只读调用
eth_estimateGasgas 估算
eth_gasPricegas price
eth_maxPriorityFeePerGaspriority fee
eth_feeHistoryfee history
eth_sendRawTransaction发送 raw tx
txpool_statustxpool 状态
txpool_contenttxpool 内容
eth_syncing同步状态
eth_coinbasecoinbase
eth_miningmining 状态
eth_hashratehashrate
eth_getCode合约代码
eth_getStorageAtstorage

基础示例：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

预期 chain id：

{"jsonrpc":"2.0","id":1,"result":"0x11433"}

ZORAI 扩展方法

方法说明
zor_livenessMetrics共识活性指标
zor_getStats链统计
zor_getValidators验证人列表
zor_getValidator验证人详情
zor_getAccountCount账户数
zor_getContractCount合约数
zor_getTotalStaked总质押
zor_getBurnedFeesburned fees
zor_getCommunityPoolcommunity pool
zor_getGPUPowerGPU power
zor_getAvgGasPrice平均 gas price
zor_pause暂停节点业务
zor_unpause恢复节点业务
zor_pauseStatus暂停状态

查询 liveness：

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zor_livenessMetrics","params":[]}'

Validator 方法

方法说明
validator_getInfo本地 validator 信息
validator_getStatusvalidator 状态
validator_getPendingRewards待领取奖励
validator_join加入验证人集合
validator_leave离开验证人集合
validator_vote治理/验证人投票
validator_updateStake更新质押
validator_slash惩罚
validator_getUptimeuptime

Bridge 方法

方法说明
bridge_statusbridge 状态
bridge_deposit源链 deposit 进入 ZORAI
bridge_burnZORAI burn 准备出链
bridge_outboundReceipt生成 outbound receipt
bridge_getOutboundReceipt查询 outbound receipt
bridge_listOutboundReceipts列出 outbound receipts
bridge_registerChain注册链
bridge_updateCheckpoint更新 checkpoint
bridge_registerRelayer注册 relayer
bridge_submitMessage提交跨链消息
bridge_addRelayerSignature添加 relayer 签名
bridge_processMessage处理消息
bridge_getMessage查询消息
bridge_registerWrappedAsset注册 wrapped asset
bridge_listWrappedAssets列出 wrapped asset
bridge_updateWrappedAssetControls更新控制参数
bridge_burnWrappedburn wrapped asset

RWA 方法

RWA 方法很多，建议按业务域使用：

域方法
资产rwa_getAsset, rwa_listAssets, rwa_getAssetStats, rwa_registerAsset
发行人rwa_registerIssuer, rwa_listIssuers
文档rwa_submitDocument, rwa_revokeDocument, rwa_getDocuments
Tokenrwa_getToken, rwa_getAllTokens, rwa_getTokenInfo, rwa_getBalance, rwa_getHolders
转让rwa_transfer, rwa_validateTransfer, rwa_preTradeCheck, rwa_setTokenRole
治理发行rwa_createProposal, rwa_voteProposal, rwa_activateToken, rwa_getProposal, rwa_getPendingProposals
验证rwa_startVerification, rwa_addOwnershipProof, rwa_addLegalReview, rwa_addAudit, rwa_completeVerification, rwa_approveVerification
估值rwa_submitValuation, rwa_verifyValuation, rwa_getCurrentValuation, rwa_getValuationHistory
合规rwa_setKYCRecord, rwa_getKYCRecord, rwa_isVerified, rwa_freezeAddress, rwa_unfreezeAddress, rwa_setComplianceRules
基金/监管rwa_registerSPV, rwa_createFund, rwa_addTranche, rwa_updateNAV, rwa_submitAttestation, rwa_generateRegulatoryReport
分红/赎回rwa_createDistribution, rwa_claimDividend, rwa_requestRedemption, rwa_approveRedemption, rwa_executeRedemption
披露/统计rwa_submitDisclosure, rwa_getAssetDisclosures, rwa_getStats

Compute 方法

方法说明
zor_publishTask发布计算任务
zor_acceptTaskProvider 接单
zor_submitProof提交结果证明
zor_getTaskStatus查询任务状态
zor_getNodeEndpoint查询 Provider endpoint
zor_claimReward领取奖励
zor_disputeTask争议任务
zor_registerNode注册 Provider
zor_updateNodeStatus更新 Provider 状态
zor_submitProviderAttestation提交 Provider 证明
zor_getProviderAttestation查询 Provider 证明
zor_getOpenTasks查询开放任务
zor_getTasksByRequester按 requester 查询
zor_getTasksByNode按 node 查询
zor_getRecentEvents最近事件
zor_getMarketStats市场统计
zor_getDispute查询争议
zor_getTaskEscrow查询 escrow

11. 开发者指南

快速启动节点

构建节点：

cd /home/zhangxg/zoraiv5
go build -o build/xihud ./cmd/xihud

使用配置启动：

./build/xihud \
  --config configs/config.toml \
  --data-dir /data/zorai

关键配置默认值见 configs/config.toml：

[genesis]
chain_id = 70707

[consensus]
block_time = "400ms"

[rpc]
port = 8545
compute_port = 8646

[network]
p2p_port = 30303
network_id = "zorai-mainnet"

部署合约示例

最小 ethers.js 部署流程：

import { ethers } from "ethers";
import fs from "node:fs";

const provider = new ethers.JsonRpcProvider("https://rpc.zorai.co", {
  chainId: 70707,
  name: "zorai"
});
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const artifact = JSON.parse(fs.readFileSync("./artifacts/contracts/MyToken.sol/MyToken.json", "utf8"));
const factory = new ethers.ContractFactory(artifact.abi, artifact.bytecode, wallet);

const contract = await factory.deploy("My Token", "MYT", wallet.address, ethers.parseEther("1000000"), {
  maxFeePerGas: ethers.parseUnits("2", "gwei"),
  maxPriorityFeePerGas: ethers.parseUnits("1", "gwei")
});

await contract.waitForDeployment();
console.log(await contract.getAddress());

发布 AI 任务

开发者可以直接调用 Compute RPC，也可以走 Compute Relay。链上任务字段结构参考 pkg/taskmarket/types.go:52。

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"zor_getOpenTasks",
    "params":[{"limit":20}]
  }'

RWA 发行示例

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"rwa_registerAsset",
    "params":[{
      "asset_id":"rwa-bond-2026-001",
      "asset_type":"bond",
      "name":"ZORAI Bond 2026",
      "issuer":"issuer-001",
      "jurisdiction":"HK",
      "currency":"USD",
      "total_value":"100000000",
      "metadata_uri":"ipfs://bafy.../asset.json"
    }]
  }'

Bridge 使用示例

curl -s https://rpc.zorai.co \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"bridge_status",
    "params":[]
  }'

12. 技术参数与配置

链参数

参数值代码位置
Chain ID70707pkg/types/chain.go:3
Chain ID Hex0x11433pkg/types/chain.go:4
Network Namezorai-mainnetpkg/types/chain.go:5
默认区块时间400msconfigs/config.toml:21
默认 block gas limit30000000pkg/evm/evm.go:797
默认 base fee1 gweipkg/evm/evm.go:793
target gas ratio50%pkg/evm/evm.go:799
base fee denominator8pkg/evm/evm.go:798

P2P 配置

参数值代码位置
P2P port30303configs/config.toml:12
Protocol ID/zorai/1.0.0pkg/network/network.go:34
max peers50configs/config.toml:14
max message size10MBpkg/network/network.go:43
max decompressed size32MBpkg/network/network.go:44
broadcast concurrency16pkg/network/network.go:45

RPC 配置

参数值代码位置
JSON-RPC port8545configs/config.toml:27
Compute RPC port8646configs/config.toml:28
rate limit100configs/config.toml:32
metrics port9200configs/config.toml:77

当前公网 8 节点拓扑

当前生产测试目标是 7 个 validator + 1 个 RPC 节点。节点清单保存在 scripts/nodes.conf：

节点角色代码位置
val-hk-1validator / bootnodescripts/nodes.conf:11
val-hk-2validatorscripts/nodes.conf:20
val-hk-3validatorscripts/nodes.conf:29
val-hk-4validatorscripts/nodes.conf:38
val-zj-1validatorscripts/nodes.conf:47
rpc-hk-1rpcscripts/nodes.conf:56
rpc-hz-1validatorscripts/nodes.conf:64
rpc-jp-2validatorscripts/nodes.conf:73

推荐硬件规格

节点类型推荐配置
Validator8 vCPU、32GB RAM、1TB NVMe、1Gbps 网络、固定公网 IP
RPC8 到 16 vCPU、32GB 到 64GB RAM、1TB NVMe、充足带宽
Archive/Indexer16 vCPU、64GB RAM、2TB+ NVMe、独立 LevelDB/索引盘
GPU Provider独立于 validator，按任务市场需要配置 A10/A100/H100 等 GPU

13. 部署与运维

8 节点部署指南

公网节点部署应使用 scripts/nodes.conf 作为节点清单来源。每个节点需要：

  1. 相同的 genesis、chain ID、validator set。
  2. 唯一 node key 和 validator signing key。
  3. 正确的 external IP、P2P port、RPC port。
  4. systemd 管理 xihud 进程。
  5. 日志进入 journal，监控脚本可远程抓取。

本地或测试环境可使用稳定性脚本生成 8 节点环境：

cd /home/zhangxg/zoraiv5
scripts/stability-test/deploy_8nodes.sh --clean

脚本默认参数位于 scripts/stability-test/deploy_8nodes.sh:4，包括 chain id、network id、block time、端口范围、初始余额和 validator stake。

24h / 720h 稳定性测试

720 小时生产监控脚本位于 scripts/stability-test/run_720h_public_monitor.sh:118，默认采样间隔为 1800 秒，即 30 分钟。Python monitor 会采样 eth_blockNumber、net_peerCount、common height/root、交易测试状态，并把生产失败条件写入 summary，见 scripts/stability-test/zorai_720h_monitor.py:139、scripts/stability-test/zorai_720h_monitor.py:200。

启动：

cd /home/zhangxg/zoraiv5
DURATION_HOURS=720 \
INTERVAL_SECONDS=1800 \
REQUIRE_PEER_COUNT=7 \
scripts/stability-test/run_720h_public_monitor.sh

90 秒级 liveness watchdog 位于 scripts/stability-test/run_liveness_watchdog.sh:4。它会在连续多次高度不增长、peer 过低、root 分叉或节点不可用时自动生成 incident，并采集 8 节点日志摘要。故障分类见 scripts/stability-test/zorai_liveness_watchdog.py:231，远程日志采集见 scripts/stability-test/zorai_liveness_watchdog.py:281。

启动：

cd /home/zhangxg/zoraiv5
INTERVAL_SECONDS=90 \
STALL_THRESHOLD=3 \
REQUIRE_PEER_COUNT=7 \
scripts/stability-test/run_liveness_watchdog.sh

连续交易测试

连续交易 supervisor 默认已经调整为每日 80000 笔，每 50 笔新增一个地址，见 scripts/stability-test/run_continuous_tx_supervised.sh:15、scripts/stability-test/run_continuous_tx_supervised.sh:17。地址池新增逻辑见 scripts/stability-test/continuous_tx.py:431。

启动：

cd /home/zhangxg/zoraiv5
DAILY_TARGET_TX=80000 \
ADD_ADDRESS_EVERY=50 \
scripts/stability-test/run_continuous_tx_supervised.sh

监控、日志、备份

建议生产监控指标：

指标RPC / 来源
当前块高eth_blockNumber
peer 数net_peerCount
livenesszor_livenessMetrics
txpooltxpool_status
同步状态eth_syncing
systemd 日志journalctl -u xihud -n 300
watchdog incidentscripts/stability-test/logs/alerts/*.jsonl

备份建议：

sudo systemctl stop xihud
sudo tar -czf /backup/zorai-data-$(date +%F).tar.gz /data/zorai
sudo systemctl start xihud

LevelDB、WAL、BFT state、validator keys 和 node key 都属于关键恢复资产。不要在 validator 间复用私钥。

常见问题排查

问题检查命令可能原因
停块curl -s ... eth_blockNumber 连续比较proposer 未出块、BFT round 分散、网络消息阻塞
peer 过低net_peerCount、journalctlbootnode 不通、防火墙、external addr 错误
state divergedeth_syncing本地执行结果与 finalized block 不一致
tx 不上链txpool_content、receiptnonce 错、fee cap 低、余额不足
RPC 落后eth_blockNumber 对比 validatorsync 落后、finalized block 接收失败

控制平面用于未来新节点加入时的网络拓扑分配、配置下发、身份漂移检查和全节点状态观测。服务入口见 cmd/controlplane/main.go:13，配置要求见 internal/controlplane/config/config.go:80，节点客户端注册、心跳、配置获取见 pkg/controlplane/client.go:223、pkg/controlplane/client.go:231、pkg/controlplane/client.go:239。cmd/xihud/controlplane_agent.go:272 支持 observe mode，cmd/xihud/controlplane_agent.go:297 支持 managed mode。生产条件中应把控制平面恢复为核心要素之一，而不是只依赖人工 SSH 巡检。

14. 路线图与当前状态

已完成功能

功能状态证据
Chain ID / Mainnet 参数已实现pkg/types/chain.go:3
区块结构和校验已实现pkg/types/block.go:21、pkg/types/block.go:187
Legacy / EIP-1559 交易已实现pkg/types/transaction.go:17
MPT 状态管理已实现pkg/state/mpt_state.go:43
LevelDB + WAL 存储已实现pkg/blockchain/store.go:34
London EVM已实现pkg/evm/evm.go:78
EIP-1559 gas已实现pkg/evm/evm.go:495
Mempool已实现pkg/mempool/mempool.go:91
PoS validator已实现pkg/consensus/pos_complete.go:37
BFT QC / Finality已实现pkg/consensus/bft.go:76
BFT liveness recovery已实现，需要长稳验证pkg/consensus/bft.go:839
libp2p 网络已实现pkg/network/network.go:107
Ethereum JSON-RPC已实现pkg/rpc/web3_full.go:598
WebSocket 订阅已实现pkg/websocket/websocket.go:22
Explorer / Token Indexer已实现cmd/explorer/main.go:235、cmd/explorer/token_indexer.go:23
RWA RPC已实现pkg/rpc/rwa_rpc.go:24
ERC-3643 模板和预编译已实现contracts/zorai-token-templates/ZORAIRWAToken.sol:260、pkg/evm/erc3643_precompiled.go:17
Compute Market已实现pkg/taskmarket/market.go:17
Compute Relay已实现pkg/computerelay/relay.go:264
Bridge / Wrapped Asset已实现pkg/bridge/cross_chain.go:174、pkg/evm/bridge_executor.go:35
Stablecoin V2已实现contracts/zorai-token-templates/ZORAIStablecoinV2.sol:1
720h monitor已实现scripts/stability-test/run_720h_public_monitor.sh:118
90s liveness watchdog已实现scripts/stability-test/run_liveness_watchdog.sh:4
控制平面基础已实现，需要恢复生产使用cmd/controlplane/main.go:13

即将上线或建议优先补强

  1. 720 小时无停块生产证据：7 validator + 1 RPC 公网拓扑，结合 30 分钟 monitor 和 90 秒 watchdog。
  2. 控制平面恢复生产作用：节点注册、拓扑分配、配置下发、状态可视化、identity drift 拒绝策略。
  3. BFT 形式化测试与故障注入：覆盖网络限流、round 分散、节点重启、finalized 水位落后、Byzantine double vote。
  4. Bridge 外部审计：跨链 proof、relayer quorum、wrapped asset mint/burn replay protection 需要外部审计。
  5. RWA 合规审计：KYC、隐私证明、监管报告、强制转让和赎回流程需要法务与安全审计。
  6. RPC 兼容性测试：用 Hardhat、Foundry、ethers、web3.py、MetaMask 做完整兼容矩阵。
  7. Explorer 文档发布：将本文档接入 https://explorer.zorai.co/docs，替换当前简版页面。
  8. 性能压测：持续交易目标 80000/day 是生产观察基础，还应增加峰值 TPS、合约调用、事件日志、RPC 查询压测。

附录 A：常用命令速查

# 构建节点
go build -o build/xihud ./cmd/xihud

# 全仓测试
go test ./...

# 单独测试共识与网络
go test ./pkg/consensus ./pkg/network

# 查询链 ID
curl -s https://rpc.zorai.co -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 查询块高
curl -s https://rpc.zorai.co -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 查询 peer
curl -s https://rpc.zorai.co -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_peerCount","params":[]}'

# 启动 720h monitor
DURATION_HOURS=720 INTERVAL_SECONDS=1800 REQUIRE_PEER_COUNT=7 \
  scripts/stability-test/run_720h_public_monitor.sh

# 启动 90s watchdog
INTERVAL_SECONDS=90 STALL_THRESHOLD=3 REQUIRE_PEER_COUNT=7 \
  scripts/stability-test/run_liveness_watchdog.sh

# 启动连续交易
DAILY_TARGET_TX=80000 ADD_ADDRESS_EVERY=50 \
  scripts/stability-test/run_continuous_tx_supervised.sh

附录 B：发布到 Explorer Docs 的建议

当前 Explorer 文档路由位于 cmd/explorer/main.go:235，/docs 页面由 docsEnPage 生成，处理函数见 cmd/explorer/main.go:1330。建议把本文档作为独立 Markdown 内容源，由 Explorer 在启动时读取并渲染，而不是继续把长文档硬编码在 Go handler 中。这样后续文档可以单独维护、审阅和版本化。

推荐落地方式：

  1. 将本文档保留在 docs/ZORAI_PUBLIC_CHAIN_TECHNICAL_DOCS_V1.md。
  2. 在 Explorer 中增加 Markdown 渲染 helper。
  3. /docs 默认读取该 Markdown 文件。
  4. 保留 /docs/zh、/docs/whitepaper 等专题页面入口。
  5. 在发布流程中把 docs/ 目录同步到 Explorer 节点。