Командная строка

Из cargo build --release получаются три бинарных файла: rand-node (узел и команды оператора), rand (экранированный кошелёк) и rand-prover (делегированный prover). Каждая команда принимает -h/--help. Эта страница описывает релиз v0.6.8 (c9c9bd3c), сборку, на которой работает chain 20; где v0.6.7 вёл себя иначе, это указано. Кошелёк rand старше v0.6.8 не может отправлять транзакции в chain 20: её genesis привязывает к своему хешу каждое доказательство и каждое подписанное сообщение. Первые два хранят ключи разного рода: ключ узла — это пара ключей Dilithium2, которой подписываются блоки; ключ кошелька — это экранированный ключ траты, который ничего не подписывает в сети.

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 и bridge-gov появились в v0.6.8. Команд balance и transfer нет: для перевода нужен экранированный ключ траты, а он есть только у кошелька.

Один глобальный флаг, --allow-test-fri-profile (или RAND_ALLOW_TEST_FRI_PROFILE=1), позволяет init, run и verify принять genesis с fri_profile, равным test. Этот профиль даёт около 17 бит стойкости, а назвать его может любой, кто пишет файл genesis, поэтому начиная с v0.6.8 узел отказывается принимать такой genesis без флага. Наборы тестов его задают; больше ничто не должно.

keygen, address

keygen записывает { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> } с правами 0600. Файл — единственная копия seed. Начиная с v0.6.8 keygen отказывается работать с уже существующим --out (… already exists or cannot be created; refusing to overwrite a key file) и не трогает его; флага --force нет, поэтому чтобы заменить старый файл, переместите его в сторону. v0.6.7 и более ранние версии перезаписывали его без предупреждения. address выводит address, public_key (1 312 байт в hex) и peer_id.

genesis

Выводит по одной строке alloc на каждый --alloc, затем хеш genesis, числа валидаторов и нот, длину эпохи, пять пределов, hc_bundle и hc_auth (none без --auth-guest), затем строку gas: gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying, или gas: none без --gas-price, а с --program-state-cell-fee — ещё строку program_state: cell fee N RAND. init выводит ту же строку gas. Пять флагов пределов ведут себя одинаково: если опущены, в файле нет такого поля, и цепочка работает со значением по умолчанию; если указаны, поле входит в хеш genesis даже при значении по умолчанию. Chain 20 была создана с этими флагами (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

Цепочки 18 и 19 созданы с теми же флагами вплоть до --envelope-bytes 1860 и без флагов v0.6.8. Предел размера доказательства составляет 4 MiB вместо 8 MiB у цепочек 13–16: транзакция с раздельной авторизацией несёт до трёх доказательств, а 3 × 4 MiB + 1 MiB укладывается в блок размером 20 MiB. В tokens.json записаны registration_fee в 1 RAND, mint_cap_per_day со значением 10000000000000, max_tokens 4096, burn_registration_fee и bound_note_value, а также zUSD с семью обеспечениями. Флага --bridge нет, и скрипт создания по-прежнему добавляет в файл секции bridge, staking и consensus_domain уже после генерации (в цепочке 20: bridge с набором хранителей 1 и восемью PQ-ключами хранителей, ключ паузы, rules_v2, rotation и fees; секция staking с белым списком крана, admission_by_vote и бюджетом входа 2 500 bps; consensus_domain: 1; и генезисные ноты zUSD, созданные командой alloc-note --asset 1 --envelope-bytes 1860). Значение имеет тот хеш генезиса, который init печатает для готового файла.

Каждый --alloc создаёт одну депозитную ноту со свежей случайностью обязательства, поэтому двукратное создание даёт два разных хеша. Команда всегда записывает раскрытие ноты рядом с cm и amount, что требуется для цепочки с секцией 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>" } }
]

Поэтому владелец и сумма генезисной ноты публичны по замыслу после публикации файла; приватными остаются только момент её последующей траты и то, во что она будет потрачена. Создайте генезис один раз и сохраните файл.

alloc-note

