Archivos planos de Polygon: datos históricos masivos de la cadena sin límites de RPC

Qué son realmente los archivos planos de Polygon

Los archivos planos de Polygon son archivos inmutables producidos periódicamente que contienen datos brutos de bloques, transacciones y registros de la cadena Polygon. Se almacenan en almacenamiento de objetos, comúnmente un bucket compatible con S3, y se direccionan por rango de bloques en lugar de consultarse interactivamente. Cada exportación es una instantánea: una vez escrita, el archivo no cambia, y aparece un nuevo archivo para el siguiente rango. Esto es fundamentalmente diferente de un endpoint JSON-RPC, que responde a solicitudes en vivo para el estado actual y bloques recientes.

El formato suele ser exportaciones CSV o columnares estilo Parquet, aunque el esquema exacto y la compresión varían según el proveedor. Debido a que son archivos, los descargas con herramientas estándar de almacenamiento de objetos y los analizas localmente o en tu propio pipeline. No son un reemplazo de RPC; son una superficie de transferencia masiva de datos para análisis histórico, indexación y rellenos. Para una visión más amplia de las superficies de acceso a datos, consulta Acceso a datos históricos de blockchain.

• Exportaciones inmutables producidas periódicamente de datos de bloques, transacciones y registros.
• Almacenadas en almacenamiento de objetos (p. ej., bucket compatible con S3) y direccionadas por rango de bloques.
• No es un endpoint de consulta en vivo; sin semántica de eth_call o eth_getLogs.
• El formato y el diseño varían según el proveedor; siempre lee la documentación del proveedor.

Por qué existen los archivos planos: el problema del relleno por RPC

Un indexador que necesita rellenar millones de bloques de otra manera emitiría millones de llamadas eth_getBlockByNumber o eth_getLogs. Cada llamada consume unidades de solicitud, y las lecturas sostenidas de alto volumen agotan rápidamente los límites de velocidad, produciendo respuestas HTTP 429. La especificación JSON-RPC 2.0 define un protocolo de solicitud-respuesta optimizado para consultas interactivas, no para extracción secuencial masiva. La especificación JSON-RPC de Ethereum documenta los métodos de bloque, transacción y registro que reemplaza una extracción masiva.

Los archivos planos invierten el modelo: en lugar de millones de solicitudes pequeñas, realizas un puñado de descargas secuenciales de objetos grandes. El volumen de datos es el mismo, pero el número de solicitudes cae en órdenes de magnitud, y evitas la sobrecarga por solicitud y la presión de los límites de velocidad. Por eso los archivos planos son la superficie preferida para rellenos históricos, mientras que RPC sigue siendo la herramienta adecuada para el estado actual y bloques recientes. Para una mirada más profunda a la mecánica de límites de velocidad, consulta Polygon RPC 429 y límites de velocidad.

• Millones de llamadas RPC consumen unidades de solicitud y provocan 429s.
• Los archivos planos transfieren los mismos datos como unas pocas descargas de objetos grandes.
• RPC está optimizado para consultas interactivas, no para extracción secuencial masiva.
• Usa archivos planos para rellenos; usa RPC para el estado actual y bloques recientes.

Tres rutas de datos de Polygon: RPC en vivo, nodo de archivo y archivos planos

Polygon expone tres superficies distintas de acceso a datos, y elegir la incorrecta es la fuente más común de presupuesto desperdiciado y rellenos fallidos. JSON-RPC en vivo sirve el estado actual y bloques recientes; es la superficie adecuada para billeteras, dApps y monitoreo en tiempo real. Un nodo de archivo sirve consultas de estado histórico que necesitan eth_call en un bloque pasado, como verificar el saldo de un token en una altura específica. Los archivos planos sirven datos históricos de bloques, transacciones y registros que procesarás de forma masiva sin conexión.

La distinción importa porque los nodos de archivo y los archivos planos no son intercambiables. Un nodo de archivo puede responder consultas de estado en cualquier bloque, pero consultar millones de bloques a través de él aún incurre en costos por solicitud y límites de velocidad. Los archivos planos no pueden responder consultas de estado en absoluto, pero entregan datos históricos de bloques y registros de manera mucho más eficiente. Para una comparación detallada de tipos de nodos, consulta Nodo de archivo vs nodo completo y Nodos de archivo de Polygon y RPC histórico.

