交易 trace：debug_traceTransaction 与 Data API 的 trace 接口

重建调用树的两种方式

交易 trace 是一次执行重建出来的调用树：调用了哪个合约、传入什么参数、消耗多少 gas、又发起了哪些子调用。BlockVectra 通过两个入口提供：

• JSON-RPC debug_trace 系列方法（如 debug_traceTransaction） —— 通过 JSON-RPC 端点在这条链的节点上执行，因此可以追踪节点仍保留的最新状态。
• Data API trace 接口 —— GET /{chain}/transactions/{hash}/trace 与 GET /{chain}/blocks/{number}/traces 通过 REST 返回已存储、已索引的调用树。

两者使用同一个 API key，并按方法权重以 CU 计量（见下方权重表）。选哪一种，取决于要查单笔交易还是整个区块、目标有多新，以及是否要一次取回整个区块。

debug_trace 系列方法受到的限制

debug_trace 系列请求需要该链的方法策略允许对应方法，且 tracer 取值在允许范围内：

• 允许的 tracer：tracer 参数仅允许内置原生 tracer —— callTracer、flatCallTracer、prestateTracer、4byteTracer、noopTracer，或缺省使用默认 struct logger。其余取值返回 JSON-RPC 错误 -32602 tracer not allowed（不计费）。
• trace 超时：timeout 参数需为合法 duration 且不超过 30s，否则返回 -32602 trace timeout not allowed（不计费）。
• 节点同步门：当某条链的节点未同步时，除 eth_chainId 外的所有方法（包括 debug_trace 系列方法）一律返回 -32010（不计费）。
• 状态窗口：debug_traceCall、debug_traceBlockByNumber、debug_traceTransaction、debug_traceBlockByHash 的目标区块必须在链的状态窗口内；早于窗口，或使用 safe、finalized、earliest 标签，返回 -32011（不计费）。
• 哈希与区块查询：哈希格式不对或查不到时返回 -32000 transaction not found / block not found；临时失败返回 -32603 upstream unavailable（可重试）。均不计费。
• 逐链方法策略：某条链允许哪些 debug_trace 方法，由公开的 GET /v1/chains 响应公布。请在运行时读取，不要写死方法列表；链列表见支持的链，方法参考见 JSON-RPC 方法页面。

请求 debug_traceTransaction 并使用 callTracer

下面的调用增加 tracer 参数以请求调用树：

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# 增加 "tracer"，用允许的内置原生 tracer 请求调用树。
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" }
    ]
  }'

Data API trace 接口提供什么

Data API 为两种范围返回已存储的调用树。两者都不分页：绝不会有 next_cursor。

• GET /{chain}/transactions/{hash}/trace —— 按交易哈希查询单笔交易的调用帧。
• GET /{chain}/blocks/{number}/traces —— 区块内每笔交易一棵调用树，按 tx_index 顺序排列。没有交易的区块返回 data: []。

响应信封为：

• TxTraceEnvelope：data 直接是一个 CallFrame，另有 meta。
• BlockTracesEnvelope：data 是 BlockTraceItem 数组，每项含 txHash 与 result（一个 CallFrame），另有 meta。

两个 trace 接口都返回标准的以太坊 callTracer 格式。这是 Data API「金额安全」编码的一处例外：其他接口会把可能超过 2^53 的数值序列化为十进制字符串；这两个接口的 value、gas、gasUsed 是 0x 前缀的十六进制数量，而不是十进制字符串。每个 CallFrame 都带 type、from、gas、gasUsed、input；type 为 CALL、DELEGATECALL、STATICCALL、CREATE、CREATE2、SELFDESTRUCT 之一。CREATE/CREATE2 帧的目标地址没有 to，STATICCALL 帧没有 value。可选成员有 output（调用没有返回数据时缺失）、error（成功时缺失）、revertReason（仅在以 Error(string) 回滚时出现）、calls（按调用顺序排列的嵌套子调用）。调用帧里的其他成员会原样保留。

为便于理解结构，下面给出 CallFrame 的字段骨架：

{
  "type": "CALL | DELEGATECALL | STATICCALL | CREATE | CREATE2 | SELFDESTRUCT",
  "from": "0x…",                      // 20 字节地址
  "to": "0x…",                        // CREATE/CREATE2 的目标地址缺失
  "value": "0x…",                     // 0x 前缀十六进制数量；STATICCALL 帧缺失
  "gas": "0x…",                       // 0x 前缀十六进制数量
  "gasUsed": "0x…",                   // 0x 前缀十六进制数量
  "input": "0x…",
  "output": "0x…",                    // 调用没有返回数据时缺失
  "error": "…",                       // 成功时缺失
  "revertReason": "…",                // 仅当以 Error(string) 回滚时出现
  "calls": []                         // 按调用顺序排列的嵌套子调用；叶子帧缺失
}

参数

• {chain}（路径参数，必填）：链标识，即 GET /chains 中某项的 chain 值。精确匹配且区分大小写；别名与数字 chain ID 均不接受。
• {hash}（路径参数，交易 trace 必填）：32 字节交易哈希，0x 前缀可选，大小写不限。
• {number}（路径参数，区块 traces 必填）：非负区块高度。

覆盖范围与最终性

• 两个接口都属于 traces 能力。未提供该能力的链返回 422 no_coverage。提供该数据集的链以支持的链页面为准。
• trace 数据可能晚于该链其余已索引历史开始。GET /chains 以 coverage.traces_from_block 公布这一边界；早于它的 trace 请求（或落在无法追踪的区间内）返回 422 no_coverage。
• 交易 trace：若不存在则返回 404 not_found（刚提交或刚出块的交易，请在视为永久不存在前稍后重试）；若解析出的区块高于 as_of_block，则返回 409 not_indexed_yet。
• 区块 traces 接口接收区块高度。{number} 高于 as_of_block 时返回 409 not_indexed_yet，并带 indexed_through；不高于 as_of_block 的区块立即返回。
• 有交易但尚无 trace 数据的新近区块返回 503 unavailable，并带 Retry-After 头。

用 Data API 请求 trace

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# 单笔交易的调用帧。
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/transactions/0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd/trace" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

# 某个区块内，每笔交易一棵调用树。
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/79900000/traces" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

该选哪一个

单次调用的 CU

每个方法都按其 CU 权重计费。下方权重从平台计划接口读取：

被拒绝的请求不计费。完整计费规则见哪些请求不计费：错误码与计费规则。

下一步

• 查看免费额度与定价，确认账户可用的方案。
• 登录控制台创建 API key。