--to <rand1…> (обязателен), --amount <N> (обязателен), --asset <INDEX> (по умолчанию 0), --envelope-bytes <N> (по умолчанию: прежний формат). Печатает одну ноту аллокации в виде JSON, запечатанную для --to так же, как её запечатывает genesis --alloc. Генезис, задающий envelope_bytes, отвергает ноту, запечатанную без соответствующего --envelope-bytes. --amount указывается в целых единицах актива: девять знаков после запятой для RAND, восемь для токена из моста (10 для актива 1 — это 10 zUSD). Нота токена из списка требует, чтобы в обеспечениях этого токена суммы locked в точности равнялись сумме его нот.

init

Печатает хеш генезиса и ту же строку gas:, что и genesis.

run

Окружение: RUST_LOG (по умолчанию info,libp2p=warn,libp2p_mdns=off). Ctrl-C или SIGTERM корректно останавливает узел.

Публичная конечная точка https://rpc.randprotocol.org — это прокси со списком разрешённых методов перед архивным узлом; с 2026-10-01 её список разрешённых методов совпадает с набором методов публичного слушателя.

safety

Состояние безопасности консенсуса остановленного валидатора (v0.6.8). Каждая команда сама открывает каталог данных, поэтому ни одну нельзя запускать рядом с работающим узлом.

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 печатает зафиксированную голову, вью и последний вью, в котором был подан голос, high QC, заблокирован ли валидатор выше своей головы, и любую записанную остановку по безопасности. Узел, увидевший, что certified three-chain пытается зафиксировать блок, не являющийся потомком его собственной зафиксированной головы, останавливается и записывает это (audit v6, CON-5); после этого run завершается с этой записью, пока не будет выполнена clear-halt. Прежде чем очищать, сравните голову этого узла с головами двух других валидаторов и, если она отличается, выполните повторную синхронизацию с архивного узла. Начиная с v0.6.8 (CON-4) никакой кворум ответов «не удерживается» больше не снимает блокировку: валидатор, заблокированный на блоке, который не может получить, молчит, пока не придёт предложение, чей justify старше блокировки, или пока блок не будет получен. release-lock понижает сохранённую блокировку до сертификата зафиксированной головы; применяйте её на одном валидаторе за раз и только тогда, когда блок утрачен безвозвратно. Без флага подтверждения каждая записывающая команда печатает, что она сделала бы, и ничего не меняет.

verify

Код выхода 0, если данные согласованы, и 2, если проблема найдена без --repair.

db

db drop-receipts-index --datadir <DATADIR> при остановленном узле: удаляет индекс receipts_by_program перед откатом к сборке до v0.3, которая не может открыть базу данных с этим индексом. Последующий запуск перестраивает индекс по квитанциям.

status

