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

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 aufgeführt und die Methodenreferenz befindet sich auf der Seite JSON-RPC-Methoden.

debug_traceTransaction mit callTracer anfordern

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

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

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:

{
  "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 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

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"

Welche Variante gewählt werden sollte

CU pro Aufruf

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

Abgelehnte Anfragen werden nicht berechnet. Die vollständigen Abrechnungsregeln finden Sie unter Was nicht berechnet wird: Fehlercodes und Abrechnungsregeln.

Nächste Schritte

• Kostenlosen Plan und Preise ansehen, um den Leistungsumfang Ihres Kontos zu prüfen.
• In der Konsole anmelden, um einen API-Schlüssel zu erstellen.