Riga di comando

Dalla cargo build --release escono tre binari: rand-node (il nodo e i comandi dell’operatore), rand (il wallet schermato) e rand-prover (il prover delegato). Ogni comando accetta -h/--help. Questa pagina descrive la release v0.6.8 (c9c9bd3c), la build su cui gira la chain 20; dove v0.6.7 si comportava in modo diverso, lo indica. Un wallet rand precedente a v0.6.8 non può inviare sulla chain 20, il cui genesis lega ogni prova e ogni messaggio firmato al proprio hash. I primi due custodiscono tipi diversi di chiave: una chiave del nodo è una coppia di chiavi Dilithium2 che firma i blocchi; una chiave del wallet è una chiave di spesa schermata che non firma nulla 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)
  aggregator  register | unbond | withdraw — the aggregator role (aggregation chains only)
  aggregate   The aggregate daemon (aggregation chains only)

safety, admit e bridge-gov sono nuovi in v0.6.8. Non esistono né balance né transfer: un trasferimento richiede una chiave di spesa schermata, che solo il wallet possiede.

Un flag globale, --allow-test-fri-profile (o RAND_ALLOW_TEST_FRI_PROFILE=1), permette a init, run e verify di accettare un genesis il cui fri_profile è test. Quel profilo offre circa 17 bit di soundness e chiunque scriva un file genesis può indicarlo, per cui da v0.6.8 un nodo rifiuta un tale genesis senza il flag. Le suite di test lo impostano; nient’altro dovrebbe farlo.

keygen, address

keygen scrive { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } con modalità 0600. Il file è l’unica copia del seed. Da v0.6.8 keygen rifiuta un --out già esistente (… already exists or cannot be created; refusing to overwrite a key file) e lo lascia intatto; non esiste --force, quindi per sostituire un vecchio file occorre prima spostarlo altrove. v0.6.7 e le versioni precedenti lo sovrascrivevano senza chiedere. address stampa address, public_key (1.312 byte in esadecimale) e peer_id.

genesis

