از API اکسپلورر برای خواندن chain 20 از یک اسکریپت، یک ربات یا یک بک‌اند بدون اجرای گره استفاده کنید. راهنمای کامل با همه فیلدها در مخزن اکسپلورر است: randscan.org/docs/api.md؛ این صفحه خلاصه‌ای از آن است.
| نشانی پایه | https://randscan.org/api/v1 |
| WebSocket | wss://randscan.org/ws |
| ناشناس | ۶۰ درخواست در دقیقه برای هر IP |
| با کلید API | ۶۰۰ درخواست در دقیقه؛ کلیدها از randscan.org/dashboard گرفته می‌شوند و به صورت Authorization: Bearer rsk_… یا X-API-Key ارسال می‌شوند |
اکسپلورر یک زنجیرهٔ محافظت‌شده چه چیزی می‌تواند نشان دهد
در این API هیچ حساب، موجودی، فرستنده یا گیرنده‌ای وجود ندارد، و از chain 14 به بعد هیچ دارایی عمومی‌ای روی یک بسته (bundle) نیست: انتقال RAND و انتقال هر توکن RPL هم‌شکل‌اند. آنچه این API ارائه می‌کند این‌هاست: هر بلوک؛ بستهٔ دارایی پنهان هر تراکنش به همان صورت که منتشر شده (anchor، چهار nullifier، چهار commitment، کارمزد، burn_a، burn_r، burn_asset، زمان، اندازهٔ اثبات و envelope، و از chain 17 به بعد auth_commit و اندازهٔ اثبات احراز)؛ کنشی که یک تراکنش حمل کرده و فیلدهای عمومی آن، از جمله ثبت، mint و burn یک توکن RPL، کنش‌های حاکمیت پل و گذار حالت یک invoke از نوع RPL-2؛ رجیستری توکن‌های RPL؛ سلول‌ها و خزانهٔ (vault) یک برنامه؛ درخت commitment به تفکیک برگ؛ مجموعهٔ nullifierها؛ دفتر اعتبارسنج‌ها؛ حسابرسی عرضه؛ و وضعیت عمومی پل، از جمله توقف mint و مجموعهٔ نگهبانان PQ آن. اینکه یک انتقال کدام دارایی را جابه‌جا کرده فقط به یک کلید مشاهده یا یک کلید تراکنش، در مرورگر، نشان داده می‌شود. GET /accounts/:address پاسخ 410 { "error": "no_accounts" } می‌دهد.
قراردادها: مقدارها رشته‌های اعشاری از واحدها هستند. مقداری که asset_index آن به توکنی غیر از RAND (اندیس 0) اشاره کند، بر حسب کوچک‌ترین واحد خود آن توکن است، نه نُه رقم اعشار RAND؛ پیش از تقسیم کردن، اندیس را از طریق GET /tokens/:id به توکن مربوط تبدیل کنید. registration_fee و next_index دو فیلدی هستند که اکسپلورر به صورت عدد ساده در JSON ارائه می‌کند؛ هش‌ها، شناسه‌های برنامه، commitmentها و nullifierها ۶۴ نویسهٔ hex با حروف کوچک هستند؛ نشانی اعتبارسنج‌ها base58 است؛ ارتفاع‌ها اعداد صحیح اعشاری از 0 هستند؛ فقط بلوک‌های commitشده نمایه می‌شوند، بنابراین بلوک موجود در API نهایی است. فهرست‌ها 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، اندازهٔ درخت، تعداد اعتبارسنج‌ها، کل stake، عرضه، تعداد برنامه‌ها، میانگین زمان بلوک، epoch، هش genesis و build گره؛ hc_bundle و hc_auth؛ limits (پنج سقف genesis، سپس envelope_bytes، hardening_v6، hc_auth، gas_price و byte_price در genesis، gas_metering، bundle_gas_limit، adjust_bps، و در گره از v0.6.8 به بعد program_state)؛ gas_prices، قیمت‌های زندهٔ سر زنجیره. limits فیلدهای جدید دیگر v0.6.8 را ندارد (binding_domain، proof_window_blocks، سقف قیمت‌ها، admission_by_vote، testnet): آن‌ها را از rand_getLimits گره بخوانید |
GET /supply | حسابرسی عرضهٔ گره بدون تغییر، از جمله چهار شمارندهٔ vesting_* که در chain 20 همگی "0" هستند چون genesis آن بخش 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 (از chain 14 به بعد null)، rotation_nonce، rules_v2 (با global_minted_in_window و global_mint_headroom)، min_inbound_sequence، assets، و endpoints، یعنی نمایش خود اکسپلورر از هر emitter به همان صورت که زنجیرهٔ مبدأ آن را چاپ می‌کند. fees، rotation_rules و pending_rotations مربوط به v0.6.8 گره را ارائه نمی‌کند: آن‌ها را از rand_getBridgeState بخوانید |
GET /bridge/assets | یک سطر برای هر پشتوانه: سطر رجیستری (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: یک واریز توکنی را که mint کرده نام می‌برد، نه سکه‌ای را که برای آن قفل شده است). برای هر توکن، یکسان در هر سطر با 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 | یک توکن بر اساس اندیس رجیستری، شناسهٔ ۶۴ رقمی hex یا شکل متنی 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 | یادداشت‌هایی که یک تراکنش ساخته، با envelopeهایشان: چهار شکاف بسته، با احتساب یادداشت‌های ساختگی (dummy)، به‌علاوهٔ یادداشت‌هایی که زنجیره محاسبه می‌کند و یک واریز bridge_attest، یک token_mint، mint اولیهٔ یک register_token یا پرداخت‌های یک invoke اضافه می‌کنند؛ برای یک call، h_in و رونوشت ورودی مهروموم‌شده |
GET /envelopes?from_leaf&limit | برگ‌های دارای envelope، قدیمی‌ترین‌ها اول، تا ۱٬۰۰۰ مورد در هر صفحه، برای پویش تاریخچه |
GET /notes?page&limit، GET /notes/:id | برگ‌های درخت، بر اساس commitment یا اندیس برگ |
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ها؛ callها و invokeهای اخیر یک برنامه، و program_state آن که زنده از گره خوانده می‌شود: vault (به تفکیک دارایی)، ۱۰۰ سلول اول به ترتیب کلید در cells، و cells_next |
GET /programs/:id/cells?after&limit | یک صفحه از سلول‌های برنامه به ترتیب کلید، زنده از گره (limit از 1 تا ۱٬۰۰۰، پیش‌فرض 100): { "cells", "next" }؛ در زنجیره‌ای که بخش program_state ندارد 404 |
GET /search?q= | بلوک‌ها، تراکنش‌ها، برنامه‌ها، یادداشت‌ها، nullifierها و اعتبارسنج‌ها |
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 از faucet به مقدار 10 RAND در ارتفاع ۱۰۲٬۱۹۷ از chain 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 با mint اولیه — و برای یک transfer که asset_index آن هم همیشه null است، null است. has_bundle برای mint، unbond، withdraw، pause_mints و unpause_mints که بسته‌ای حمل نمی‌کنند و کارمزدی نمی‌پردازند، false است. جزئیات این موارد را اضافه می‌کند: chain_id، bundle، و برای هر نوع: words_len برای deploy؛ call_proof_len، input_envelope_len و receipt (tx، program، tier، outputs، height، index، h_in، h_pub) برای call؛ registered برای bond؛ action_nonce برای unbond یا withdraw؛ attestation_len، recipient، note_time، deposit_r، commitment، pq_signers برای یک گواهی پل؛ relayer_fee، to_chain، bridge_to، bridge_token برای یک burn پل؛ token_action برای یک کنش RPL (فیلدهای خود کنش، برچسب‌خورده با kind)، با recipient، note_time، deposit_r برای یک یادداشت mintشده و 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 که این build اکسپلورر نمی‌شناسد (admit_validator، slash_equivocation، rotationهای _v2، cancel_rotation) other است.
در chain 20، با وجود کارمزدهای پل، amount در bridge_attest و bridge_burn مقدار ناخالص است: مقداری که نگهبانان امضا کرده‌اند، یا مقداری که بسته burn کرده است. اکسپلورر واریز خالص، مقدار آزادشده یا یادداشت کارمزد را ارائه نمی‌کند؛ آن‌ها را از rand_getTransaction گره (deposit_amount، release_amount، fee_note) و rand_getBridgeBurn بخوانید. burn مقدار 0.999 zUSD در ارتفاع ۲٬۸۹۹ اینجا "amount": "99900000" نشان داده می‌شود؛ نگهبانان آزادسازی 99800100 را امضا کردند.
بسته در جزئیات تراکنش همان بستهٔ دارایی پنهان است، بدون فیلد دارایی و بدون بستهٔ دوم در burn. این بسته هزینهٔ call در مثال curl بالا را در ارتفاع ۹۸٬۳۳۵ از chain 18 پرداخته است؛ آن تراکنش در chain 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 همان احراز تقسیم‌شده هستند (chain 17 و بعد از آن، که limits.hc_auth در آن‌ها تنظیم شده است): اثبات بسته از کلید مشاهده ساخته می‌شود و auth_commit را منتشر می‌کند، و یک اثبات دوم و کوچک روی کلید خرج‌کردن، که به همان تراکنش گره خورده است، باید با آن مطابقت کند. هر دو اثبات فقط با طول گزارش می‌شوند. هر envelope در chain 20 برابر ۱٬۸۶۰ بایت است (limits.envelope_bytes) و یک memo رمزگذاری‌شده دارد؛ زنجیره‌ها تا 17 مقدار ۱٬۳۴۸ بایت را مهروموم می‌کردند. سقف gas اعلام‌شدهٔ یک call مقداری عمومی از اثبات آن است، نه فیلدی از receipt، بنابراین اکسپلورر آن را برای هر تراکنش نشان نمی‌دهد؛ کارمزدی که پرداخته در fee است.
burn_a دارایی خصوصیِ سوزانده‌شده است و فقط در token_burn، bridge_burn یا invokeای که توکنی را واریز یا می‌سوزاند غیرصفر است، و burn_asset شاخص ثبت‌نام (registry) را مشخص می‌کند؛ burn_r مقدار RAND سوزانده‌شده است و فقط در bond یا invokeای که RAND را به vault برنامه واریز می‌کند غیرصفر است.
در chain 20، zUSD («Shielded USD»، هشت رقم اعشار) در شاخص 1 قرار دارد و در genesis با هر هفت پشتوانه فهرست شده است (registered_at برابر 0 است، بنابراین deploy_tx برابر null است) و با همان شناسه دارایی از chain 14 منتقل شده است. بنابراین GET /bridge/assets هفت ردیف زیر شاخص 1 برمی‌گرداند. پنج توکن دیگر در همان روز نخست در chain 20 و در شاخص‌های 2 تا 6 ثبت شدند که سه‌تای آن‌ها یک برنامه را به‌عنوان مرجع ضرب (mint authority) دارند؛ 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 (در chain 19 برابر 1 و 4): کف بازپخش (replay) در genesis، یعنی کمترین شماره‌ترتیب قفل که گواهی یک زنجیره مبدأ می‌تواند داشته باشد تا در اینجا ضرب شود. در chain 14، این توکن در ارتفاع 256 با یک register_bridged_token ثبت شد و شش پشتوانه دیگر با تراکنش‌های list_backing افزوده شدند.
باز کردن envelopeها در مرورگر
envelope داده عمومی زنجیره است و explorer هیچ کلیدی در اختیار ندارد. صفحه تراکنش و صفحه History آن، envelopeها را در مرورگر با یک نسخه WebAssembly از کد خود node (crates/randscan-viewing) باز می‌کنند: یک viewing key (nk، 64 رقم hex) را بچسبانید تا هر noteای را که آن طرف فرستاده یا دریافت کرده است ببینید، یک transaction key تا یک پرداخت را باز کنید، یک call key تا ورودی‌های یک فراخوانی را باز کنید، یا یک فایل کلید کیف پول، که از آن فقط viewing key مشتق‌شده نگه داشته می‌شود. note بازشده با محاسبه دوباره commitment آن راستی‌آزمایی می‌شود. asset افشاشده آن، شاخص ثبت‌نام توکن است که نماد و تعداد ارقام اعشار آن از طریق GET /tokens به‌دست می‌آید؛ این تنها جایی است که یک مقدار در یک انتقال به یک دارایی گره می‌خورد. یک اسلات ساختگی (dummy) با هیچ کلیدی باز نمی‌شود و مانند noteای که متعلق به شما نیست دیده می‌شود. هیچ چیز درباره کلید از طریق شبکه ارسال نمی‌شود؛ برای ساخت همین ابزار، /envelopes و /transactions/:hash/envelopes را دریافت کنید و از آن crate استفاده کنید.
فید 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": { … } }برای عبور از پراکسی‌ها، هر 30 ثانیه { "type": "ping" } بفرستید. این فید بازپخش ندارد: در صورت قطع شدن، دوباره متصل شوید و با GET /transactions?height= داده‌های از دست‌رفته را تکمیل کنید.
اجرای نسخه خودتان
همه آنچه در اینجا ارائه می‌شود توسط explorer متن‌باز در randprotocol/randscan.org سرو می‌شود؛ indexer فقط به rand_* JSON-RPC یک node و یک پایگاه داده PostgreSQL نیاز دارد.