Linha de comando

Três binários resultam de cargo build --release: rand-node (o nó e os comandos do operador), rand (a carteira blindada) e rand-prover (o provador delegado). Todos os comandos aceitam -h/--help. Esta página descreve a versão v0.6.8 (c9c9bd3c), o build que a chain 20 executa; onde a v0.6.7 se comportava de outra forma, a página o indica. Uma carteira rand anterior à v0.6.8 não consegue enviar na chain 20, cujo genesis vincula ao seu hash cada prova e cada mensagem assinada. Os dois primeiros guardam tipos diferentes de chave: uma chave de nó é um par de chaves Dilithium2 que assina blocos; uma chave de carteira é uma chave de gasto blindada que não assina nada 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 são novos na v0.6.8. Não existe balance nem transfer: uma transferência exige uma chave de gasto blindada, que só a carteira possui.

Uma flag global, --allow-test-fri-profile (ou RAND_ALLOW_TEST_FRI_PROFILE=1), permite que init, run e verify aceitem um genesis cujo fri_profile seja test. Esse perfil tem cerca de 17 bits de segurança, e quem escreve um arquivo de genesis pode nomeá-lo; por isso, desde a v0.6.8, um nó recusa esse genesis sem a flag. As suítes de testes a ativam; nada mais deveria fazê-lo.

keygen, address

keygen grava { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } com modo 0600. O arquivo é a única cópia da seed. Desde a v0.6.8, keygen recusa um --out que já exista (… already exists or cannot be created; refusing to overwrite a key file) e o deixa intacto; não há --force, portanto mova o arquivo antigo para outro lugar para substituí-lo. A v0.6.7 e as anteriores o sobrescreviam sem perguntar. address imprime address, public_key (1.312 bytes em hex) e peer_id.

genesis

