Traces de transaction : debug_traceTransaction et les points de terminaison de traces de la Data API

Deux façons de reconstruire un arbre d'appels

Une trace de transaction est l'arbre d'appels reconstruit d'une exécution : quel contrat a été appelé, avec quelles entrées, combien de gas il a consommé et quels sous-appels il a effectués. BlockVectra l'expose à travers deux surfaces :

• Méthodes JSON-RPC debug_trace (telles que debug_traceTransaction) — s'exécutent sur le nœud de la chaîne via le point de terminaison JSON-RPC, ce qui leur permet de tracer l'état récent que le nœud possède encore.
• Traces de la Data API — GET /{chain}/transactions/{hash}/trace et GET /{chain}/blocks/{number}/traces renvoient des arbres d'appels stockés et indexés via REST.

Les deux utilisent la même API key et sont mesurées en CU selon la pondération de la méthode (voir les pondérations ci-dessous). Le choix de l'une ou l'autre dépend du besoin d'une transaction unique ou d'un bloc entier, de l'ancienneté de la cible et du souhait de parcourir un bloc complet sans pagination.

Limites s'appliquant aux méthodes debug_trace

Les requêtes debug_trace ne sont acceptées que pour les méthodes et traceurs autorisés par la politique de méthodes de la chaîne :

• Traceurs autorisés : le paramètre tracer accepte uniquement les traceurs natifs intégrés — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, ou son omission pour utiliser le journaliseur de structure (struct logger) par défaut. Toute autre valeur est rejetée avec l'erreur JSON-RPC -32602 tracer not allowed (non facturée).
• Délai d'expiration du traceur (timeout) : le paramètre timeout doit être une durée valide et d'au maximum 30s ; sinon la requête est rejetée avec -32602 trace timeout not allowed (non facturée).
• Garde-fou de synchronisation du nœud : tant que le nœud d'une chaîne n'est pas synchronisé, chaque méthode à l'exception d'eth_chainId — y compris les méthodes debug_trace — renvoie -32010 (non facturé).
• Fenêtre d'état : debug_traceCall, debug_traceBlockByNumber, debug_traceTransaction et debug_traceBlockByHash ciblent un bloc qui doit se trouver à l'intérieur de la fenêtre d'état de la chaîne. Une cible antérieure à la fenêtre, ou qui utilise les balises safe, finalized ou earliest, renvoie -32011 (non facturé).
• Recherches par hash et par bloc : un hash malformé ou inconnu renvoie -32000 transaction not found / block not found ; un échec temporaire renvoie -32603 upstream unavailable (réessayable). Non facturé.
• Politique de méthodes par chaîne : les méthodes debug_trace autorisées par une chaîne sont publiées dans la réponse publique GET /v1/chains. Lisez-la au moment de l'exécution au lieu de coder en dur une liste de méthodes ; les chaînes sont répertoriées sur la page des Chaînes prises en charge, et la référence des méthodes se trouve sur la page des méthodes JSON-RPC.

Demander debug_traceTransaction avec callTracer

L'appel ci-dessous ajoute le paramètre tracer pour demander un arbre d'appels :

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# Ajouter "tracer" pour demander un arbre d'appels avec l'un des traceurs natifs autorisés.
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" }
    ]
  }'

Ce que fournissent les points de terminaison de traces de la Data API

La Data API renvoie les arbres d'appels stockés pour deux périmètres. Aucun des deux n'est paginé : next_cursor n'est jamais présent.

• GET /{chain}/transactions/{hash}/trace — le cadre d'appel (call frame) d'une transaction, recherché par hash de transaction.
• GET /{chain}/blocks/{number}/traces — un arbre d'appels par transaction dans un bloc, dans l'ordre de tx_index. Un bloc sans transaction renvoie data: [].

L'enveloppe de réponse est :

• TxTraceEnvelope : data est directement un CallFrame, accompagné de meta.
• BlockTracesEnvelope : data est un tableau de BlockTraceItem, chacun contenant txHash et le CallFrame result, accompagné de meta.

Les deux points de terminaison de traces renvoient le format standard callTracer d'Ethereum. Il s'agit d'une exception à l'encodage de sécurité financière (money-safety) de la Data API : ailleurs, toute valeur pouvant dépasser 2^53 est sérialisée sous forme de chaîne décimale ; sur ces deux points de terminaison, value, gas et gasUsed sont des quantités hexadécimales préfixées par 0x, et non des chaînes décimales. Chaque CallFrame porte type, from, gas, gasUsed et input ; type est l'un des suivants : CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2 ou SELFDESTRUCT. to est absent pour la cible d'un cadre CREATE/CREATE2, et value est absente pour un cadre STATICCALL. Les membres optionnels sont output (absent lorsque l'appel n'a renvoyé aucune donnée), error (absent en cas de succès), revertReason (présent uniquement pour un revert Error(string)) et calls (sous-appels imbriqués dans l'ordre d'appel). Les membres additionnels du cadre sont préservés.

Pour concrétiser cette structure, voici le squelette des champs de 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
}

Paramètres

• {chain} (paramètre de chemin, obligatoire) : identifiant de chaîne, la valeur chain d'une entrée dans GET /chains. La correspondance est exacte et sensible à la casse ; les alias et les identifiants numériques de chaîne ne sont pas acceptés.
• {hash} (paramètre de chemin, obligatoire pour la trace de transaction) : hash de transaction sur 32 octets, préfixe 0x optionnel, majuscules ou minuscules acceptées.
• {number} (paramètre de chemin, obligatoire pour les traces de bloc) : hauteur de bloc non négative.

Couverture et finalité

• Les deux points de terminaison relèvent de la capacité traces. Une chaîne ne la prenant pas en charge renvoie 422 no_coverage. Les chaînes fournissant ce jeu de données sont soumises à la page des Chaînes prises en charge et au répertoire des jeux de données.
• Les données de trace peuvent commencer plus tard que le reste de l'historique indexé d'une chaîne. GET /chains indique cette limite via coverage.traces_from_block ; une requête antérieure à ce bloc, ou dans une plage qui n'a pas pu être tracée, renvoie 422 no_coverage.
• Pour les traces de transaction : si le hash est introuvable, le point de terminaison renvoie 404 not_found (pour une transaction venant d'être soumise ou minée, réessayez après quelques secondes avant de considérer cela comme permanent) ; si le hash correspond à un bloc supérieur à as_of_block, il renvoie à la place 409 not_indexed_yet.
• Le point de terminaison de traces de bloc accepte un numéro de bloc. Un {number} supérieur à as_of_block renvoie 409 not_indexed_yet avec indexed_through ; un {number} inférieur ou égal à as_of_block est servi immédiatement.
• Un bloc récent contenant des transactions mais pas encore de données de trace renvoie 503 unavailable avec un en-tête Retry-After.

Demander une trace à la Data API

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# Le cadre d'appel d'une seule transaction.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd/trace" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

# Un arbre d'appels par transaction dans un bloc.
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Laquelle utiliser

CU par appel

Chaque méthode est facturée selon sa pondération en CU. Les pondérations ci-dessous sont lues depuis l'API des forfaits de la plateforme :

Les requêtes rejetées ne sont pas facturées. Pour connaître l'intégralité des règles de facturation, consultez Ce qui n'est pas facturé : codes d'erreur et règles de facturation.

Étapes suivantes

• Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
• Se connecter à la console pour créer une API key.