ZORAI Public Chain Technical Documentation (v1.0)

Complete developer documentation generated from the current codebase and published at explorer.zorai.co/docs
Last updated：2026-05-07 · Source：/opt/zorai/docs/ZORAI_PUBLIC_CHAIN_TECHNICAL_DOCS_V1_EN.md

ZORAI Public Chain Technical Documentation v1.0

Code baseline: current /home/zhangxg/zoraiv5 workspace
Last updated: 2026-05-22
Audience: node operators, DApp developers, RWA issuers, legal/notary evidence providers, AI/GPU providers, bridge integrators, explorer and indexer developers
Legal notice: ZORAI Evidence/Notary Layer is designed for judicial evidence-preservation workflows, but final legal effect depends on recognition by the competent local judicial authority.

Table of Contents

  1. ZORAI Public Chain Overview
  2. System Architecture
  3. Core Protocol Features
  4. EVM Compatibility and Smart Contracts
  5. RWA Support
  6. Legal / Notary Evidence System
  7. AI / GPU Compute Market
  8. Cross-chain Functionality
  9. Stablecoins: ZUSD / zUSDT
  10. RPC Reference
  11. Developer Guide
  12. Technical Parameters and Configuration
  13. Deployment and Operations
  14. Roadmap and Current Status

1. ZORAI Public Chain Overview

ZORAI is an EVM-compatible Layer 1 public chain designed for high-frequency applications, compliant RWA issuance, AI/GPU compute markets, and cross-chain asset movement. The current repository includes a full node, BFT + PoS consensus, EVM execution, MPT state, LevelDB persistence, JSON-RPC/WebSocket APIs, Explorer/Indexer, RWA RPC, Compute RPC, Bridge/Wrapped Asset modules, and production monitoring scripts.

Key implementation references:

ModuleCode pathNotes
Node binarycmd/xihud/main.go:2208Block production, BFT proposal, execution, finality broadcast
BFT consensuspkg/consensus/bft.go:366BFTManager, QC, vote history, liveness recovery
PoS validatorspkg/consensus/pos_complete.go:37Validator metadata, stake, proposer selection
EVM executionpkg/evm/evm.go:40go-ethereum EVM, London rules, precompiles
State layerpkg/state/mpt_state.go:43MPT state manager, account state, proofs
Chain storepkg/blockchain/store.go:34LevelDB + WAL, block and transaction indexes
Networkpkg/network/network.go:107libp2p, gossip, rate limits, DHT, sync
RPCpkg/rpc/web3_full.go:598Ethereum JSON-RPC and ZORAI extension methods
WebSocketpkg/websocket/websocket.go:22newHeads, pending transactions, logs, syncing
Explorer/Indexercmd/explorer/main.go:235Blocks, transactions, accounts, validators, tokens, docs

Positioning

ZORAI focuses on four main goals:

  1. EVM-compatible application chain: chain ID 70707, hex 0x11433, defined in pkg/types/chain.go:3.
  2. Sub-second block target: default block time is 400ms, configured in configs/config.toml:21.
  3. BFT finality: proposals, votes, quorum certificates and finalized block broadcast are implemented in pkg/consensus/bft.go:70, pkg/consensus/bft.go:76, and cmd/xihud/main.go:5454.
  4. Native business modules: RWA, compute market and bridge modules are implemented under pkg/rwa, pkg/taskmarket, pkg/computerelay, pkg/crosschain, pkg/bridge, and pkg/evm/bridge_executor.go.

Current Maturity

The codebase is a production-candidate chain implementation. The critical production gate is long-running public-network evidence, especially BFT liveness on the current 7 validator + 1 RPC topology. Recent liveness fixes include pending block recovery, voteHistory cleanup, finalized watermark synchronization, round_timeout critical-message bypass and a 90-second watchdog. Relevant code paths include pkg/consensus/bft.go:650, pkg/consensus/bft.go:839, pkg/consensus/bft.go:2372, pkg/network/network.go:1865, and scripts/stability-test/zorai_liveness_watchdog.py:231.