• JSON-RPC en vivo: estado actual, bloques recientes, dApps en tiempo real.
• Nodo de archivo: consultas de estado histórico (eth_call en un bloque pasado).
• Archivos planos: datos históricos de bloques, transacciones y registros para procesamiento masivo sin conexión.

Tabla de decisión práctica: elegir la superficie correcta

Usa esta tabla para asignar una tarea a la mejor superficie de datos. El objetivo es evitar usar un endpoint RPC en vivo para extracción histórica masiva, y evitar usar archivos planos para cualquier cosa que requiera estado o la punta de la cadena. La tabla refleja el comportamiento documentado; los detalles específicos del proveedor, como el diseño del bucket y la cadencia de exportación, varían y deben confirmarse en la documentación del proveedor.

Cuando una tarea abarca múltiples superficies, divídela: usa archivos planos para el volumen histórico, y RPC para la cola reciente y cualquier consulta de estado. Este patrón híbrido mantiene bajo el consumo de unidades de solicitud mientras preserva la corrección para la lógica dependiente del estado.

• Rellenar millones de bloques de transacciones/registros → Archivos planos → Evita millones de llamadas RPC y 429s.
• Consultar el saldo actual de un token → JSON-RPC en vivo → El estado solo está disponible vía RPC o una base de datos.
• Verificar el saldo histórico en el bloque N → Nodo de archivo → Los archivos planos no contienen estado.
• Transmitir bloques recientes para un panel → JSON-RPC en vivo → Los archivos planos van por detrás de la punta de la cadena.
• Construir un conjunto de datos analíticos históricos → Archivos planos → Las descargas secuenciales masivas son eficientes.
• Resolver una reorganización cerca de la punta → JSON-RPC en vivo → Los archivos planos son instantáneas inmutables, no en vivo.

Cómo se organizan y enumeran los archivos planos

Los archivos planos se organizan por rango de bloques y se almacenan bajo un prefijo en un bucket de almacenamiento de objetos. Para enumerarlos, listas el bucket para tu rango de bloques objetivo, descargas las claves relevantes, descomprimes si es necesario y analizas en streaming el contenido en lugar de cargar todo en memoria. La estructura exacta de claves, el nombre de archivo y la compresión varían según el proveedor, así que siempre lee la documentación del proveedor para el diseño autoritativo. La documentación para desarrolladores de Polygon en docs.polygon.technology describe las superficies de acceso a datos y los endpoints RPC, mientras que los detalles del bucket de archivos planos son definidos por el proveedor.

Un flujo de trabajo típico es: determina el rango de bloques que necesitas, lista el prefijo del bucket que cubre ese rango, descarga cada objeto y analízalo línea por línea o fila por fila. Debido a que los archivos son inmutables, puedes almacenarlos en caché localmente y reprocesarlos sin volver a descargarlos. Para rangos grandes, procesa archivos en paralelo hasta tus límites de ancho de banda y memoria, pero mantén el análisis en streaming para evitar errores de falta de memoria.

• Lista el prefijo del bucket para tu rango de bloques para descubrir los archivos disponibles.
• Descarga por clave; los archivos son inmutables y se pueden almacenar en caché localmente.
• Descomprime si el proveedor almacena exportaciones comprimidas.
• Analiza en streaming en lugar de cargar archivos completos en memoria.
• Confirma el diseño y formato exactos en la documentación del proveedor.

Ejemplo ejecutable: listar y transmitir un objeto de archivo plano

El siguiente ejemplo de Node.js lista un prefijo de archivo plano compatible con S3 para un rango de bloques, descarga un objeto y lo analiza en streaming para contar transacciones. Usa el SDK de AWS v3, que funciona con cualquier endpoint compatible con S3. Reemplaza el bucket, el prefijo y las credenciales con los valores de tu proveedor. El código asume JSON delimitado por saltos de línea o CSV; ajusta el analizador para que coincida con el formato del proveedor.

