命令行

本页介绍的三个二进制文件均由 cargo build --release 生成：rand-node（节点及运维命令）、rand（屏蔽钱包）和 rand-prover（委托证明者）。每个命令都接受 -h/--help。本页描述 v0.8.0 版本（c0878c3f），即 chain 21 自 2026-10-12 起运行的构建；v0.6.8（chain 20 的构建）行为不同之处会另行说明，v0.8.0 新增的内容集中在末尾的 What chain 21 and v0.8.0 add。早于 v0.8.0 的 rand 钱包无法在 chain 21 上发送交易：约束集 9 更改了每个证明的编码和每个验证密钥，而且自 chain 20 起每条链携带的创世绑定无论如何都会拒绝为另一条链生成的证明。前两者持有不同类型的密钥：节点密钥是用于签署区块的 Dilithium2 密钥对；钱包密钥是屏蔽花费密钥，不在链上签署任何内容。

rand-node

rand-node <COMMAND>
  keygen      Generate a new Dilithium2 key file (refuses to overwrite an existing one)
  address     Print the address, public key, and libp2p peer id of a key file
  genesis     Write a genesis.json: every validator key is staked, each --alloc becomes a deposit note
  alloc-note  Print one genesis alloc note as JSON, RAND or a listed token, for splicing into a genesis
  init        Initialise a data directory from a genesis file
  run         Run the node
  verify      Verify the chain in a data directory without running the node
  db          Database maintenance on a stopped node's data directory
  safety      status | clear-halt | release-lock: a stopped validator's consensus safety state
  status      Show node status
  register    Print this node's Registration, for the wallet that bonds it in
  admit       sign | submit: the validator set's vote to admit a new key (admission by vote)
  unbond      Move bonded stake into unbonding
  withdraw    Pay released stake and rewards into a note at the payout address
  bridge-gov  rotate-pq | rotate-pause | cancel-rotation: the bridge's post-quantum rotations
  vesting     status | claim | revoke | bond | unbond: genesis vesting (chains with a vesting section)
  multisig    id | status | pay | rotate: the signers' side of a multisig account (chains with a multisig section)
  price       status | sign | submit: the validator set's RAND/USD price vote (chains with fees.usd_subsidy)
  aggregator  register | unbond | withdraw — the aggregator role (aggregation chains only)
  aggregate   The aggregate daemon (aggregation chains only)

safety、admit 和 bridge-gov 是 v0.6.8 新增的；multisig 和 price 是 v0.8.0 新增的。没有 balance 和 transfer：转账需要屏蔽花费密钥，而只有钱包持有该密钥。

有一个全局标志 --allow-test-fri-profile（或 RAND_ALLOW_TEST_FRI_PROFILE=1），可让 init、run 和 verify 接受 fri_profile 为 test 的创世文件。该配置约有 17 位安全强度，而任何编写创世文件的人都可以指定它，因此自 v0.6.8 起，没有该标志时节点会拒绝这样的创世文件。测试套件会设置它；其他场景都不应设置。

keygen, address

keygen 以 0600 权限写入 { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> }。该文件是种子的唯一副本。自 v0.6.8 起，keygen 会拒绝已存在的 --out（… already exists or cannot be created; refusing to overwrite a key file）并保持该文件不变；没有 --force，因此要替换旧文件，请先将其移开。v0.6.7 及更早版本会不加询问地覆盖。address 输出 address、public_key（1,312 字节十六进制）和 peer_id。

genesis

