Traces de transações: debug_traceTransaction e endpoints de trace da Data API

Duas formas de reconstruir uma árvore de chamadas

Um trace de transação é a árvore de chamadas reconstruída de uma execução: qual contrato foi chamado, com qual entrada, quanto gas consumiu e quais subchamadas realizou. A BlockVectra o disponibiliza por meio de duas superfícies:

• Métodos debug_trace de JSON-RPC (como debug_traceTransaction) — executados no nó da rede via endpoint JSON-RPC, permitindo rastrear o estado recente que o nó ainda mantém.
• Traces da Data API — GET /{chain}/transactions/{hash}/trace e GET /{chain}/blocks/{number}/traces retornam árvores de chamadas armazenadas e indexadas via REST.

Ambos usam a mesma API key e são medidos em CU pelo peso do método (consulte os pesos abaixo). A escolha adequada depende se você precisa de uma única transação ou de um bloco inteiro, de quão recente é o alvo e se deseja percorrer um bloco completo sem paginação.

Limites aplicáveis aos métodos debug_trace

As requisições debug_trace são aceitas apenas para métodos e rastreadores permitidos pela política de métodos da rede:

• Rastreadores permitidos: o parâmetro tracer aceita apenas os rastreadores nativos integrados — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, ou a omissão dele para usar o registrador de estruturas padrão. Qualquer outro valor é rejeitado com o erro JSON-RPC -32602 tracer not allowed (não cobrado).
• Tempo limite de trace: o parâmetro timeout deve ser uma duração válida e de no máximo 30s; caso contrário, a requisição será rejeitada com -32602 trace timeout not allowed (não cobrado).
• Proteção de sincronização do nó: enquanto o nó de uma rede não estiver sincronizado, todos os métodos exceto eth_chainId — incluindo os métodos debug_trace — retornam -32010 (não cobrado).
• Janela de estado: debug_traceCall, debug_traceBlockByNumber, debug_traceTransaction e debug_traceBlockByHash têm como alvo um bloco que deve estar dentro da janela de estado da rede. Um alvo anterior à janela, ou que use as tags safe, finalized ou earliest, retorna -32011 (não cobrado).
• Consultas de hash e bloco: um hash malformado ou desconhecido retorna -32000 transaction not found / block not found; uma falha temporária retorna -32603 upstream unavailable (repetível). Não cobrado.
• Política de métodos por rede: quais métodos debug_trace uma rede permite é publicado pela resposta pública de GET /v1/chains. Leia-a em tempo de execução em vez de fixar uma lista de métodos no código; as redes estão listadas em Redes suportadas, e a referência de métodos está na página de métodos JSON-RPC.

Requisitando debug_traceTransaction com callTracer

A chamada abaixo adiciona o parâmetro tracer para solicitar uma árvore de chamadas:

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# Add "tracer" to request a call tree with one of the allowed native tracers.
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "debug_traceTransaction",
    "params": [
      "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      { "tracer": "callTracer" }
    ]
  }'

O que os endpoints de trace da Data API oferecem

A Data API retorna árvores de chamadas armazenadas para dois escopos. Nenhum deles é paginado: next_cursor nunca está presente.

• GET /{chain}/transactions/{hash}/trace — o quadro de chamada de uma transação, consultado pelo hash da transação.
• GET /{chain}/blocks/{number}/traces — uma árvore de chamadas por transação em um bloco, em ordem de tx_index. Um bloco sem transações retorna data: [].

O envelope de resposta é:

• TxTraceEnvelope: data é diretamente um CallFrame, mais meta.
• BlockTracesEnvelope: data é um array de BlockTraceItem, cada um com txHash e o CallFrame em result, mais meta.

Ambos os endpoints de trace retornam o formato padrão callTracer do Ethereum. Esta é uma exceção à codificação segura de valores monetários da Data API: em outros locais, valores que podem exceder 2^53 são serializados como strings decimais; nesses dois endpoints, value, gas e gasUsed são quantidades hexadecimais com prefixo 0x, e não strings decimais. Cada CallFrame contém type, from, gas, gasUsed e input; type é um entre CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2 ou SELFDESTRUCT. to fica ausente para o destino de um quadro CREATE/CREATE2, e value fica ausente para um quadro STATICCALL. Membros opcionais são output (ausente quando a chamada não retornou dados), error (ausente em caso de sucesso), revertReason (presente apenas para reversões Error(string)) e calls (subchamadas aninhadas na ordem de chamada). Membros adicionais do quadro são preservados.

Para tornar o formato concreto, aqui está a estrutura dos campos do CallFrame:

{
  "type": "CALL | DELEGATECALL | STATICCALL | CREATE | CREATE2 | SELFDESTRUCT",
  "from": "0x…",                      // 20-byte address
  "to": "0x…",                        // absent for a CREATE/CREATE2 target
  "value": "0x…",                     // 0x-prefixed hex quantity; absent for STATICCALL
  "gas": "0x…",                       // 0x-prefixed hex quantity
  "gasUsed": "0x…",                   // 0x-prefixed hex quantity
  "input": "0x…",
  "output": "0x…",                    // absent when the call returned no data
  "error": "…",                       // absent on success
  "revertReason": "…",                // absent unless the call reverted with Error(string)
  "calls": []                         // nested sub-calls in call order; absent for a leaf frame
}

Parâmetros

• {chain} (parâmetro de caminho, obrigatório): identificador da rede, o valor chain de uma entrada em GET /chains. A correspondência é exata e diferencia maiúsculas de minúsculas; aliases e IDs numéricos de rede não são aceitos.
• {hash} (parâmetro de caminho, obrigatório para o trace de transação): hash de transação de 32 bytes, prefixo 0x opcional, em qualquer formatação de maiúsculas/minúsculas.
• {number} (parâmetro de caminho, obrigatório para os traces de bloco): altura de bloco não negativa.

Cobertura e finalidade

• Ambos os endpoints pertencem à capacidade traces. Uma rede sem essa capacidade retorna 422 no_coverage. Redes que fornecem este conjunto de dados estão sujeitas à página de Redes suportadas e ao diretório de conjuntos de dados.
• Dados de trace podem iniciar posteriormente em relação ao restante do histórico indexado de uma rede. GET /chains informa esse limite como coverage.traces_from_block; uma requisição anterior a ele, ou dentro de um intervalo que não pôde ser rastreado, retorna 422 no_coverage.
• Para traces de transações: se o hash não for encontrado, ele retorna 404 not_found (para uma transação recém-enviada ou minerada, tente novamente após alguns segundos antes de tratar isso como permanente); se o hash for resolvido para um bloco superior a as_of_block, ele retorna 409 not_indexed_yet.
• O endpoint de traces de bloco recebe um número de bloco. Um {number} acima de as_of_block retorna 409 not_indexed_yet com indexed_through; um {number} igual ou inferior a as_of_block é atendido imediatamente.
• Um bloco recente com transações, mas ainda sem dados de trace, retorna 503 unavailable com um cabeçalho Retry-After.

Requisitando um trace da Data API

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# One transaction's call frame.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd/trace" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

# One call tree per transaction in a block.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Qual deles utilizar

CU por chamada

Todo método é cobrado pelo seu peso em CU. Os pesos abaixo são lidos a partir da API de planos da plataforma:

Requisições rejeitadas não são cobradas. Para obter as regras de cobrança completas, consulte O que não é cobrado: códigos de erro e regras de cobrança.

Próximos passos

• Consulte o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.