Este ejemplo demuestra el patrón central: enumerar, descargar, analizar en streaming. No carga el archivo completo en memoria, lo cual es esencial para exportaciones grandes. Para un pipeline de producción completo, agrega manejo de errores, reintentos y descargas paralelas dentro de tus límites de recursos.

const { S3Client, ListObjectsV2Command, GetObjectCommand } = require('@aws-sdk/client-s3');
const { createGunzip } = require('zlib');
const readline = require('readline');

const s3 = new S3Client({
  region: 'us-east-1',
  endpoint: 'https://your-s3-compatible-endpoint',
  credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY },
  forcePathStyle: true,
});

async function listFlatFiles(bucket, prefix) {
  const res = await s3.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix }));
  return (res.Contents || []).map((o) => o.Key);
}

async function streamCountTransactions(bucket, key) {
  const res = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
  const stream = res.Body.pipe(createGunzip());
  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
  let txCount = 0;
  for await (const line of rl) {
    if (!line.trim()) continue;
    const row = JSON.parse(line);
    if (row.transactionHash) txCount++;
  }
  return txCount;
}

(async () => {
  const bucket = 'your-flat-file-bucket';
  const prefix = 'polygon/blocks/19000000/'; // adjust to provider layout
  const keys = await listFlatFiles(bucket, prefix);
  console.log('Found files:', keys.length);
  if (keys.length) {
    const count = await streamCountTransactions(bucket, keys[0]);
    console.log('Transactions in', keys[0], ':', count);
  }
})();

Contraste: el bucle RPC equivalente y su costo

Para apreciar la diferencia, considera el equivalente RPC del ejemplo anterior. Rellenar el mismo rango de bloques a través de JSON-RPC requeriría una llamada eth_getBlockByNumber por bloque, más llamadas adicionales para registros si es necesario. Para un rango de un millón de bloques, eso es un millón de solicitudes, cada una consumiendo unidades de solicitud y contando contra los límites de velocidad. La especificación JSON-RPC de Ethereum documenta estos métodos, y la especificación JSON-RPC 2.0 define el modelo de solicitud-respuesta que hace que las lecturas por bloque sean ineficientes para la extracción masiva.

El siguiente fragmento muestra el patrón de bucle RPC. Es correcto para rangos pequeños o bloques recientes, pero no escala a millones de bloques sin encontrar respuestas HTTP 429. Úsalo para la cola reciente, no para rellenos históricos.

const { ethers } = require('ethers');

async function rpcBackfill(providerUrl, fromBlock, toBlock) {
  const provider = new ethers.JsonRpcProvider(providerUrl);
  let txCount = 0;
  for (let n = fromBlock; n <= toBlock; n++) {
    const block = await provider.send('eth_getBlockByNumber', ['0x' + n.toString(16), false]);
    if (block && block.transactions) txCount += block.transactions.length;
  }
  return txCount;
}

// For a large range, this loop will consume enormous request units
// and likely trigger HTTP 429 responses. Use flat files instead.

Tabla de resultados reproducibles: mide tu propio pipeline

Para tomar una decisión informada, mide tu propio pipeline contra tu propio endpoint y proveedor. La tabla a continuación es una plantilla: complétala con tus propias mediciones. No confíes en benchmarks de proveedores ni en cifras de terceros; las variables que importan (rango de bloques, tamaño de archivo, ancho de banda de red, límites de velocidad del proveedor) son específicas de tu entorno. Ejecuta la misma tarea lógica sobre archivos planos y sobre RPC, y registra los resultados.

Usa la tabla para comparar tiempo total, bytes transferidos y conteos de HTTP 429. El objetivo no es demostrar que una superficie siempre es más rápida, sino cuantificar el compromiso para tu carga de trabajo. Para implicaciones de precios de las unidades de solicitud RPC, consulta Precios de RPC.

