트랜잭션 추적: debug_traceTransaction 및 Data API trace 엔드포인트

호출 트리를 재구성하는 두 가지 방법

트랜잭션 추적(trace)은 실행 시점의 재구성된 호출 트리입니다. 즉, 어떤 컨트랙트가 어떤 입력값으로 호출되었는지, 가스를 얼마나 소비했는지, 어떤 하위 호출을 수행했는지를 보여줍니다. BlockVectra는 두 가지 인터페이스를 통해 이를 제공합니다:

• JSON-RPC debug_trace 메서드(debug_traceTransaction 등) — JSON-RPC 엔드포인트를 통해 체인 노드를 대상으로 실행되므로, 노드가 여전히 보유하고 있는 최근 상태를 추적할 수 있습니다.
• Data API traces — 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(과금되지 않음)로 거부됩니다.
• 추적 제한 시간: timeout 파라미터는 유효한 기간이어야 하며 최대 30초여야 합니다. 그렇지 않으면 요청이 -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 메서드 페이지에 있습니다.

callTracer로 debug_traceTransaction 요청하기

아래 호출은 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 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을 초과할 수 있는 값이 10진수 문자열로 직렬화되지만, 이 두 엔드포인트에서는 value, gas, gasUsed가 10진수 문자열이 아닌 0x 접두사가 붙은 16진수 수량으로 반환됩니다. 모든 CallFrame은 type, from, gas, gasUsed, input을 포함합니다. type은 CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2, SELFDESTRUCT 중 하나입니다. CREATE/CREATE2 프레임의 대상에 대해서는 to가 생략되며, STATICCALL 프레임의 경우 value가 생략됩니다. 선택적 멤버는 output(호출이 데이터를 반환하지 않은 경우 생략), error(성공 시 생략), revertReason(Error(string)으로 revert된 경우에만 존재), 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} (경로 파라미터, 필수): 체인 식별자이며 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을 대신 반환합니다.
• 블록 추적 엔드포인트는 블록 번호를 받습니다. as_of_block보다 높은 {number}는 indexed_through와 함께 409 not_indexed_yet을 반환하며, as_of_block 이하인 {number}는 즉시 제공됩니다.
• 트랜잭션이 있지만 아직 추적 데이터가 없는 최근 블록은 Retry-After 헤더와 함께 503 unavailable을 반환합니다.

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 생성.