Ligne de commande

Trois binaires sortent de cargo build --release : rand-node (le nœud et les commandes d’opérateur), rand (le portefeuille protégé) et rand-prover (le prouveur délégué). Chaque commande accepte -h/--help. Cette page décrit la version v0.6.8 (c9c9bd3c), le build qu’exécute la chain 20 ; lorsque v0.6.7 se comportait autrement, elle le signale. Un portefeuille rand antérieur à v0.6.8 ne peut pas envoyer sur la chain 20, dont le genesis lie chaque preuve et chaque message signé à son hash. Les deux premiers détiennent des clés de nature différente : une clé de nœud est une paire de clés Dilithium2 qui signe les blocs ; une clé de portefeuille est une clé de dépense protégée qui ne signe rien 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 et bridge-gov sont nouveaux dans v0.6.8. Il n’existe ni balance ni transfer : un transfert exige une clé de dépense protégée, que seul le portefeuille détient.

Un indicateur global, --allow-test-fri-profile (ou RAND_ALLOW_TEST_FRI_PROFILE=1), permet à init, run et verify d’accepter un genesis dont le fri_profile vaut test. Ce profil offre environ 17 bits de sécurité, et quiconque écrit un fichier genesis peut le nommer ; c’est pourquoi, depuis v0.6.8, un nœud refuse un tel genesis sans cet indicateur. Les suites de tests l’activent ; rien d’autre ne devrait le faire.

keygen, address

keygen écrit { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } avec le mode 0600. Le fichier est la seule copie de la graine. Depuis v0.6.8, keygen refuse un --out qui existe déjà (… already exists or cannot be created; refusing to overwrite a key file) et le laisse intact ; il n’existe pas de --force, il faut donc déplacer l’ancien fichier pour le remplacer. v0.6.7 et les versions antérieures l’écrasaient sans rien demander. address affiche address, public_key (1 312 octets en hexadécimal) et peer_id.

genesis

Affiche une ligne alloc par --alloc, puis le hash du genesis, le nombre de validateurs et de notes, la longueur de l’époque, les cinq limites, hc_bundle et hc_auth (none sans --auth-guest), puis la ligne gas : gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, ou gas: none sans --gas-price, et avec --program-state-cell-fee une ligne program_state: cell fee N RAND. init affiche la même ligne gas. Les cinq indicateurs de limite se comportent de la même façon : omis, le fichier n’a pas ce champ et la chaîne applique la valeur par défaut ; donné, le champ fait partie du hash du genesis même à sa valeur par défaut. La chain 20 a été créée avec ces indicateurs (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

Les chaînes 18 et 19 ont été créées avec les mêmes options, jusqu’à --envelope-bytes 1860, et sans aucune de celles de la v0.6.8. Le plafond des preuves est de 4 MiB, contre 8 MiB pour les chaînes 13 à 16 : une transaction à autorisation partagée porte jusqu’à trois preuves, et 3 × 4 MiB + 1 MiB tiennent dans le bloc de 20 MiB. tokens.json contient un registration_fee de 1 RAND, un mint_cap_per_day de 10000000000000, max_tokens à 4096, burn_registration_fee et bound_note_value, ainsi que zUSD, listé avec ses sept garanties. Il n’existe pas d’option --bridge, et le script de création insère encore a posteriori dans le fichier les sections bridge, staking et consensus_domain (sur la chaîne 20 : le bridge au guardian set 1 avec huit clés de guardians post-quantiques, la clé de pause, rules_v2, rotation et fees ; la section staking avec la liste d’autorisation du faucet, admission_by_vote et un budget d’entrée de 2 500 bps ; consensus_domain: 1 ; et les notes de genèse de zUSD, produites avec alloc-note --asset 1 --envelope-bytes 1860). Le hash de genèse qui fait foi est celui qu’affiche init sur le fichier terminé.

Chaque --alloc construit une note de dépôt avec une aléa d’engagement neuf ; créer deux fois la chaîne donne donc deux hashs différents. La commande écrit toujours l’ouverture de la note à côté de cm et amount, ce que requiert une chaîne dotée d’une section 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>" } }
]

Le propriétaire et le montant d’une note de genèse sont donc publics par conception dès la publication du fichier ; seuls le moment où elle est dépensée par la suite, et ce en quoi elle l’est, restent privés. Ne créez une genèse qu’une seule fois et conservez le fichier.

alloc-note

