명령줄

cargo build --release를 실행하면 세 개의 바이너리가 생성됩니다. rand-node(노드와 운영자 명령), rand(차폐 지갑), rand-prover(위임 prover)입니다. 모든 명령은 -h/--help를 받습니다. 이 페이지는 chain 20이 실행하는 빌드인 v0.6.8 릴리스(c9c9bd3c)를 설명하며, v0.6.7에서 동작이 달랐던 곳은 그렇게 명시합니다. v0.6.8보다 오래된 rand 지갑은 chain 20에서 전송할 수 없습니다. chain 20의 제네시스가 모든 증명과 서명 메시지를 그 해시에 묶기 때문입니다. 앞의 두 바이너리는 서로 다른 종류의 키를 보유합니다. 노드 키는 블록에 서명하는 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가 fri_profile이 test인 제네시스를 받아들이도록 합니다. 이 프로파일은 건전성이 약 17비트이고 제네시스 파일을 작성하는 사람은 누구나 이를 지정할 수 있으므로, v0.6.8부터 노드는 이 플래그 없이는 그런 제네시스를 거부합니다. 테스트 스위트는 이 플래그를 설정하지만, 그 밖에는 어디에서도 설정해서는 안 됩니다.

keygen, address

keygen은 { "seed": <32-byte hex>, "address": <base58>, "public_key": <hex> }를 모드 0600으로 기록합니다. 이 파일이 시드의 유일한 사본입니다. 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 줄 하나를 출력한 뒤, 제네시스 해시, validator와 노트의 개수, 에폭 길이, 다섯 가지 상한, hc_bundle과 hc_auth(--auth-guest가 없으면 none)를 출력하고, 이어서 gas 줄을 출력합니다. gas 줄은 gas: price P/gas, B/KiB, bundle limit N, dynamic: target … B / … gas, adjust … bps, floor …/…, ceiling …/…, byte load all|paying이며, --gas-price가 없으면 gas: none입니다. --program-state-cell-fee가 있으면 program_state: cell fee N RAND 줄이 추가됩니다. init도 같은 gas 줄을 출력합니다. 다섯 가지 상한 플래그는 모두 같게 동작합니다. 생략하면 파일에 해당 필드가 없고 체인은 기본값으로 동작하며, 지정하면 기본값과 같더라도 그 필드가 제네시스 해시에 포함됩니다. 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의 플래그는 하나도 사용하지 않았습니다. 증명 상한은 체인 13~16의 8 MiB에서 4 MiB로 낮아졌습니다. 분할 승인 트랜잭션은 최대 세 개의 증명을 담으며, 3 × 4 MiB + 1 MiB는 20 MiB 블록에 들어갑니다. tokens.json에는 1 RAND의 registration_fee, 10000000000000의 mint_cap_per_day, max_tokens 4096, burn_registration_fee, bound_note_value가 있으며, zUSD가 일곱 개의 담보와 함께 등재되어 있습니다. --bridge 플래그는 없으며, 생성 스크립트는 이후에도 bridge, staking, consensus_domain 섹션을 파일에 끼워 넣습니다(체인 20의 경우: 가디언 세트 1과 여덟 개의 PQ 가디언 키를 갖춘 브리지, 일시 중지 키, rules_v2, rotation, fees; 파우셋 허용 목록, admission_by_vote, 2,500 bps의 진입 예산을 담은 staking 섹션; consensus_domain: 1; 그리고 alloc-note --asset 1 --envelope-bytes 1860으로 만든 zUSD의 제네시스 노트). 의미가 있는 제네시스 해시는 완성된 파일에 대해 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>(기본값: 레거시 형식). alloc 노트 하나를 JSON으로 출력하며, genesis --alloc이 봉인하는 방식과 같이 --to에 봉인됩니다. envelope_bytes를 설정한 제네시스는 이에 맞는 --envelope-bytes 없이 봉인된 노트를 거부합니다. --amount는 자산의 정수 단위입니다. RAND는 소수점 아래 아홉 자리, 브리지된 토큰은 여덟 자리입니다(자산 1에서 10은 10 zUSD입니다). 등재된 토큰의 노트에는 해당 토큰의 담보가 locked 금액을 가져야 하며, 그 합계가 해당 토큰의 노트 총액과 정확히 일치해야 합니다.

init

제네시스 해시와 genesis와 같은 gas: 행을 출력합니다.

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, 검증자가 자신의 헤드보다 높은 곳에서 잠겨 있는지 여부, 그리고 기록된 안전성 중단을 출력합니다. 인증된 three-chain이 자신의 커밋된 헤드의 후손이 아닌 블록을 커밋하려는 것을 본 노드는 멈추고 이를 기록합니다(audit v6, CON-5). 이후 run은 clear-halt가 실행될 때까지 그 기록과 함께 종료합니다. 해제하기 전에 이 노드의 헤드를 다른 두 검증자의 헤드와 비교하고, 다르면 아카이브에서 다시 동기화하십시오. v0.6.8부터(CON-4) “보유하지 않음”이라는 응답의 어떤 쿼럼도 더 이상 잠금을 해제하지 않습니다. 얻을 수 없는 블록에 잠긴 검증자는 justify가 잠금보다 높은 제안이 도착하거나 그 블록을 가져올 때까지 침묵합니다. release-lock은 저장된 잠금을 커밋된 헤드의 인증서로 낮춥니다. 한 번에 한 검증자에게만, 그리고 블록이 영구적으로 유실된 경우에만 사용하십시오. 승인 플래그가 없으면 쓰기 명령은 수행할 작업을 출력할 뿐 아무것도 변경하지 않습니다.

