Command line

Three binaries come out of cargo build --release: rand-node (the node and the operator commands), rand (the shielded wallet) and rand-prover (the delegated prover). Every command accepts -h/--help. This page describes the v0.8.0 release (c0878c3f), the build chain 21 runs since 2026-10-12; where v0.6.8 (chain 20’s build) behaved differently, it says so, and what v0.8.0 adds is gathered at the end, What chain 21 and v0.8.0 add. A rand wallet older than v0.8.0 cannot send on chain 21: constraint set 9 changed every proof’s encoding and every verifier key, and the genesis binding every chain since 20 carries refuses a proof made for another chain in any case. The first two hold different kinds of key: a node key is a Dilithium2 key pair that signs blocks; a wallet key is a shielded spend key that signs nothing on chain.

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 and bridge-gov are new in v0.6.8; multisig and price in v0.8.0. There is no balance and no transfer: a transfer needs a shielded spend key, which only the wallet holds.

One global flag, --allow-test-fri-profile (or RAND_ALLOW_TEST_FRI_PROFILE=1), lets init, run and verify accept a genesis whose fri_profile is test. That profile is about 17 bits of soundness, and whoever writes a genesis file can name it, so since v0.6.8 a node refuses such a genesis without the flag. The test suites set it; nothing else should.

keygen, address

keygen writes { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } with mode 0600. The file is the only copy of the seed. Since v0.6.8 keygen refuses an --out that already exists (… already exists or cannot be created; refusing to overwrite a key file) and leaves it untouched; there is no --force, so move an old file aside to replace it. v0.6.7 and earlier overwrote it without asking. address prints address, public_key (1,312 bytes hex) and peer_id.

genesis

