Antarmuka baris perintah

Tiga biner dihasilkan oleh cargo build --release: rand-node (node dan perintah operator), rand (dompet terlindung/shielded) dan rand-prover (prover terdelegasi). Setiap perintah menerima -h/--help. Halaman ini menjelaskan rilis v0.6.8 (c9c9bd3c), yaitu build yang dijalankan chain 20; bila v0.6.7 berperilaku berbeda, hal itu disebutkan. Dompet rand yang lebih lama dari v0.6.8 tidak dapat mengirim di chain 20, yang genesis-nya mengikat setiap bukti dan pesan bertanda tangan pada hash-nya. Dua yang pertama memegang jenis kunci yang berbeda: kunci node adalah pasangan kunci Dilithium2 yang menandatangani blok; kunci dompet adalah kunci pembelanjaan terlindung (shielded) yang tidak menandatangani apa pun di 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 dan bridge-gov baru di v0.6.8. Tidak ada balance maupun transfer: sebuah transfer memerlukan kunci pembelanjaan terlindung (shielded), yang hanya dipegang oleh dompet.

Satu flag global, --allow-test-fri-profile (atau RAND_ALLOW_TEST_FRI_PROFILE=1), membuat init, run dan verify menerima genesis yang fri_profile-nya adalah test. Profil itu hanya memiliki sekitar 17 bit soundness, dan siapa pun yang menulis berkas genesis dapat menamainya, sehingga sejak v0.6.8 sebuah node menolak genesis semacam itu tanpa flag tersebut. Rangkaian pengujian menyetelnya; tidak ada yang lain yang seharusnya melakukannya.

keygen, address

keygen menulis { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } dengan mode 0600. Berkas itu adalah satu-satunya salinan seed. Sejak v0.6.8 keygen menolak --out yang sudah ada (… already exists or cannot be created; refusing to overwrite a key file) dan membiarkannya tidak tersentuh; tidak ada --force, jadi pindahkan berkas lama ke tempat lain untuk menggantinya. v0.6.7 dan yang lebih lama menimpanya tanpa bertanya. address mencetak address, public_key (1.312 byte hex) dan peer_id.

genesis

Mencetak satu baris alloc untuk setiap --alloc, lalu hash genesis, jumlah validator dan catatan (note), panjang epoch, lima batas, hc_bundle dan hc_auth (none tanpa --auth-guest), kemudian baris gas: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, atau gas: none tanpa --gas-price, dan dengan --program-state-cell-fee sebuah baris program_state: cell fee N RAND. init mencetak baris gas yang sama. Kelima flag batas berperilaku serupa: bila dihilangkan, berkas tidak memiliki bidang tersebut dan chain menjalankan nilai bawaan; bila diberikan, bidang itu menjadi bagian dari hash genesis bahkan pada nilai bawaannya. Chain 20 dibuat dengan flag-flag ini (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

Chain 18 dan 19 dibuat dengan flag yang sama hingga --envelope-bytes 1860, tanpa satu pun flag v0.6.8. Batas bukti adalah 4 MiB, turun dari 8 MiB pada chain 13 hingga 16: satu transaksi otorisasi terpisah membawa hingga tiga bukti, dan 3 × 4 MiB + 1 MiB muat dalam blok 20 MiB. tokens.json memuat registration_fee sebesar 1 RAND, mint_cap_per_day sebesar 10000000000000, max_tokens 4096, burn_registration_fee dan bound_note_value, serta zUSD yang tercantum dengan tujuh backing-nya. Tidak ada flag --bridge, dan skrip pencetakan masih menyisipkan bagian bridge, staking dan consensus_domain ke dalam berkas sesudahnya (pada chain 20: bridge pada guardian set 1 dengan delapan kunci guardian PQ, kunci jeda, rules_v2, rotation dan fees; bagian staking dengan daftar izin faucet, admission_by_vote dan anggaran masuk 2.500 bps; consensus_domain: 1; serta note genesis zUSD, yang dibuat dengan alloc-note --asset 1 --envelope-bytes 1860). Hash genesis yang berlaku adalah hash yang dicetak init pada berkas yang sudah jadi.

Setiap --alloc membuat satu note deposit dengan keacakan komitmen yang baru, sehingga pencetakan dua kali menghasilkan dua hash yang berbeda. Perintah ini selalu menulis opening note di samping cm dan amount, yang diwajibkan oleh chain dengan bagian 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>" } }
]

Pemilik dan jumlah sebuah note genesis karenanya bersifat publik secara desain begitu berkas diterbitkan; hanya kapan dan ke mana note itu dibelanjakan kemudian yang tetap privat. Cetak genesis satu kali dan simpan berkasnya.

alloc-note