verify

일관되면 종료 코드 0, --repair 없이 문제가 발견되면 2입니다.

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이 그러합니다)에서는, 투표 가중치의 3분의 2를 엄격히 넘는 밸리데이터가 서명해 승인한 뒤에야 새 밸리데이터 키를 등록할 수 있습니다.

후보는 등록에 담길 키입니다. rand-node address --key가 이를 출력하며, register가 출력한 16진수에도 이 키가 들어 있습니다. 승인이 커밋된 뒤의 본딩은 이전과 같고(rand bond … --registration) 이 승인을 소모합니다. rand_getAdmitted는 승인되어 대기 중인 항목을 나열합니다.

bridge-gov

가디언과 일시 정지 키 보유자를 위한 브리지의 양자 내성 이후(post-quantum) 키 교체(v0.6.8)입니다. 모든 단계는 --rpc(기본값 http://127.0.0.1:8545)에서 체인 ID, 그 바인딩 도메인, rand_getBridgeState.rotation_nonce를 읽습니다.

--new-key는 16진수 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를 폴링하여 집계 하나를 증명하고 제출하는 데몬입니다. 제네시스에 aggregation 섹션이 없는 체인 20에서는 동작하지 않습니다.

rand (지갑)

서브커맨드 앞이나 뒤에 쓸 수 있는 전역 옵션입니다.

금액은 소수점 아래 아홉 자리까지의 십진수 RAND입니다(1, 1.5, .25, 0.000000001). send, token mint, token burn의 토큰 금액과 randpay: 링크의 토큰 금액은 해당 토큰 레지스트리 행의 decimals에 따른 표시 단위입니다(zUSD의 10은 10 zUSD입니다). bridge-burn, token create --fixed-supply, --initial은 토큰의 최소 단위로 된 일반 정수를 받으며, asset-balance가 이 값을 출력합니다. 명령이 토큰을 받는 곳에서는 레지스트리 인덱스, rpl1… ID, 64자리 16진수 ID를 모두 받습니다. ID는 토큰별 조회가 아니라 노드의 전체 레지스트리 목록(rand_getTokens, 모든 페이지)으로 인덱스로 변환하는데, 토큰별 조회는 어떤 토큰이 곧 이동할지를 노드에 알려 주기 때문입니다. 숫자 인덱스는 노드에 전혀 전달되지 않습니다.

--cuda는 --features cuda로 빌드해야 하며 대체 경로가 없습니다. 아직 PTX는 빌드되지 않았습니다. 호출 입력 봉투(envelope)를 봉인할 수 없으므로 rand call --cuda에는 --no-envelope가 필요합니다. 가스 상한만 선언하며 --gas-limit N은 거부합니다.

CLI가 출력하는 모든 메모와 연락처 이름(send의 확인 메시지, notes, history, tx-key)은 먼저 하나의 표시 규칙을 거칩니다. 제어 문자, 유니코드 서식 문자(양방향 제어 문자, 폭이 없는 문자, 소프트 하이픈) 및 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>로 열 수 있습니다. 제네시스에서 envelope_bytes를 설정한 최초의 체인은 Chain 18입니다. 체인 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 카운터

체인 20과 같이 program_state 섹션이 있는 체인에서의 예입니다. 카운터는 셀 하나를 읽어 첫 번째 워드에 1을 더해 다시 기록하는 전이만 정확히 허용합니다. 전이의 나머지 부분(번들이 예치하는 금액, 볼트가 지급하는 금액, 프로그램이 발행하는 금액)은 검증 없이 그대로 통과하므로, 이 프로그램은 시연용일 뿐 가치를 맡길 프로그램이 아닙니다.

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자리 16진수 문자를 나타내며, 지갑은 이를 요구합니다.

deploy와 call이 출력하는 내용

분할 인가(split-authorisation) 체인에서는 모든 번들이 이 머신에서 만든 두 개의 증명으로 구성됩니다. tier-10 지출 인가와 tier-14 번들입니다. 2026-09-30, 체인 18에서 rand v0.6.7로 실행한 program deploy의 출력입니다.

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>는 여유분 없이 tip의 가격으로 이 한도를 산정합니다.

rand-prover

위임 prover를 별도의 바이너리로 만든 것으로, 지갑의 tier-14 번들 증명을 다른 머신에서 생성합니다. rand-node run --prover는 같은 서비스를 노드 안에서 호스팅합니다. 모든 하위 명령은 --home <DIR>(환경 변수 RAND_PROVER_HOME, 기본값 ~/.rand-prover)을 받으며, 이 디렉터리에 prover.key.json과 pairings.json이 있습니다.

체인 20의 prover는 지갑의 viewing key nk와 새로운 솔트(salt)를 받습니다. prover는 지출할 수 없지만, 그 지갑이 받았거나 보낸 모든 내역을 읽을 수 있습니다. 거래 내역을 보여줘도 되는 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>). 지갑 키를 잃으면 그 키로 열 수 있던 모든 노트를 잃게 되며, 이번 릴리스에는 복구 문구가 없습니다.