Prints one alloc line per --alloc, then the genesis hash, the validator and note counts, the epoch length, the five limits, hc_bundle and hc_auth (none without --auth-guest), then the gas line: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, or gas: none without --gas-price, and with --program-state-cell-fee a program_state: cell fee N RAND line. init prints the same gas line. The five limit flags behave alike: omitted, the file has no such field and the chain runs the default; given, the field is part of the genesis hash even at its default value. Chain 20 was cut with these flags (deploy/cut-chain20-genesis.sh); chain 21 (deploy/cut-chain21-genesis.sh, v0.8.0) with the same ones except --max-proof-bytes 6291456 --max-block-bytes 19922944 --gas-dynamic 9961472,262144,1250, plus --fees fees.json (burn_base and burn_floor), --perps … (RPL-3, one BTC-PERP market on zUSD), --multisig MULTISIG.JSON (the foundation treasury) and --auth-multisig-guest (the private-multisig 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

Chains 18 and 19 were cut with the same flags up to --envelope-bytes 1860 and none of the v0.6.8 ones. Chain 20’s proof cap was 4 MiB, down from the 8 MiB of chains 13 to 16, and chain 21’s is 6 MiB with a 19 MiB block, room for the tier-18 multisig auth proof: a split-authorisation transaction carries up to three proofs, and 3 × 4 MiB + 1 MiB fits the 20 MiB block. tokens.json holds a registration_fee of 1 RAND, a mint_cap_per_day of 10000000000000, max_tokens 4096, burn_registration_fee and bound_note_value, and zUSD listed with its seven backings. There is no --bridge flag, and the cut script still splices the bridge, staking and consensus_domain sections into the file afterwards (on chains 20 and 21: the bridge at guardian set 1 with eight PQ guardian keys, the pause key, rules_v2, rotation and fees; the staking section with the faucet allowlist, admission_by_vote and a 2,500 bps entry budget; consensus_domain: 1; and zUSD’s genesis notes, made with alloc-note --asset 1 --envelope-bytes 1860). The genesis hash that counts is the one init prints on the finished file.

Each --alloc builds one deposit note with fresh commitment randomness, so cutting twice yields two different hashes. The command always writes the note’s opening beside cm and amount, which a chain with a tokens section requires:

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

A genesis note’s owner and amount are therefore public by design once the file is published; only when and into what it is later spent stays private. Cut a genesis once and keep the file.

alloc-note

--to <rand1…> (required), --amount <N> (required), --asset <INDEX> (default 0), --envelope-bytes <N> (default: the legacy format). Prints one alloc note as JSON, sealed to --to as genesis --alloc seals one. A genesis that sets envelope_bytes refuses a note sealed without the matching --envelope-bytes. --amount is in whole units of the asset: nine decimals for RAND, eight for a bridged token (10 at asset 1 is 10 zUSD). A note of a listed token needs that token’s backings to carry locked amounts summing to exactly its notes.

init

Prints the genesis hash and the same gas: line as genesis.

run

Environment: RUST_LOG (default info,libp2p=warn,libp2p_mdns=off). Ctrl-C or SIGTERM shuts the node down cleanly.

The public endpoint https://rpc.randprotocol.org is an allowlist proxy in front of an archive node; since 2026-10-01 its allowlist is the public listener’s method set.

safety

A stopped validator’s consensus safety state (v0.6.8). Each command opens the data directory itself, so none runs beside a live node.

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 prints the committed head, the view and last voted view, the high QC, whether the validator is locked above its head, and any recorded safety halt. A node that sees a certified three-chain try to commit a block that does not descend from its own committed head stops and records it (audit v6, CON-5); run then exits with the record until clear-halt. Compare this node’s head with two other validators’ and re-sync from an archive if it differs before clearing. Since v0.6.8 (CON-4) no quorum of “not held” answers releases a lock any more: a validator locked on a block it cannot obtain stays silent until a proposal whose justify outranks the lock arrives or the block is fetched. release-lock lowers the persisted lock to the committed head’s certificate; use it on one validator at a time, and only when the block is lost for good. Without its acknowledgement flag each writing command prints what it would do and changes nothing.

verify

Exit code 0 if consistent, 2 if a problem was found without --repair.

db

db drop-receipts-index --datadir <DATADIR>, with the node stopped: drop the receipts_by_program index before rolling back to a pre-v0.3 build, which cannot open a database that has it. A later start rebuilds the index from the receipts.

status

--rpc <URL> (default http://127.0.0.1:8545). Prints rand_status verbatim.

register, unbond, withdraw

admit sign|submit

Admission by vote (v0.6.8). On a chain whose genesis sets staking.admission_by_vote, as chains 20 and 21 do, a new validator key registers only after validators holding strictly more than two thirds of the voting weight have signed it in.

The candidate is the key the registration will carry; rand-node address --key prints it, and the hex register printed holds it. After the admission commits, the bond is as before (rand bond … --registration) and consumes it. rand_getAdmitted lists what is admitted and waiting.

bridge-gov

The bridge’s post-quantum rotations (v0.6.8), for guardians and the pause-key holder. Every step reads the chain id, its binding domain and rand_getBridgeState.rotation_nonce from --rpc (default http://127.0.0.1:8545).

--new-key is a hex Dilithium2 public key, @file holding one, or @key-file (its public key). Signature lines are index:hex, separated by whitespace or newlines, # comments allowed.

vesting status|claim|revoke|bond|unbond

The holder’s and the revoker’s side of a timelocked genesis allocation, on a chain whose genesis carries a vesting section. Chain 20’s had none and chain 21’s has none. The key is a rand-node keygen file.

aggregator register|unbond|withdraw, aggregate

The aggregator role’s commands for a chain with an aggregation section: aggregator register --key --bond <RAND> --payout <rand1…> --rpc prints a signed AggregatorRegistration; aggregator unbond and aggregator withdraw mirror the validator pair. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] is the daemon that polls rand_getUnsealed, proves one aggregate and submits it. Inert on chain 21, as on chain 20: neither genesis has an aggregation section. Since v0.8.0 a failed pass (an RPC failure, a nonce that moved, a refused aggregate) is logged and retried on the interval rather than stopping the daemon, up to --watch-max-failures (20) in a row.

multisig id|status|pay|rotate

v0.8.0, the signers’ side of a multisig account (multisig accounts), on a chain whose genesis carries a multisig section, as chain 21’s does. Creating and funding an account are the wallet’s (rand multisig create / deposit, below); the key here is a rand-node keygen file, one per signer.

The chain-21 treasury, d5fd1883…1958, is such an account: 2 of 3 signers, seeded with 100,000 RAND at the cut.

price status|sign|submit

v0.8.0, the validator set’s RAND/USD price vote for the dollar-indexed sealing subsidy (genesis fees.usd_subsidy), in admit’s shape with a nonce: price status --rpc prints the voted price, the height that set it, whether it is fresh for the next block and the next nonce; price sign --price <dollars> --nonce <N> --key <validator key> --genesis-hash <hex> prints one validator’s vote, offline; price submit --price … --nonce <N> --signature <line or file> … --rpc checks every vote against the node’s genesis hash, price and nonce and sends the fee-less SetRandPrice. Inert on chain 21, whose genesis has no usd_subsidy: the action is refused there.

run: proving, the verify checkpoint and the apply thread (v0.8.0)

Three run flags are new. --verify-chain quick, the default startup check, is skipped when this same clean build already verified the store through its head (the startup checkpoint, written as the node runs); --verify-chain replay forces the walk, and rand-node verify always walks. --apply-proposals-inline restores the pre-v0.8.0 behaviour of applying an incoming proposal on the consensus loop; by default a follower applies it on a blocking thread (at most four at once) while the prechecks and the insert stay on the loop. --msauth-vk <PATH> (default $RAND_MSAUTH_VK, else msauth-vk-<profile>.bin beside the binary) names the pinned multisig verifier key: on a chain naming hc_auth_multisig, as chain 21 does, run and verify load it at start and refuse to start without it, so every chain-21 node ships msauth-vk-production.bin next to rand-node (Running a node).

rand (wallet)

Global options, before or after the subcommand:

Amounts are decimal RAND with up to nine decimals (1, 1.5, .25, 0.000000001). A token amount on send, token mint and token burn, and in a randpay: link, is in the token’s display units, at its registry row’s own decimals (10 of zUSD is 10 zUSD). bridge-burn, token create --fixed-supply and --initial take plain integers in the token’s smallest unit, and asset-balance prints them. Wherever a command takes a token, it takes the registry index, the rpl1… id or the 64-hex id; an id is resolved to its index from the node’s whole registry listing (rand_getTokens, every page), never by a per-token lookup, which would tell the node which token is about to move. A numeric index never reaches the node at all.

--cuda requires a build with --features cuda and has no fallback; no PTX has been built yet. It cannot seal a call-input envelope: rand call --cuda needs --no-envelope. It declares the gas ceiling only, and refuses --gas-limit N.

Every memo and contact name the CLI prints (send’s confirmation, notes, history, tx-key) goes through one display rule first: control characters, Unicode format characters (bidi controls, zero-width characters, the soft hyphen) and U+2028/U+2029 are shown as U+FFFD, and a run of space separators as one space.

multisig-private: a T-of-N account that looks like any wallet

v0.8.0, on a chain whose rand_status names hc_auth_multisig, as chain 21 does. A private multisig account is a T-of-N policy of Dilithium2 signer keys whose address and spends look like any wallet’s: the account has a viewing key and no spend key; a spend is a proposal that T signers check and sign offline, and the signatures are hidden inside the auth proof, so the chain learns only that the bundle was authorised. The policy file holds the account’s secret msk (its viewing power over every note) and a proposal holds the witness: both are written mode 0600, never over an existing file, and never printed. Signers need the policy file (handed to them out of band) and a rand-node keygen key of their own.

A proposal expires proof_window_blocks after it is prepared (1,024 blocks on chain 21): the shares must be gathered and the transaction proved before then, or prepare again. No chain-21 transaction has carried a private-multisig spend yet.

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

The memo sits inside the same sealed body as the note, so whoever can open one can open the other: the payee through notes, and anyone holding that output’s per-transaction key through rand_checkTransaction <hash> <key>. Chain 18 is the first chain whose genesis sets envelope_bytes; on chains 14 to 17 --memo was refused before anything proved.

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

On a chain with a program_state section, as chains 20 and 21 are. The counter accepts exactly the transitions that read one cell and write it back with its first word plus one; everything else in the transition (what the bundle deposits, what the vault pays, what the program mints) rides along unchecked, which makes it a demonstration and not a program to put value behind.

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)

The … in the file stand for the full 64 hex characters, which the wallet requires.

What a deploy and a call print

On a split-authorisation chain every bundle is two proofs made on this machine: the tier-10 spend authorisation and the tier-14 bundle. A program deploy with rand v0.6.7 on chain 18, 2026-09-30:

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)

