Wiersz poleceń

Z cargo build --release powstają trzy pliki binarne: rand-node (węzeł i polecenia operatora), rand (portfel shielded) oraz rand-prover (prover delegowany). Każde polecenie przyjmuje -h/--help. Ta strona opisuje wydanie v0.6.8 (c9c9bd3c), czyli build, na którym działa chain 20; tam, gdzie v0.6.7 zachowywał się inaczej, jest to zaznaczone. Portfel rand starszy niż v0.6.8 nie może wysyłać na chain 20, którego genesis wiąże z swoim hashem każdy dowód i każdą podpisaną wiadomość. Dwa pierwsze przechowują różne rodzaje kluczy: klucz węzła to para kluczy Dilithium2, która podpisuje bloki; klucz portfela to klucz wydatkowy shielded, który nie podpisuje niczego w łańcuchu.

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 i bridge-gov są nowe w v0.6.8. Nie ma balance ani transfer: transfer wymaga klucza wydatkowego shielded, który posiada tylko portfel.

Jedna flaga globalna, --allow-test-fri-profile (lub RAND_ALLOW_TEST_FRI_PROFILE=1), pozwala poleceniom init, run i verify zaakceptować genesis, w którym fri_profile ma wartość test. Ten profil daje około 17 bitów bezpieczeństwa (soundness), a nazwać go może każdy, kto pisze plik genesis, dlatego od v0.6.8 węzeł odrzuca taki genesis bez tej flagi. Ustawiają ją zestawy testów; nic innego nie powinno.

keygen, address

keygen zapisuje { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } z uprawnieniami 0600. Ten plik to jedyna kopia ziarna (seed). Od v0.6.8 keygen odmawia zapisu do istniejącego --out (… already exists or cannot be created; refusing to overwrite a key file) i nie zmienia tego pliku; nie ma --force, więc aby go zastąpić, trzeba najpierw odłożyć stary plik na bok. v0.6.7 i wcześniejsze nadpisywały go bez pytania. address wypisuje address, public_key (1 312 bajtów w hex) oraz peer_id.

genesis

Wypisuje jedną linię alloc dla każdego --alloc, następnie hash genesis, liczbę validatorów i notatek, długość epoki, pięć limitów, hc_bundle i hc_auth (none bez --auth-guest), a potem linię gas: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, lub gas: none bez --gas-price, a z --program-state-cell-fee także linię program_state: cell fee N RAND. init wypisuje tę samą linię gas. Pięć flag limitów zachowuje się tak samo: po pominięciu plik nie ma takiego pola i łańcuch używa wartości domyślnej; po podaniu pole wchodzi do hasha genesis nawet przy wartości domyślnej. Chain 20 został wycięty z tymi flagami (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

Łańcuchy 18 i 19 zostały utworzone z tymi samymi flagami, aż do --envelope-bytes 1860, i bez żadnej z flag z v0.6.8. Limit dowodu wynosi 4 MiB, w porównaniu z 8 MiB w łańcuchach od 13 do 16: transakcja z podzieloną autoryzacją niesie do trzech dowodów, a 3 × 4 MiB + 1 MiB mieści się w bloku o rozmiarze 20 MiB. Plik tokens.json zawiera registration_fee równe 1 RAND, mint_cap_per_day równe 10000000000000, max_tokens równe 4096, burn_registration_fee i bound_note_value, a także zUSD wraz z jego siedmioma zabezpieczeniami. Nie ma flagi --bridge, a skrypt tworzący genezę nadal dokleja później do pliku sekcje bridge, staking i consensus_domain (w łańcuchu 20: most przy zestawie strażników 1 z ośmioma kluczami PQ strażników, klucz wstrzymania, rules_v2, rotation i fees; sekcja staking z listą dozwolonych kranu, admission_by_vote i budżetem wejść 2,500 bps; consensus_domain: 1; oraz notatki genezy zUSD, utworzone poleceniem alloc-note --asset 1 --envelope-bytes 1860). Liczy się ten hash genezy, który init wypisuje dla gotowego pliku.

Każde --alloc buduje jedną notę depozytową ze świeżą losowością zobowiązania, więc dwukrotne utworzenie genezy daje dwa różne hashe. Polecenie zawsze zapisuje otwarcie noty obok cm i amount, czego wymaga łańcuch z sekcją 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>" } }
]

Właściciel i kwota noty genezy są zatem jawne z założenia po opublikowaniu pliku; prywatne pozostaje tylko to, kiedy i na co zostanie ona później wydana. Utwórz genezę raz i zachowaj plik.

alloc-note

--to <rand1…> (wymagane), --amount <N> (wymagane), --asset <INDEX> (domyślnie 0), --envelope-bytes <N> (domyślnie: format dawny). Wypisuje jedną notę alokacji jako JSON, zaszyfrowaną dla --to tak, jak robi to genesis --alloc. Geneza, która ustawia envelope_bytes, odrzuca notę zaszyfrowaną bez odpowiadającego jej --envelope-bytes. --amount podaje się w pełnych jednostkach aktywa: dziewięć miejsc dziesiętnych dla RAND, osiem dla tokena mostkowanego (10 przy aktywie 1 to 10 zUSD). Nota tokena z listy wymaga, aby zabezpieczenia tego tokena miały kwoty locked sumujące się dokładnie do jego not.

