Línea de comandos

Tres binarios resultan de cargo build --release: rand-node (el nodo y los comandos del operador), rand (la billetera protegida) y rand-prover (el prover delegado). Todos los comandos aceptan -h/--help. Esta página describe la versión v0.6.8 (c9c9bd3c), la compilación que ejecuta la chain 20; cuando v0.6.7 se comportaba de otro modo, se indica. Una billetera rand anterior a v0.6.8 no puede enviar en la chain 20, cuyo génesis vincula cada prueba y cada mensaje firmado a su hash. Los dos primeros usan claves de distinto tipo: una clave de nodo es un par de claves Dilithium2 que firma bloques; una clave de billetera es una clave de gasto protegida que no firma nada en la cadena.

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 y bridge-gov son nuevos en v0.6.8. No existe balance ni transfer: una transferencia necesita una clave de gasto protegida, y solo la billetera la tiene.

Una opción global, --allow-test-fri-profile (o RAND_ALLOW_TEST_FRI_PROFILE=1), permite que init, run y verify acepten un génesis cuyo fri_profile es test. Ese perfil ofrece unos 17 bits de solidez, y quien escribe un archivo de génesis puede nombrarlo, así que desde v0.6.8 un nodo rechaza ese génesis sin la opción. Las suites de pruebas la activan; nada más debería hacerlo.

keygen, address

keygen escribe { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } con modo 0600. El archivo es la única copia de la semilla. Desde v0.6.8, keygen rechaza un --out que ya existe (… already exists or cannot be created; refusing to overwrite a key file) y lo deja intacto; no hay --force, así que hay que mover a un lado el archivo antiguo para reemplazarlo. v0.6.7 y anteriores lo sobrescribían sin preguntar. address imprime address, public_key (1312 bytes en hex) y peer_id.

genesis

Imprime una línea alloc por cada --alloc, luego el hash del génesis, los recuentos de validadores y de notas, la duración de la época, los cinco límites, hc_bundle y hc_auth (none sin --auth-guest), y después la línea de gas: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, o gas: none sin --gas-price, y con --program-state-cell-fee una línea program_state: cell fee N RAND. init imprime la misma línea de gas. Las cinco opciones de límite se comportan igual: si se omiten, el archivo no tiene ese campo y la cadena aplica el valor por defecto; si se indican, el campo forma parte del hash del génesis incluso con su valor por defecto. La chain 20 se creó con estas opciones (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

Las cadenas 18 y 19 se cortaron con las mismas flags hasta --envelope-bytes 1860 y sin ninguna de las de v0.6.8. El límite de las pruebas es de 4 MiB, frente a los 8 MiB de las cadenas 13 a 16: una transacción con autorización dividida lleva hasta tres pruebas, y 3 × 4 MiB + 1 MiB caben en el bloque de 20 MiB. tokens.json contiene un registration_fee de 1 RAND, un mint_cap_per_day de 10000000000000, max_tokens 4096, burn_registration_fee y bound_note_value, y zUSD figura con sus siete respaldos. No existe la flag --bridge, y el script de corte sigue incorporando después al archivo las secciones bridge, staking y consensus_domain (en la cadena 20: el puente en el conjunto de guardianes 1 con ocho claves de guardián PQ, la clave de pausa, rules_v2, rotation y fees; la sección staking con la lista de permitidos del faucet, admission_by_vote y un presupuesto de entrada de 2500 bps; consensus_domain: 1; y las notas de génesis de zUSD, creadas con alloc-note --asset 1 --envelope-bytes 1860). El hash de génesis que cuenta es el que init imprime sobre el archivo terminado.

Cada --alloc construye una nota de depósito con aleatoriedad de compromiso nueva, de modo que cortar dos veces produce dos hashes distintos. El comando siempre escribe la apertura de la nota junto a cm y amount, algo que exige una cadena con una sección 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>" } }
]

Por tanto, el propietario y el importe de una nota de génesis son públicos por diseño una vez publicado el archivo; solo el momento en que se gasta después y en qué se gasta siguen siendo privados. Corte un génesis una sola vez y conserve el archivo.

alloc-note