A call prints its gas and its fee before the call proof, then proves the paying bundle the same way:

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 [...]

Here 6,144 is 5,636 rounded up to a multiple of 2^10, and rand fee call 12 --gas 6144 --bytes <B> prices that limit at the tip’s prices with no headroom.

rand-prover

The delegated prover as a binary of its own: it makes a wallet’s tier-14 bundle proof on another machine. rand-node run --prover hosts the same service inside a node. Every subcommand takes --home <DIR> (env RAND_PROVER_HOME, default ~/.rand-prover), the directory that holds prover.key.json and pairings.json.

A prover on chain 21, as on chain 20, receives the wallet’s viewing key nk and a fresh salt. It cannot spend, and it can read everything that wallet ever received or sent: pair with a prover you would show your history to. The wallet checks every proof it gets back.

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 writes it with mode 0600, and since v0.6.8 every rand command refuses a wallet key file that group or other can read: a key copied or restored by hand must be set back to 0600 (chmod 600 <key>). Losing a wallet key loses every note it could open; there is no recovery phrase in this release.

What chain 21 and v0.8.0 add

Chain 21 went live on 2026-10-12 on fullnode v0.8.0 (c0878c3f). Against the v0.6.8 command set, as this page gave it for chain 20:

• rand-node: multisig id|status|pay|rotate and price status|sign|submit; run --verify-chain replay, --apply-proposals-inline and --msauth-vk; verify --mode; aggregate --watch-max-failures; genesis --fees, --perps, --multisig, --auth-multisig-guest and --aggregation-tree (the last refused on every chain so far). Every chain-21 node needs msauth-vk-production.bin beside rand-node.
• rand: multisig create|deposit, perp …, multisig-private …, --threads and --cpu (v0.7.1), and a scan that pages envelope heads (rand_getScanLeaves) and falls back to full pages on an older node. A v0.8.0 wallet sends on chain 21 only; a wallet older than v0.8.0 sends on no chain that still runs.
• rand-prover: the same --threads/--cpu module (cores − 1 by default, capped at 8), a proving timeout (v0.7.0, audit v7), and the pool unit confined to loopback with a syscall filter.

The fullnode’s own docs/cli.md at c0878c3f is what this page is read against.