Utilisez l’API de l’explorateur pour lire la chaîne 20 depuis un script, un bot ou un backend, sans exécuter de nœud. Le guide complet, avec chaque champ, se trouve dans le dépôt de l’explorateur, randscan.org/docs/api.md ; cette page en est le résumé.
| URL de base | https://randscan.org/api/v1 |
| WebSocket | wss://randscan.org/ws |
| anonyme | 60 requêtes par minute et par IP |
| avec une clé d’API | 600 requêtes par minute ; clés sur randscan.org/dashboard, envoyées sous la forme Authorization: Bearer rsk_… ou X-API-Key |
Ce que l’explorateur d’une chaîne blindée peut montrer
Cette API ne comporte nulle part de comptes, de soldes, d’expéditeurs ni de destinataires, et depuis la chaîne 14 aucun actif public sur un lot : un transfert de RAND et un transfert de n’importe quel jeton RPL ont la même forme. Elle sert chaque bloc ; le lot à actif masqué de chaque transaction tel qu’il a été publié (ancre, quatre nullifiers, quatre engagements, frais, burn_a, burn_r, burn_asset, heure, tailles de la preuve et de l’enveloppe, et depuis la chaîne 17 l’auth_commit et la taille de la preuve d’autorisation) ; l’action portée par une transaction et ses champs publics, y compris l’enregistrement, les émissions et les destructions d’un jeton RPL, les actions de gouvernance du pont et la transition d’état d’un invoke RPL-2 ; le registre des jetons RPL ; les cellules et le coffre d’un programme ; l’arbre d’engagements feuille par feuille ; l’ensemble des nullifiers ; le registre des validateurs ; l’audit de l’offre ; l’état public du pont, y compris sa pause d’émission et son ensemble de gardiens PQ. L’actif déplacé par un transfert n’est montré qu’à une clé de visualisation ou à une clé de transaction, dans le navigateur. GET /accounts/:address répond 410 { "error": "no_accounts" }.
Conventions : les montants sont des chaînes décimales d’unités. Un montant dont l’asset_index désigne un jeton autre que RAND (indice 0) est exprimé dans la plus petite unité de ce jeton, et non dans les neuf décimales de RAND ; résolvez l’indice avec GET /tokens/:id avant de diviser. registration_fee et next_index sont les deux champs que l’explorateur sert sous forme de nombres JSON ordinaires ; les hachages, identifiants de programme, engagements et nullifiers sont des chaînes de 64 caractères hexadécimaux en minuscules ; les adresses de validateur sont en base58 ; les hauteurs sont des entiers décimaux à partir de 0 ; seuls les blocs validés sont indexés, de sorte qu’un bloc présent dans l’API est final. Les listes acceptent page (à partir de 1) et limit (de 1 à 100, 20 par défaut), renvoient { "data": [...], "pagination": { page, limit, total, total_pages, has_next, has_prev } }, du plus récent au plus ancien. Les erreurs sont { "error", "message", "code" } avec 400, 404, 410, 429 ou 500.
Points d’accès
| méthode et chemin | renvoie |
|---|---|
GET /health | l’état de l’explorateur et le retard de l’indexeur |
GET /stats | l’identifiant de chaîne, la hauteur, la vue, la taille de l’arbre, le nombre de validateurs, la mise totale, l’offre, le nombre de programmes, le temps de bloc moyen, l’époque, le hachage de genèse et la version du nœud ; hc_bundle et hc_auth ; limits (les cinq plafonds de genèse, puis envelope_bytes, hardening_v6, hc_auth, le gas_price et le byte_price de genèse, gas_metering, bundle_gas_limit, adjust_bps, et program_state sur un nœud depuis v0.6.8) ; gas_prices, les prix en vigueur en tête de chaîne. limits ne porte pas les autres nouveaux champs de v0.6.8 (binding_domain, proof_window_blocks, les plafonds de prix, admission_by_vote, testnet) : lisez-les dans rand_getLimits du nœud |
GET /supply | l’audit de l’offre du nœud tel quel, y compris les quatre compteurs vesting_*, tous à "0" sur la chaîne 20, dont la genèse n’a pas de section vesting, ainsi que program_rand_out et program_rand_held de RPL-2, le RAND versé par les coffres de programmes et le RAND qu’ils détiennent encore |
GET /bridge | l’état public du pont : emitter, emitters, guardian_set_index, guardians, pq_guardians, mint_paused, pause_nonce, list_nonce, pause_key, registration_fee, burn_sequence, next_index (null depuis la chaîne 14), rotation_nonce, rules_v2 (avec global_minted_in_window et global_mint_headroom), min_inbound_sequence, assets, et endpoints, la représentation propre à l’explorateur de chaque émetteur, telle que sa chaîne d’origine l’écrit. Il ne sert pas les fees, rotation_rules ni pending_rotations de v0.6.8 du nœud : lisez-les dans rand_getBridgeState |
GET /bridge/assets | une ligne par garantie : la ligne du registre (index, chain, token, asset_id, locked, minted_today, mint_cap_per_day, et sur un nœud v0.6.8 minted_in_window, mint_window_secs et mint_headroom, le plus gros dépôt que les plafonds admettent actuellement) jointe à symbol, name, decimals et backings, et aux totaux indexés. Par garantie : burns, burned, outstanding (le locked du registre), et deposits/deposited seulement lorsque le jeton n’a qu’une garantie (null sinon : un dépôt nomme le jeton qu’il a émis, non la pièce verrouillée en contrepartie). Par jeton, identiques sur chaque ligne portant le même index : token_deposits, token_deposited, token_burns, token_burned, first_height, last_height ; comptez chaque index une seule fois lors des totalisations |
GET /bridge/tokens | la liste d’autorisation des jetons, une liste statique : USDT et USDC sur Ethereum, BSC, Tron et Solana, USDC sur Tron étant abandonné |
GET /tokens | le registre complet des jetons RPL tel que mis en cache depuis le nœud : enabled, registration_fee, next_index, tokens |
GET /tokens/:id | un jeton par indice de registre, identifiant en 64 caractères hexadécimaux ou forme textuelle rpl1…, plus deploy_tx et supply_history ; 404 si aucun ne correspond |
GET /nodes | le nœud de l’explorateur et ses pairs, avec géolocalisation |
GET /provers | les prouveurs délégués connus de l’explorateur (sa propre liste ; la chaîne n’en garde aucune trace) : si chacun répond à son prover_info, sa capacité et ses frais, et où se trouvent ses hôtes |
GET /blocks?page&limit&proposer, GET /blocks/latest?limit, GET /blocks/:id | les blocs, par hauteur ou par hachage |
GET /transactions?page&limit&kind&height&validator&program, GET /transactions/latest, GET /transactions/:hash | les transactions ; kind vaut 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. Il n’existe pas de token_transfer : un transfert de n’importe quel jeton RPL est un transfer |
GET /transactions/:hash/envelopes | les notes créées par une transaction avec leurs enveloppes : les quatre emplacements du lot, leurres compris, plus les notes calculées par la chaîne qu’ajoutent un dépôt bridge_attest, un token_mint, l’émission initiale d’un register_token ou les paiements d’un invoke ; pour un appel, h_in et la transcription d’entrée scellée |
GET /envelopes?from_leaf&limit | les feuilles avec enveloppes, de la plus ancienne à la plus récente, jusqu’à 1 000 par page, pour un balayage de l’historique |
GET /notes?page&limit, GET /notes/:id | les feuilles de l’arbre, par engagement ou par indice de feuille |
GET /nullifiers/:nf | la transaction qui a publié un nullifier |
GET /validators, GET /validators/:address | le registre, avec share_percent, blocks_proposed, la dernière hauteur proposée |
GET /programs?page&limit, GET /programs/:id | les programmes déployés (base_pc, words_len, code_hash, public_words_len, public_digest) avec leurs nombres d’appels et d’invocations ; les appels et invocations récents d’un programme, et son program_state, lu en direct depuis le nœud : vault (par actif), les 100 premières cells dans l’ordre des clés, et cells_next |
GET /programs/:id/cells?after&limit | une page des cellules du programme dans l’ordre des clés, en direct depuis le nœud (limit de 1 à 1 000, 100 par défaut) : { "cells", "next" } ; 404 sur une chaîne sans section program_state |
GET /search?q= | les blocs, transactions, programmes, notes, nullifiers et validateurs |
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/8aa13d1f76d28f63a46c30bb09ef44b1ba35083ca80ba7301997f98e5f783666Un résumé de transaction (un mint de faucet de 10 RAND à la hauteur 102 197 de la chaîne 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 n’est renseigné que pour les genres dotés d’un montant public — mint, bond, unbond, withdraw, bridge_attest, bridge_burn, token_mint, token_burn, et un register_token avec émission initiale — et vaut null pour un transfert, dont l’asset_index est toujours lui aussi null. has_bundle est faux pour mint, unbond, withdraw, pause_mints et unpause_mints, qui ne portent aucun lot et ne paient aucuns frais. Le détail ajoute chain_id, bundle, et selon le genre : le words_len d’un déploiement ; les call_proof_len, input_envelope_len et receipt d’un appel (tx, program, tier, outputs, height, index, h_in, h_pub) ; le registered d’un bond ; l’action_nonce d’un unbond ou d’un withdraw ; les attestation_len, recipient, note_time, deposit_r, commitment, pq_signers d’une attestation du pont ; les relayer_fee, to_chain, bridge_to, bridge_token d’une destruction du pont ; le token_action d’une action RPL (les champs propres à l’action, étiquetés par kind), avec recipient, note_time, deposit_r pour une note émise et action_nonce pour un token_mint ou un set_authority ; le bridge_governance d’une action de gouvernance du pont, avec pq_signers sur toutes sauf pause_mints ; les call_proof_len, input_envelope_len, receipt et transition d’un invoke (la représentation du nœud : les cellules lues et écrites, l’inflow, et chaque note de pays et de mints avec son recipient, son time, son r et son cm). Un genre de v0.6.8 que cette version de l’explorateur ne connaît pas (admit_validator, slash_equivocation, les rotations _v2, cancel_rotation) est other.
Sur la chaîne 20, avec les frais de pont, l’amount d’un bridge_attest et d’un bridge_burn est le montant brut : celui que les gardiens ont signé, ou celui que le lot a détruit. L’explorateur ne sert ni le dépôt net, ni le montant libéré, ni la note de frais ; lisez-les dans rand_getTransaction du nœud (deposit_amount, release_amount, fee_note) et dans rand_getBridgeBurn. La destruction de 0,999 zUSD à la hauteur 2 899 s’affiche ici "amount": "99900000" ; les gardiens ont signé une libération de 99800100.
Le lot d’un détail de transaction est le lot à actif masqué, sans champ d’actif et sans second lot sur une destruction. Celui-ci a payé l’appel de l’exemple curl ci-dessus, à la hauteur 98 335 de la chaîne 18 ; cette transaction n’existe pas sur la chaîne 20, où le troisième curl répond 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 et auth_proof_len relèvent de l’autorisation scindée (chaînes 17 et suivantes, où limits.hc_auth est défini) : la preuve du lot est produite à partir de la clé de visualisation et publie auth_commit, et une seconde petite preuve sur la clé de dépense, liée à la même transaction, doit lui correspondre. Les deux preuves ne sont indiquées que par leur longueur. Chaque enveloppe de la chaîne 20 fait 1 860 octets (limits.envelope_bytes) et porte un mémo chiffré ; les chaînes jusqu’à la 17 scellaient 1 348 octets. La limite de gaz déclarée d’un appel est une valeur publique de sa preuve, et non un champ du reçu ; l’explorateur ne l’affiche donc pas par transaction ; les frais payés figurent dans fee.
burn_a est l’actif privé brûlé, non nul uniquement pour un token_burn, un bridge_burn ou un invoke qui dépose ou brûle un jeton, burn_asset désignant l’indice du registre ; burn_r est la quantité de RAND brûlée, non nulle uniquement pour un bond ou un invoke qui dépose des RAND dans le coffre du programme.
Sur la chain 20, zUSD (« Shielded USD », huit décimales) se trouve à l’indice 1, inscrit dans le genesis avec les sept garanties (registered_at 0, donc deploy_tx vaut null) et reporté depuis la chain 14 sous le même identifiant d’actif. GET /bridge/assets renvoie donc sept lignes à l’indice 1. Cinq autres jetons ont été enregistrés sur la chain 20 dès son premier jour, aux indices 2 à 6, dont trois avec un programme comme autorité de mint ; GET /tokens les liste. Sur la chain 20, GET /bridge indique rules_v2 avec un plafond global de mint de 4 000 zUSD ("400000000000") par fenêtre de 86 400 secondes, rotation_nonce à 0, burn_sequence à 13 au genesis, et un min_inbound_sequence de 3 pour les chains sources 2, 3 et 4 et de 7 pour la chain source 5 (1 et 4 sur la chain 19) : le plancher de relecture du genesis, c’est-à-dire le plus petit numéro de séquence de verrouillage qu’une attestation d’une chain source peut porter pour être mintée ici. Sur la chain 14, il a été enregistré à la hauteur 256 par un register_bridged_token, les six autres garanties étant ajoutées par des transactions list_backing.
Ouvrir les enveloppes dans le navigateur
Une enveloppe est une donnée publique de la chain, et l’explorateur ne détient aucune clé. Sa page de transaction et sa page History ouvrent les enveloppes dans le navigateur grâce à une version WebAssembly du code propre au nœud (crates/randscan-viewing) : collez une clé de visualisation (nk, 64 hex) pour voir toutes les notes que cette partie a envoyées ou reçues, une clé de transaction pour ouvrir un paiement, une clé d’appel pour ouvrir les entrées d’un appel, ou un fichier de clé de portefeuille, dont seule la clé de visualisation dérivée est conservée. Une note ouverte est vérifiée en recalculant son engagement. Son asset divulgué est l’indice du registre des jetons, résolu via GET /tokens pour le symbole et les décimales ; c’est le seul endroit où un montant est rattaché à un actif pour un transfert. Un emplacement factice ne s’ouvre avec aucune clé et se lit comme une note qui n’est pas la vôtre. Rien d’une clé ne transite par le réseau ; pour construire le même outil, récupérez /envelopes et /transactions/:hash/envelopes et utilisez le crate.
Flux WebSocket
Connectez-vous à wss://randscan.org/ws et abonnez-vous à blocks, transactions ou stats :
{ "type": "subscribe", "channel": "blocks" }
{ "type": "new_block", "block": { … BlockSummary … } }
{ "type": "new_transaction", "transaction": { … TransactionSummary … } }
{ "type": "stats_update", "stats": { … } }Envoyez { "type": "ping" } toutes les 30 secondes à travers les proxys. Le flux n’offre aucune relecture : en cas de coupure, reconnectez-vous et comblez l’écart avec GET /transactions?height=.
Exécuter votre propre instance
Tout ce qui précède est servi par l’explorateur open source de randprotocol/randscan.org ; l’indexeur n’a besoin que du JSON-RPC rand_* d’un nœud et d’une base de données PostgreSQL.