استخدم واجهة المستكشف البرمجية لقراءة السلسلة 20 من سكربت أو روبوت أو خدمة خلفية دون تشغيل عقدة. الدليل الكامل بكل الحقول موجود في مستودع المستكشف، randscan.org/docs/api.md؛ وهذه الصفحة ملخص له.
| عنوان URL الأساسي | https://randscan.org/api/v1 |
| WebSocket | wss://randscan.org/ws |
| دون مفتاح | 60 طلبًا في الدقيقة لكل عنوان IP |
| بمفتاح API | 600 طلب في الدقيقة؛ تُستخرج المفاتيح من randscan.org/dashboard، وتُرسل بالصيغة Authorization: Bearer rsk_… أو X-API-Key |
ما الذي يستطيع مستكشف سلسلة محمية عرضه
لا توجد في هذه الواجهة حسابات ولا أرصدة ولا مرسلون ولا مستلمون، ومنذ السلسلة 14 لا يوجد أصل عام في الحزمة: فتحويل RAND وتحويل أي رمز RPL لهما الشكل نفسه. وما تقدمه هو: كل كتلة؛ وحزمة الأصل المخفي لكل معاملة كما نُشرت (المرساة، وأربعة مبطِلات (nullifiers)، وأربعة التزامات، والرسم، وburn_a وburn_r وburn_asset، والوقت، وأحجام الإثبات والمغلّف، ومنذ السلسلة 17 قيمة auth_commit وحجم إثبات التفويض)؛ والإجراء الذي حملته المعاملة وحقوله العامة، ومنها تسجيل رمز RPL وسك الرموز وحرقها، وإجراءات حوكمة الجسر، والانتقال في الحالة الناتج عن invoke في RPL-2؛ وسجل رموز RPL؛ وخلايا البرنامج وخزنته؛ وشجرة الالتزامات ورقةً ورقة؛ ومجموعة المبطِلات (nullifiers)؛ وسجل المصادِقين؛ وتدقيق المعروض؛ والحالة العامة للجسر، بما فيها إيقاف السك ومجموعة حراس PQ. أما الأصل الذي نقلته المعاملة فلا يظهر إلا لمفتاح العرض أو لمفتاح المعاملة، داخل المتصفح. ويردّ GET /accounts/:address بالرمز 410 { "error": "no_accounts" }.
الاصطلاحات: المبالغ سلاسل عشرية من الوحدات. والمبلغ الذي يشير asset_index فيه إلى رمز غير RAND (الفهرس 0) يكون بأصغر وحدة لذلك الرمز نفسه، لا بخانات RAND التسع؛ فحلّ الفهرس عبر GET /tokens/:id قبل القسمة. وregistration_fee وnext_index هما الحقلان الوحيدان اللذان يقدمهما المستكشف كأرقام JSON عادية؛ أما التجزئات ومعرّفات البرامج والالتزامات والمبطِلات (nullifiers) فهي 64 خانة سداسية عشرية بأحرف صغيرة؛ وعناوين المصادِقين بصيغة base58؛ والارتفاعات أعداد صحيحة عشرية تبدأ من 0؛ ولا تُفهرَس إلا الكتل المثبّتة، فالكتلة الظاهرة في الواجهة نهائية. وتقبل القوائم المعاملين page (من 1) وlimit (من 1 إلى 100، والافتراضي 20)، وتعيد { "data": [...], "pagination": { page, limit, total, total_pages, has_next, has_prev } }، الأحدث أولًا. والأخطاء بالشكل { "error", "message", "code" } مع 400 أو 404 أو 410 أو 429 أو 500.
نقاط النهاية
| الطريقة والمسار | ما يعيده |
|---|---|
GET /health | حالة المستكشف وتأخر المفهرِس |
GET /stats | معرّف السلسلة، والارتفاع، والعرض (view)، وحجم الشجرة، وأعداد المصادِقين، وإجمالي الحصة، والمعروض، وعدد البرامج، ومتوسط زمن الكتلة، والحقبة، وتجزئة التكوين (genesis) وإصدار العقدة؛ وhc_bundle وhc_auth؛ وlimits (الحدود الخمسة للتكوين، ثم envelope_bytes وhardening_v6 وhc_auth وgas_price وbyte_price الخاصين بالتكوين، وgas_metering وbundle_gas_limit وadjust_bps، وprogram_state على العقدة منذ v0.6.8)؛ وgas_prices، أي الأسعار الحية عند رأس السلسلة. ولا يحمل limits الحقول الجديدة الأخرى في v0.6.8 (binding_domain وproof_window_blocks وسقوف الأسعار وadmission_by_vote وtestnet): اقرأها من rand_getLimits في العقدة |
GET /supply | تدقيق المعروض في العقدة كما هو، بما فيه عدّادات vesting_* الأربعة، وكلها "0" على السلسلة 20 التي لا يحتوي تكوينها على قسم vesting، وكذلك program_rand_out وprogram_rand_held الخاصان بـ RPL-2، أي RAND المدفوع من خزائن البرامج وRAND الذي ما زالت تحتفظ به |
GET /bridge | الحالة العامة للجسر: emitter وemitters وguardian_set_index وguardians وpq_guardians وmint_paused وpause_nonce وlist_nonce وpause_key وregistration_fee وburn_sequence وnext_index (null منذ السلسلة 14) وrotation_nonce وrules_v2 (مع global_minted_in_window وglobal_mint_headroom) وmin_inbound_sequence وassets وendpoints، وهي عرض المستكشف نفسه لكل مُصدِر كما تطبعه سلسلته المصدر. ولا يقدّم الحقول fees وrotation_rules وpending_rotations الخاصة بالعقدة في v0.6.8: اقرأها من rand_getBridgeState |
GET /bridge/assets | صف لكل دعم (backing): صف السجل (index وchain وtoken وasset_id وlocked وminted_today وmint_cap_per_day، وعلى عقدة v0.6.8 أيضًا minted_in_window وmint_window_secs وmint_headroom، أي أكبر إيداع تسمح به السقوف الآن) مضمومًا إلى symbol وname وdecimals وbackings، والمجاميع المفهرسة. لكل دعم: burns وburned وoutstanding (وهو locked في السجل)، وdeposits/deposited فقط حين يكون للرمز دعم واحد (وإلا null: فالإيداع يسمّي الرمز الذي سكّه لا العملة المقفلة مقابله). ولكل رمز، وهي متطابقة في كل صف له الـ index نفسه: token_deposits وtoken_deposited وtoken_burns وtoken_burned وfirst_height وlast_height؛ فاحسب كل index مرة واحدة عند الجمع |
GET /bridge/tokens | قائمة الرموز المسموح بها، وهي قائمة ثابتة: USDT وUSDC على Ethereum وBSC وTron وSolana، مع إيقاف USDC على Tron |
GET /tokens | سجل رموز RPL كاملًا كما هو مخزَّن مؤقتًا من العقدة: enabled وregistration_fee وnext_index وtokens |
GET /tokens/:id | رمز واحد بفهرس السجل أو بمعرّف من 64 خانة سداسية عشرية أو بصيغة النص rpl1…، إضافةً إلى deploy_tx وsupply_history؛ ويردّ 404 عند عدم وجود مطابق |
GET /nodes | عقدة المستكشف ونظراؤها، مع الموقع الجغرافي |
GET /provers | المُبرهِنون المفوَّضون الذين يعرفهم المستكشف (قائمته الخاصة؛ فالسلسلة لا تحتفظ بأي سجل عنهم): هل يردّ كل منهم على prover_info، وسعته ورسمه، وأين مضيفاته |
GET /blocks?page&limit&proposer، GET /blocks/latest?limit، GET /blocks/:id | الكتل، بالارتفاع أو بالتجزئة |
GET /transactions?page&limit&kind&height&validator&program، GET /transactions/latest، GET /transactions/:hash | المعاملات؛ وkind هو transfer أو mint أو deploy أو call أو bond أو unbond أو withdraw أو bridge_attest أو bridge_burn أو register_token أو token_mint أو set_authority أو token_burn أو pause_mints أو unpause_mints أو register_bridged_token أو list_backing أو invoke. ولا يوجد token_transfer: فتحويل أي رمز RPL هو transfer |
GET /transactions/:hash/envelopes | المذكرات التي أنشأتها المعاملة مع مغلّفاتها: خانات الحزمة الأربع، بما فيها الوهمية، إضافةً إلى المذكرات التي تحسبها السلسلة وتُلحقها عملية إيداع bridge_attest أو token_mint أو السك الأولي في register_token أو مدفوعات invoke؛ وفي حالة الاستدعاء (call): h_in ونص المدخلات المختوم |
GET /envelopes?from_leaf&limit | الأوراق ذات المغلّفات، الأقدم أولًا، حتى 1,000 في الصفحة، لمسح التاريخ |
GET /notes?page&limit، GET /notes/:id | أوراق الشجرة، بالالتزام أو بفهرس الورقة |
GET /nullifiers/:nf | المعاملة التي نشرت المُبطِل (nullifier) |
GET /validators، GET /validators/:address | السجل، مع share_percent وblocks_proposed وآخر ارتفاع اقترحه المصادِق |
GET /programs?page&limit، GET /programs/:id | البرامج المنشورة (base_pc وwords_len وcode_hash وpublic_words_len وpublic_digest) مع أعداد الاستدعاءات (call) والاستدعاءات (invoke)؛ وأحدث استدعاءات البرنامج، وprogram_state الخاص به، مقروءًا حيًّا من العقدة: vault (لكل أصل)، وأول 100 من cells بترتيب المفاتيح، وcells_next |
GET /programs/:id/cells?after&limit | صفحة من خلايا البرنامج بترتيب المفاتيح، حيّة من العقدة (limit من 1 إلى 1,000، والافتراضي 100): { "cells", "next" }؛ ويردّ 404 على سلسلة لا تحتوي قسم program_state |
GET /search?q= | الكتل والمعاملات والبرامج والمذكرات والمبطِلات (nullifiers) والمصادِقون |
curl -s https://randscan.org/api/v1/stats
curl -s https://randscan.org/api/v1/tokens/1
curl -s https://randscan.org/api/v1/transactions/8aa13d1f76d28f63a46c30bb09ef44b1ba35083ca80ba7301997f98e5f783666ملخص معاملة (عملية mint من الصنبور بقيمة 10 RAND عند الارتفاع 102,197 من السلسلة 18):
{
"hash": "a20b…feb5", "height": 102197, "block_hash": "f362…a06f", "tx_index": 0,
"kind": "mint", "fee": "0", "timestamp_ms": 1790777106034,
"has_bundle": false, "program": null, "validator": "EdrEC2QRQrQF64iRXxF9927jNj6RidiHHByzx5xD6F1e",
"amount": "10000000000", "asset_index": null
}لا يُملأ amount إلا للأنواع ذات المبلغ العام — mint وbond وunbond وwithdraw وbridge_attest وbridge_burn وtoken_mint وtoken_burn، وكذلك register_token ذو السك الأولي — ويكون null في التحويل، الذي يكون asset_index فيه null دائمًا أيضًا. وhas_bundle قيمته false للأنواع mint وunbond وwithdraw وpause_mints وunpause_mints، التي لا تحمل حزمة ولا تدفع رسمًا. ويضيف التفصيل chain_id وbundle، ثم بحسب النوع: words_len للنشر (deploy)؛ وcall_proof_len وinput_envelope_len وreceipt للاستدعاء (call) (tx وprogram وtier وoutputs وheight وindex وh_in وh_pub)؛ وregistered للربط (bond)؛ وaction_nonce لفكّ الربط (unbond) أو السحب (withdraw)؛ وattestation_len وrecipient وnote_time وdeposit_r وcommitment وpq_signers لإقرار الجسر؛ وrelayer_fee وto_chain وbridge_to وbridge_token لحرق الجسر؛ وtoken_action لإجراء RPL (حقول الإجراء نفسه، موسومة بـ kind)، مع recipient وnote_time وdeposit_r للمذكرة المسكوكة، وaction_nonce لـ token_mint أو set_authority؛ وbridge_governance لإجراء حوكمة الجسر، مع pq_signers في كل الإجراءات عدا pause_mints؛ وcall_proof_len وinput_envelope_len وreceipt وtransition لـ invoke (عرض العقدة: الخلايا المقروءة والمكتوبة، وinflow، وكل مذكرة pays وmints مع recipient وtime وr وcm). أما النوع الجديد في v0.6.8 الذي لا يعرفه إصدار المستكشف هذا (admit_validator وslash_equivocation وتدويرات _v2 وcancel_rotation) فيظهر other.
على السلسلة 20، مع رسوم الجسر، يكون amount في bridge_attest وbridge_burn هو الإجمالي: المبلغ الذي وقّع عليه الحراس، أو المبلغ الذي أحرقته الحزمة. ولا يقدّم المستكشف صافي الإيداع ولا المبلغ المُفرَج عنه ولا مذكرة الرسم؛ فاقرأها من rand_getTransaction في العقدة (deposit_amount وrelease_amount وfee_note) ومن rand_getBridgeBurn. فحرق 0.999 zUSD عند الارتفاع 2,899 يظهر هنا "amount": "99900000"؛ بينما وقّع الحراس على إفراج قدره 99800100.
الحزمة في تفاصيل المعاملة هي حزمة الأصل المخفي، بلا حقل أصل ولا حزمة ثانية عند الحرق. وقد دفعت هذه الحزمة ثمن الاستدعاء في مثال curl أعلاه، عند الارتفاع 98,335 من السلسلة 18؛ وهذه المعاملة غير موجودة على السلسلة 20، حيث يردّ curl الثالث بالرمز 404:
"bundle": {
"anchor": "b814…b1ed",
"nullifiers": ["49d4…a766", "3363…61ea", "aac0…fcfc", "546c…3efd"],
"commitments": ["b52b…4f7b", "9ddd…0448", "5fa7…1630", "2827…8343"],
"fee": "6191437", "burn_a": "0", "burn_r": "0", "burn_asset": 0, "time": 98185,
"proof_len": 1504260, "envelope_len": [1860, 1860, 1860, 1860],
"auth_commit": "0bda…6512", "auth_proof_len": 1367303
}auth_commit وauth_proof_len هما التفويض المجزّأ (السلسلة 17 وما بعدها، حيث يكون limits.hc_auth مضبوطًا): يُصنع إثبات الحزمة من مفتاح العرض وينشر auth_commit، ويجب أن يطابقه إثبات ثانٍ صغير على مفتاح الإنفاق، مرتبط بالمعاملة نفسها. ويُبلَّغ عن الإثباتين بطولهما فقط. وكل مغلّف على السلسلة 20 حجمه 1,860 بايت (limits.envelope_bytes) ويحمل مذكرة مشفرة؛ أما السلاسل حتى 17 فكانت تختم 1,348 بايت. وحد الغاز المعلن للاستدعاء قيمة عامة في إثباته، لا حقلًا في الإيصال، ولذلك لا يعرضه المستكشف لكل معاملة؛ أما الرسم الذي دفعته فهو في fee.
burn_a هو الأصل الخاص المحروق، ولا يكون غير صفري إلا في token_burn أو bridge_burn أو invoke يودع رمزًا أو يحرقه، ويحدد burn_asset فهرس السجل؛ أما burn_r فهو مقدار RAND المحروق، ولا يكون غير صفري إلا في bond أو invoke يودع RAND في خزينة البرنامج.
على chain 20 يقع zUSD (“Shielded USD”، ثمانية منازل عشرية) عند الفهرس 1، وهو مدرج في genesis مع جميع الضمانات السبعة (registered_at يساوي 0، ولذلك فإن deploy_tx هو null)، ومنقول من chain 14 بمعرّف الأصل نفسه. ولذلك يعيد GET /bridge/assets سبعة صفوف تحت الفهرس 1. وسُجّلت خمسة رموز أخرى على chain 20 في يومها الأول، عند الفهارس من 2 إلى 6، ثلاثة منها بسلطة سكّ هي برنامج؛ ويسردها GET /tokens. وعلى chain 20 يعرض GET /bridge القيمة rules_v2 مع سقف سكّ عام قدره 4,000 zUSD ("400000000000") لكل نافذة مدتها 86,400 ثانية، وrotation_nonce يساوي 0، وburn_sequence يساوي 13 عند genesis، وmin_inbound_sequence يساوي 3 لسلاسل المصدر 2 و3 و4، و7 لسلسلة المصدر 5 (1 و4 على chain 19): وهو الحد الأدنى لإعادة التشغيل في genesis، أي أدنى تسلسل قفل يجوز أن تحمله شهادة سلسلة مصدر لكي يُسكّ هنا. أما على chain 14 فقد سُجّل عند الارتفاع 256 بواسطة register_bridged_token، وأُضيفت الضمانات الستة الأخرى بمعاملات list_backing.
فتح المظاريف في المتصفح
المظروف بيانات عامة على السلسلة، ولا يحتفظ المستكشف بأي مفتاح. تفتح صفحة المعاملة وصفحة History المظاريف في المتصفح عبر نسخة WebAssembly من شيفرة العقدة نفسها (crates/randscan-viewing): الصق مفتاح عرض (nk، 64 رمزًا سداسي عشريًا) لترى كل note أرسلها ذلك الطرف أو استلمها، أو مفتاح معاملة لفتح دفعة واحدة، أو مفتاح استدعاء لفتح مدخلات استدعاء واحد، أو ملف مفتاح محفظة لا يُحتفظ منه إلا بمفتاح العرض المشتق. ويُتحقق من أي note مفتوحة بإعادة حساب التزامها. وasset المفصح عنه فيها هو فهرس سجل الرموز، ويُحلّ عبر GET /tokens للحصول على الرمز والمنازل العشرية؛ وهذا هو الموضع الوحيد الذي يُربط فيه مقدار بأصل في عملية تحويل. وتُفتح خانة وهمية بلا أي مفتاح وتُقرأ مثل note ليست لك. لا يخرج شيء عن المفتاح عبر الشبكة؛ ولبناء الأداة نفسها، اجلب /envelopes و/transactions/:hash/envelopes واستخدم الحزمة.
بث WebSocket
اتصل بـ wss://randscan.org/ws واشترك في blocks أو transactions أو stats:
{ "type": "subscribe", "channel": "blocks" }
{ "type": "new_block", "block": { … BlockSummary … } }
{ "type": "new_transaction", "transaction": { … TransactionSummary … } }
{ "type": "stats_update", "stats": { … } }أرسل { "type": "ping" } كل 30 ثانية عبر الوسطاء. لا يوفّر البث إعادة تشغيل: عند الانقطاع، أعد الاتصال واملأ الفجوة بـ GET /transactions?height=.
تشغيل مستكشفك الخاص
كل ما هنا يخدمه المستكشف مفتوح المصدر في randprotocol/randscan.org؛ ولا يحتاج المفهرس إلا إلى rand_* JSON-RPC لعقدة وقاعدة بيانات PostgreSQL.