AreaCurrent assessmentNotes
EVM compatibility8.5/10London EVM and EIP-1559 are implemented
Consensus safety8.0/10QC, BLS aggregation and 2/3 stake checks exist
Consensus liveness8.0 to 8.5/10Candidate after recent fixes, pending 720h evidence
RPC/developer experience8.0/10Ethereum RPC plus ZORAI extension APIs
RWA/Compute/Bridge7.5 to 8.5/10Broad modules exist, but need audit and integration evidence
Operations8.0/108-node scripts, 720h monitor, watchdog and control plane foundations exist

Comparison With Ethereum, Solana, Monad and Avalanche

DimensionZORAIEthereumSolanaMonadAvalanche
ExecutionLondon EVMEVMSVMEVMEVM/Subnet
Consensus directionPoS + BFT QCPoS finalityPoH + Tower BFThigh-performance EVMAvalanche consensus
Block target400ms defaultaround 12ssub-second slotlow-latency targetseconds-level
StateMPT + LevelDBMPT, Verkle roadmapAccountsDBparallel state directionLevelDB/RocksDB-style
DifferentiatorRWA + Compute + Bridge moduleslargest ecosystemhigh-throughput non-EVM nativehigh-performance EVMmature multi-chain model
Current stageproduction candidateproduction matureproduction matureemergingproduction mature

2. System Architecture

Text Architecture Diagram

Wallets / DApps / Operators / Explorer users
        |
        | JSON-RPC / WebSocket / Explorer UI
        v
RPC layer: pkg/rpc + pkg/websocket
        |
        | sendRawTransaction / eth_call / logs / compute / rwa / bridge
        v
Mempool: pkg/mempool  --->  Block production: cmd/xihud
        |                         |
        |                         | BFT Proposal / Vote / QC
        v                         v
Execution: pkg/evm  <---->  Consensus: pkg/consensus
        |
        | StateDB / receipts / logs
        v
State: pkg/state MPT + Storage: pkg/blockchain LevelDB/WAL
        |
        v
P2P network: pkg/network libp2p / DHT / Gossip / Sync
        |
        v
Explorer / Indexer: cmd/explorer

Consensus Layer: BFT + PoS

Validator metadata includes address, P2P multiaddr, RPC URL, stake and BLS public key, defined in pkg/consensus/pos_complete.go:37. Proposer selection uses active validators, stake weights, epoch height, round and previous hash, implemented in pkg/consensus/pos_complete.go:144.

BFTManager maintains pending blocks, votes, vote history, fork and equivocation records, round locks, highQC, currentQC and finalized watermark. See pkg/consensus/bft.go:366. A quorum certificate contains block hash, height, round, aggregate signature, signers, total stake and validator-set hash. See pkg/consensus/bft.go:76. QC validity requires at least 2/3 total stake, implemented in pkg/consensus/bft.go:103.

Execution Layer: EVM

The EVM executor wraps go-ethereum StateDB, trie DB, ChainConfig, receipts and the ZORAI state manager. See pkg/evm/evm.go:40. ZORAI activates Homestead, EIP150, EIP155, Byzantium, Constantinople, Petersburg, Istanbul, Berlin and London from block 0 in pkg/evm/evm.go:78.

State Storage: MPT + LevelDB

MPTStateManager holds LevelDB, account state, trie, state root, dirty accounts and state-root history. See pkg/state/mpt_state.go:43. Commits rebuild a canonical trie from sorted accounts and persist state_root, implemented in pkg/state/mpt_state.go:477.

The chain store is backed by LevelDB plus WAL and keeps block, transaction and receipt indexes. See pkg/blockchain/store.go:34. Trusted block writes use WAL plus LevelDB batch operations in pkg/blockchain/store.go:337.

P2P Network

The network layer uses libp2p with protocol ID /zorai/1.0.0, defined in pkg/network/network.go:34. It supports Kademlia DHT, routing discovery, peer scoring, CRDT peer exchange, snapshot sync, incremental sync, message dedupe, rate limiting and critical-message bypass. The core network structure is in pkg/network/network.go:107.

Consensus message types include block_proposal, vote, round_timeout, finalized_block, validator join/leave/vote. See pkg/network/network.go:63. round_timeout bypasses peer rate limits because it is critical for BFT liveness. See pkg/network/network.go:1865.

RPC Layer

RPC dispatch is centralized in pkg/rpc/web3_full.go:598. It supports Ethereum JSON-RPC, ZORAI extension methods, validator RPC, bridge RPC, RWA RPC and compute RPC. WebSocket subscriptions support newHeads, newPendingTransactions, logs and syncing, defined in pkg/websocket/websocket.go:22.