--to <rand1…> (obligatorio), --amount <N> (obligatorio), --asset <INDEX> (por defecto 0), --envelope-bytes <N> (por defecto: el formato heredado). Imprime una nota de asignación como JSON, sellada para --to del mismo modo que genesis --alloc sella una. Un génesis que define envelope_bytes rechaza una nota sellada sin el --envelope-bytes correspondiente. --amount se expresa en unidades enteras del activo: nueve decimales para RAND, ocho para un token con puente (10 en el activo 1 son 10 zUSD). Una nota de un token listado exige que los respaldos de ese token tengan importes locked cuya suma sea exactamente la de sus notas.

init

Imprime el hash de génesis y la misma línea gas: que genesis.

run

Entorno: RUST_LOG (por defecto info,libp2p=warn,libp2p_mdns=off). Ctrl-C o SIGTERM apagan el nodo de forma limpia.

El endpoint público https://rpc.randprotocol.org es un proxy de lista de permitidos delante de un nodo de archivo; desde el 2026-10-01 su lista de permitidos es el conjunto de métodos del listener público.

safety

El estado de seguridad del consenso de un validador detenido (v0.6.8). Cada comando abre por sí mismo el directorio de datos, de modo que ninguno se ejecuta junto a un nodo activo.

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 imprime la cabeza confirmada, la vista y la última vista votada, el QC alto, si el validador está bloqueado por encima de su cabeza y cualquier detención de seguridad registrada. Un nodo que ve que una cadena de tres certificada intenta confirmar un bloque que no desciende de su propia cabeza confirmada se detiene y lo registra (auditoría v6, CON-5); run termina entonces con ese registro hasta clear-halt. Compare la cabeza de este nodo con la de otros dos validadores y vuelva a sincronizar desde un archivo si difiere antes de borrar el registro. Desde v0.6.8 (CON-4) ningún quórum de respuestas «no lo tengo» libera ya un bloqueo: un validador bloqueado en un bloque que no puede obtener permanece en silencio hasta que llega una propuesta cuyo justify supera al bloqueo o se obtiene el bloque. release-lock reduce el bloqueo persistido al certificado de la cabeza confirmada; úselo en un validador a la vez, y solo cuando el bloque se haya perdido definitivamente. Sin su flag de confirmación, cada comando de escritura imprime lo que haría y no cambia nada.

verify

Código de salida 0 si es consistente, 2 si se encontró un problema sin --repair.

db

db drop-receipts-index --datadir <DATADIR>, con el nodo detenido: elimina el índice receipts_by_program antes de volver a una compilación anterior a v0.3, que no puede abrir una base de datos que lo tenga. Un inicio posterior reconstruye el índice a partir de los recibos.

status