--rpc <URL> (по умолчанию http://127.0.0.1:8545). Печатает rand_status дословно.

register, unbond, withdraw

admit sign|submit

Допуск голосованием (v0.6.8). В цепочке, чей генезис задаёт staking.admission_by_vote, как у цепочки 20, ключ нового валидатора регистрируется только после того, как его подписали валидаторы, держащие строго больше двух третей весов голосования.

Кандидат — это ключ, который будет содержать регистрация; его выводит rand-node address --key, и он же входит в hex, выведенный register. После фиксации допуска залог вносится как прежде (rand bond … --registration) и расходует допуск. rand_getAdmitted перечисляет допущенных и ожидающих.

bridge-gov

Постквантовые ротации моста (v0.6.8) для хранителей и держателя ключа паузы. Каждый шаг читает из --rpc (по умолчанию http://127.0.0.1:8545) идентификатор цепочки, её домен привязки и rand_getBridgeState.rotation_nonce.

--new-key — это hex-открытый ключ Dilithium2, @file с таким ключом или @key-file (его открытый ключ). Строки подписей имеют вид index:hex, разделяются пробелами или переводами строк, комментарии # допускаются.

vesting status|claim|revoke|bond|unbond

Сторона держателя и сторона отзывающего для генезисного распределения с временной блокировкой, в цепочке, чей генезис содержит раздел vesting. У цепочки 20 его нет. Ключ — файл rand-node keygen.

aggregator register|unbond|withdraw, aggregate

Команды роли агрегатора для цепочки с разделом aggregation: aggregator register --key --bond <RAND> --payout <rand1…> --rpc выводит подписанную AggregatorRegistration; aggregator unbond и aggregator withdraw повторяют пару команд валидатора. aggregate --key <KEY> [--rpc <URL>] [--watch] [--interval-secs 15] [--no-wait] — демон, который опрашивает rand_getUnsealed, доказывает один агрегат и отправляет его. В цепочке 20, чей генезис не содержит раздела aggregation, не действует.

rand (кошелёк)

Глобальные параметры, до подкоманды или после неё:

Суммы указываются в десятичных RAND с точностью до девяти знаков (1, 1.5, .25, 0.000000001). Сумма токена в send, token mint и token burn, а также в ссылке randpay: указывается в отображаемых единицах токена, по decimals его строки в реестре (10 zUSD — это 10 zUSD). bridge-burn, token create --fixed-supply и --initial принимают целые числа в наименьшей единице токена, и их же печатает asset-balance. Везде, где команда принимает токен, она принимает индекс в реестре, id rpl1… или 64-hex id; id сопоставляется с индексом по полному списку реестра узла (rand_getTokens, все страницы), а не поиском по отдельному токену, который сообщил бы узлу, какой токен вот-вот будет перемещён. Числовой индекс до узла не доходит вовсе.

--cuda требует сборки с --features cuda и не имеет запасного варианта; PTX пока не собран. Он не может запечатать конверт с входными данными вызова: для rand call --cuda нужен --no-envelope. Он объявляет только потолок газа и отклоняет --gas-limit N.

Каждое примечание и каждое имя контакта, которые печатает CLI (подтверждение send, notes, history, tx-key), сначала проходят одно правило отображения: управляющие символы, символы формата Unicode (управляющие символы двунаправленного текста, символы нулевой ширины, мягкий перенос) и U+2028/U+2029 показываются как U+FFFD, а последовательность пробельных разделителей — как один пробел.

Первый 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

Передача адреса и примечание

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

Примечание лежит внутри того же запечатанного тела, что и нота, поэтому тот, кто может открыть одно, может открыть и другое: получатель — через notes, а любой, у кого есть ключ данной транзакции для этого выхода, — через rand_checkTransaction <hash> <key>. Chain 18 — первая цепочка, в genesis которой задан envelope_bytes; в цепочках с 14 по 17 --memo отклонялся до начала любого доказательства.

Конфиденциальный вызов, который можно открыть позже

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)

Программа с состоянием: счётчик RPL-2

В цепочке с разделом program_state, как у chain 20. Счётчик принимает ровно те переходы, которые читают одну ячейку и записывают её обратно с первым словом, увеличенным на единицу; всё остальное в переходе (что бандл вносит, что выплачивает хранилище, что выпускает программа) проходит без проверки, поэтому это демонстрация, а не программа, под которую стоит помещать ценности.

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)

Символ … в файле заменяет все 64 шестнадцатеричных символа, которых требует кошелёк.

Что печатают deploy и call

В цепочке с раздельной авторизацией каждый бандл — это два доказательства, построенных на этой машине: авторизация траты уровня 10 и бандл уровня 14. program deploy с rand v0.6.7 в 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 печатает свой газ и свою комиссию до доказательства вызова, а затем так же доказывает оплачивающий бандл:

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

Здесь 6 144 — это 5 636, округлённое вверх до кратного 2^10, а rand fee call 12 --gas 6144 --bytes <B> оценивает этот лимит по ценам вершины цепочки без запаса.

rand-prover

Делегированный prover как отдельный бинарный файл: он строит доказательство бандла уровня 14 для кошелька на другой машине. rand-node run --prover размещает тот же сервис внутри узла. Каждая подкоманда принимает --home <DIR> (переменная окружения RAND_PROVER_HOME, по умолчанию ~/.rand-prover) — каталог, в котором лежат prover.key.json и pairings.json.

Prover в chain 20 получает ключ просмотра кошелька nk и свежую соль. Он не может тратить, но может прочитать всё, что этот кошелёк когда-либо получил или отправил: сопрягайтесь с тем prover, которому вы показали бы свою историю. Кошелёк проверяет каждое полученное обратно доказательство.

Форматы файлов ключей

Ключ узла:

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

Ключ кошелька, версия 2:

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

rand keygen записывает его с правами 0600, а начиная с v0.6.8 каждая команда rand отказывается принимать файл ключа кошелька, доступный для чтения группе или остальным: вручную скопированному или восстановленному ключу нужно вернуть права 0600 (chmod 600 <key>). Потеря ключа кошелька означает потерю каждой ноты, которую он мог открыть; в этом выпуске нет фразы восстановления.