打印每个 --alloc 对应的一行 alloc，然后是创世哈希、验证者数与票据数、epoch 长度、五项上限、hc_bundle 与 hc_auth（未给 --auth-guest 时为 none），最后是 gas 行：gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying；未给 --gas-price 时为 gas: none；给了 --program-state-cell-fee 时再多一行 program_state: cell fee N RAND。init 打印同样的 gas 行。五个上限标志的行为一致：省略时，文件中没有该字段，链按默认值运行；给定时，即使取默认值，该字段也计入创世哈希。Chain 20 用这些标志切出（deploy/cut-chain20-genesis.sh）；chain 21（deploy/cut-chain21-genesis.sh，v0.8.0）使用相同的标志，只是 --max-proof-bytes 6291456 --max-block-bytes 19922944 --gas-dynamic 9961472,262144,1250 不同，并增加了 --fees fees.json（burn_base 与 burn_floor）、--perps …（RPL-3，zUSD 上的一个 BTC-PERP 市场）、--multisig MULTISIG.JSON（基金会金库）以及 --auth-multisig-guest（私密多签 guest，hc_auth_multisig）：

--max-program-words 65535 --max-proof-bytes 4194304 --max-block-bytes 20971520 \
--max-call-envelope-bytes 65536 --max-program-public-words 32768 \
--tokens tokens.json \
--bundle-guest v3 --auth-guest --hardening-v6 \
--gas-price 100 --byte-price 800 --bundle-gas-limit 20479 --gas-dynamic 10485760,262144,1250 \
--max-gas-price 10000 --max-byte-price 80000 --gas-byte-load paying \
--envelope-bytes 1860 \
--testnet --binding-domain 1 --proof-window-blocks 1024 --program-state-cell-fee 10000000 \
--epoch-blocks 1000 --faucet --fri-profile production

Chain 18 与 chain 19 使用相同的标志，直至 --envelope-bytes 1860，且不含任何 v0.6.8 的标志。Chain 20 的证明上限为 4 MiB，低于 chain 13 至 16 的 8 MiB；chain 21 为 6 MiB，区块为 19 MiB，为 tier-18 多签授权证明留出空间：一笔拆分授权交易最多携带三个证明，3 × 4 MiB + 1 MiB 可放入 20 MiB 的区块。tokens.json 包含 1 RAND 的 registration_fee、10000000000000 的 mint_cap_per_day、max_tokens 4096、burn_registration_fee 与 bound_note_value，以及列有七项支持资产的 zUSD。没有 --bridge 标志，切出脚本仍会在事后把 bridge、staking 与 consensus_domain 各节拼接进文件（chain 20 与 21 上为：处于守护者集合 1、带八个后量子守护者密钥的桥、暂停密钥、rules_v2、rotation 与 fees；含水龙头白名单、admission_by_vote 以及 2,500 bps 准入额度的 staking 节；consensus_domain: 1；以及用 alloc-note --asset 1 --envelope-bytes 1860 生成的 zUSD 创世票据）。真正有效的创世哈希，是 init 在完成的文件上打印出的那个。

每个 --alloc 会用全新的承诺随机数构建一张存入票据，因此切两次会得到两个不同的哈希。该命令总是把票据的 opening 与 cm、amount 一并写出，带有 tokens 节的链要求如此：

"alloc": [
  { "cm": "<64 hex>",
    "envelope": { "kem_ct": "<hex>", "to_receiver": "<hex>", "to_sender": "<hex>", "body": "<hex>" },
    "amount": 1000000000000,
    "opening": { "pk": "<64 hex>", "time": 0, "r": "<64 hex>" } }
]

因此，创世票据的所有者与金额在文件发布后即按设计公开；只有它之后何时被花费、被花费到何处仍保持私密。创世只切一次，并保存好文件。

alloc-note

--to <rand1…>（必填）、--amount <N>（必填）、--asset <INDEX>（默认 0）、--envelope-bytes <N>（默认：旧格式）。以 JSON 打印一张 alloc 票据，并像 genesis --alloc 那样向 --to 密封。设置了 envelope_bytes 的创世会拒绝未带匹配 --envelope-bytes 密封的票据。--amount 以资产的整数单位计：RAND 为九位小数，桥接代币为八位（资产 1 上的 10 即 10 zUSD）。列入清单的代币的票据，要求该代币的支持资产携带的 locked 数额之和恰好等于其票据总额。

