Use a API do explorador para ler a chain 20 a partir de um script, de um bot ou de um backend, sem executar um nó. O guia completo, com todos os campos, está no repositório do explorador, randscan.org/docs/api.md; esta página é o resumo.
| URL base | https://randscan.org/api/v1 |
| WebSocket | wss://randscan.org/ws |
| anônimo | 60 requisições por minuto por IP |
| com chave de API | 600 requisições por minuto; as chaves vêm de randscan.org/dashboard e são enviadas como Authorization: Bearer rsk_… ou X-API-Key |
O que o explorador de uma cadeia blindada pode mostrar
Não há contas, saldos, remetentes nem destinatários em nenhum ponto desta API e, desde a chain 14, nenhum ativo público em um bundle: uma transferência de RAND e uma transferência de qualquer token RPL têm a mesma forma. O que ela serve é: cada bloco; o bundle de ativo oculto de cada transação, como publicado (âncora, quatro nullifiers, quatro compromissos, taxa, burn_a, burn_r, burn_asset, hora, tamanhos da prova e do envelope e, desde a chain 17, o auth_commit e o tamanho da prova de autorização); a ação que uma transação carregava e seus campos públicos, incluindo o registro, as emissões e as queimas de um token RPL, as ações de governança da ponte e a transição de estado de um invoke de RPL-2; o registro de tokens RPL; as células e o cofre de um programa; a árvore de compromissos folha a folha; o conjunto de nullifiers; o registro de validadores; a auditoria da oferta; o estado público da ponte, incluindo a pausa de emissões e o conjunto de guardiões PQ. O ativo que uma transferência moveu só é mostrado a uma chave de visualização ou a uma chave de transação, no navegador. GET /accounts/:address responde 410 { "error": "no_accounts" }.
Convenções: os valores são strings decimais de unidades. Um valor cujo asset_index nomeia um token diferente de RAND (índice 0) está na menor unidade do próprio token, não nas nove casas decimais do RAND; resolva o índice por meio de GET /tokens/:id antes de dividir. registration_fee e next_index são os dois campos que o explorador serve como números JSON simples; hashes, ids de programa, compromissos e nullifiers têm 64 caracteres hexadecimais minúsculos; os endereços de validadores são base58; as alturas são inteiros decimais a partir de 0; apenas blocos confirmados são indexados, portanto um bloco na API é final. As listas aceitam page (a partir de 1) e limit (1 a 100, padrão 20), retornam { "data": [...], "pagination": { page, limit, total, total_pages, has_next, has_prev } }, do mais recente para o mais antigo. Os erros são { "error", "message", "code" } com 400, 404, 410, 429 ou 500.
Endpoints
| método e caminho | retorna |
|---|---|
GET /health | estado do explorador e atraso do indexador |
GET /stats | id da chain, altura, view, tamanho da árvore, contagens de validadores, stake total, oferta, número de programas, tempo médio de bloco, época, o hash de gênese e o build do nó; hc_bundle e hc_auth; limits (os cinco limites de gênese, depois envelope_bytes, hardening_v6, hc_auth, o gas_price e o byte_price de gênese, gas_metering, bundle_gas_limit, adjust_bps e, em um nó desde a v0.6.8, program_state); gas_prices, os preços vigentes no topo da cadeia. limits não traz os demais campos novos da v0.6.8 (binding_domain, proof_window_blocks, os tetos de preço, admission_by_vote, testnet): leia-os em rand_getLimits, do nó |
GET /supply | a auditoria da oferta do nó, literal, incluindo os quatro contadores vesting_*, todos "0" na chain 20, cuja gênese não tem seção vesting, e program_rand_out e program_rand_held do RPL-2, o RAND pago pelos cofres de programas e o RAND que eles ainda guardam |
GET /bridge | o estado público da ponte: emitter, emitters, guardian_set_index, guardians, pq_guardians, mint_paused, pause_nonce, list_nonce, pause_key, registration_fee, burn_sequence, next_index (null desde a chain 14), rotation_nonce, rules_v2 (com global_minted_in_window e global_mint_headroom), min_inbound_sequence, assets e endpoints, a representação própria do explorador de cada emissor, como a chain de origem o imprime. Não serve fees, rotation_rules nem pending_rotations da v0.6.8 do nó: leia-os em rand_getBridgeState |
GET /bridge/assets | uma linha por lastro: a linha do registro (index, chain, token, asset_id, locked, minted_today, mint_cap_per_day e, em um nó v0.6.8, minted_in_window, mint_window_secs e mint_headroom, o maior depósito que os limites admitem agora) combinada com symbol, name, decimals e backings, e os totais indexados. Por lastro: burns, burned, outstanding (o locked do registro) e deposits/deposited somente quando o token tem um único lastro (null caso contrário: um depósito nomeia o token que emitiu, não a moeda bloqueada para isso). Por token, idênticos em toda linha com o mesmo index: token_deposits, token_deposited, token_burns, token_burned, first_height, last_height; conte cada index uma única vez ao somar |
GET /bridge/tokens | a lista de tokens permitidos, uma lista estática: USDT e USDC em Ethereum, BSC, Tron e Solana, com USDC em Tron descontinuado |
GET /tokens | o registro completo de tokens RPL, em cache a partir do nó: enabled, registration_fee, next_index, tokens |
GET /tokens/:id | um token por índice de registro, id de 64 caracteres hexadecimais ou forma textual rpl1…, mais deploy_tx e supply_history; 404 quando nenhum corresponde |
GET /nodes | o nó do explorador e seus pares, com geolocalização |
GET /provers | os provadores delegados que o explorador conhece (lista própria dele; a chain não guarda registro deles): se cada um responde a prover_info, sua capacidade e taxa, e onde estão seus hosts |
GET /blocks?page&limit&proposer, GET /blocks/latest?limit, GET /blocks/:id | blocos, por altura ou hash |
GET /transactions?page&limit&kind&height&validator&program, GET /transactions/latest, GET /transactions/:hash | transações; 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. Não existe token_transfer: uma transferência de qualquer token RPL é transfer |
GET /transactions/:hash/envelopes | as notas que uma transação criou, com seus envelopes: os quatro slots do bundle, incluindo os dummies, mais as notas calculadas pela chain que um depósito de bridge_attest, um token_mint, a emissão inicial de um register_token ou os pagamentos de um invoke acrescentam; para uma chamada, h_in e a transcrição de entrada selada |
GET /envelopes?from_leaf&limit | folhas com envelopes, das mais antigas para as mais recentes, até 1.000 por página, para uma varredura do histórico |
GET /notes?page&limit, GET /notes/:id | folhas da árvore, por compromisso ou índice da folha |
GET /nullifiers/:nf | a transação que publicou um nullifier |
GET /validators, GET /validators/:address | o registro, com share_percent, blocks_proposed e a última altura proposta |
GET /programs?page&limit, GET /programs/:id | programas implantados (base_pc, words_len, code_hash, public_words_len, public_digest) com contagens de chamadas e de invokes; as chamadas e os invokes recentes de um programa e seu program_state, lido ao vivo do nó: vault (por ativo), as 100 primeiras cells em ordem de chave e cells_next |
GET /programs/:id/cells?after&limit | uma página das células do programa em ordem de chave, ao vivo do nó (limit de 1 a 1.000, padrão 100): { "cells", "next" }; 404 em uma chain sem seção program_state |
GET /search?q= | blocos, transações, programas, notas, nullifiers e validadores |
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/8aa13d1f76d28f63a46c30bb09ef44b1ba35083ca80ba7301997f98e5f783666Um resumo de transação (um mint do faucet de 10 RAND na altura 102.197 da 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 só é preenchido para os tipos com valor público — mint, bond, unbond, withdraw, bridge_attest, bridge_burn, token_mint, token_burn e um register_token com emissão inicial — e é null para uma transferência, cujo asset_index também é sempre null. has_bundle é falso para mint, unbond, withdraw, pause_mints e unpause_mints, que não carregam bundle e não pagam taxa. O detalhe acrescenta chain_id, bundle e, por tipo: o words_len de um deploy; o call_proof_len, o input_envelope_len e o receipt de uma chamada (tx, program, tier, outputs, height, index, h_in, h_pub); o registered de um bond; o action_nonce de um unbond ou withdraw; o attestation_len, recipient, note_time, deposit_r, commitment e pq_signers de uma atestação da ponte; o relayer_fee, to_chain, bridge_to e bridge_token de uma queima da ponte; o token_action de uma ação RPL (os campos próprios da ação, marcados por kind), com recipient, note_time e deposit_r para uma nota emitida e action_nonce para um token_mint ou set_authority; o bridge_governance de uma ação de governança da ponte, com pq_signers em todas, exceto pause_mints; o call_proof_len, o input_envelope_len, o receipt e a transition de um invoke (a representação do nó: as células lidas e escritas, o inflow e cada nota de pays e mints com seu recipient, time, r e cm). Um tipo da v0.6.8 que este build do explorador não conhece (admit_validator, slash_equivocation, as rotações _v2, cancel_rotation) é other.
Na chain 20, com taxas de ponte, o amount de um bridge_attest e de um bridge_burn é o valor bruto: o valor que os guardiões assinaram ou o valor que o bundle queimou. O explorador não serve o depósito líquido, o valor liberado nem a nota de taxa; leia-os em rand_getTransaction (deposit_amount, release_amount, fee_note) e em rand_getBridgeBurn, do nó. A queima de 0,999 zUSD na altura 2.899 aparece aqui como "amount": "99900000"; os guardiões assinaram uma liberação de 99800100.
O bundle no detalhe de uma transação é o bundle de ativo oculto, sem campo de ativo e sem segundo bundle em uma queima. Este pagou pela chamada do exemplo curl acima, na altura 98.335 da chain 18; essa transação não existe na chain 20, onde o terceiro curl responde 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 e auth_proof_len são a autorização dividida (chains 17 e posteriores, onde limits.hc_auth está definido): a prova do bundle é feita a partir da chave de visualização e publica auth_commit, e uma segunda prova, pequena, sobre a chave de gasto, vinculada à mesma transação, deve corresponder a ele. As duas provas são informadas apenas pelo tamanho. Todo envelope na chain 20 tem 1.860 bytes (limits.envelope_bytes) e carrega um memorando criptografado; as chains até a 17 selavam 1.348 bytes. O limite de gas declarado de uma chamada é um valor público de sua prova, não um campo do recibo, portanto o explorador não o mostra por transação; a taxa que ela pagou está em fee.
burn_a é o ativo privado queimado, diferente de zero apenas em um token_burn, um bridge_burn ou um invoke que deposita ou queima um token, com burn_asset indicando o índice no registro; burn_r é a quantidade de RAND queimada, diferente de zero apenas em um bond ou em um invoke que deposita RAND no vault do programa.
Na chain 20, zUSD (“Shielded USD”, oito casas decimais) está no índice 1, listado no genesis com todos os sete lastros (registered_at 0, portanto deploy_tx é null) e herdado da chain 14 sob o mesmo identificador de ativo. GET /bridge/assets retorna, portanto, sete linhas sob o índice 1. Outros cinco tokens foram registrados na chain 20 em seu primeiro dia, nos índices 2 a 6, três deles com um programa como autoridade de emissão; GET /tokens os lista. Na chain 20, GET /bridge informa rules_v2 com um limite global de emissão de 4.000 zUSD ("400000000000") por janela de 86.400 segundos, rotation_nonce 0, burn_sequence 13 no genesis e um min_inbound_sequence de 3 para as chains de origem 2, 3 e 4 e de 7 para a chain de origem 5 (1 e 4 na chain 19): o piso de repetição do genesis, a menor sequência de bloqueio que a atestação de uma chain de origem pode ter para ser emitida aqui. Na chain 14, foi registrado na altura 256 por um register_bridged_token, com os outros seis lastros adicionados por transações list_backing.
Abrir envelopes no navegador
Um envelope é dado público da chain, e o explorer não guarda nenhuma chave. A página de transação e a página de Histórico abrem envelopes no navegador, com uma compilação em WebAssembly do código do próprio nó (crates/randscan-viewing): cole uma chave de visualização (nk, 64 hex) para ver todas as notes que aquela parte enviou ou recebeu, uma chave de transação para abrir um pagamento, uma chave de chamada para abrir as entradas de uma chamada, ou um arquivo de chave da carteira, do qual apenas a chave de visualização derivada é mantida. Uma note aberta é verificada recalculando-se seu compromisso. O asset divulgado é o índice do registro de tokens, resolvido por meio de GET /tokens para obter o símbolo e as casas decimais; é o único lugar em que um valor é associado a um ativo em uma transferência. Um slot fictício não abre com nenhuma chave e aparece da mesma forma que uma note que não é sua. Nada sobre uma chave trafega pela rede; para construir a mesma ferramenta, busque /envelopes e /transactions/:hash/envelopes e use o crate.
Feed WebSocket
Conecte-se a wss://randscan.org/ws e assine blocks, transactions ou stats:
{ "type": "subscribe", "channel": "blocks" }
{ "type": "new_block", "block": { … BlockSummary … } }
{ "type": "new_transaction", "transaction": { … TransactionSummary … } }
{ "type": "stats_update", "stats": { … } }Envie { "type": "ping" } a cada 30 segundos através de proxies. O feed não tem reexecução: em caso de queda, reconecte e recupere o histórico com GET /transactions?height=.
Executar o seu próprio
Tudo aqui é servido pelo explorer de código aberto em randprotocol/randscan.org; o indexador precisa apenas do JSON-RPC rand_* de um nó e de um banco de dados PostgreSQL.