# Trace transaksi: debug_traceTransaction dan endpoint trace Data API

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

## 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](https://docs.blockvectra.com/id/chains/), dan referensi metode tersedia di halaman [metode JSON-RPC](https://docs.blockvectra.com/id/api/json-rpc/methods/).

### Meminta debug\_traceTransaction dengan callTracer

Panggilan di bawah menambahkan parameter `tracer` untuk meminta pohon panggilan:

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


## 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`:

```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}` (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](https://docs.blockvectra.com/id/chains/) 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

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


## Mana yang sebaiknya digunakan

| Tugas umum                                                                                     | Pilihan yang lebih sesuai                | Alasan                                                                                                    |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Merekonstruksi satu transaksi tepat setelah masuk ke blok                                      | `debug_traceTransaction`                 | Berjalan terhadap state node saat ini; ketersediaannya mengikuti kebijakan metode chain.                  |
| Membaca pohon panggilan satu transaksi yang tersimpan                                          | `GET /{chain}/transactions/{hash}/trace` | Mengembalikan `CallFrame` transaksi secara langsung melalui REST; dilayani hingga `as_of_block`.          |
| Membaca semua pohon panggilan satu blok dalam satu permintaan                                  | `GET /{chain}/blocks/{number}/traces`    | Mengembalikan seluruh blok tanpa paginasi, dalam urutan `tx_index`; dilayani hingga `as_of_block`.        |
| Melakukan trace pada state yang masih dimiliki node tetapi belum tersimpan dalam kumpulan data | Metode `debug_trace`                     | Data API melayani data tersimpan hingga `as_of_block`; node dapat menjawab untuk blok yang belum ditulis. |

## CU per panggilan

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

**Bobot CU per panggilan**

| Metode | CU per panggilan |
| --- | --- |
| `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 |

Permintaan yang ditolak tidak ditagih. Untuk aturan penagihan lengkap, lihat [Yang tidak ditagih: kode error dan aturan penagihan](https://docs.blockvectra.com/en/guides/billing-rules/).

## Langkah berikutnya

* [Lihat paket gratis dan harga](https://blockvectra.com/id/pricing/#free) untuk memeriksa apa saja yang tercakup dalam akun Anda.
* [Masuk ke konsol](https://console.blockvectra.com/login/?next=%2Fkeys%2F) untuk membuat API key.