init

打印创世哈希以及与 genesis 相同的 gas: 行。

run

环境变量：RUST_LOG（默认 info,libp2p=warn,libp2p_mdns=off）。Ctrl-C 或 SIGTERM 会让节点干净地关闭。

公共端点 https://rpc.randprotocol.org 是位于归档节点之前的白名单代理；自 2026-10-01 起，其白名单即公共监听器的方法集。

safety

已停止的验证者的共识安全状态（v0.6.8）。每条命令都自行打开数据目录，因此不能与运行中的节点同时执行。

rand-node safety status       --datadir <dir>
rand-node safety clear-halt   --datadir <dir> --i-have-compared-this-node-with-the-fleet
rand-node safety release-lock --datadir <dir> --i-give-up-this-validators-lock

status 打印已提交的头部区块、当前视图与最后投票视图、最高 QC、验证者是否被锁定在其头部之上，以及已记录的安全停机。节点若发现一条经认证的三链试图提交一个并非源自其自身已提交头部的区块，便会停止并记录此事（audit v6，CON-5）；此后 run 会带着该记录退出，直至执行 clear-halt。清除之前，请将本节点的头部与另外两个验证者的头部比对，若有差异，则先从归档重新同步。自 v0.6.8 起（CON-4），任何数量的“未持有”应答都不再能解除锁定：被锁定在一个无法获取的区块上的验证者保持静默，直到收到一个其 justify 高于该锁的提案，或该区块被取回。release-lock 将持久化的锁降至已提交头部的证书；一次只对一个验证者使用，并且仅在该区块确已永久丢失时使用。凡会写入的命令，若不带其确认标志，只打印将要执行的操作，不做任何更改。

verify

若一致，退出码为 0；若发现问题且未使用 --repair，退出码为 2。

db

db drop-receipts-index --datadir <DATADIR>，须在节点停止时执行：在回滚到 v0.3 之前的构建之前，删除 receipts_by_program 索引，因为该构建无法打开带有此索引的数据库。之后再次启动时，将根据收据重建该索引。

status

--rpc <URL>（默认 http://127.0.0.1:8545）。原样打印 rand_status。

register, unbond, withdraw

admit sign|submit

投票准入（v0.6.8）。在创世设置了 staking.admission_by_vote 的链上（如链 20 和 21），新的验证者密钥须经持有严格多于三分之二投票权重的验证者签名准入后，方可注册。

候选者是注册将携带的密钥；rand-node address --key 会将其打印出来，register 打印的十六进制中也包含它。准入提交之后，绑定质押照旧（rand bond … --registration），并消耗该准入。rand_getAdmitted 列出已获准入且在等待的项目。

bridge-gov

桥的后量子轮换（v0.6.8），供守护者与暂停密钥持有者使用。每一步都从 --rpc（默认 http://127.0.0.1:8545）读取链 id、其绑定域以及 rand_getBridgeState.rotation_nonce。

--new-key 是十六进制的 Dilithium2 公钥、存放有一个公钥的 @file，或 @key-file（取其公钥）。签名行的格式为 index:hex，以空白或换行分隔，允许使用 # 注释。

vesting status|claim|revoke|bond|unbond

在创世带有 vesting 部分的链上，这是带时间锁的创世分配的持有者一侧与撤销者一侧的命令。链 20 没有该部分，链 21 也没有。密钥为 rand-node keygen 文件。

aggregator register|unbond|withdraw, aggregate

适用于带有 aggregation 部分的链上聚合者角色的命令：aggregator register --key --bond <RAND> --payout <rand1…> --rpc 打印一份已签名的 AggregatorRegistration；aggregator unbond 与 aggregator withdraw 与验证者的那一对命令相对应。aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] 是轮询 rand_getUnsealed、证明一个聚合并提交的守护进程。在链 21 上不起作用，链 20 亦然：两者的创世都没有 aggregation 部分。自 v0.8.0 起，一次失败的轮次（RPC 失败、nonce 已变动、聚合被拒绝）会被记录并按该间隔重试，而不是令守护进程停止，最多连续 --watch-max-failures（20）次。

