Trace transaksi: debug_traceTransaction dan endpoint trace Data API

Dua cara merekonstruksi pohon panggilan

Trace transaksi adalah pohon panggilan eksekusi yang direkonstruksi: kontrak mana yang dipanggil, dengan input apa, berapa gas yang digunakan, dan subpanggilan apa yang dibuatnya. BlockVectra menyediakannya melalui dua antarmuka:

• Metode JSON-RPC debug_trace (seperti debug_traceTransaction) — dijalankan terhadap node chain melalui endpoint JSON-RPC, sehingga dapat melakukan trace terhadap state terkini yang masih dimiliki node.
• Trace Data API — GET /{chain}/transactions/{hash}/trace dan GET /{chain}/blocks/{number}/traces mengembalikan pohon panggilan yang tersimpan dan terindeks melalui REST.

Keduanya menggunakan API key yang sama dan diukur dalam CU berdasarkan bobot metode (lihat bobot di bawah). Pilihan yang sesuai bergantung pada apakah Anda memerlukan satu transaksi atau seluruh blok, seberapa baru targetnya, dan apakah Anda ingin menelusuri satu blok penuh tanpa paginasi.

Batas yang berlaku untuk metode debug_trace

Permintaan debug_trace hanya diterima untuk metode dan tracer yang diizinkan oleh kebijakan metode chain:

• Tracer yang diizinkan: Parameter tracer hanya menerima tracer native bawaan — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, atau tidak menyertakannya untuk menggunakan struct logger default. Nilai lain ditolak dengan error JSON-RPC -32602 tracer not allowed (tidak ditagih).
• Batas waktu trace: Parameter timeout harus berupa durasi yang valid dan maksimal 30s; jika tidak, permintaan ditolak dengan -32602 trace timeout not allowed (tidak ditagih).
• Pemeriksaan sinkronisasi node: Selama node chain belum tersinkronisasi, setiap metode kecuali eth_chainId — termasuk metode debug_trace — mengembalikan -32010 (tidak ditagih).
• Jendela state: debug_traceCall, debug_traceBlockByNumber, debug_traceTransaction, dan debug_traceBlockByHash menargetkan blok yang harus berada dalam jendela state chain. Target sebelum jendela, atau yang menggunakan tag safe, finalized, atau earliest, mengembalikan -32011 (tidak ditagih).
• Pencarian hash dan blok: Hash dengan format salah atau tidak dikenal mengembalikan -32000 transaction not found / block not found; kegagalan sementara mengembalikan -32603 upstream unavailable (dapat dicoba ulang). Tidak ditagih.
• Kebijakan metode per chain: Metode debug_trace yang diizinkan suatu chain dipublikasikan melalui respons publik GET /v1/chains. Baca saat runtime, jangan menanamkan daftar metode dalam kode; chain tercantum pada Chain yang Didukung, dan referensi metode tersedia di halaman metode JSON-RPC.

Meminta debug_traceTransaction dengan callTracer

Panggilan di bawah menambahkan parameter tracer untuk meminta pohon panggilan:

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

Yang disediakan endpoint trace Data API

Data API mengembalikan pohon panggilan yang tersimpan untuk dua cakupan. Keduanya tidak menggunakan paginasi: next_cursor tidak pernah disertakan.

• GET /{chain}/transactions/{hash}/trace — frame panggilan satu transaksi, dicari berdasarkan hash transaksi.
• GET /{chain}/blocks/{number}/traces — satu pohon panggilan per transaksi dalam satu blok, dengan urutan tx_index. Blok tanpa transaksi mengembalikan data: [].

Struktur responsnya adalah:

• TxTraceEnvelope: data langsung berupa CallFrame, ditambah meta.
• BlockTracesEnvelope: data adalah array BlockTraceItem, masing-masing berisi txHash dan result berupa CallFrame, ditambah meta.

Kedua endpoint trace mengembalikan format callTracer Ethereum standar. Ini merupakan pengecualian terhadap pengodean aman untuk nilai uang Data API: pada endpoint lain, nilai yang dapat melampaui 2^53 diserialisasi sebagai string desimal; pada kedua endpoint ini, value, gas, dan gasUsed berupa kuantitas heksadesimal berawalan 0x, bukan string desimal. Setiap CallFrame memuat type, from, gas, gasUsed, dan input; type adalah salah satu dari CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2, atau SELFDESTRUCT. to tidak disertakan untuk target frame CREATE/CREATE2, dan value tidak disertakan untuk frame STATICCALL. Anggota opsional adalah output (tidak disertakan jika panggilan tidak mengembalikan data), error (tidak disertakan saat berhasil), revertReason (hanya ada untuk revert Error(string)), dan calls (subpanggilan bertingkat dalam urutan panggilan). Anggota tambahan frame tetap dipertahankan.

Untuk memperjelas bentuknya, berikut kerangka bidang 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} (parameter jalur, wajib): pengenal chain, yaitu nilai chain dari entri dalam GET /chains. Pencocokan harus persis dan peka huruf besar/kecil; alias dan chain ID numerik tidak diterima.
• {hash} (parameter jalur, wajib untuk trace transaksi): hash transaksi 32 byte, prefiks 0x opsional, digit huruf besar maupun kecil diterima.
• {number} (parameter jalur, wajib untuk trace blok): tinggi blok non-negatif.

Cakupan dan finalitas

• Kedua endpoint termasuk dalam kemampuan traces. Chain tanpa kemampuan ini mengembalikan 422 no_coverage. Chain yang menyediakan kumpulan data ini mengikuti halaman Chain yang Didukung dan direktori kumpulan data.
• Data trace dapat dimulai lebih lambat daripada bagian lain dari riwayat chain yang diindeks. GET /chains melaporkan batasnya sebagai coverage.traces_from_block; permintaan sebelum batas tersebut, atau dalam rentang yang tidak dapat ditelusuri, mengembalikan 422 no_coverage.
• Untuk trace transaksi: jika hash tidak ditemukan, mengembalikan 404 not_found (untuk transaksi yang baru dikirim atau ditambang, coba ulang setelah beberapa detik sebelum menganggapnya permanen); jika hash merujuk ke blok yang lebih tinggi dari as_of_block, mengembalikan 409 not_indexed_yet sebagai gantinya.
• Endpoint trace blok menerima nomor blok. {number} di atas as_of_block mengembalikan 409 not_indexed_yet dengan indexed_through; {number} yang sama dengan atau di bawah as_of_block langsung dilayani.
• Blok baru yang memiliki transaksi tetapi belum memiliki data trace mengembalikan 503 unavailable dengan header Retry-After.

Meminta trace dari 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"

Mana yang sebaiknya digunakan

CU per panggilan

Setiap metode ditagih berdasarkan bobot CU-nya. Bobot di bawah dibaca dari API paket platform:

Permintaan yang ditolak tidak ditagih. Untuk aturan penagihan lengkap, lihat Yang tidak ditagih: kode error dan aturan penagihan.

Langkah berikutnya

• Lihat paket gratis dan harga untuk memeriksa apa saja yang tercakup dalam akun Anda.
• Masuk ke konsol untuk membuat API key.