init

Wypisuje hash genezy oraz tę samą linię gas: co genesis.

run

Środowisko: RUST_LOG (domyślnie info,libp2p=warn,libp2p_mdns=off). Ctrl-C lub SIGTERM zamyka węzeł w sposób czysty.

Publiczny punkt końcowy https://rpc.randprotocol.org to proxy z listą dozwolonych metod przed węzłem archiwalnym; od 2026-10-01 jego listą dozwolonych jest zestaw metod publicznego nasłuchu.

safety

Stan bezpieczeństwa konsensusu zatrzymanego walidatora (v0.6.8). Każde polecenie samo otwiera katalog danych, więc żadne nie działa obok działającego węzła.

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 wypisuje zatwierdzoną głowę, widok i ostatnio głosowany widok, wysoki QC, informację, czy walidator jest zablokowany powyżej swojej głowy, oraz każde zapisane zatrzymanie bezpieczeństwa. Węzeł, który widzi, jak certyfikowany łańcuch trzech bloków próbuje zatwierdzić blok niewywodzący się z jego własnej zatwierdzonej głowy, zatrzymuje się i zapisuje to; run kończy się wtedy z tym zapisem aż do clear-halt (audit v6, CON-5). Porównaj głowę tego węzła z głowami dwóch innych walidatorów i przed wyczyszczeniem zatrzymania zsynchronizuj ponownie z archiwum, jeśli się różni. Od v0.6.8 (CON-4) żaden kworum odpowiedzi „nie posiadam” nie zwalnia już blokady: walidator zablokowany na bloku, którego nie może uzyskać, milczy, dopóki nie nadejdzie propozycja, której justify przewyższa blokadę, albo blok nie zostanie pobrany. release-lock obniża zapisaną blokadę do certyfikatu zatwierdzonej głowy; używaj go na jednym walidatorze naraz i tylko wtedy, gdy blok jest utracony bezpowrotnie. Bez flagi potwierdzenia każde polecenie zapisujące wypisuje, co by zrobiło, i niczego nie zmienia.

verify

Kod wyjścia 0, jeśli spójne, 2, jeśli znaleziono problem bez --repair.

db

db drop-receipts-index --datadir <DATADIR>, przy zatrzymanym węźle: usuwa indeks receipts_by_program przed cofnięciem do kompilacji sprzed v0.3, która nie potrafi otworzyć bazy zawierającej ten indeks. Późniejszy start odbudowuje indeks z potwierdzeń.

status

