# Transaktions-Traces: debug_traceTransaction und die Trace-Endpunkte der Data API

> Source: https://docs.blockvectra.com/de/guides/transaction-traces/

## Zwei Wege zur Rekonstruktion einer Aufrufstruktur

Ein Transaktions-Trace ist die rekonstruierte Aufrufstruktur (Call Tree) einer Ausführung: Welcher Vertrag wurde aufgerufen, mit welcher Eingabe, wie viel Gas wurde verbraucht und welche Unteraufrufe wurden getätigt. BlockVectra stellt diese Informationen über zwei Schnittstellen bereit:

* **JSON-RPC `debug_trace`-Methoden** (wie `debug_traceTransaction`) — werden über den JSON-RPC-Endpunkt direkt gegen den Node der Chain ausgeführt und können daher aktuelle Zustände tracen, die der Node noch vorhält.
* **Data API-Traces** — `GET /{chain}/transactions/{hash}/trace` und `GET /{chain}/blocks/{number}/traces` geben gespeicherte, indexierte Call Trees über REST zurück.

Beide nutzen denselben API-Schlüssel und werden in CU anhand des Methodengewichts abgerechnet (siehe Gewichtungen unten). Welche Variante sich eignet, hängt davon ab, ob Sie eine einzelne Transaktion oder einen ganzen Block benötigen, wie aktuell das Ziel ist und ob Sie einen vollständigen Block ohne Paginierung durchlaufen möchten.

## Limits für debug\_trace-Methoden

`debug_trace`-Anfragen werden nur für Methoden und Tracer akzeptiert, die die Methodenrichtlinie der Chain zulässt:

* **Zulässige Tracer**: Der Parameter `tracer` akzeptiert ausschließlich die integrierten nativen Tracer — `callTracer`, `flatCallTracer`, `prestateTracer`, `4byteTracer`, `noopTracer` oder das Weglassen des Parameters, um den standardmäßigen Struct-Logger zu verwenden. Jeder andere Wert wird mit dem JSON-RPC-Fehler `-32602 tracer not allowed` abgewiesen (wird nicht berechnet).
* **Trace-Timeout**: Der Parameter `timeout` muss eine gültige Zeitdauer und maximal 30s sein; andernfalls wird die Anfrage mit `-32602 trace timeout not allowed` abgewiesen (wird nicht berechnet).
* **Node-Sync-Schranke**: Solange der Node einer Chain nicht synchronisiert ist, gibt jede Methode außer `eth_chainId` — einschließlich `debug_trace`-Methoden — `-32010` zurück (wird nicht berechnet).
* **State-Fenster**: `debug_traceCall`, `debug_traceBlockByNumber`, `debug_traceTransaction` und `debug_traceBlockByHash` zielen auf einen Block ab, der innerhalb des State-Fensters der Chain liegen muss. Ein Ziel, das älter als dieses Fenster ist oder das Tag `safe`, `finalized` oder `earliest` verwendet, gibt `-32011` zurück (wird nicht berechnet).
* **Hash- und Blockabfragen**: Ein fehlerhafter oder unbekannter Hash gibt `-32000 transaction not found` / `block not found` zurück; ein vorübergehender Fehler gibt `-32603 upstream unavailable` zurück (wiederholbar). Wird nicht berechnet.
* **Methodenrichtlinie pro Chain**: Welche `debug_trace`-Methoden eine Chain erlaubt, wird über die öffentliche Antwort von `GET /v1/chains` bereitgestellt. Lesen Sie diese zur Laufzeit aus, anstatt eine Methodenliste fest im Code zu hinterlegen; Chains sind unter [Unterstützte Chains](https://docs.blockvectra.com/de/chains/) aufgeführt und die Methodenreferenz befindet sich auf der Seite [JSON-RPC-Methoden](https://docs.blockvectra.com/de/api/json-rpc/methods/).

### debug\_traceTransaction mit callTracer anfordern

Der folgende Aufruf fügt den Parameter `tracer` hinzu, um einen Call Tree anzufordern:

**cURL**

```bash
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" }
    ]
  }'
```


  **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"])
```


## Was die Trace-Endpunkte der Data API bieten

Die Data API gibt gespeicherte Call Trees für zwei Bereiche zurück. Keiner von beiden ist paginiert: `next_cursor` ist niemals vorhanden.

* `GET /{chain}/transactions/{hash}/trace` — der Call Frame einer einzelnen Transaktion, abgefragt über den Transaktions-Hash.
* `GET /{chain}/blocks/{number}/traces` — ein Call Tree pro Transaktion in einem Block, in Reihenfolge des `tx_index`. Ein Block ohne Transaktionen gibt `data: []` zurück.

Die Antwortstruktur ist:

* `TxTraceEnvelope`: `data` ist direkt ein `CallFrame`, zuzüglich `meta`.
* `BlockTracesEnvelope`: `data` ist ein Array von `BlockTraceItem`, jeweils mit `txHash` und dem `result`-`CallFrame`, zuzüglich `meta`.

Beide Trace-Endpunkte geben das standardmäßige Ethereum-`callTracer`-Format zurück. Dies ist eine Ausnahme von der finanzsicheren Codierung (Money-Safety) der Data API: An anderer Stelle werden Werte, die `2^53` überschreiten können, als Dezimal-String serialisiert; an diesen beiden Endpunkten sind `value`, `gas` und `gasUsed` Hex-Werte mit `0x`-Präfix, keine Dezimal-Strings. Jeder `CallFrame` enthält `type`, `from`, `gas`, `gasUsed` und `input`; `type` ist eines von `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2` oder `SELFDESTRUCT`. `to` fehlt beim Ziel eines `CREATE`/`CREATE2`-Frames, und `value` fehlt bei einem `STATICCALL`-Frame. Optionale Felder sind `output` (fehlt, wenn der Aufruf keine Daten zurückgegeben hat), `error` (fehlt bei Erfolg), `revertReason` (nur bei einem Revert mit `Error(string)` vorhanden) und `calls` (verschachtelte Unteraufrufe in Aufrufreihenfolge). Zusätzliche Felder des Frames bleiben erhalten.

Zur Veranschaulichung der Struktur dient dieses Felderskelett von `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
}
```

### Parameter

* `{chain}` (Pfadparameter, erforderlich): Chain-Kennung, der `chain`-Wert eines Eintrags in `GET /chains`. Der Abgleich erfolgt exakt und case-sensitiv; Aliase und numerische Chain-IDs werden nicht akzeptiert.
* `{hash}` (Pfadparameter, für Transaktions-Trace erforderlich): 32-Byte-Transaktions-Hash, `0x`-Präfix optional, Groß-/Kleinschreibung wird akzeptiert.
* `{number}` (Pfadparameter, für Block-Traces erforderlich): nicht-negative Blockhöhe.

### Abdeckung und Finalität

* Beide Endpunkte gehören zur Funktion `traces`. Eine Chain ohne diese Funktion gibt `422 no_coverage` zurück. Chains, die diesen Datensatz bereitstellen, unterliegen der Seite [Unterstützte Chains](https://docs.blockvectra.com/de/chains/) und dem Datensatzverzeichnis.
* Trace-Daten können später beginnen als der Rest der indexierten Historie einer Chain. `GET /chains` meldet die Grenze als `coverage.traces_from_block`; eine Anfrage vor dieser Grenze oder in einem Bereich, der nicht getracet werden konnte, gibt `422 no_coverage` zurück.
* Für Transaktions-Traces: Wird der Hash nicht gefunden, wird `404 not_found` zurückgegeben (wiederholen Sie die Anfrage bei einer gerade übermittelten oder geminten Transaktion nach wenigen Sekunden, bevor Sie dies als dauerhaft betrachten); löst der Hash zu einem Block auf, der höher als `as_of_block` ist, wird stattdessen `409 not_indexed_yet` zurückgegeben.
* Der Endpunkt für Block-Traces nimmt eine Blocknummer entgegen. Ein `{number}` über `as_of_block` gibt `409 not_indexed_yet` mit `indexed_through` zurück; ein `{number}` bei oder unter `as_of_block` wird sofort beantwortet.
* Ein kürzlich erzeugter Block mit Transaktionen, für den jedoch noch keine Trace-Daten vorliegen, gibt `503 unavailable` mit einem `Retry-After`-Header zurück.

### Einen Trace über die Data API anfordern

**cURL**

```bash
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"
```


  **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_ = "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
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"]])
```


