سطر الأوامر

تخرج ثلاثة ملفات تنفيذية من الأمر cargo build --release: rand-node (العقدة وأوامر المشغّل)، و**rand** (المحفظة المحمية)، و**rand-prover** (المُثبِت المفوَّض). يقبل كل أمر الخيار -h/--help. تصف هذه الصفحة إصدار v0.6.8 (c9c9bd3c)، وهو الإصدار الذي تعمل به السلسلة 20؛ وحيث كان سلوك v0.6.7 مختلفًا، تذكر الصفحة ذلك. لا تستطيع محفظة rand الأقدم من v0.6.8 الإرسال على السلسلة 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 بايت بالست عشري) وpeer_id.

genesis

يطبع الأمر سطر alloc واحدًا لكل --alloc، ثم تجزئة الجينيسيس، وعدد المدقّقين (validators) والملاحظات، وطول الحقبة، والحدود الخمسة، وhc_bundle وhc_auth (none دون --auth-guest)، ثم سطر الغاز: 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 سطر الغاز نفسه. وتتصرف خيارات الحدود الخمسة على نحو متماثل: عند إغفالها لا يحتوي الملف على الحقل وتعمل السلسلة بالقيمة الافتراضية؛ وعند تحديدها يصبح الحقل جزءًا من تجزئة الجينيسيس حتى لو كان بقيمته الافتراضية. قُطعت السلسلة 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: الجسر عند مجموعة الحراس 1 مع ثمانية مفاتيح حراس ما بعد الكم، ومفتاح الإيقاف المؤقت، و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 الرأس المُلتزَم به، والعرض وآخر عرض جرى التصويت عليه، وأعلى QC، وهل المدقِّق مقفل فوق رأسه، وأي إيقاف سلامة مسجَّل. العقدة التي ترى سلسلة ثلاثية مصدَّقة تحاول الالتزام بكتلة لا تنحدر من رأسها الملتزَم به تتوقف وتسجّل ذلك (التدقيق 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، كما في سلسلة 20، لا يُسجَّل مفتاح مدقّق (validator) جديد إلا بعد أن يوقّع عليه مدقّقون يملكون أكثر من ثلثي ثقل التصويت بالتحديد.

المرشّح هو المفتاح الذي سيحمله التسجيل؛ يطبعه rand-node address --key، ويحويه السداسي العشري الذي طبعه register. بعد اعتماد القبول، يجري الربط كما سبق (rand bond … --registration) ويستهلكه. يسرد rand_getAdmitted ما قُبل وينتظر.

bridge-gov

عمليات تدوير الجسر المقاومة للحوسبة الكمومية (v0.6.8)، للحرّاس (guardians) وحامل مفتاح الإيقاف المؤقت. تقرأ كل خطوة معرّف السلسلة ونطاق الربط الخاص بها و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. سلسلة 20 لا تحمل أيًّا منه. المفتاح ملف من rand-node keygen.

aggregator register|unbond|withdraw, aggregate

أوامر دور المجمِّع (aggregator) لسلسلة فيها قسم 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، إذ لا يحوي genesis فيها قسم aggregation.

rand (wallet)

الخيارات العامة، قبل الأمر الفرعي أو بعده:

المبالغ 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. وحيثما يأخذ أمر رمزًا، فإنه يقبل فهرس السجل أو المعرّف rpl1… أو المعرّف ذا 64 خانة سداسية عشرية؛ ويُحوَّل المعرّف إلى فهرسه من قائمة سجل العقدة الكاملة (rand_getTokens، كل الصفحات)، لا بالبحث عن كل رمز على حدة، إذ سيُعلم ذلك العقدة بالرمز الذي توشك على تحريكه. أما الفهرس الرقمي فلا يصل إلى العقدة إطلاقًا.

--cuda يتطلب بناءً بالخيار --features cuda وليس له بديل احتياطي؛ ولم يُبنَ أي PTX حتى الآن. ولا يستطيع ختم غلاف مدخلات الاستدعاء: فالأمر rand call --cuda يحتاج إلى --no-envelope. وهو يعلن سقف الغاز فقط، ويرفض --gas-limit N.

كل مذكرة واسم جهة اتصال تطبعها واجهة سطر الأوامر (تأكيد send، وnotes، وhistory، وtx-key) تمر أولًا بقاعدة عرض واحدة: تُعرض محارف التحكم، ومحارف التنسيق في Unicode (محارف التحكم ثنائية الاتجاه، والمحارف عديمة العرض، والواصلة اللينة)، و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

تقع المذكرة داخل الجسم المختوم نفسه الذي توجد فيه الملاحظة، فمن يستطيع فتح أحدهما يستطيع فتح الآخر: المستفيد عبر notes، وكل من يملك المفتاح الخاص بالمعاملة لذلك الخرج عبر rand_checkTransaction <hash> <key>. السلسلة 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، كما هي حال السلسلة 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)

تمثّل … في الملف الأحرف الستة عشرية الأربعة والستين كاملةً، وهي ما تشترطه المحفظة.

ما يطبعه النشر والاستدعاء

على سلسلة ذات تفويض منفصل، تتكوّن كل حزمة من إثباتين يُنشآن على هذا الجهاز: تفويض الإنفاق من المستوى 10 وحزمة المستوى 14. أمر program deploy باستخدام rand v0.6.7 على السلسلة 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

المُثبِت المفوَّض في ملف تنفيذي مستقل: ينشئ إثبات حزمة المستوى 14 الخاصة بمحفظة على جهاز آخر. ويستضيف rand-node run --prover الخدمة نفسها داخل عقدة. يقبل كل أمر فرعي الخيار --home <DIR> (متغير البيئة RAND_PROVER_HOME، والافتراضي ~/.rand-prover)، وهو الدليل الذي يضم prover.key.json وpairings.json.

يتلقى المُثبِت على السلسلة 20 مفتاح العرض nk الخاص بالمحفظة وملحًا جديدًا. لا يستطيع الإنفاق، لكنه يستطيع قراءة كل ما استلمته تلك المحفظة أو أرسلته: اقترن بمُثبِت تقبل أن تُطلعه على سجلّك. وتتحقق المحفظة من كل إثبات يعود إليها.

صيغ ملفات المفاتيح

مفتاح العقدة:

{ "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>). وضياع مفتاح المحفظة يُضيع كل ملاحظة كان بإمكانه فتحها؛ ولا توجد عبارة استرداد في هذا الإصدار.