Explorer and Indexer

Explorer routes are registered in cmd/explorer/main.go:235. Token indexer persistence uses LevelDB and supports token metadata, holders and transfer history. ERC1155 event hashes and indexer state are in cmd/explorer/token_indexer.go:23 and cmd/explorer/token_indexer.go:64.

3. Core Protocol Features

Account Model and State Management

ZORAI uses the EVM account model. Accounts track balance, nonce, code hash and storage root. Balance, nonce, storage, code, proof and state-root operations are implemented across pkg/state/mpt_state.go:216 to pkg/state/mpt_state.go:535.

Get balance:

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

Get nonce:

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

Transaction Structure and Signatures

Transaction types are defined in pkg/types/transaction.go:17:

TypeValueNotes
Legacy0x00Traditional Ethereum transaction
AccessList0x01EIP-2930 access-list transaction
DynamicFee0x02EIP-1559 dynamic-fee transaction

The transaction structure includes from, to, value, gasLimit, gasPrice, maxFeePerGas, maxPriorityFeePerGas, nonce, data, signature and chainID fields. See pkg/types/transaction.go:26. Signing uses go-ethereum LatestSignerForChainID, implemented in pkg/types/transaction.go:62. Verification checks chain ID, signature, gas limit and EIP-1559 fields in pkg/types/transaction.go:169.

Send a 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 transfer:

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 Mechanism: EIP-1559

Default gas configuration is in pkg/evm/evm.go:791:

ParameterDefaultCode path
EIP-1559enabledpkg/evm/evm.go:792
Initial 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 adjustment is implemented in pkg/evm/evm.go:495. RPC supports eth_gasPrice, eth_maxPriorityFeePerGas and eth_feeHistory.

Mempool and Block Packing

TxPool tracks pending and queued transactions, account indexes, transaction size limit, minimum gas price, replacement bump, chain ID and base fee. See pkg/mempool/mempool.go:91. Defaults include 3-hour expiration, 1 gwei min gas price, 128KB max transaction size and 10% replacement bump, defined in pkg/mempool/mempool.go:110.

Transaction validation checks signature, nonce, balance, gas, size and chain ID. See pkg/mempool/mempool.go:409. Block production filters nonce, fee cap, balance and gas limit before proposal. See cmd/xihud/main.go:2208.

Block Production and Finality

Block headers contain height, previous hash, state root, transaction hash, receipt hash, gas used, gas limit, base fee, chain ID, proposer and signature. See pkg/types/block.go:21. NewBlock sets default chain ID and base fee in pkg/types/block.go:52.

Finalization flow:

  1. PoS selects proposer, see pkg/consensus/pos_complete.go:144.
  2. Proposer packages and pre-executes transactions, see cmd/xihud/main.go:2208.
  3. Proposer creates a BFT proposal, see pkg/consensus/bft.go:1120.
  4. Validators validate proposer, chain ID, validator set, parent hash, round, signature and local vote history, see pkg/consensus/bft.go:1219.
  5. Validators create votes, see pkg/consensus/bft.go:1430.
  6. A QC forms after 2/3 stake and the finalized block is broadcast, see cmd/xihud/main.go:5454.

BFT Liveness Protection

Recent liveness protections:

MechanismCode pathPurpose
Pending timeout recoverypkg/consensus/bft.go:650Clear stale pending and allow re-proposal
Height recovery cleanuppkg/consensus/bft.go:839Clear pending, forks, round locks and vote history
Higher-round vote rulespkg/consensus/bft.go:788Same-round double vote rejected, higher-round progress allowed by rules
Finalized watermark advancepkg/consensus/bft.go:2098Align BFT finalized height with canonical chain head
State loadingpkg/consensus/bft.go:2372Avoid restoring stale vote history that can deadlock
Round timeout protectionpkg/network/network.go:1543Deduplicate and protect consensus channels from timeout storms

Events and WebSocket Subscriptions

Receipts and logs are defined in pkg/receipt/receipt.go:18 and pkg/receipt/receipt.go:33. Log filtering is implemented in pkg/receipt/receipt.go:257. eth_getLogs is handled in pkg/rpc/web3_full.go:1920.

WebSocket subscription types:

TypeCode pathNotes
newHeadspkg/websocket/websocket.go:22New block headers
newPendingTransactionspkg/websocket/websocket.go:23Pending transaction hashes
logspkg/websocket/websocket.go:24Contract events
syncingpkg/websocket/websocket.go:25Sync state

4. EVM Compatibility and Smart Contracts

Supported EVM Version

ZORAI currently exposes a London-compatible EVM configuration. The code activates major forks up to London from block 0 in pkg/evm/evm.go:78. Shanghai/Cancun configuration is not present in the current code, so public documentation should describe the chain as London EVM compatible.

Precompiles

ZORAI inherits go-ethereum Berlin/Istanbul precompiles and registers custom ERC-3643 precompiles in pkg/evm/evm.go:158. ERC-3643 precompile addresses are defined in pkg/evm/erc3643_precompiled.go:17:

AddressFunction
0x0000000000000000000000000000000000000200ERC3643 transfer
0x0000000000000000000000000000000000000201ERC3643 mint
0x0000000000000000000000000000000000000202ERC3643 burn
0x0000000000000000000000000000000000000203ERC3643 balance
0x0000000000000000000000000000000000000204ERC3643 whitelist
0x0000000000000000000000000000000000000205ERC3643 freeze

ERC Standard Support

StandardStatusNotes
ERC20supportedOfficial template at contracts/zorai-token-templates/ZORAIERC20.sol:9
ERC721deployable on EVMUse OpenZeppelin standard contracts; no official template found in repo
ERC1155deployable and partially indexedEvent hashes exist in cmd/explorer/token_indexer.go:23
ERC3643first-class supportSolidity template, EVM precompile and RWA RPC support
Stablecoinsupported templateZORAIStablecoinV2 supports mint, burn, pause, blacklist, freeze, roles and multisig

Hardhat Configuration

Hardhat includes a ZORAI network in 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] : [],
}

Deploy:

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 Support

ZORAI's RWA module covers issuer onboarding, asset registration, valuation, documents, KYC, compliance rules, governance proposals, distributions, redemptions, disclosures, regulatory reports and price oracle updates. Asset types and records are defined in pkg/rwa/types.go:37, KYC records in pkg/rwa/types.go:137, and redemption requests in pkg/rwa/types.go:218.

ERC-3643 Implementation

The official RWA Solidity template is contracts/zorai-token-templates/ZORAIRWAToken.sol:260. It includes:

ComponentCode pathPurpose
ClaimTopicscontracts/zorai-token-templates/ZORAIRWAToken.sol:20Required claim topics
TrustedIssuerscontracts/zorai-token-templates/ZORAIRWAToken.sol:59Trusted claim issuers
IdentityRegistrycontracts/zorai-token-templates/ZORAIRWAToken.sol:111Address identity and country
Compliancecontracts/zorai-token-templates/ZORAIRWAToken.sol:172Freeze, blacklist, country and daily-limit checks
RWA Tokencontracts/zorai-token-templates/ZORAIRWAToken.sol:260ERC20 plus KYC/compliance controls

Compliance, KYC and Access Control

RWA RPC dispatch is implemented in pkg/rpc/rwa_rpc.go:24. Key compliance methods include:

MethodPurpose
rwa_setKYCRecordSet investor KYC record
rwa_getKYCRecordRead KYC record
rwa_isVerifiedCheck verification status
rwa_freezeAddress / rwa_unfreezeAddressFreeze or unfreeze address
rwa_setComplianceRulesSet asset compliance rules
rwa_setSanctionSet sanction status
rwa_registerTradingVenueRegister trading venue
rwa_setTransferRestrictionSet transfer restriction

Set KYC example:

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,
      "kyc_hash":"ipfs://bafy.../kyc-proof.json",
      "expires":1798761600
    }]
  }'

RWA Issuance Flow

  1. Register issuer with rwa_registerIssuer.
  2. Register asset with rwa_registerAsset.
  3. Submit legal, audit, valuation and custody documents with rwa_submitDocument.
  4. Start asset verification with rwa_startVerification.
  5. Add ownership proof, legal review, audit and regulatory check.
  6. Complete and approve verification.
  7. Configure KYC and compliance rules.
  8. Create issuance proposal.
  9. Vote and activate the token.
  10. Operate transfers, distributions, redemptions and disclosures.