--to <rand1…> (wajib), --amount <N> (wajib), --asset <INDEX> (bawaan 0), --envelope-bytes <N> (bawaan: format lama). Mencetak satu note alokasi dalam bentuk JSON, yang disegel untuk --to sebagaimana genesis --alloc menyegelnya. Genesis yang menetapkan envelope_bytes menolak note yang disegel tanpa --envelope-bytes yang sesuai. --amount dinyatakan dalam satuan utuh aset tersebut: sembilan desimal untuk RAND, delapan untuk token yang dijembatani (10 pada asset 1 berarti 10 zUSD). Note dari token yang terdaftar mensyaratkan backing token itu memuat jumlah locked yang totalnya persis sama dengan note-note-nya.

init

Mencetak hash genesis dan baris gas: yang sama seperti genesis.

run

Environment: RUST_LOG (bawaan info,libp2p=warn,libp2p_mdns=off). Ctrl-C atau SIGTERM mematikan node dengan bersih.

Endpoint publik https://rpc.randprotocol.org adalah proxy allowlist di depan sebuah node arsip; sejak 2026-10-01 allowlist-nya adalah kumpulan metode milik listener publik.

safety

Status keselamatan konsensus sebuah validator yang dihentikan (v0.6.8). Setiap perintah membuka direktori data sendiri, sehingga tidak ada yang berjalan bersama node yang aktif.

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 mencetak head yang telah di-commit, view dan view terakhir yang divoting, high QC, apakah validator terkunci di atas head-nya, serta setiap safety halt yang tercatat. Node yang melihat three-chain tersertifikasi mencoba meng-commit blok yang bukan turunan dari head commit-nya sendiri akan berhenti dan mencatatnya (audit v6, CON-5); run kemudian keluar dengan catatan itu hingga clear-halt. Bandingkan head node ini dengan milik dua validator lain dan sinkronkan ulang dari arsip jika berbeda sebelum menghapus halt. Sejak v0.6.8 (CON-4) tidak ada kuorum jawaban “tidak dipegang” yang melepaskan kunci lagi: validator yang terkunci pada blok yang tidak dapat diperolehnya tetap diam hingga datang proposal yang justify-nya melampaui kunci atau blok berhasil diambil. release-lock menurunkan kunci yang tersimpan ke sertifikat head yang telah di-commit; gunakan pada satu validator dalam satu waktu, dan hanya bila blok hilang untuk selamanya. Tanpa flag konfirmasinya, setiap perintah penulisan mencetak apa yang akan dilakukannya dan tidak mengubah apa pun.

verify

Kode keluar 0 jika konsisten, 2 jika ditemukan masalah tanpa --repair.

db

db drop-receipts-index --datadir <DATADIR>, dengan node dihentikan: menghapus indeks receipts_by_program sebelum melakukan rollback ke build pra-v0.3, yang tidak dapat membuka basis data yang memilikinya. Start berikutnya membangun ulang indeks dari receipt.

status