Stampa una riga alloc per ogni --alloc, poi l’hash del genesis, i conteggi di validatori e note, la lunghezza dell’epoca, i cinque limiti, hc_bundle e hc_auth (none senza --auth-guest), quindi la riga del gas: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, oppure gas: none senza --gas-price, e con --program-state-cell-fee una riga program_state: cell fee N RAND. init stampa la stessa riga del gas. I cinque flag dei limiti si comportano allo stesso modo: se omessi, il file non ha il campo corrispondente e la chain usa il valore predefinito; se indicati, il campo fa parte dell’hash del genesis anche al suo valore predefinito. La chain 20 è stata creata con questi flag (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

Le catene 18 e 19 sono state create con gli stessi flag fino a --envelope-bytes 1860 e senza nessuno di quelli della v0.6.8. Il limite di dimensione delle prove è 4 MiB, in calo rispetto agli 8 MiB delle catene da 13 a 16: una transazione con autorizzazione suddivisa porta fino a tre prove, e 3 × 4 MiB + 1 MiB entrano nel blocco da 20 MiB. tokens.json contiene una registration_fee di 1 RAND, una mint_cap_per_day di 10000000000000, max_tokens 4096, burn_registration_fee e bound_note_value, e zUSD elencato con i suoi sette backing. Non esiste un flag --bridge, e lo script di creazione inserisce ancora in seguito nel file le sezioni bridge, staking e consensus_domain (sulla catena 20: il bridge al guardian set 1 con otto chiavi PQ dei guardiani, la chiave di pausa, rules_v2, rotation e fees; la sezione staking con la allowlist del faucet, admission_by_vote e un budget di ingresso di 2.500 bps; consensus_domain: 1; e le note di genesi di zUSD, create con alloc-note --asset 1 --envelope-bytes 1860). L’hash di genesi che conta è quello che init stampa sul file finito.

Ogni --alloc costruisce una nota di deposito con una nuova casualità dell’impegno, quindi creare la genesi due volte produce due hash diversi. Il comando scrive sempre l’apertura della nota accanto a cm e amount, cosa che una catena con una sezione tokens richiede:

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

Il proprietario e l’importo di una nota di genesi sono quindi pubblici per progetto una volta pubblicato il file; solo il momento in cui viene spesa in seguito, e verso che cosa, resta privato. Crea la genesi una sola volta e conserva il file.

alloc-note

--to <rand1…> (obbligatorio), --amount <N> (obbligatorio), --asset <INDEX> (predefinito 0), --envelope-bytes <N> (predefinito: il formato legacy). Stampa come JSON una nota di allocazione, sigillata verso --to come la sigilla genesis --alloc. Una genesi che imposta envelope_bytes rifiuta una nota sigillata senza il corrispondente --envelope-bytes. --amount è in unità intere dell’asset: nove decimali per RAND, otto per un token bridged (10 con asset 1 sono 10 zUSD). Una nota di un token elencato richiede che i backing di quel token portino importi locked la cui somma sia esattamente pari alle sue note.

init

Stampa l’hash di genesi e la stessa riga gas: di genesis.

run

Ambiente: RUST_LOG (predefinito info,libp2p=warn,libp2p_mdns=off). Ctrl-C o SIGTERM arrestano il nodo in modo pulito.

L’endpoint pubblico https://rpc.randprotocol.org è un proxy con allowlist davanti a un nodo archivio; dal 2026-10-01 la sua allowlist è l’insieme di metodi del listener pubblico.

safety

Lo stato di sicurezza del consenso di un validatore arrestato (v0.6.8). Ogni comando apre da sé la directory dei dati, quindi nessuno gira accanto a un nodo attivo.

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 stampa la testa committed, la view e l’ultima view votata, il QC più alto, se il validatore è bloccato sopra la sua testa e qualsiasi arresto di sicurezza registrato. Un nodo che vede una three-chain certificata tentare di eseguire il commit di un blocco che non discende dalla propria testa committed si ferma e lo registra (audit v6, CON-5); run termina poi con quella registrazione fino a clear-halt. Confronta la testa di questo nodo con quella di altri due validatori e, se differisce, risincronizza da un archivio prima di cancellare. Dalla v0.6.8 (CON-4) nessun quorum di risposte “not held” sblocca più un lock: un validatore bloccato su un blocco che non riesce a ottenere resta in silenzio finché non arriva una proposta il cui justify supera il lock o il blocco viene recuperato. release-lock abbassa il lock persistito al certificato della testa committed; usalo su un validatore alla volta, e solo quando il blocco è perso per sempre. Senza il suo flag di conferma ogni comando di scrittura stampa ciò che farebbe e non modifica nulla.

verify

Codice di uscita 0 se coerente, 2 se è stato trovato un problema senza --repair.

db

db drop-receipts-index --datadir <DATADIR>, con il nodo arrestato: elimina l’indice receipts_by_program prima di tornare a una build precedente alla v0.3, che non può aprire un database che lo contiene. Un avvio successivo ricostruisce l’indice dalle ricevute.

status

--rpc <URL> (predefinito http://127.0.0.1:8545). Stampa rand_status alla lettera.

register, unbond, withdraw

admit sign|submit

Ammissione per voto (v0.6.8). Su una chain il cui genesis imposta staking.admission_by_vote, come quello della chain 20, una nuova chiave di validatore si registra solo dopo che i validatori che detengono strettamente più di due terzi del peso di voto l’hanno approvata con la propria firma.

Il candidato è la chiave che la registrazione porterà con sé; rand-node address --key la stampa, e l’esadecimale stampato da register la contiene. Dopo che l’ammissione è stata confermata, il bond procede come prima (rand bond … --registration) e la consuma. rand_getAdmitted elenca ciò che è ammesso e in attesa.

bridge-gov

Le rotazioni post-quantistiche del bridge (v0.6.8), per i guardiani e per il detentore della pause key. Ogni passaggio legge da --rpc (predefinito http://127.0.0.1:8545) l’id della chain, il suo dominio di binding e rand_getBridgeState.rotation_nonce.

--new-key è una chiave pubblica Dilithium2 in esadecimale, @file che ne contiene una, oppure @key-file (la sua chiave pubblica). Le righe di firma hanno la forma index:hex, separate da spazi o a capo; sono ammessi commenti con #.

vesting status|claim|revoke|bond|unbond

Il lato del detentore e quello del revocatore di un’allocazione di genesis soggetta a timelock, su una chain il cui genesis contiene una sezione vesting. Quello della chain 20 non ne ha. La chiave è un file di rand-node keygen.

aggregator register|unbond|withdraw, aggregate

I comandi del ruolo di aggregatore per una chain con una sezione aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc stampa una AggregatorRegistration firmata; aggregator unbond e aggregator withdraw rispecchiano la coppia del validatore. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] è il demone che interroga rand_getUnsealed, dimostra un aggregato e lo invia. Inerte sulla chain 20, il cui genesis non ha alcuna sezione aggregation.

rand (wallet)

Opzioni globali, prima o dopo il sottocomando:

Gli importi sono RAND decimali con fino a nove decimali (1, 1.5, .25, 0.000000001). Un importo in token su send, token mint e token burn, e in un link randpay:, è espresso nelle unità di visualizzazione del token, secondo i decimals propri della riga del suo registro (10 di zUSD sono 10 zUSD). bridge-burn, token create --fixed-supply e --initial accettano interi semplici nell’unità più piccola del token, e asset-balance li stampa. Ovunque un comando accetti un token, accetta l’indice di registro, l’id rpl1… o l’id di 64 caratteri esadecimali; un id viene risolto nel suo indice a partire dall’elenco completo del registro del nodo (rand_getTokens, ogni pagina), mai con una ricerca per singolo token, che direbbe al nodo quale token sta per essere spostato. Un indice numerico non raggiunge mai il nodo.

--cuda richiede una build con --features cuda e non prevede alcun ripiego; non è ancora stato compilato alcun PTX. Non può sigillare un envelope di input della chiamata: rand call --cuda richiede --no-envelope. Dichiara solo il tetto di gas e rifiuta --gas-limit N.

Ogni memo e ogni nome di contatto che la CLI stampa (la conferma di send, notes, history, tx-key) passa prima per un’unica regola di visualizzazione: i caratteri di controllo, i caratteri di formato Unicode (controlli bidirezionali, caratteri a larghezza zero, il trattino morbido) e U+2028/U+2029 sono mostrati come U+FFFD, e una sequenza di separatori di spazio come un solo spazio.

Un primo trasferimento shielded

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

Condividere un indirizzo, e un 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

Il memo si trova nello stesso corpo sigillato della nota, quindi chi può aprire l’uno può aprire l’altra: il destinatario tramite notes, e chiunque possieda la chiave per transazione di quell’output tramite rand_checkTransaction <hash> <key>. La chain 18 è la prima chain il cui genesis imposta envelope_bytes; sulle chain da 14 a 17 --memo veniva rifiutato prima ancora di generare qualsiasi prova.

Una chiamata riservata che puoi riaprire in seguito

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)

Un programma con stato: il contatore RPL-2

Su una chain con una sezione program_state, come la chain 20. Il contatore accetta esattamente le transizioni che leggono una cella e la riscrivono con la sua prima parola aumentata di uno; tutto il resto della transizione (ciò che il bundle deposita, ciò che il vault paga, ciò che il programma conia) passa senza alcun controllo, il che ne fa una dimostrazione e non un programma su cui appoggiare valore.

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)