Deploy RWA contracts:

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

ZORAI Evidence/Notary Layer provides a general-purpose evidence registry for legal, notary, audit, enterprise contract and judicial evidence-preservation workflows. The design rule is strict: only hashes, roles, timestamps, transaction proofs and event proofs are stored on-chain; raw files must remain in encrypted off-chain preservation systems.

CapabilityImplementationNotes
Evidence registry contractcontracts/zorai-token-templates/ZORAINotaryRegistry.solregisterEvidence, appendEvidence, revokeEvidence, batchRegister, Merkle leaf verification
Legal rolesZORAINotaryRegistry.sol / pkg/rwa/evidence.goNOTARY_ROLE, LAW_FIRM_ROLE, COURT_ROLE, ENTERPRISE_ROLE, AUDITOR_ROLE, OPERATOR_ROLE
Multisig and timelockZORAINotaryRegistry.solappend, revoke and batch registration require approveOperation plus 24h timelock
RWA Evidence RPCpkg/rpc/rwa_rpc.gorwa_registerLegalIdentity, rwa_registerEvidence, rwa_verifyEvidence, rwa_getEvidenceReport
Persistencepkg/rwa/state_snapshot.golegal identities, address indexes and evidence records are persisted in the RWA snapshot
Explorer verification portalcmd/explorer/evidence.go/evidence, /evidence/verify, /api/evidence/verify, PDF/JSON report export
Off-chain preservationpkg/rwa/evidence.goIPFS CID, Arweave ID, S3/Object Lock URI, encryption algorithm and access-log hash

6.1 Evidence Registry

The ZORAINotaryRegistry contract is based on OpenZeppelin AccessControlEnumerable, Pausable and MerkleProof. A normal evidence registration flow is:

  1. Compute SHA-256 or Keccak-256 over the original file.
  2. Canonicalize metadata JSON and compute metadataHash.
  3. A legal-role account calls registerEvidence(contentHash, metadataHash, caseHash, subjectHash, previousEvidenceId, evidenceType, uri).
  4. The contract emits EvidenceRegistered, binding evidenceId, contentHash, submitter, case hash, subject hash and URI.
  5. Explorer or API reads the transaction receipt, block hash and event log to generate a legal verification report.

High-risk operations:

OperationControl
appendEvidenceAt least 2 multisig signer approvals plus 24h timelock
revokeEvidenceAt least 2 multisig signer approvals plus 24h timelock
batchRegisterAt least 2 multisig signer approvals plus 24h timelock
pause/unpauseOPERATOR_ROLE, recommended to be controlled by multisig in production

LegalIdentity extends the RWA identity system with legally meaningful actors:

{
  "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"]
}

In production, the Operations Console should authenticate operators through OIDC/WebAuthn/RBAC and submit write requests through the Control Plane approval flow. Nodes, Explorer and the console must not store private keys.

6.3 Verification Portal and Reports

Explorer routes:

RoutePurpose
/evidenceEvidence verification page
/evidence/verifySame verification page
/api/evidence/verify?tx=0x...&hash=0x...Parse EvidenceRegistered from receipt and compare file hash
/api/evidence/report.json?tx=0x...&hash=0x...Export JSON report
/api/evidence/report.pdf?tx=0x...&hash=0x...Export PDF report

The browser computes SHA-256 locally with WebCrypto. Raw files are not uploaded. Reports include file hash, evidence ID, transaction hash, block height, block hash, block timestamp, submitter, contract address, receipt status, event log and legal notice.

6.4 Evidence RPC

Register evidence:

{
  "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...",
    "offchain_storage": {
      "ipfs_cid": "bafy...",
      "object_lock_uri": "s3://zorai-evidence/legal/001",
      "encrypted": true,
      "encryption_alg": "AES-256-GCM",
      "access_log_hash": "0x..."
    }
  }
}

Verify:

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

Export report:

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

6.5 Deployment and Tests

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

Legal notice: ZORAI Evidence/Notary Layer is designed for judicial evidence-preservation scenarios, but final legal effect depends on recognition by the competent local judicial authority.

7. AI / GPU Compute Market

ZORAI Compute Market coordinates task publishing, provider assignment, result submission, proof verification, escrow settlement and disputes.