--rpc <URL> (bawaan http://127.0.0.1:8545). Mencetak rand_status apa adanya.

register, unbond, withdraw

admit sign|submit

Admisi melalui pemungutan suara (v0.6.8). Pada chain yang genesis-nya menetapkan staking.admission_by_vote, seperti genesis chain 20, kunci validator baru baru dapat terdaftar setelah validator yang memegang lebih dari dua pertiga bobot suara menandatangani penerimaannya.

Kandidat adalah kunci yang akan dibawa oleh registrasi; rand-node address --key mencetaknya, dan heksadesimal yang dicetak register memuatnya. Setelah admisi di-commit, bond berlaku seperti sebelumnya (rand bond … --registration) dan menggunakannya. rand_getAdmitted mencantumkan siapa saja yang telah diterima dan sedang menunggu.

bridge-gov

Rotasi pasca-kuantum pada bridge (v0.6.8), untuk guardian dan pemegang kunci jeda (pause key). Setiap langkah membaca chain id, domain pengikatnya, dan rand_getBridgeState.rotation_nonce dari --rpc (bawaan http://127.0.0.1:8545).

--new-key adalah kunci publik Dilithium2 heksadesimal, @file yang memuatnya, atau @key-file (kunci publiknya). Baris tanda tangan berbentuk index:hex, dipisahkan oleh spasi atau baris baru, dan komentar # diperbolehkan.

vesting status|claim|revoke|bond|unbond

Sisi pemegang dan sisi pencabut (revoker) dari alokasi genesis yang terkunci waktu, pada chain yang genesis-nya memuat bagian vesting. Genesis chain 20 tidak memilikinya. Kuncinya adalah berkas rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Perintah untuk peran aggregator pada chain yang memiliki bagian aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc mencetak AggregatorRegistration yang ditandatangani; aggregator unbond dan aggregator withdraw sepadan dengan pasangan perintah validator. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] adalah daemon yang melakukan polling rand_getUnsealed, membuktikan satu agregat, lalu mengirimkannya. Tidak aktif pada chain 20, yang genesis-nya tidak memiliki bagian aggregation.

rand (wallet)

Opsi global, sebelum atau sesudah subperintah:

Jumlah dinyatakan dalam RAND desimal dengan hingga sembilan desimal (1, 1.5, .25, 0.000000001). Jumlah token pada send, token mint, dan token burn, serta dalam tautan randpay:, dinyatakan dalam satuan tampilan token, sesuai decimals milik baris registrinya sendiri (10 zUSD adalah 10 zUSD). bridge-burn, token create --fixed-supply dan --initial menerima bilangan bulat biasa dalam satuan terkecil token, dan asset-balance mencetaknya. Di mana pun sebuah perintah menerima token, perintah itu menerima indeks registri, id rpl1…, atau id 64-hex; sebuah id diselesaikan menjadi indeksnya dari daftar registri seluruh node (rand_getTokens, setiap halaman), tidak pernah lewat pencarian per token, yang akan memberi tahu node token mana yang akan dipindahkan. Indeks numerik sama sekali tidak pernah sampai ke node.

--cuda memerlukan build dengan --features cuda dan tidak memiliki fallback; belum ada PTX yang dibangun. Opsi ini tidak dapat menyegel envelope input panggilan: rand call --cuda memerlukan --no-envelope. Opsi ini hanya mendeklarasikan batas atas gas, dan menolak --gas-limit N.

Setiap memo dan nama kontak yang dicetak oleh CLI (konfirmasi send, notes, history, tx-key) terlebih dahulu melewati satu aturan tampilan: karakter kontrol, karakter format Unicode (kontrol bidi, karakter lebar nol, soft hyphen) dan U+2028/U+2029 ditampilkan sebagai U+FFFD, dan rangkaian spasi pemisah ditampilkan sebagai satu spasi.

Transfer shielded pertama

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

Membagikan alamat, dan sebuah 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

Memo berada di dalam badan tersegel yang sama dengan note, sehingga siapa pun yang dapat membuka yang satu dapat membuka yang lain: penerima melalui notes, dan siapa pun yang memegang kunci per-transaksi output tersebut melalui rand_checkTransaction <hash> <key>. Chain 18 adalah chain pertama yang genesis-nya menetapkan envelope_bytes; pada chain 14 hingga 17 --memo ditolak sebelum ada yang dibuktikan.

Panggilan rahasia yang dapat dibuka kembali nanti

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 stateful: penghitung RPL-2

Pada chain dengan bagian program_state, seperti chain 20. Penghitung ini menerima tepat transisi yang membaca satu cell dan menuliskannya kembali dengan kata pertamanya ditambah satu; segala hal lain dalam transisi (apa yang disetorkan bundle, apa yang dibayarkan vault, apa yang dicetak program) ikut berjalan tanpa diperiksa, sehingga ini hanya sebuah demonstrasi dan bukan program untuk menyimpan nilai.

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)

Tanda … dalam berkas mewakili 64 karakter heksadesimal penuh, yang diwajibkan oleh wallet.

Apa yang dicetak oleh deploy dan call

Pada chain dengan otorisasi terpisah, setiap bundle terdiri dari dua bukti yang dibuat di mesin ini: otorisasi pembelanjaan tier-10 dan bundle tier-14. Sebuah program deploy dengan rand v0.6.7 pada 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)

Sebuah call mencetak gas dan biayanya sebelum bukti panggilan, lalu membuktikan bundle pembayarnya dengan cara yang sama:

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

Di sini 6,144 adalah 5,636 yang dibulatkan ke atas hingga kelipatan 2^10, dan rand fee call 12 --gas 6144 --bytes <B> menetapkan harga batas tersebut pada harga tip tanpa ruang cadangan.

rand-prover

Prover terdelegasi sebagai biner tersendiri: ia membuat bukti bundle tier-14 milik sebuah wallet pada mesin lain. rand-node run --prover menjalankan layanan yang sama di dalam sebuah node. Setiap subperintah menerima --home <DIR> (env RAND_PROVER_HOME, bawaan ~/.rand-prover), yaitu direktori yang menyimpan prover.key.json dan pairings.json.

Prover pada chain 20 menerima viewing key nk milik wallet dan sebuah salt baru. Prover tidak dapat membelanjakan, tetapi dapat membaca semua yang pernah diterima atau dikirim wallet tersebut: lakukan pairing dengan prover yang riwayat Anda boleh ia lihat. Wallet memeriksa setiap bukti yang diterimanya kembali.

Format berkas kunci

Kunci node:

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

Kunci wallet, versi 2:

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

rand keygen menulisnya dengan mode 0600, dan sejak v0.6.8 setiap perintah rand menolak berkas kunci wallet yang dapat dibaca oleh group atau other: kunci yang disalin atau dipulihkan secara manual harus dikembalikan ke 0600 (chmod 600 <key>). Kehilangan kunci wallet berarti kehilangan setiap note yang dapat dibukanya; tidak ada frasa pemulihan pada rilis ini.