--rpc <URL> (domyślnie http://127.0.0.1:8545). Wypisuje rand_status bez zmian.

register, unbond, withdraw

admit sign|submit

Przyjęcie w drodze głosowania (v0.6.8). W łańcuchu, którego genesis ustawia staking.admission_by_vote, jak w łańcuchu 20, nowy klucz walidatora rejestruje się dopiero wtedy, gdy walidatorzy posiadający ściśle więcej niż dwie trzecie wagi głosów podpiszą jego przyjęcie.

Kandydat to klucz, który będzie zawierać rejestracja; wypisuje go rand-node address --key, a zawiera go także szesnastkowy wynik register. Po zatwierdzeniu przyjęcia wiązanie stake’u przebiega jak dotąd (rand bond … --registration) i zużywa to przyjęcie. rand_getAdmitted wymienia przyjętych i oczekujących.

bridge-gov

Postkwantowe rotacje mostu (v0.6.8), dla strażników (guardians) i posiadacza klucza wstrzymania. Każdy krok odczytuje z --rpc (domyślnie http://127.0.0.1:8545) identyfikator łańcucha, jego domenę wiązania oraz rand_getBridgeState.rotation_nonce.

--new-key to szesnastkowy klucz publiczny Dilithium2, @file zawierający taki klucz albo @key-file (jego klucz publiczny). Linie podpisów mają postać index:hex, rozdzielone białymi znakami lub nowymi liniami; dozwolone są komentarze #.

vesting status|claim|revoke|bond|unbond

Strona posiadacza i strona odwołującego (revoker) alokacji genesis objętej blokadą czasową, w łańcuchu, którego genesis zawiera sekcję vesting. Genesis łańcucha 20 jej nie ma. Kluczem jest plik z rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Polecenia roli agregatora (aggregator) w łańcuchu z sekcją aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc wypisuje podpisane AggregatorRegistration; aggregator unbond i aggregator withdraw odpowiadają parze poleceń walidatora. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] to demon, który odpytuje rand_getUnsealed, dowodzi jeden agregat i go składa. Nieaktywne w łańcuchu 20, którego genesis nie ma sekcji aggregation.

rand (portfel)

Opcje globalne, przed podpoleceniem lub po nim:

Kwoty są dziesiętnymi RAND z dokładnością do dziewięciu miejsc po przecinku (1, 1.5, .25, 0.000000001). Kwota tokena w send, token mint i token burn oraz w linku randpay: jest podawana w jednostkach wyświetlania tokena, według decimals jego własnego wiersza w rejestrze (10 zUSD to 10 zUSD). bridge-burn, token create --fixed-supply i --initial przyjmują zwykłe liczby całkowite w najmniejszej jednostce tokena, a asset-balance je wypisuje. Wszędzie tam, gdzie polecenie przyjmuje token, przyjmuje indeks rejestru, identyfikator rpl1… lub 64-znakowy identyfikator szesnastkowy; identyfikator jest rozwiązywany do indeksu z całej listy rejestru węzła (rand_getTokens, każda strona), nigdy przez zapytanie o pojedynczy token, które zdradziłoby węzłowi, jaki token zaraz zostanie przesunięty. Indeks liczbowy w ogóle nie trafia do węzła.

--cuda wymaga kompilacji z --features cuda i nie ma rozwiązania zastępczego; PTX nie został jeszcze zbudowany. Nie potrafi zapieczętować koperty z danymi wejściowymi wywołania: rand call --cuda wymaga --no-envelope. Deklaruje wyłącznie pułap gazu i odrzuca --gas-limit N.

Każda notatka i nazwa kontaktu, które wypisuje CLI (potwierdzenie send, notes, history, tx-key), przechodzą najpierw przez jedną regułę wyświetlania: znaki sterujące, znaki formatujące Unicode (znaczniki dwukierunkowe, znaki o zerowej szerokości, miękki łącznik) oraz U+2028/U+2029 są pokazywane jako U+FFFD, a ciąg znaków odstępu jako jedna spacja.

Pierwszy przelew 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

Udostępnianie adresu i notatka

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

Notatka (memo) znajduje się w tym samym zapieczętowanym ciele co nota, więc kto potrafi otworzyć jedno, otworzy i drugie: odbiorca przez notes, a każdy, kto posiada klucz danej transakcji dla tego wyjścia, przez rand_checkTransaction <hash> <key>. Chain 18 jest pierwszym łańcuchem, którego genesis ustawia envelope_bytes; na łańcuchach od 14 do 17 --memo było odrzucane, zanim cokolwiek zostało udowodnione.

Poufne wywołanie, które można później otworzyć ponownie

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)

Program ze stanem: licznik RPL-2

Na łańcuchu z sekcją program_state, jak chain 20. Licznik akceptuje dokładnie te przejścia, które odczytują jedną komórkę i zapisują ją z powrotem z pierwszym słowem zwiększonym o jeden; wszystko inne w przejściu (to, co pakiet wpłaca, co skarbiec wypłaca, co program emituje) przechodzi bez sprawdzenia, przez co jest to demonstracja, a nie program, za którym należy umieszczać wartość.

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)

Znak … w pliku oznacza pełne 64 znaki szesnastkowe, których wymaga portfel.

Co wypisuje deploy i wywołanie

Na łańcuchu z rozdzielonym uwierzytelnianiem każdy pakiet to dwa dowody tworzone na tej maszynie: uwierzytelnienie wydatku tier-10 i pakiet tier-14. program deploy z rand v0.6.7 na 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)

call wypisuje gaz i opłatę przed dowodem wywołania, po czym w ten sam sposób dowodzi pakiet płacący:

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

Tutaj 6,144 to 5,636 zaokrąglone w górę do wielokrotności 2^10, a rand fee call 12 --gas 6144 --bytes <B> wycenia ten limit według cen na szczycie łańcucha, bez zapasu.

rand-prover

Delegowany prover jako osobny plik binarny: tworzy dowód pakietu tier-14 portfela na innej maszynie. rand-node run --prover uruchamia tę samą usługę wewnątrz węzła. Każde polecenie podrzędne przyjmuje --home <DIR> (zmienna środowiskowa RAND_PROVER_HOME, domyślnie ~/.rand-prover), czyli katalog zawierający prover.key.json i pairings.json.

Prover na chain 20 otrzymuje klucz podglądu nk portfela i świeży salt. Nie może wydawać środków, ale może odczytać wszystko, co ten portfel kiedykolwiek otrzymał lub wysłał: sparuj się z proverem, przed którym pokazałbyś swoją historię. Portfel sprawdza każdy otrzymany dowód.

Formaty plików kluczy

Klucz węzła:

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

Klucz portfela, wersja 2:

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

rand keygen zapisuje go z trybem 0600, a od v0.6.8 każde polecenie rand odmawia pracy z plikiem klucza portfela, który mogą odczytać grupa lub inni: klucz skopiowany lub przywrócony ręcznie trzeba ustawić z powrotem na 0600 (chmod 600 <key>). Utrata klucza portfela oznacza utratę każdej noty, którą mógł otworzyć; w tym wydaniu nie ma frazy odzyskiwania.