Architecture

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 settlement / dispute / reward

Task fields are defined in pkg/taskmarket/types.go:52. Provider endpoint and GPU metadata are defined in pkg/taskmarket/types.go:123 and pkg/taskmarket/types.go:163.

TaskMarket

TaskMarket stores tasks, nodes, events, disputes, escrow records, attestations, ledger and persistent store. See pkg/taskmarket/market.go:17. Default market settings are in pkg/taskmarket/market.go:57.

OperationCode pathPurpose
PublishTaskpkg/taskmarket/market.go:158Lock budget and create task
AcceptTaskpkg/taskmarket/market.go:235Provider accepts task
SubmitProofpkg/taskmarket/market.go:328Submit result and compute proof
SettleTaskpkg/taskmarket/market.go:387Settle after challenge window
Disputepkg/taskmarket/market.go:423Open dispute and possible slashing
RegisterNodepkg/taskmarket/market.go:520Register provider

Compute Relay

Relay HTTP routes are in pkg/computerelay/relay.go:264:

PathMethodPurpose
/healthGETHealth check
/v1/provider/connectWebSocketProvider connection
/v1/providersGETProvider list
/v1/tasksPOST/GETCreate or list tasks
/v1/tasks/{task_id}GETTask details
/v1/tasks/{task_id}/disputePOSTOpen dispute
/v1/chat/completionsPOSTOpenAI-style compute entry

Mutation signing domain is ZORAI_COMPUTE_RPC_V1, verified in pkg/rpc/compute_rpc.go:115.

Register GPU provider:

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"
    }]
  }'

Publish task:

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},
      "budget":"1000000000000000000",
      "deposit":"100000000000000000",
      "deadline":1778115600,
      "nonce":2,
      "timestamp":1778112000,
      "signature":"0xRequesterSignature"
    }]
  }'

8. Cross-chain Functionality

ZORAI bridge functionality has two complementary layers:

  1. pkg/crosschain: cross-chain messages, proofs, chain state, finality binding, digest and replay protection.
  2. pkg/bridge plus pkg/evm/bridge_executor.go: bridge execution, relayers, wrapped asset mint/burn/unlock, outbound receipts.

Ethereum and Solana Bridge Design

Cross-chain messages are defined in pkg/crosschain/types.go:28. Proof fields support Ethereum transaction/receipt MPT proofs, finalized checkpoints, Solana slots, program IDs and guardian signatures. See pkg/crosschain/types.go:49.

BridgeManager registers Ethereum and Solana verifiers in pkg/crosschain/manager.go:172. Message verification is implemented in pkg/crosschain/manager.go:261. Digest binding includes source chain ID, tx hash, nonce, target chain ID, target contract, token, amount, receiver and payload. See pkg/crosschain/manager.go:554.

Wrapped Asset Mechanism

Wrapped asset execution is implemented in pkg/evm/bridge_executor.go:35. Mint validates the message, checks replay state, updates balance and total supply, emits a Transfer log and marks the message processed. Wrapped asset metadata is defined in pkg/evm/wrapped_registry.go:292.

Bridge RPC Example

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

9. Stablecoins: ZUSD / zUSDT

ZORAI supports two stablecoin paths:

  1. Native stablecoin issuance with ZORAIStablecoinV2.
  2. Wrapped stablecoins such as zUSDT or zUSDC via Bridge + Wrapped Asset.

ZORAIStablecoinV2 Features

Template path: contracts/zorai-token-templates/ZORAIStablecoinV2.sol:1.

FeatureCode pathNotes
6 decimalscontracts/zorai-token-templates/ZORAIStablecoinV2.sol:44Common stablecoin precision
MINTER/BURNERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:24Mint and burn permissions
PAUSERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:26Pause transfers
BLACKLISTERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:27Blacklist addresses
FREEZERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:28Freeze addresses
UPGRADERcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:29UUPS upgrade
Multisig operationscontracts/zorai-token-templates/ZORAIStablecoinV2.sol:47OperationRecord plus signer threshold

Deploy ZUSD:

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

10. RPC Reference

RPC dispatch is implemented in pkg/rpc/web3_full.go:598. Bridge RPC is in pkg/rpc/bridge_admin_rpc.go:28. RWA RPC is in pkg/rpc/rwa_rpc.go:24. Compute RPC is in pkg/rpc/compute_rpc.go:51.