--rpc <URL> (por defecto http://127.0.0.1:8545). Imprime rand_status textualmente.

register, unbond, withdraw

admit sign|submit

Admisión por voto (v0.6.8). En una cadena cuyo génesis establece staking.admission_by_vote, como el de la cadena 20, una nueva clave de validador solo se registra después de que la hayan firmado validadores que sumen estrictamente más de dos tercios del peso de voto.

El candidato es la clave que llevará el registro; rand-node address --key la imprime, y el hexadecimal que imprimió register la contiene. Una vez confirmada la admisión, la vinculación sigue como antes (rand bond … --registration) y la consume. rand_getAdmitted enumera lo admitido y en espera.

bridge-gov

Las rotaciones poscuánticas del puente (v0.6.8), para los guardianes y el titular de la clave de pausa. Cada paso lee del --rpc (por defecto http://127.0.0.1:8545) el id de la cadena, su dominio de vinculación y rand_getBridgeState.rotation_nonce.

--new-key es una clave pública Dilithium2 en hexadecimal, @file que contenga una, o @key-file (su clave pública). Las líneas de firma son index:hex, separadas por espacios en blanco o saltos de línea; se admiten comentarios con #.

vesting status|claim|revoke|bond|unbond

El lado del titular y el del revocador de una asignación de génesis con bloqueo temporal, en una cadena cuyo génesis incluye una sección vesting. El de la cadena 20 no la tiene. La clave es un archivo de rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Los comandos del rol de agregador para una cadena con una sección aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc imprime un AggregatorRegistration firmado; aggregator unbond y aggregator withdraw replican el par del validador. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] es el demonio que consulta rand_getUnsealed, prueba un agregado y lo envía. Inerte en la cadena 20, cuyo génesis no tiene sección aggregation.

rand (wallet)

Opciones globales, antes o después del subcomando:

Los importes son RAND decimales con hasta nueve decimales (1, 1.5, .25, 0.000000001). Un importe de token en send, token mint y token burn, y en un enlace randpay:, está en las unidades de visualización del token, con los decimals propios de su fila del registro (10 de zUSD son 10 zUSD). bridge-burn, token create --fixed-supply y --initial toman enteros simples en la unidad mínima del token, y asset-balance los imprime. Dondequiera que un comando toma un token, acepta el índice del registro, el id rpl1… o el id de 64 caracteres hexadecimales; un id se resuelve a su índice a partir del listado completo del registro del nodo (rand_getTokens, todas las páginas), nunca mediante una consulta por token, que le revelaría al nodo qué token está a punto de moverse. Un índice numérico no llega nunca al nodo.

--cuda requiere una compilación con --features cuda y no tiene alternativa; todavía no se ha compilado ningún PTX. No puede sellar un sobre de entrada de llamada: rand call --cuda necesita --no-envelope. Declara únicamente el límite de gas y rechaza --gas-limit N.

Todo memo y todo nombre de contacto que imprime la CLI (la confirmación de send, notes, history, tx-key) pasa primero por una misma regla de visualización: los caracteres de control, los caracteres de formato Unicode (controles bidi, caracteres de ancho cero, el guion blando) y U+2028/U+2029 se muestran como U+FFFD, y una secuencia de separadores de espacio se muestra como un único espacio.

Una primera transferencia 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

Compartir una dirección y 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

El memo va dentro del mismo cuerpo sellado que la nota, de modo que quien pueda abrir uno puede abrir el otro: el beneficiario mediante notes, y cualquiera que tenga la clave por transacción de esa salida mediante rand_checkTransaction <hash> <key>. Chain 18 es la primera cadena cuyo génesis establece envelope_bytes; en las cadenas 14 a 17 --memo se rechazaba antes de que se generara cualquier prueba.

Una llamada confidencial que puedes volver a abrir más tarde

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 programa con estado: el contador RPL-2

En una cadena con una sección program_state, como lo es la chain 20. El contador acepta exactamente las transiciones que leen una celda y la reescriben con su primera palabra más uno; todo lo demás de la transición (lo que el bundle deposita, lo que la bóveda paga, lo que el programa acuña) pasa sin comprobarse, lo que lo convierte en una demostración y no en un programa sobre el que respaldar valor.

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)

Los … del archivo representan los 64 caracteres hexadecimales completos, que la wallet exige.

Qué imprimen un deploy y una llamada

En una cadena de autorización dividida, cada bundle consta de dos pruebas generadas en esta máquina: la autorización de gasto de nivel 10 y el bundle de nivel 14. Un program deploy con rand v0.6.7 en la 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 imprime su gas y su comisión antes de la prueba de la llamada, y después genera la prueba del bundle de pago de la misma manera:

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

Aquí 6,144 es 5,636 redondeado al alza a un múltiplo de 2^10, y rand fee call 12 --gas 6144 --bytes <B> valora ese límite a los precios de la punta de la cadena, sin margen.

rand-prover

El prover delegado como binario independiente: genera la prueba del bundle de nivel 14 de una wallet en otra máquina. rand-node run --prover aloja el mismo servicio dentro de un nodo. Todos los subcomandos aceptan --home <DIR> (variable de entorno RAND_PROVER_HOME, por defecto ~/.rand-prover), el directorio que contiene prover.key.json y pairings.json.

Un prover en la chain 20 recibe la clave de visualización nk de la wallet y una sal nueva. No puede gastar, y puede leer todo lo que esa wallet haya recibido o enviado alguna vez: empareja solo con un prover al que mostrarías tu historial. La wallet comprueba cada prueba que recibe de vuelta.

Formatos de los archivos de clave

Clave del nodo:

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

Clave de la wallet, versión 2:

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

rand keygen la escribe con modo 0600, y desde v0.6.8 todo comando de rand se niega a usar un archivo de clave de wallet que el grupo u otros puedan leer: una clave copiada o restaurada a mano debe volver a ponerse en 0600 (chmod 600 <key>). Perder una clave de wallet supone perder todas las notas que podía abrir; en esta versión no hay frase de recuperación.