• Tarea: describe la operación (p. ej., contar transacciones en los bloques 19,000,000–19,100,000).
• Método: archivos planos o bucle RPC.
• Bloques cubiertos: el rango exacto.
• Tiempo total: tiempo transcurrido total en segundos.
• Bytes: datos totales transferidos.
• HTTP 429s: número de respuestas de límite de velocidad encontradas.

Limitaciones y compromisos de los archivos planos

Los archivos planos solo están tan actualizados como la última exportación. No pueden servir la punta de la cadena, y no pueden responder consultas de estado como eth_call en un bloque pasado. Son específicos de la red: un archivo plano de Polygon se aplica a Polygon, no a otra cadena. El esquema es estable solo dentro de una versión documentada; si el proveedor cambia el formato, tu analizador debe adaptarse. El diseño exacto del bucket, el nombre de archivo y la compresión varían según el proveedor y deben leerse de la documentación de ese proveedor.

Todavía necesitas RPC o una base de datos para el estado, el mempool y cualquier cosa más reciente que la última exportación. Los archivos planos son una superficie de datos históricos masivos, no un motor de consultas de propósito general. Para lógica dependiente del estado, combina archivos planos con un nodo de archivo o un endpoint RPC en vivo. Para una comparación de tipos de nodos, consulta Nodo de archivo vs nodo completo.

• Solo tan actualizados como la última exportación; no pueden servir la punta de la cadena.
• Específicos de la red; no portables entre cadenas.
• Esquema estable solo dentro de una versión documentada.
• El diseño del bucket y el formato varían según el proveedor.
• Sin cobertura de estado, mempool o bloques recientes.

Solución de problemas comunes de archivos planos y RPC

Cuando falla un pipeline de archivos planos, la causa suele ser una discrepancia entre el diseño del proveedor y tus suposiciones. Si el listado no devuelve claves, verifica el prefijo y el rango de bloques contra la documentación del proveedor. Si el análisis falla, revisa la compresión y el formato; un flujo gzip alimentado a un analizador CSV producirá errores. Si las descargas son lentas, revisa tu ancho de banda y considera descargas paralelas dentro de tus límites. Si ves respuestas HTTP 429, probablemente sigues usando RPC para extracción masiva; cambia a archivos planos para el rango histórico.

Para problemas específicos de RPC, como límites de velocidad y manejo de 429, consulta Polygon RPC 429 y límites de velocidad. Para consultas de estado de nodos de archivo, consulta Nodos de archivo de Polygon y RPC histórico. Para una guía general de RPC, consulta la Guía de RPC de Polygon (RPC Assistant).

• No se listan claves: verifica el prefijo y el rango de bloques en la documentación del proveedor.
• Errores de análisis: confirma la compresión y el formato antes de analizar.
• Descargas lentas: revisa el ancho de banda; paraleliza dentro de los límites.
• HTTP 429s: probablemente estás usando RPC para extracción masiva; cambia a archivos planos.
• Fallan las consultas de estado: los archivos planos no contienen estado; usa un nodo de archivo.

Próximos pasos: integrar archivos planos en tu stack

Comienza identificando el rango de bloques históricos que necesitas y el proveedor cuyos archivos planos lo cubren. Lee la documentación de ese proveedor para el diseño del bucket, el formato y la cadencia de exportación. Construye un pequeño pipeline que liste, descargue y analice en streaming un archivo, luego escala a tu rango completo. Mide tu pipeline con la tabla de resultados anterior y compáralo con un bucle RPC para el mismo rango. Usa archivos planos para la carga histórica masiva, y reserva RPC para la cola reciente y las consultas de estado.

Para detalles específicos de la red, consulta la página de la red Polygon. Para opciones de API y servicios, consulta el servicio de API. Para más guías, visita el centro de aprendizaje de OnFinality. Para implicaciones de precios, consulta Precios de RPC.

• Identifica el rango de bloques históricos y el proveedor cuyos archivos planos lo cubren.
• Lee la documentación del proveedor para el diseño, formato y cadencia.
• Construye un pipeline mínimo de listar-descargar-analizar, luego escala.
• Mide con la tabla de resultados y compara contra RPC.
• Usa archivos planos para el historial masivo; usa RPC para la cola reciente y el estado.