I … nel file stanno per i 64 caratteri esadecimali completi, che il wallet richiede.

Che cosa stampano un deploy e una chiamata

Su una chain con autorizzazione separata ogni bundle comporta due prove generate su questa macchina: l’autorizzazione di spesa di tier 10 e il bundle di tier 14. Un program deploy con rand v0.6.7 sulla 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)

Una call stampa il suo gas e la sua commissione prima della prova della chiamata, poi dimostra allo stesso modo il bundle di pagamento:

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

Qui 6,144 è 5,636 arrotondato per eccesso a un multiplo di 2^10, e rand fee call 12 --gas 6144 --bytes <B> quota quel limite ai prezzi della punta della chain, senza margine.

rand-prover

Il prover delegato come binario a sé stante: genera la prova del bundle di tier 14 di un wallet su un’altra macchina. rand-node run --prover ospita lo stesso servizio all’interno di un nodo. Ogni sottocomando accetta --home <DIR> (env RAND_PROVER_HOME, predefinito ~/.rand-prover), la directory che contiene prover.key.json e pairings.json.

Un prover sulla chain 20 riceve la viewing key nk del wallet e un salt nuovo. Non può spendere, e può leggere tutto ciò che quel wallet ha mai ricevuto o inviato: abbinati a un prover a cui mostreresti la tua cronologia. Il wallet verifica ogni prova che riceve.

Formati dei file di chiave

Chiave del nodo:

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

Chiave del wallet, versione 2:

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

rand keygen la scrive con modalità 0600, e dalla v0.6.8 ogni comando rand rifiuta un file di chiave del wallet leggibile da gruppo o altri: una chiave copiata o ripristinata a mano deve essere riportata a 0600 (chmod 600 <key>). Perdere una chiave del wallet significa perdere ogni nota che avrebbe potuto aprire; in questa versione non esiste alcuna frase di recupero.