Ethereum / Web3 / Net Methods

MethodPurpose
web3_clientVersionClient version
net_versionNetwork version
net_peerCountPeer count
net_peersPeer list
net_addPeerAdd peer
net_peerScoresPeer scores
net_metricsNetwork metrics
net_listeningListening state
eth_blockNumberCurrent height
eth_chainIdChain ID
eth_getBalanceAccount balance
eth_getTransactionCountAccount nonce
eth_getBlockByNumberBlock by height
eth_getBlockByHashBlock by hash
eth_getTransactionByHashTransaction lookup
eth_getTransactionReceiptReceipt lookup
eth_getTransactionsByAddressAddress transaction history
eth_getLogsEvent logs
eth_callRead-only execution
eth_estimateGasGas estimation
eth_gasPriceGas price
eth_maxPriorityFeePerGasPriority fee
eth_feeHistoryFee history
eth_sendRawTransactionSend raw transaction
txpool_statusTxpool status
txpool_contentTxpool content
eth_syncingSync state
eth_coinbaseCoinbase
eth_miningMining state
eth_hashrateHashrate
eth_getCodeContract code
eth_getStorageAtStorage slot

Chain ID:

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

Expected result:

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

ZORAI Extension Methods

MethodPurpose
zor_livenessMetricsConsensus liveness metrics
zor_getStatsChain statistics
zor_getValidatorsValidator list
zor_getValidatorValidator details
zor_getAccountCountAccount count
zor_getContractCountContract count
zor_getTotalStakedTotal stake
zor_getBurnedFeesBurned fees
zor_getCommunityPoolCommunity pool
zor_getGPUPowerGPU power
zor_getAvgGasPriceAverage gas price
zor_pausePause node services
zor_unpauseResume node services
zor_pauseStatusPause status

Validator, Bridge, RWA and Compute Methods

Validator methods include validator_getInfo, validator_getStatus, validator_getPendingRewards, validator_join, validator_leave, validator_vote, validator_updateStake, validator_slash, and validator_getUptime.

Bridge methods include bridge_status, bridge_deposit, bridge_burn, bridge_outboundReceipt, bridge_getOutboundReceipt, bridge_listOutboundReceipts, bridge_registerChain, bridge_updateCheckpoint, bridge_registerRelayer, bridge_submitMessage, bridge_addRelayerSignature, bridge_processMessage, bridge_getMessage, bridge_registerWrappedAsset, bridge_listWrappedAssets, bridge_updateWrappedAssetControls, and bridge_burnWrapped.

RWA methods include asset, issuer, document, token, transfer, governance, verification, valuation, compliance, fund, regulatory, dividend, redemption, disclosure and stats APIs. The full dispatch list is in pkg/rpc/rwa_rpc.go:24.

Compute methods include zor_publishTask, zor_acceptTask, zor_submitProof, zor_getTaskStatus, zor_registerNode, zor_updateNodeStatus, zor_getOpenTasks, zor_getMarketStats, zor_getDispute, and zor_getTaskEscrow.

11. Developer Guide

Start a Node

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

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

Core defaults:

[genesis]
chain_id = 70707

[consensus]
block_time = "400ms"

[rpc]
port = 8545
compute_port = 8646

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

Deploy a Contract

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());

Publish an AI Task

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

Issue an RWA Asset

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"
    }]
  }'

12. Technical Parameters and Configuration

Chain Parameters

ParameterValueCode path
Chain ID70707pkg/types/chain.go:3
Chain ID Hex0x11433pkg/types/chain.go:4
Network namezorai-mainnetpkg/types/chain.go:5
Default block time400msconfigs/config.toml:21
Default block gas limit30000000pkg/evm/evm.go:797
Default base fee1 gweipkg/evm/evm.go:793
Target gas ratio50%pkg/evm/evm.go:799

P2P and RPC

ParameterValueCode path
P2P port30303configs/config.toml:12
Protocol ID/zorai/1.0.0pkg/network/network.go:34
Max peers50configs/config.toml:14
JSON-RPC port8545configs/config.toml:27
Compute RPC port8646configs/config.toml:28
Metrics port9200configs/config.toml:77

Current Public 8-node Topology

The current public test topology is 7 validators + 1 RPC-only node, recorded in scripts/nodes.conf.

