Trazas de transacciones: debug_traceTransaction y los endpoints de trazas de la Data API

Dos formas de reconstruir un árbol de llamadas

Una traza de transacción es el árbol de llamadas reconstruido de una ejecución: qué contrato se llamó, con qué entrada, cuánto gas consumió y qué subllamadas realizó. BlockVectra lo ofrece mediante dos interfaces:

• Métodos JSON-RPC debug_trace (como debug_traceTransaction) — se ejecutan contra el nodo de la cadena mediante el endpoint JSON-RPC, por lo que pueden trazar el estado reciente que el nodo aún conserva.
• Trazas de la Data API — GET /{chain}/transactions/{hash}/trace y GET /{chain}/blocks/{number}/traces devuelven árboles de llamadas almacenados e indexados mediante REST.

Ambas usan la misma API key y se miden en CU según el peso del método (consulta los pesos más abajo). La elección depende de si necesitas una transacción o un bloque completo, de lo reciente que sea el objetivo y de si quieres recorrer un bloque completo sin paginación.

Límites aplicables a los métodos debug_trace

Las solicitudes debug_trace solo se aceptan para los métodos y trazadores que permite la política de métodos de la cadena:

• Trazadores permitidos: el parámetro tracer solo acepta los trazadores nativos integrados — callTracer, flatCallTracer, prestateTracer, 4byteTracer, noopTracer, o puede omitirse para usar el registro estructurado predeterminado. Cualquier otro valor se rechaza con el error JSON-RPC -32602 tracer not allowed (sin facturación).
• Tiempo máximo de trazado: el parámetro timeout debe ser una duración válida de como máximo 30s; de lo contrario, la solicitud se rechaza con -32602 trace timeout not allowed (sin facturación).
• Control de sincronización del nodo: mientras el nodo de una cadena no esté sincronizado, todos los métodos excepto eth_chainId —incluidos los métodos debug_trace— devuelven -32010 (sin facturación).
• Ventana de estado: debug_traceCall, debug_traceBlockByNumber, debug_traceTransaction y debug_traceBlockByHash apuntan a un bloque que debe estar dentro de la ventana de estado de la cadena. Un objetivo anterior a la ventana, o que use la etiqueta safe, finalized o earliest, devuelve -32011 (sin facturación).
• Consultas de hash y bloque: un hash mal formado o desconocido devuelve -32000 transaction not found / block not found; un fallo temporal devuelve -32603 upstream unavailable (se puede reintentar). Sin facturación.
• Política de métodos por cadena: los métodos debug_trace que permite cada cadena se publican en la respuesta pública de GET /v1/chains. Léela en tiempo de ejecución en lugar de fijar una lista de métodos; las cadenas aparecen en cadenas compatibles y la referencia de métodos está en la página de métodos JSON-RPC.

Solicitar debug_traceTransaction con callTracer

La siguiente llamada añade el parámetro tracer para solicitar un árbol de llamadas:

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

Qué ofrecen los endpoints de trazas de la Data API

La Data API devuelve árboles de llamadas almacenados para dos ámbitos. Ninguno usa paginación: next_cursor nunca está presente.

• GET /{chain}/transactions/{hash}/trace — el marco de llamada de una transacción, consultado por su hash.
• GET /{chain}/blocks/{number}/traces — un árbol de llamadas por transacción de un bloque, en orden de tx_index. Un bloque sin transacciones devuelve data: [].

La estructura de la respuesta es:

• TxTraceEnvelope: data es directamente un CallFrame, más meta.
• BlockTracesEnvelope: data es una matriz de BlockTraceItem, cada uno con txHash y result de tipo CallFrame, más meta.

Ambos endpoints de trazas devuelven el formato estándar Ethereum callTracer. Esto es una excepción a la codificación de seguridad numérica para importes de la Data API: en otros endpoints, un valor que puede superar 2^53 se serializa como cadena decimal; en estos dos endpoints, value, gas y gasUsed son cantidades hexadecimales con prefijo 0x, no cadenas decimales. Cada CallFrame contiene type, from, gas, gasUsed e input; type es uno de CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2 o SELFDESTRUCT. to no está presente para el destino de un marco CREATE/CREATE2, y value no está presente en un marco STATICCALL. Los miembros opcionales son output (ausente cuando la llamada no devolvió datos), error (ausente en caso de éxito), revertReason (presente solo para una reversión Error(string)) y calls (subllamadas anidadas en orden de llamada). Se conservan los miembros adicionales del marco.

Para concretar la estructura, este es el esquema de campos de 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
}

Parámetros

• {chain} (parámetro de ruta, obligatorio): identificador de cadena, el valor chain de una entrada en GET /chains. La coincidencia es exacta y distingue mayúsculas de minúsculas; no se aceptan alias ni Chain IDs numéricos.
• {hash} (parámetro de ruta, obligatorio para la traza de transacción): hash de transacción de 32 bytes, con prefijo 0x opcional y dígitos en mayúsculas o minúsculas.
• {number} (parámetro de ruta, obligatorio para las trazas del bloque): altura de bloque no negativa.

Cobertura y finalidad

• Ambos endpoints pertenecen a la capacidad traces. Una cadena que no la tenga devuelve 422 no_coverage. Las cadenas que ofrecen este conjunto de datos se indican en la página de cadenas compatibles y en el directorio de conjuntos de datos.
• Los datos de trazas pueden comenzar después que el resto del historial indexado de una cadena. GET /chains indica el límite en coverage.traces_from_block; una solicitud anterior a él, o dentro de un rango que no pudo trazarse, devuelve 422 no_coverage.
• Para trazas de transacciones: si no se encuentra el hash, devuelve 404 not_found (para una transacción recién enviada o minada, reintenta tras unos segundos antes de tratarlo como permanente); si el hash corresponde a un bloque superior a as_of_block, devuelve 409 not_indexed_yet en su lugar.
• El endpoint de trazas de bloques recibe un número de bloque. Un {number} superior a as_of_block devuelve 409 not_indexed_yet con indexed_through; un {number} igual o inferior a as_of_block se sirve inmediatamente.
• Un bloque reciente con transacciones pero sin datos de trazas todavía devuelve 503 unavailable con una cabecera Retry-After.

Solicitar una traza a la 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ál usar

CU por llamada

Cada método se factura según su peso en CU. Los siguientes pesos se leen de la API de planes de la plataforma:

Las solicitudes rechazadas no se facturan. Consulta las reglas de facturación completas en qué no se factura: códigos de error y reglas de facturación.

Próximos pasos

• Consulta el Plan gratuito y los precios para comprobar qué incluye tu cuenta.
• Inicia sesión en la consola para crear una API key.