--to <rand1…> (obligatoire), --amount <N> (obligatoire), --asset <INDEX> (par défaut 0), --envelope-bytes <N> (par défaut : le format historique). Affiche une note d’allocation au format JSON, scellée pour --to comme le fait genesis --alloc. Une genèse qui définit envelope_bytes refuse toute note scellée sans l’option --envelope-bytes correspondante. --amount est exprimé en unités entières de l’actif : neuf décimales pour RAND, huit pour un jeton ponté (10 pour l’actif 1 correspond à 10 zUSD). Une note d’un jeton listé exige que les garanties de ce jeton portent des montants locked dont la somme égale exactement ses notes.

init

Affiche le hash de genèse et la même ligne gas: que genesis.

run

Environnement : RUST_LOG (par défaut info,libp2p=warn,libp2p_mdns=off). Ctrl-C ou SIGTERM arrête proprement le nœud.

Le point d’accès public https://rpc.randprotocol.org est un proxy à liste d’autorisation placé devant un nœud d’archive ; depuis le 2026-10-01, sa liste d’autorisation est le jeu de méthodes de l’écouteur public.

safety

L’état de sûreté du consensus d’un validateur arrêté (v0.6.8). Chaque commande ouvre elle-même le répertoire de données ; aucune ne s’exécute donc en parallèle d’un nœud actif.

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 affiche la tête validée, la vue et la dernière vue votée, le high QC, si le validateur est verrouillé au-dessus de sa tête, et tout arrêt de sûreté enregistré. Un nœud qui voit une chaîne de trois blocs certifiée tenter de valider un bloc ne descendant pas de sa propre tête validée s’arrête et l’enregistre (audit v6, CON-5) ; run se termine alors avec cet enregistrement jusqu’à clear-halt. Comparez la tête de ce nœud avec celles de deux autres validateurs et resynchronisez-le depuis une archive si elle diffère, avant d’effacer l’arrêt. Depuis la v0.6.8 (CON-4), aucun quorum de réponses « non détenu » ne lève plus un verrou : un validateur verrouillé sur un bloc qu’il ne peut obtenir reste silencieux jusqu’à l’arrivée d’une proposition dont le justify surclasse le verrou, ou jusqu’à ce que le bloc soit récupéré. release-lock abaisse le verrou persistant au certificat de la tête validée ; ne l’utilisez que sur un validateur à la fois, et seulement lorsque le bloc est définitivement perdu. Sans son option de confirmation, chaque commande d’écriture affiche ce qu’elle ferait et ne modifie rien.

verify

Code de sortie 0 si l’état est cohérent, 2 si un problème a été trouvé sans --repair.

db

db drop-receipts-index --datadir <DATADIR>, nœud arrêté : supprime l’index receipts_by_program avant un retour à une version antérieure à la v0.3, qui ne peut pas ouvrir une base qui le contient. Un démarrage ultérieur reconstruit l’index à partir des reçus.

status