## Welche Variante gewählt werden sollte

| Typische Aufgabe                                                                          | Bessere Wahl                             | Grund                                                                                                                     |
| ----------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Eine einzelne Transaktion direkt nach Aufnahme in die Chain rekonstruieren                | `debug_traceTransaction`                 | Läuft gegen den aktuellen Zustand des Nodes; Verfügbarkeit folgt der Methodenrichtlinie der Chain.                        |
| Den gespeicherten Call Tree einer einzelnen Transaktion auslesen                          | `GET /{chain}/transactions/{hash}/trace` | Gibt den `CallFrame` der Transaktion direkt über REST zurück; wird bis zu `as_of_block` bedient.                          |
| Alle Call Trees in einem Block mit einer einzigen Anfrage auslesen                        | `GET /{chain}/blocks/{number}/traces`    | Gibt den gesamten Block unpaginiert in Reihenfolge des `tx_index` zurück; wird bis zu `as_of_block` bedient.              |
| Zustände tracen, die der Node noch vorhält, der Datensatz aber noch nicht gespeichert hat | `debug_trace`-Methoden                   | Die Data API bedient gespeicherte Daten bis zu `as_of_block`; der Node kann für noch nicht geschriebene Blöcke antworten. |

## CU pro Aufruf

Jede Methode wird nach ihrem CU-Gewicht abgerechnet. Die folgenden Gewichtungen werden aus der Plans-API der Plattform ausgelesen:

**CU-Gewichtung pro Aufruf**

| Methode | CU pro Aufruf |
| --- | --- |
| `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 |

Abgelehnte Anfragen werden nicht berechnet. Die vollständigen Abrechnungsregeln finden Sie unter [Was nicht berechnet wird: Fehlercodes und Abrechnungsregeln](https://docs.blockvectra.com/de/guides/billing-rules/).

## Nächste Schritte

* [Kostenlosen Plan und Preise ansehen](https://blockvectra.com/de/pricing/#free), um den Leistungsumfang Ihres Kontos zu prüfen.
* [In der Konsole anmelden](https://console.blockvectra.com/login/?next=%2Fkeys%2F), um einen API-Schlüssel zu erstellen.