multisig id|status|pay|rotate

v0.8.0，多签账户（multisig accounts）的签名者一侧，适用于创世带有 multisig 部分的链，如链 21。创建账户和为其注资属于钱包的命令（rand multisig create / deposit，见下文）；此处的密钥是 rand-node keygen 文件，每位签名者一个。

链 21 的金库 d5fd1883…1958 就是这样一个账户：3 位签名者中需 2 位，在切换时注入了 100,000 RAND。

price status|sign|submit

v0.8.0,验证者集合针对美元挂钩的封装补贴(创世配置 fees.usd_subsidy)所投的 RAND/USD 价格投票,形态与 admit 相同并带有 nonce:price status --rpc 打印已投出的价格、设定该价格的区块高度、该价格对下一个区块是否仍然有效,以及下一个 nonce;price sign --price <dollars> --nonce <N> --key <validator key> --genesis-hash <hex> 离线打印单个验证者的投票;price submit --price … --nonce <N> --signature <line or file> … --rpc 会对照节点的创世哈希、价格和 nonce 检查每一张投票,然后发送免手续费的 SetRandPrice。在链 21 上不生效,因为其创世配置中没有 usd_subsidy:该操作在那里会被拒绝。

run:证明、验证检查点与应用线程(v0.8.0)

run 新增三个标志。--verify-chain quick 是默认的启动检查,若同一个干净构建已将存储验证至其头部(启动检查点,在节点运行时写入),则跳过该检查;--verify-chain replay 强制逐块遍历,而 rand-node verify 始终会遍历。--apply-proposals-inline 恢复 v0.8.0 之前的行为,即在共识循环上应用收到的提案;默认情况下,跟随者在阻塞线程上应用提案(同时最多四个),而预检查和插入仍留在循环上。--msauth-vk <PATH>(默认为 $RAND_MSAUTH_VK,否则为二进制文件旁的 msauth-vk-<profile>.bin)指定固定的多签验证密钥:在指定了 hc_auth_multisig 的链上(如链 21),run 和 verify 会在启动时加载它,没有它则拒绝启动,因此每个链 21 节点都在 rand-node 旁附带 msauth-vk-production.bin(Running a node)。

rand(钱包)

全局选项,可置于子命令之前或之后:

金额为十进制 RAND,最多九位小数(1、1.5、.25、0.000000001)。send、token mint 和 token burn 上的代币金额,以及 randpay: 链接中的代币金额,均以该代币的显示单位计,精度取其登记表行自身的 decimals(10 个 zUSD 即 10 zUSD)。bridge-burn、token create --fixed-supply 和 --initial 取以代币最小单位表示的纯整数,asset-balance 也以此打印。凡是命令需要指定代币之处,都可以使用登记表索引、rpl1… id 或 64 位十六进制 id;id 是根据节点的完整登记表列表(rand_getTokens,每一页)解析为索引的,绝不通过逐个代币的查询,否则会让节点得知哪个代币即将被转移。数字索引则根本不会到达节点。

--cuda 需要使用 --features cuda 构建,且没有回退路径;目前尚未构建 PTX。它无法封装调用输入信封(envelope):rand call --cuda 需要 --no-envelope。它只声明 gas 上限,并拒绝 --gas-limit N。

CLI 打印的每个备注(memo)和联系人名称(send 的确认信息、notes、history、tx-key)都会先经过同一条显示规则:控制字符、Unicode 格式字符(双向控制符、零宽字符、软连字符)以及 U+2028/U+2029 显示为 U+FFFD,连续的空格分隔符显示为一个空格。

multisig-private:外观与任何钱包无异的 T-of-N 账户

