Трейсы транзакций: debug_traceTransaction и эндпоинты трейсов Data API

Два способа восстановления дерева вызовов

Трейс транзакции представляет собой восстановленное дерево вызовов исполнения: какой контракт был вызван, с какими входными данными, сколько газа он израсходовал и какие подвызовы совершил. BlockVectra предоставляет доступ к нему через два интерфейса:

• Методы JSON-RPC debug_trace (такие как debug_traceTransaction) — выполняются на узле сети через JSON-RPC эндпоинт, поэтому могут трассировать недавнее состояние, которое узел все еще хранит.
• Трейсы Data API — GET /{chain}/transactions/{hash}/trace и GET /{chain}/blocks/{number}/traces возвращают сохраненные индексированные деревья вызовов через REST.

Оба интерфейса используют один и тот же API key и тарифицируются в CU по весу метода (см. веса ниже). Выбор подходящего зависит от того, нужна ли вам одна транзакция или весь блок целиком, насколько свежей является цель и хотите ли вы пройти весь блок без пагинации.

Ограничения, действующие для методов debug_trace

Запросы debug_trace принимаются только для методов и трассировщиков (tracers), разрешенных политикой методов конкретной сети:

• Разрешенные трассировщики: параметр tracer принимает только встроенные нативные трассировщики — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, либо может быть опущен для использования стандартного struct logger. Любое другое значение отклоняется с ошибкой JSON-RPC -32602 tracer not allowed (не тарифицируется).
• Таймаут трассировки: параметр timeout должен быть допустимой длительностью и не превышать 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

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

Что предоставляют эндпоинты трейсов Data API

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 и результирующий CallFrame, плюс meta.

Оба эндпоинта трейсов возвращают стандартный формат callTracer Ethereum. Это исключение из правил кодирования Data API для безопасности финансовых вычислений (money-safety): в остальных случаях любое значение, способное превысить 2^53, сериализуется как десятичная строка; на этих двух эндпоинтах value, gas и gasUsed представляют собой шестнадцатеричные величины с префиксом 0x, а не десятичные строки. Каждый CallFrame содержит type, from, gas, gasUsed и input; type принимает одно из значений: CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2 или SELFDESTRUCT. Поле to отсутствует для целевого адреса фреймов CREATE/CREATE2, а value отсутствует для фрейма STATICCALL. Необязательные поля: output (отсутствует, если вызов не вернул данных), error (отсутствует при успешном выполнении), revertReason (присутствует только при откате с Error(string)) и calls (вложенные подвызовы в порядке вызова). Дополнительные поля фрейма сохраняются.

Чтобы наглядно представить структуру, ниже приведен скелет полей 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
}

Параметры

• {chain} (параметр пути, обязательный): идентификатор сети, значение поля chain записи из GET /chains. Сопоставление строгое и чувствительное к регистру; псевдонимы и числовые chain ID не принимаются.
• {hash} (параметр пути, обязательный для трейса транзакции): 32-байтовый хеш транзакции, префикс 0x необязателен, допускается любой регистр.
• {number} (параметр пути, обязательный для трейсов блока): неотрицательная высота блока.

Покрытие и финальность

• Оба эндпоинта относятся к возможности traces. Сеть без нее возвращает 422 no_coverage. Список сетей, предоставляющих этот набор данных, регулируется страницей Поддерживаемые сети и каталогом наборов данных.
• Данные трейсов могут начинаться позже остальной индексированной истории сети. GET /chains сообщает границу в поле coverage.traces_from_block; запрос до нее или внутри диапазона, который не удалось трассировать, возвращает 422 no_coverage.
• Для трейсов транзакций: если хеш не найден, возвращается 404 not_found (для только что отправленной или добытой транзакции повторите попытку через несколько секунд, прежде чем считать ошибку постоянной); если хеш относится к блоку выше as_of_block, вместо этого возвращается 409 not_indexed_yet.
• Эндпоинт трейсов блока принимает номер блока. Значение {number} выше as_of_block возвращает 409 not_indexed_yet с указанием indexed_through; значение {number} на уровне или ниже as_of_block отдается немедленно.
• Недавний блок с транзакциями, для которого данные трейсов еще не сформированы, возвращает 503 unavailable с заголовком Retry-After.

Запрос трейса через 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"

Что выбрать

CU за вызов

Каждый метод тарифицируется по своему весу CU. Веса ниже считываются из API тарифных планов платформы:

Отклоненные запросы не тарифицируются. Полные правила биллинга см. в руководстве Что не тарифицируется: коды ошибок и правила биллинга.

Следующие шаги

• Ознакомьтесь с бесплатным тарифом и ценами, чтобы узнать, что включено в ваш аккаунт.
• Войдите в консоль, чтобы создать API key.