--rpc <URL> (par défaut http://127.0.0.1:8545). Affiche rand_status tel quel.

register, unbond, withdraw

admit sign|submit

Admission par vote (v0.6.8). Sur une chaîne dont la genèse définit staking.admission_by_vote, comme celle de la chaîne 20, une nouvelle clé de validateur ne s’inscrit qu’une fois qu’elle a été validée par des validateurs détenant strictement plus des deux tiers du poids de vote.

Le candidat est la clé que portera l’inscription ; rand-node address --key l’affiche, et l’hexadécimal que register a affiché la contient. Une fois l’admission validée, l’engagement se fait comme auparavant (rand bond … --registration) et la consomme. rand_getAdmitted liste ce qui est admis et en attente.

bridge-gov

Les rotations post-quantiques du bridge (v0.6.8), pour les gardiens et le détenteur de la clé de pause. Chaque étape lit l’identifiant de chaîne, son domaine de liaison et rand_getBridgeState.rotation_nonce depuis --rpc (par défaut http://127.0.0.1:8545).

--new-key est une clé publique Dilithium2 en hexadécimal, @file en contenant une, ou @key-file (sa clé publique). Les lignes de signature ont la forme index:hex, séparées par des espaces ou des retours à la ligne ; les commentaires # sont autorisés.

vesting status|claim|revoke|bond|unbond

Le côté du titulaire et celui du révocateur pour une allocation de genèse soumise à un verrouillage temporel, sur une chaîne dont la genèse comporte une section vesting. Celle de la chaîne 20 n’en a pas. La clé est un fichier produit par rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Les commandes du rôle d’agrégateur pour une chaîne dotée d’une section aggregation : aggregator register --key --bond <RAND> --payout <rand1…> --rpc affiche une AggregatorRegistration signée ; aggregator unbond et aggregator withdraw reprennent la paire du validateur. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] est le démon qui interroge rand_getUnsealed, prouve un agrégat et le soumet. Inerte sur la chaîne 20, dont la genèse n’a pas de section aggregation.

rand (portefeuille)

Options globales, avant ou après la sous-commande :

Les montants sont en RAND décimaux, avec jusqu’à neuf décimales (1, 1.5, .25, 0.000000001). Un montant de jeton sur send, token mint et token burn, ainsi que dans un lien randpay:, est exprimé dans les unités d’affichage du jeton, selon les decimals propres à sa ligne du registre (10 de zUSD valent 10 zUSD). bridge-burn, token create --fixed-supply et --initial prennent des entiers simples dans la plus petite unité du jeton, et asset-balance les affiche. Partout où une commande prend un jeton, elle accepte l’index du registre, l’id rpl1… ou l’id de 64 caractères hexadécimaux ; un id est résolu en index à partir de la liste complète du registre du nœud (rand_getTokens, toutes les pages), jamais par une recherche jeton par jeton, qui indiquerait au nœud quel jeton est sur le point de bouger. Un index numérique n’atteint jamais le nœud.

--cuda nécessite une compilation avec --features cuda et n’a pas de solution de repli ; aucun PTX n’a encore été compilé. Il ne peut pas sceller une enveloppe d’entrée d’appel : rand call --cuda exige --no-envelope. Il ne déclare que le plafond de gas et refuse --gas-limit N.

Chaque mémo et chaque nom de contact que la CLI affiche (la confirmation de send, notes, history, tx-key) passe d’abord par une règle d’affichage unique : les caractères de contrôle, les caractères de format Unicode (contrôles bidirectionnels, caractères de largeur nulle, trait d’union conditionnel) et U+2028/U+2029 sont affichés sous la forme U+FFFD, et une suite de séparateurs d’espace est réduite à une seule espace.

Un premier transfert 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

Partager une adresse, et un mémo

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

Le mémo se trouve dans le même corps scellé que la note : qui peut ouvrir l’un peut ouvrir l’autre, à savoir le destinataire au moyen de notes, et toute personne détenant la clé par transaction de cette sortie au moyen de rand_checkTransaction <hash> <key>. La chain 18 est la première chaîne dont le genesis définit envelope_bytes ; sur les chains 14 à 17, --memo était refusé avant toute preuve.

Un appel confidentiel que vous pourrez rouvrir plus tard

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 programme avec état : le compteur RPL-2

Sur une chaîne dotée d’une section program_state, comme l’est la chain 20. Le compteur n’accepte que les transitions qui lisent une cellule et la réécrivent avec son premier mot augmenté de un ; tout le reste de la transition (ce que le bundle dépose, ce que le vault verse, ce que le programme émet) passe sans être vérifié, ce qui en fait une démonstration et non un programme auquel confier de la valeur.

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)

Les … dans le fichier représentent les 64 caractères hexadécimaux complets, que le wallet exige.

Ce qu’affichent un déploiement et un appel

Sur une chaîne à autorisation scindée, chaque bundle correspond à deux preuves produites sur cette machine : l’autorisation de dépense de niveau 10 et le bundle de niveau 14. Un program deploy avec rand v0.6.7 sur la chain 18, le 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)

Un call affiche son gas et ses frais avant la preuve d’appel, puis prouve le bundle payeur de la même manière :

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

Ici, 6,144 correspond à 5,636 arrondi au multiple supérieur de 2^10, et rand fee call 12 --gas 6144 --bytes <B> tarife cette limite aux prix du tip, sans marge.

rand-prover

Le prover délégué sous forme de binaire autonome : il produit la preuve du bundle de niveau 14 d’un wallet sur une autre machine. rand-node run --prover héberge le même service au sein d’un nœud. Chaque sous-commande accepte --home <DIR> (variable d’environnement RAND_PROVER_HOME, par défaut ~/.rand-prover), le répertoire qui contient prover.key.json et pairings.json.

Un prover sur la chain 20 reçoit la clé de visualisation nk du wallet et un salt frais. Il ne peut pas dépenser, mais il peut lire tout ce que ce wallet a jamais reçu ou envoyé : appairez-vous à un prover auquel vous montreriez votre historique. Le wallet vérifie chaque preuve qu’il reçoit en retour.

Formats des fichiers de clé

Clé de nœud :

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

Clé de wallet, version 2 :

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

rand keygen l’écrit en mode 0600, et depuis la v0.6.8 toute commande rand refuse un fichier de clé de wallet lisible par le groupe ou par les autres : une clé copiée ou restaurée à la main doit être remise en 0600 (chmod 600 <key>). La perte d’une clé de wallet fait perdre toutes les notes qu’elle pouvait ouvrir ; cette version ne comporte aucune phrase de récupération.