命令列

三個二進位檔案由 cargo build --release 產出：rand-node（節點及營運者指令）、rand（shielded 錢包）與 rand-prover（委派 prover）。每個指令均接受 -h/--help。本頁描述 v0.6.8 版本（c9c9bd3c），即 chain 20 所運行的構建；v0.6.7 的行為有所不同之處，會另行註明。早於 v0.6.8 的 rand 錢包無法在 chain 20 上發送交易，因為其創世區塊將每個證明與已簽署訊息均綁定至該創世區塊的雜湊。前兩者所持的密鑰種類不同：節點密鑰是用於為區塊簽署的 Dilithium2 密鑰對；錢包密鑰是 shielded 花費密鑰，不會在鏈上簽署任何內容。

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)
  aggregator  register | unbond | withdraw — the aggregator role (aggregation chains only)
  aggregate   The aggregate daemon (aggregation chains only)

safety、admit 與 bridge-gov 為 v0.6.8 新增。系統沒有 balance 或 transfer：轉賬需要 shielded 花費密鑰，而只有錢包持有該密鑰。

有一個全域旗標 --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 起，若 --out 已存在，keygen 會拒絕執行（… already exists or cannot be created; refusing to overwrite a key file），並保持原檔不變；系統沒有 --force，因此要替換舊檔案，須先將其移開。v0.6.7 及更早版本會在不詢問的情況下覆寫。address 會輸出 address、public_key（1,312 byte 的十六進位）及 peer_id。

genesis

指令會為每個 --alloc 輸出一行 alloc，然後輸出創世雜湊、validator 與 note 的數目、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）：

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

第18和第19條鏈以相同旗標切出,直至 --envelope-bytes 1860 為止,而 v0.6.8 的旗標一概沒有使用。證明大小上限為 4 MiB,低於第 13 至 16 條鏈的 8 MiB:一筆拆分授權的交易最多帶有三份證明,而 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 各節拼接進檔案(在第20條鏈上:bridge 設於守護者集合 1,帶有八把後量子守護者金鑰、暫停金鑰、rules_v2、rotation 與 fees;staking 一節載有水龍頭允許名單、admission_by_vote 及 2,500 bps 的加入額度;consensus_domain: 1;以及 zUSD 的創世 note,以 alloc-note --asset 1 --envelope-bytes 1860 製成)。具意義的創世雜湊,是 init 在完成的檔案上所印出的那一個。

每個 --alloc 會以全新的承諾隨機數建立一個存入 note,因此切創世兩次會得出兩個不同的雜湊。該命令總會在 cm 與 amount 旁寫入該 note 的開啟資料(opening),而設有 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>" } }
]

因此,創世檔案一經發布,創世 note 的擁有者與金額即按設計公開;只有它日後在何時、花用到何處,仍保持私密。創世只切一次,並保存該檔案。

alloc-note

--to <rand1…>(必填)、--amount <N>(必填)、--asset <INDEX>(預設 0)、--envelope-bytes <N>(預設:舊版格式)。以 JSON 印出一個 alloc note,並如 genesis --alloc 封裝 note 般,向 --to 封裝。設有 envelope_bytes 的創世,會拒絕未帶相符 --envelope-bytes 而封裝的 note。--amount 以資產的整數單位計:RAND 為九位小數,橋接代幣為八位(資產 1 的 10 即 10 zUSD)。屬於已列出代幣的 note,要求該代幣的支持資產所帶的 locked 金額,總和須恰好等於其 note 的總額。

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、驗證者是否鎖定於鏈首之上,以及任何已記錄的安全停機。若節點見到已認證的三鏈試圖提交一個並非源自其自身已提交鏈首的區塊,便會停止並記錄此事(審計 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 的鏈上(如 chain 20),新的驗證者密鑰必須先獲持有嚴格多於三分之二投票權重的驗證者簽署准入,方可註冊。

候選者即註冊將帶有的密鑰;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 部分的鏈上,持有人及撤銷方對鎖定期創世分配的操作。Chain 20 並無此部分。密鑰為 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、證明一個聚合並提交的常駐程式。在 chain 20 上不起作用,因其創世沒有 aggregation 部分。

rand(錢包)

全域選項,可置於子指令之前或之後:

數額為十進制 RAND,最多九位小數(1、1.5、.25、0.000000001)。send、token mint 及 token burn 上的代幣數額,以及 randpay: 連結中的代幣數額,均以代幣的顯示單位計,採用其登記冊列的 decimals(zUSD 的 10 即 10 zUSD)。bridge-burn、token create --fixed-supply 及 --initial 取代幣最小單位的純整數,asset-balance 亦以此印出。凡指令需要指定代幣,均可使用登記冊索引、rpl1… id 或 64 位十六進制 id;id 是根據節點完整的登記冊清單(rand_getTokens,每一頁)解析為索引,絕不會逐個代幣查詢,否則會讓節點得知哪個代幣即將轉移。數字索引則完全不會送達節點。

--cuda 須以 --features cuda 構建，且沒有後備方案；目前尚未構建任何 PTX。它無法封裝調用輸入信封（call-input envelope）：rand call --cuda 須加 --no-envelope。它只聲明 gas 上限，並拒絕 --gas-limit N。

CLI 輸出的每個備註和聯絡人名稱（send 的確認訊息、notes、history、tx-key）都會先經過同一條顯示規則：控制字元、Unicode 格式字元（雙向控制字元、零寬字元、軟連字號）以及 U+2028/U+2029 一律顯示為 U+FFFD，連續的空格分隔符則顯示為單一空格。

第一筆屏蔽轉賬

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

分享地址與備註

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

備註與票據位於同一個密封主體之內，因此能打開其中一個的人也能打開另一個：收款人透過 notes，而持有該輸出的每筆交易密鑰者，則透過 rand_checkTransaction <hash> <key>。chain 18 是首條在創世區塊中設定 envelope_bytes 的鏈；在 chain 14 至 17 上，--memo 會在任何證明生成之前即被拒絕。

日後可再次打開的保密調用

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)

有狀態程式：RPL-2 計數器

適用於設有 program_state 區段的鏈，例如 chain 20。計數器只接受這樣的狀態轉換：讀取一個單元，並寫回其第一個字加一的值；轉換中的其餘部分（資料包存入的款項、金庫支付的款項、程式鑄造的數額）均不經檢查，因此它僅供示範，不宜用作承載價值的程式。

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 個十六進制字元，錢包要求必須提供完整內容。

部署與調用會輸出甚麼

在分離授權的鏈上，每個資料包都包含在本機生成的兩個證明：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

委託證明者（delegated prover）是獨立的二進制程式：它在另一部機器上為錢包生成 tier-14 資料包證明。rand-node run --prover 則在節點內部提供同一項服務。每個子命令均接受 --home <DIR>（環境變數 RAND_PROVER_HOME，預設為 ~/.rand-prover），即存放 prover.key.json 與 pairings.json 的目錄。

chain 20 上的證明者會收到錢包的查看密鑰 nk 和一個新的鹽值。它無法花費資金，但可以讀取該錢包曾經收到或發出的一切：請只與你願意讓其查看歷史記錄的證明者配對。錢包會檢驗收回的每一個證明。

密鑰檔案格式

節點密鑰：

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

錢包密鑰，版本 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>）。遺失錢包密鑰，即失去它所能打開的每一張票據；此版本沒有助記詞可供復原。