NodeRoleCode path
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

13. Deployment and Operations

8-node Deployment

Production/public deployment should use scripts/nodes.conf as the inventory source. Each node needs a consistent genesis, validator set and chain ID, a unique node key and validator key, correct external IP/ports, a systemd-managed xihud service and journal logs.

Local stability deployment:

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

720h Monitor and 90s Watchdog

The 720-hour monitor is launched by scripts/stability-test/run_720h_public_monitor.sh:118. It samples block height, peer count, common root and transaction-test state every 30 minutes. The 90-second watchdog is launched by scripts/stability-test/run_liveness_watchdog.sh:4 and creates incident files when height stalls, peer count drops, roots diverge or nodes become unavailable.

Start monitors:

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

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

Continuous transaction test:

DAILY_TARGET_TX=80000 ADD_ADDRESS_EVERY=50 \
  scripts/stability-test/run_continuous_tx_supervised.sh

Control Plane

The control plane is a production-condition component for future node onboarding, topology allocation, configuration delivery, identity-drift checks and full-node status visibility. Server entry is cmd/controlplane/main.go:13, configuration is in internal/controlplane/config/config.go:80, and node registration/heartbeat/config client calls are in pkg/controlplane/client.go:223, pkg/controlplane/client.go:231 and pkg/controlplane/client.go:239.

14. Roadmap and Current Status

Implemented

FeatureStatusEvidence
Chain ID and network parametersimplementedpkg/types/chain.go:3
Blocks and validationimplementedpkg/types/block.go:21, pkg/types/block.go:187
Legacy and EIP-1559 transactionsimplementedpkg/types/transaction.go:17
MPT stateimplementedpkg/state/mpt_state.go:43
LevelDB + WALimplementedpkg/blockchain/store.go:34
London EVMimplementedpkg/evm/evm.go:78
EIP-1559 gasimplementedpkg/evm/evm.go:495
Mempoolimplementedpkg/mempool/mempool.go:91
PoS validatorsimplementedpkg/consensus/pos_complete.go:37
BFT QC / finalityimplementedpkg/consensus/bft.go:76
BFT liveness recoveryimplemented, needs long-running evidencepkg/consensus/bft.go:839
libp2p networkimplementedpkg/network/network.go:107
Ethereum JSON-RPCimplementedpkg/rpc/web3_full.go:598
WebSocket subscriptionsimplementedpkg/websocket/websocket.go:22
Explorer / Token Indexerimplementedcmd/explorer/main.go:235, cmd/explorer/token_indexer.go:23
RWA RPCimplementedpkg/rpc/rwa_rpc.go:24
ERC-3643 template/precompileimplementedcontracts/zorai-token-templates/ZORAIRWAToken.sol:260, pkg/evm/erc3643_precompiled.go:17
Compute Marketimplementedpkg/taskmarket/market.go:17
Compute Relayimplementedpkg/computerelay/relay.go:264
Bridge / Wrapped Assetimplementedpkg/bridge/cross_chain.go:174, pkg/evm/bridge_executor.go:35
Stablecoin V2implementedcontracts/zorai-token-templates/ZORAIStablecoinV2.sol:1
720h monitorimplementedscripts/stability-test/run_720h_public_monitor.sh:118
90s liveness watchdogimplementedscripts/stability-test/run_liveness_watchdog.sh:4
Control plane foundationimplemented, needs production restorationcmd/controlplane/main.go:13

Priority Next Steps

  1. Complete uninterrupted 720h public evidence on the 7 validator + 1 RPC topology.
  2. Restore the control plane as a production operational surface.
  3. Expand BFT fault-injection tests for rate limits, round dispersion, restarts and double-vote cases.
  4. Audit bridge proof, relayer quorum and wrapped-asset replay protection.
  5. Audit RWA compliance, privacy proof, forced transfer, redemption and reporting workflows.
  6. Run wallet/RPC compatibility tests across Hardhat, Foundry, ethers, web3.py and MetaMask.
  7. Continue peak TPS, contract-call, event-log and RPC query load testing.

Appendix A: Command Cheat Sheet

# Build node
go build -o build/xihud ./cmd/xihud

# Run all tests
go test ./...

# Consensus and network tests
go test ./pkg/consensus ./pkg/network

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

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

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