خط فرمان

سه فایل اجرایی از cargo build --release به دست می‌آید: rand-node (گره و فرمان‌های اپراتور)، rand (کیف پول محافظت‌شده) و rand-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 است. این پروفایل حدود ۱۷ بیت امنیت (soundness) دارد و هر کسی که فایل 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، تعداد validatorها و نوت‌ها، طول epoch، پنج سقف، hc_bundle و hc_auth (بدون --auth-guest مقدار none)، و بعد خط 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 را چاپ می‌کند. پنج پرچم سقف یکسان رفتار می‌کنند: در صورت حذف، فایل چنین فیلدی ندارد و زنجیره پیش‌فرض را اجرا می‌کند؛ در صورت ذکر، فیلد حتی با مقدار پیش‌فرض هم جزو هش 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

زنجیرهٔ ۱۸ و ۱۹ با همان پرچم‌ها تا --envelope-bytes 1860 بریده شدند و هیچ‌یک از پرچم‌های v0.6.8 را نداشتند. سقف اثبات ۴ MiB است، کمتر از ۸ MiB زنجیره‌های ۱۳ تا ۱۶: یک تراکنش با مجوزدهی تقسیم‌شده تا سه اثبات حمل می‌کند و 3 × 4 MiB + 1 MiB در بلوک ۲۰ 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 را پس از آن به فایل می‌چسباند (در زنجیرهٔ ۲۰: پل در مجموعهٔ نگهبان ۱ با هشت کلید نگهبان PQ، کلید توقف، rules_v2، rotation و fees؛ بخش staking با فهرست مجاز faucet، 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> (پیش‌فرض: قالب قدیمی). یک نوت alloc را به‌صورت 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 سر متعهدشده، view و آخرین view رأی‌داده‌شده، QC بالا، اینکه اعتبارسنج بالاتر از سرش قفل شده است یا نه، و هر توقف ایمنی ثبت‌شده را چاپ می‌کند. گرهی که ببیند یک زنجیرهٔ سه‌تایی گواهی‌شده می‌کوشد بلوکی را متعهد کند که از سر متعهدشدهٔ خودش نشأت نمی‌گیرد، متوقف می‌شود و آن را ثبت می‌کند (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). روی زنجیره‌ای که genesis آن staking.admission_by_vote را تنظیم کرده است، مانند زنجیرهٔ ۲۰، کلید یک اعتبارسنج جدید تنها زمانی ثبت می‌شود که اعتبارسنج‌هایی که اکیداً بیش از دو سوم وزن رأی را در اختیار دارند آن را امضا کرده باشند.

نامزد همان کلیدی است که ثبت‌نام آن را حمل خواهد کرد؛ rand-node address --key آن را چاپ می‌کند و هگزی که register چاپ کرده است نیز آن را در بر دارد. پس از commit شدن پذیرش، bond مانند قبل انجام می‌شود (rand bond … --registration) و آن را مصرف می‌کند. rand_getAdmitted فهرست پذیرفته‌شده‌های در انتظار را برمی‌گرداند.

bridge-gov

چرخش‌های پساکوانتومی bridge (v0.6.8)، برای نگهبانان و دارندهٔ کلید توقف. هر مرحله شناسهٔ زنجیره، دامنهٔ الزام‌آور آن و rand_getBridgeState.rotation_nonce را از --rpc می‌خواند (پیش‌فرض http://127.0.0.1:8545).

--new-key یک کلید عمومی Dilithium2 به صورت هگزادسیمال است، یا @file که یکی را در بر دارد، یا @key-file (کلید عمومی آن). خطوط امضا به شکل index:hex هستند و با فاصله یا خط جدید جدا می‌شوند؛ توضیحات با # مجازند.

vesting status|claim|revoke|bond|unbond

سمت دارنده و سمت لغوکننده در تخصیص genesis قفل‌زمانی، روی زنجیره‌ای که genesis آن بخش vesting دارد. زنجیرهٔ ۲۰ چنین بخشی ندارد. کلید یک فایل 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 را poll می‌کند، یک aggregate را اثبات می‌کند و ارسال می‌کند. روی زنجیرهٔ ۲۰ که genesis آن بخش aggregation ندارد غیرفعال است.

rand (کیف پول)

گزینه‌های سراسری، پیش یا پس از زیرفرمان:

مقادیر، RAND اعشاری با حداکثر نه رقم اعشار هستند (1، 1.5، .25، 0.000000001). مقدار توکن در send، token mint و token burn، و در پیوند randpay:، بر حسب واحدهای نمایشی توکن و با decimals خود ردیف آن در registry است (10 از zUSD یعنی 10 zUSD). bridge-burn، token create --fixed-supply و --initial اعداد صحیح ساده را بر حسب کوچک‌ترین واحد توکن می‌گیرند و asset-balance آن‌ها را چاپ می‌کند. هرجا فرمانی توکنی را می‌گیرد، شاخص registry، شناسهٔ rpl1… یا شناسهٔ ۶۴ رقمی هگزادسیمال را می‌پذیرد؛ شناسه از کل فهرست registry نود (rand_getTokens، همهٔ صفحه‌ها) به شاخص آن تبدیل می‌شود، نه با جست‌وجوی تک‌توکنی که به نود می‌گفت کدام توکن در شرف انتقال است. شاخص عددی اصلاً به نود نمی‌رسد.

--cuda به یک بیلد با --features cuda نیاز دارد و هیچ مسیر جایگزینی ندارد؛ هنوز هیچ PTX ساخته نشده است. این گزینه نمی‌تواند پاکت ورودی فراخوانی را مهروموم کند: rand call --cuda به --no-envelope نیاز دارد. این گزینه فقط سقف گس را اعلام می‌کند و --gas-limit N را نمی‌پذیرد.

هر یادداشت و نام مخاطبی که CLI چاپ می‌کند (تأییدیهٔ send، و همچنین notes، history و tx-key) ابتدا از یک قاعدهٔ نمایش عبور می‌کند: نویسه‌های کنترلی، نویسه‌های قالب‌بندی یونیکد (کنترل‌های دوسویه، نویسه‌های با عرض صفر، خط‌تیرهٔ نرم) و U+2028/U+2029 به‌صورت U+FFFD نمایش داده می‌شوند و دنباله‌ای از فاصله‌های جداکننده به یک فاصله تبدیل می‌شود.

نخستین انتقال محافظت‌شده

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

یادداشت (memo) در همان بدنهٔ مهروموم‌شده‌ای قرار دارد که note در آن است؛ پس هر که بتواند یکی را باز کند، می‌تواند دیگری را هم باز کند: گیرنده از طریق notes، و هر کسی که کلید هر‌تراکنش آن خروجی را دارد از طریق rand_checkTransaction <hash> <key>. زنجیر ۱۸ نخستین زنجیری است که در جنسیس آن envelope_bytes تنظیم شده است؛ در زنجیرهای ۱۴ تا ۱۷، --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 دارد، مانند زنجیر ۲۰. شمارنده دقیقاً گذارهایی را می‌پذیرد که یک سلول را می‌خوانند و آن را با کلمهٔ نخستش به‌علاوهٔ یک بازمی‌نویسند؛ هر چیز دیگر در گذار (آنچه بسته واریز می‌کند، آنچه خزانه می‌پردازد، آنچه برنامه ضرب می‌کند) بدون بررسی همراه می‌آید، و به همین دلیل این برنامه یک نمایش آزمایشی است و نه برنامه‌ای که بتوان پشتش ارزشی گذاشت.

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)

نشانهٔ … در پرونده برای ۶۴ نویسهٔ کامل هگز است که کیف پول آن را الزامی می‌داند.

یک استقرار و یک فراخوانی چه چیزی چاپ می‌کنند

در زنجیری با تفکیک مجوز، هر بسته دو اثبات است که روی همین دستگاه ساخته می‌شود: مجوز خرج در سطح ۱۰ و بستهٔ سطح ۱۴. یک program deploy با rand نسخهٔ v0.6.7 روی زنجیر ۱۸، ۲۰۲۶-۰۹-۳۰:

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

اثبات‌گر تفویض‌شده به‌صورت یک باینری مستقل: اثبات بستهٔ سطح ۱۴ یک کیف پول را روی ماشینی دیگر می‌سازد. rand-node run --prover همین سرویس را درون یک نود میزبانی می‌کند. هر زیردستور --home <DIR> را می‌پذیرد (متغیر محیطی RAND_PROVER_HOME، پیش‌فرض ~/.rand-prover)، یعنی پوشه‌ای که prover.key.json و pairings.json را نگه می‌دارد.

یک اثبات‌گر روی زنجیر ۲۰ کلید مشاهدهٔ کیف پول یعنی nk و یک salt تازه دریافت می‌کند. این اثبات‌گر نمی‌تواند خرج کند، ولی می‌تواند هر چیزی را که آن کیف پول تاکنون دریافت یا ارسال کرده بخواند: با اثبات‌گری جفت شوید که حاضر باشید تاریخچهٔ خود را به او نشان دهید. کیف پول هر اثباتی را که پس می‌گیرد بررسی می‌کند.

قالب‌های پرونده کلید

کلید نود:

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

کلید کیف پول، نسخهٔ ۲:

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

rand keygen آن را با دسترسی 0600 می‌نویسد، و از v0.6.8 هر فرمان rand پرونده کلید کیف پولی را که گروه یا دیگران بتوانند بخوانند رد می‌کند: کلیدی که دستی کپی یا بازیابی شده باید دوباره روی 0600 تنظیم شود (chmod 600 <key>). از دست دادن یک کلید کیف پول یعنی از دست دادن هر note ای که می‌توانست باز کند؛ در این نسخه عبارت بازیابی وجود ندارد.