Imprime uma linha alloc por --alloc, depois o hash do genesis, as contagens de validadores e de notas, a duração da época, os cinco limites, hc_bundle e hc_auth (none sem --auth-guest), e então a linha de 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 sem --gas-price, e, com --program-state-cell-fee, uma linha program_state: cell fee N RAND. init imprime a mesma linha de gas. As cinco flags de limite se comportam de modo semelhante: omitidas, o arquivo não tem esse campo e a chain executa o valor padrão; informadas, o campo faz parte do hash do genesis mesmo no valor padrão. A chain 20 foi criada com estas flags (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

As cadeias 18 e 19 foram criadas com as mesmas flags, até --envelope-bytes 1860, e sem nenhuma das flags da v0.6.8. O limite de prova é de 4 MiB, abaixo dos 8 MiB das cadeias 13 a 16: uma transação com autorização dividida carrega até três provas, e 3 × 4 MiB + 1 MiB cabem no bloco de 20 MiB. O tokens.json contém um registration_fee de 1 RAND, um mint_cap_per_day de 10000000000000, max_tokens 4096, burn_registration_fee e bound_note_value, e o zUSD listado com seus sete lastros. Não existe a flag --bridge, e o script de criação ainda insere depois no arquivo as seções bridge, staking e consensus_domain (na chain 20: a bridge no conjunto de guardiões 1 com oito chaves PQ de guardiões, a chave de pausa, rules_v2, rotation e fees; a seção staking com a lista de permissão do faucet, admission_by_vote e um orçamento de entrada de 2.500 bps; consensus_domain: 1; e as notas de gênese do zUSD, feitas com alloc-note --asset 1 --envelope-bytes 1860). O hash de gênese que vale é o que init imprime sobre o arquivo finalizado.

Cada --alloc cria uma nota de depósito com aleatoriedade de compromisso nova, de modo que criar duas vezes resulta em dois hashes diferentes. O comando sempre grava a abertura da nota ao lado de cm e amount, o que uma cadeia com seção tokens exige:

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

O proprietário e o valor de uma nota de gênese são, portanto, públicos por concepção assim que o arquivo é publicado; apenas o momento em que ela é gasta depois, e com que destino, permanece privado. Crie a gênese uma única vez e guarde o arquivo.

alloc-note

--to <rand1…> (obrigatório), --amount <N> (obrigatório), --asset <INDEX> (padrão 0), --envelope-bytes <N> (padrão: o formato legado). Imprime uma nota de alocação como JSON, selada para --to como genesis --alloc sela uma. Uma gênese que define envelope_bytes recusa uma nota selada sem o --envelope-bytes correspondente. --amount é em unidades inteiras do ativo: nove casas decimais para RAND, oito para um token com bridge (10 no ativo 1 são 10 zUSD). Uma nota de um token listado exige que os lastros desse token tenham valores locked que somem exatamente as suas notas.

init

Imprime o hash de gênese e a mesma linha gas: de genesis.

run

Ambiente: RUST_LOG (padrão info,libp2p=warn,libp2p_mdns=off). Ctrl-C ou SIGTERM encerra o nó de forma limpa.

O endpoint público https://rpc.randprotocol.org é um proxy de lista de permissão na frente de um nó de arquivo; desde 2026-10-01 a sua lista de permissão é o conjunto de métodos do listener público.

safety

O estado de segurança de consenso de um validador parado (v0.6.8). Cada comando abre o diretório de dados por conta própria, portanto nenhum roda ao lado de um nó ativo.

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 o head confirmado, a view e a última view votada, o QC mais alto, se o validador está travado acima do seu head e qualquer parada de segurança registrada. Um nó que vê uma cadeia de três certificada tentar confirmar um bloco que não descende do seu próprio head confirmado para e registra o fato (auditoria v6, CON-5); run então encerra com o registro até clear-halt. Compare o head deste nó com o de dois outros validadores e ressincronize a partir de um nó de arquivo se ele diferir, antes de limpar. Desde a v0.6.8 (CON-4), nenhum quórum de respostas “não possuo” libera mais um lock: um validador travado em um bloco que não consegue obter permanece em silêncio até que chegue uma proposta cujo justify supere o lock ou que o bloco seja buscado. release-lock reduz o lock persistido ao certificado do head confirmado; use-o em um validador por vez, e somente quando o bloco estiver perdido de vez. Sem a sua flag de confirmação, cada comando de escrita imprime o que faria e não altera nada.

verify

Código de saída 0 se estiver consistente, 2 se um problema for encontrado sem --repair.

db

db drop-receipts-index --datadir <DATADIR>, com o nó parado: remove o índice receipts_by_program antes de reverter para um build anterior à v0.3, que não consegue abrir um banco de dados que o tenha. Uma inicialização posterior reconstrói o índice a partir dos recibos.

status

--rpc <URL> (padrão http://127.0.0.1:8545). Imprime rand_status literalmente.

register, unbond, withdraw

admit sign|submit

Admissão por voto (v0.6.8). Em uma chain cujo genesis define staking.admission_by_vote, como a da chain 20, uma nova chave de validador só é registrada depois que validadores que detêm estritamente mais de dois terços do peso de voto a tiverem assinado.

O candidato é a chave que o registro carregará; rand-node address --key a imprime, e o hexadecimal que register imprimiu a contém. Depois que a admissão é confirmada, o bond é feito como antes (rand bond … --registration) e a consome. rand_getAdmitted lista o que foi admitido e está em espera.

bridge-gov

As rotações pós-quânticas da bridge (v0.6.8), para guardiões e o detentor da chave de pausa. Cada etapa lê o chain id, seu domínio de vinculação e rand_getBridgeState.rotation_nonce de --rpc (padrão http://127.0.0.1:8545).

--new-key é uma chave pública Dilithium2 em hexadecimal, @file contendo uma, ou @key-file (sua chave pública). As linhas de assinatura têm o formato index:hex, separadas por espaços em branco ou quebras de linha, e comentários com # são permitidos.

vesting status|claim|revoke|bond|unbond

O lado do titular e do revogador de uma alocação de gênese com bloqueio temporal, em uma chain cujo genesis traz uma seção vesting. A da chain 20 não tem nenhuma. A chave é um arquivo de rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Os comandos do papel de agregador para uma chain com uma seção aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc imprime um AggregatorRegistration assinado; aggregator unbond e aggregator withdraw espelham o par do validador. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] é o daemon que consulta rand_getUnsealed, prova um agregado e o submete. Inerte na chain 20, cujo genesis não tem seção aggregation.

rand (wallet)

Opções globais, antes ou depois do subcomando:

Os valores são RAND decimais com até nove casas decimais (1, 1.5, .25, 0.000000001). Um valor de token em send, token mint e token burn, e em um link randpay:, está nas unidades de exibição do token, nas decimals da própria linha do registro (10 de zUSD é 10 zUSD). bridge-burn, token create --fixed-supply e --initial recebem inteiros simples na menor unidade do token, e asset-balance os imprime. Sempre que um comando recebe um token, aceita o índice do registro, o id rpl1… ou o id de 64 hex; um id é resolvido para seu índice a partir da listagem completa do registro do nó (rand_getTokens, todas as páginas), nunca por uma consulta por token, que informaria ao nó qual token está prestes a se mover. Um índice numérico nunca chega ao nó.

--cuda exige uma build com --features cuda e não tem fallback; nenhum PTX foi compilado ainda. Ele não consegue selar um envelope de entrada de chamada: rand call --cuda precisa de --no-envelope. Declara apenas o teto de gas e recusa --gas-limit N.

Todo memo e nome de contato que a CLI imprime (a confirmação de send, notes, history, tx-key) passa antes por uma regra de exibição: caracteres de controle, caracteres de formatação Unicode (controles bidi, caracteres de largura zero, o hífen suave) e U+2028/U+2029 são mostrados como U+FFFD, e uma sequência de separadores de espaço vira um único espaço.

Uma primeira transferência 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

Compartilhando um endereço, e um 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

O memo fica dentro do mesmo corpo selado que a nota, de modo que quem consegue abrir um consegue abrir o outro: o destinatário por meio de notes, e qualquer pessoa que possua a chave por transação daquela saída por meio de rand_checkTransaction <hash> <key>. A chain 18 é a primeira chain cujo genesis define envelope_bytes; nas chains 14 a 17, --memo era recusado antes de qualquer prova.

Uma chamada confidencial que você pode abrir de novo depois

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)

Um programa com estado: o contador RPL-2

Em uma chain com uma seção program_state, como é a chain 20. O contador aceita exatamente as transições que leem uma célula e a gravam de volta com a primeira palavra mais um; todo o resto da transição (o que o bundle deposita, o que o cofre paga, o que o programa cunha) passa sem verificação, o que o torna uma demonstração e não um programa para se colocar valor por trás.

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)

