# Traces de transaction : debug_traceTransaction et les points de terminaison de traces de la Data API > Source: https://docs.blockvectra.com/fr/guides/transaction-traces/ ## 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](https://docs.blockvectra.com/fr/chains/), et la référence des méthodes se trouve sur la page des [méthodes JSON-RPC](https://docs.blockvectra.com/fr/api/json-rpc/methods/). ### Demander debug\_traceTransaction avec callTracer L'appel ci-dessous ajoute le paramètre `tracer` pour demander un arbre d'appels : **cURL** ```bash 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" } ] }' ``` **TypeScript** ```ts const RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet"; const res = await fetch(RPC_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.BLOCKVECTRA_API_KEY!, }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "debug_traceTransaction", params: [ "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd", { tracer: "callTracer" }, ], }), }); const body = (await res.json()) as { result?: unknown; error?: { code: number; message: string }; }; if (body.error) { throw new Error(`debug_traceTransaction error ${body.error.code}: ${body.error.message}`); } console.log(body.result); // npx tsx example.mts ``` **Python** ```python import os import requests RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet" res = requests.post( RPC_ENDPOINT, headers={ "Content-Type": "application/json", "x-api-key": os.environ["BLOCKVECTRA_API_KEY"], }, json={ "jsonrpc": "2.0", "id": 1, "method": "debug_traceTransaction", "params": [ "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd", {"tracer": "callTracer"}, ], }, ) res.raise_for_status() body = res.json() if "error" in body: err = body["error"] raise RuntimeError(f"debug_traceTransaction error {err.get('code')}: {err.get('message')}") print(body["result"]) ``` ## 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` : ```jsonc { "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](https://docs.blockvectra.com/fr/chains/) 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 **cURL** ```bash 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" ``` **TypeScript** ```ts const hash = "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"; const txRes = await fetch( `https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/${hash}/trace`, { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! } }, ); const txBody = await txRes.json(); console.log(txBody.data, txBody.meta); const blockRes = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces", { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }); const blockBody = await blockRes.json(); console.log(blockBody.data.map((item: { txHash: string }) => item.txHash)); // npx tsx example.mts ``` **Python** ```python import os import requests hash_ = "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd" headers = {"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]} tx = requests.get( f"https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/{hash_}/trace", headers=headers, ) tx.raise_for_status() tx_body = tx.json() print(tx_body["data"], tx_body["meta"]) block = requests.get( "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces", headers=headers, ) block.raise_for_status() block_body = block.json() print([item["txHash"] for item in block_body["data"]]) ``` ## Laquelle utiliser | Tâche typique | Meilleur choix | Raison | | ------------------------------------------------------------------------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Reconstruire une transaction unique juste après son inclusion | `debug_traceTransaction` | S'exécute sur l'état actuel du nœud ; la disponibilité suit la politique de méthodes de la chaîne. | | Lire l'arbre d'appels stocké d'une transaction unique | `GET /{chain}/transactions/{hash}/trace` | Renvoie directement le `CallFrame` de la transaction via REST ; servi jusqu'à `as_of_block`. | | Lire tous les arbres d'appels d'un bloc en une seule requête | `GET /{chain}/blocks/{number}/traces` | Renvoie le bloc complet sans pagination, dans l'ordre de `tx_index` ; servi jusqu'à `as_of_block`. | | Tracer un état que le nœud possède encore mais que le jeu de données n'a pas encore stocké | Méthodes `debug_trace` | La Data API sert les données stockées jusqu'à `as_of_block` ; le nœud peut répondre pour les blocs non encore écrits. | ## 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 : **Poids en CU par appel** | Méthode | CU par appel | | --- | --- | | `debug_traceBlockByHash` | 100 | | `debug_traceBlockByNumber` | 100 | | `debug_traceCall` | 100 | | `debug_traceTransaction` | 100 | | `trace_block` | 100 | | `trace_call` | 100 | | `trace_get` | 100 | | `trace_replayTransaction` | 100 | | `trace_transaction` | 100 | | `data.block_traces` | 200 | | `data.transaction_trace` | 200 | 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](https://docs.blockvectra.com/fr/guides/billing-rules/). ## Étapes suivantes * [Consulter le forfait gratuit et les tarifs](https://blockvectra.com/fr/pricing/#free) pour vérifier ce que comprend votre compte. * [Se connecter à la console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) pour créer une API key.