v0.8.0,位于 rand_status 中列有 hc_auth_multisig 的链上,如 chain 21。私有多签账户是由 Dilithium2 签名者密钥组成的 T-of-N 策略,其地址和支出与任何钱包无异:账户有查看密钥而没有支出密钥;一次支出是一份提案,由 T 位签名者离线检查并签名,签名隐藏在授权证明之内,因此链上只能得知该交易包已获授权。策略文件保存账户的秘密 msk(它对每个 note 的查看权限),提案则保存见证数据(witness):二者均以 0600 权限写入,绝不覆盖已有文件,也绝不打印。签名者需要策略文件(通过带外方式交给他们)以及各自用 rand-node keygen 生成的密钥。

提案在准备后经过 proof_window_blocks 个区块过期(chain 21 上为 1,024 个区块):必须在此之前收齐签名并完成交易证明,否则需重新 prepare。目前尚无 chain-21 交易包含私有多签支出。

A first shielded transfer

rand keygen                                   # wallet.key.json
rand address                                  # rand1… on stdout, its fingerprint XXXX-XXXX-XXXX-XXXX on stderr
rand faucet                                   # testnet, allowlisted wallets only: 100 RAND into a note only you can open
rand balance                                  # balance: 100 RAND
rand send rand1q9f… 1.5                       # asks to confirm, then a minute and a half to two minutes of local proving, then the commit
rand notes                                    # the spent note, and the change note

Sharing an address, and a memo

rand address --uri --amount 1.5 --memo "invoice #42" --qr   # a randpay: link, as a terminal QR
rand contacts add alice rand1q9f…                           # shows the fingerprint, asks add? [y/N]
rand send alice 1.5 --memo "coffee"                         # the memo is sealed into the payment output
rand history --memo                                         # alice's row shows the whole memo
rand tx-key <hash>                                          # hand the sent row's key to alice or an auditor

备注与 note 位于同一个密封体内,因此能打开其一者即能打开另一者:收款方通过 notes,以及持有该输出每笔交易密钥的任何人通过 rand_checkTransaction <hash> <key>。Chain 18 是首条在创世中设置 envelope_bytes 的链;在 chain 14 至 17 上,--memo 会在任何证明生成之前被拒绝。

A confidential call you can open again later

rand program build --guest balance_check --arg 1000 --out bc.json
rand program deploy bc.json                   # prints the program id
rand call <id> --input 100 --input 200 --input 300 --input 400
rand open-call <txhash>                       # inputs: [100, 200, 300, 400] — verdict: faithful (exit 0)

A stateful program: the RPL-2 counter

在具有 program_state 部分的链上,如 chain 20 和 21。该计数器恰好接受那些读取一个单元并将其写回、且其第一个字加一的状态转换;转换中的其余一切(交易包存入的内容、金库支付的内容、程序铸造的内容)均不加检查地随行,因此它只是一个演示,而不是可以托付价值的程序。

rand program build --guest rpl2_counter --out counter.json
rand program deploy counter.json                          # prints the program id
rand token create --name "Counter Share" --symbol CTR --decimals 0 --program <id>   # say index 2
rand program state <id> --cell 0100000000000000000000000000000000000000000000000000000000000000   # 64 zeros: absent
cat > step.json <<'JSON'
{ "reads":  [{ "key": "0100…00", "value": "0000…00" }],
  "writes": [{ "key": "0100…00", "value": "0100…00" }],
  "deposit": { "rand": "500000000", "kind": "none" },
  "pays":   [{ "asset": 0, "amount": "200000000", "to": "rand1…" }],
  "mints":  [{ "asset": 2, "amount": "1" }] }
JSON
rand program invoke <id> --transition step.json           # exit 3 if the cell moved since; re-read and retry
rand program vault <id>                                   # asset 0: 300000000 units (0.5 RAND in, 0.2 out)