O … no arquivo representa os 64 caracteres hexadecimais completos, que a carteira exige.

O que um deploy e uma chamada imprimem

Em uma chain de autorização dividida, cada bundle consiste em duas provas feitas nesta máquina: a autorização de gasto do tier 10 e o bundle do tier 14. Um program deploy com rand v0.6.7 na chain 18, em 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)

Um call imprime seu gas e sua taxa antes da prova da chamada e, em seguida, prova o bundle pagador da mesma forma:

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

Aqui, 6,144 é 5,636 arredondado para cima até um múltiplo de 2^10, e rand fee call 12 --gas 6144 --bytes <B> precifica esse limite aos preços do topo da chain, sem folga.

rand-prover

O prover delegado como um binário próprio: ele gera a prova de bundle do tier 14 de uma carteira em outra máquina. rand-node run --prover hospeda o mesmo serviço dentro de um nó. Todo subcomando aceita --home <DIR> (env RAND_PROVER_HOME, padrão ~/.rand-prover), o diretório que contém prover.key.json e pairings.json.

Um prover na chain 20 recebe a chave de visualização nk da carteira e um salt novo. Ele não pode gastar, e pode ler tudo o que aquela carteira já recebeu ou enviou: pareie com um prover para o qual você mostraria seu histórico. A carteira verifica cada prova que recebe de volta.

Formatos dos arquivos de chave

Chave do nó:

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

Chave da carteira, versão 2:

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

rand keygen a grava com modo 0600 e, desde a v0.6.8, todo comando rand recusa um arquivo de chave de carteira que o grupo ou outros possam ler: uma chave copiada ou restaurada à mão deve voltar a 0600 (chmod 600 <key>). Perder a chave da carteira significa perder todas as notas que ela conseguia abrir; não há frase de recuperação nesta versão.