文件中的 … 代表完整的 64 个十六进制字符,钱包要求如此。

What a deploy and a call print

在拆分授权的链上,每个交易包都是在本机生成的两份证明:tier-10 的支出授权和 tier-14 的交易包。2026-09-30 在 chain 18 上使用 rand v0.6.7 执行 program deploy:

proving the spend authorisation on this machine (tier 10; seconds)…
authorisation proved in 6.8s: tier 10, 1368908 bytes
proving the bundle (tier 14; about a minute and a half on a laptop)…
proved in 116.7s: tier 14, 1500710 bytes
submitted deploy <hash>
  0 RAND out, 59.8545 RAND change, fee 0.1007 RAND, anchored at height 97831, proved in 116.7s (bundle) + 6.8s (auth)

call 会在调用证明之前打印其 gas 和费用,然后以同样方式为支付交易包生成证明:

proving the call locally (90 inputs stay private, over the program's 11-word public input)…
gas: 5636 (declaring 6144, tier 12)
fee 0.006191437 RAND (incl. two price steps of headroom)
proved in 29.2s: tier 12, 3346865 bytes, outputs [...]

这里 6,144 是 5,636 向上取整到 2^10 的倍数,而 rand fee call 12 --gas 6144 --bytes <B> 按链尖的价格为该上限定价,不留余量。

rand-prover

作为独立二进制文件的委托证明者:它在另一台机器上生成钱包的 tier-14 交易包证明。rand-node run --prover 在节点内部托管同一服务。每个子命令都接受 --home <DIR>(环境变量 RAND_PROVER_HOME,默认 ~/.rand-prover),即存放 prover.key.json 和 pairings.json 的目录。

在 chain 21 上,与 chain 20 一样,证明者会收到钱包的查看密钥 nk 和一个新的盐值。它无法支出,但可以读取该钱包收到或发出的一切:请与你愿意向其展示历史记录的证明者配对。钱包会检查它收到的每一份证明。

Key file formats

Node key:

{ "seed": "hex of 32 bytes", "address": "base58 of blake3(\"rand-address\" || public key)", "public_key": "hex of 1312-byte Dilithium2 public key" }

Wallet key, version 2:

{ "version": 2, "spend_key": "hex of 8 little-endian u32 words (64 characters)" }

rand keygen 以 0600 权限写入它,自 v0.6.8 起,每个 rand 命令都会拒绝组或其他用户可读的钱包密钥文件:手工复制或恢复的密钥必须重新设置为 0600(chmod 600 <key>)。丢失钱包密钥即丢失它能打开的每一个 note;此版本中没有助记词。

What chain 21 and v0.8.0 add

Chain 21 于 2026-10-12 在 fullnode v0.8.0(c0878c3f)上上线。相对于本页为 chain 20 给出的 v0.6.8 命令集:

• rand-node: multisig id|status|pay|rotate 和 price status|sign|submit;run --verify-chain replay、--apply-proposals-inline 和 --msauth-vk;verify --mode;aggregate --watch-max-failures;genesis --fees、--perps、--multisig、--auth-multisig-guest 和 --aggregation-tree(最后一项迄今在每条链上都被拒绝)。每个 chain-21 节点都需要将 msauth-vk-production.bin 放在 rand-node 旁边。
• rand: multisig create|deposit、perp …、multisig-private …、--threads 和 --cpu(v0.7.1),以及对信封头分页的扫描(rand_getScanLeaves),在较旧节点上回退为完整分页。v0.8.0 钱包只能在 chain 21 上发送;早于 v0.8.0 的钱包无法在任何仍在运行的链上发送。
• rand-prover: 同一个 --threads/--cpu 模块(默认为核心数 − 1,上限为 8)、证明超时(v0.7.0,审计 v7),以及限于回环地址并带有系统调用过滤器的池单元。

fullnode 在 c0878c3f 处自己的 docs/cli.md 即是本页所对照阅读的依据。