Indexing Blueprint

El indexado de Solana es la práctica de convertir eventos de cadena ordenados por slot en datos de aplicación duraderos y consultables para que los productos puedan responder "¿quién hizo qué, cuándo y cuánto?" sin saturar JSON-RPC para cada pantalla. Una vez que separas el acceso en vivo a la cadena (RPC, WebSockets) del historial con forma (tu base de datos y API), los plugins de Geyser, Yellowstone gRPC, webhooks, parsadores de IDL y dashboards de análisis dejan de parecer herramientas no relacionadas y empiezan a parecer capas de un único plano de datos.

Conceptos básicos de indexado es la entrada práctica; Plugins de Geyser, Yellowstone gRPC, Webhooks, Construcción de un Indexador, Análisis de datos de programas y Análisis y Dashboards cada uno se enfoca en una etapa. Esta página se sitúa debajo: por qué existen los indexadores, cómo se conectan las piezas y cuándo el RPC directo sigue siendo la respuesta correcta.

Resumen

• Un indexador ingiere continuamente transacciones y actualizaciones de cuentas de Solana, las analiza con diseños de programas y persiste filas de dominio para que las aplicaciones y los análisis consulten una base de datos en lugar de reproducir la cadena en cada solicitud.
• Por qué Importa: El sondeo RPC y la paginación no pueden potenciar el volumen SQL, el historial de billeteras a escala de ballenas o las API de productos multi-inquilino; sin indexación, las características del producto colapsan en límites de tasa, historial incompleto y raspado frágil de logs.
• Conceptos Clave: backfill vs. stream en vivo, Geyser / Yellowstone, webhooks, cursor de slot, upserts idempotentes, discriminadores IDL, instrucciones internas, compromiso y reorganizaciones, API de servicio, almacén de análisis.
• Cuándo Usar: Interfaces de búsqueda y historial de productos, métricas DeFi, instantáneas de portafolio más allá de DAS, alertas y dashboards de operaciones, o cualquier característica que necesite uniones, agregaciones o retención de varios días sobre la actividad del programa.
• Limitaciones / Compensaciones: Eres responsable del esquema, el retraso, la versión del parser y el costo de las operaciones; los streams añaden infraestructura; los webhooks pueden perder eventos; Geyser auto-alojado te ata al ciclo de vida del validador; el RPC directo sigue siendo mejor para lecturas simples de "saldo actual".
• Temas Relacionados: conceptos básicos de indexado, plugins de Geyser, Yellowstone gRPC, webhooks, construcción de un indexador, análisis de datos de programas, análisis y dashboards.

Fundamentos

El RPC de Solana responde preguntas puntuales: datos de cuenta actuales, estado de una firma, un bloque reciente o una página de firmas para una dirección. Ese modelo es correcto para billeteras y envío de transacciones. Es un modelo pobre para historial de productos, agregaciones y consultas entre entidades.

Un indexador existe porque la cadena es un registro de ejecución de solo adición optimizado para validadores, no para la forma SQL o GraphQL de tu aplicación. Necesitas una segunda tienda que reescriba "slots y bytes crudos" en "intercambios, depósitos, acuñaciones, posiciones" con índices que tu producto pueda permitirse consultar.

Piensa en el plano de datos como capas, desde el consenso hasta las superficies del producto:

  +------------------------------------------+
  |  Análisis y dashboards (BI, métricas)    |  <- lee tablas con forma
  +------------------------------------------+
  |  API de servicio (REST / GraphQL / workers)  |
  +------------------------------------------+
  |  Almacén duradero (Postgres, warehouse)     |  <- filas de dominio idempotentes
  +------------------------------------------+
  |  Parser (IDL, Borsh, Codama, eventos)     |
  +------------------------------------------+
  |  Ingesta (Geyser, Yellowstone, webhooks,  |
  |          backfill RPC / archivos)        |
  +------------------------------------------+
  |  Cadena (validadores Agave, slots, txs)    |
  +------------------------------------------+

RPC directo sigue siendo esencial para el envío, la confirmación y las lecturas interactivas pequeñas (getAccountInfo, getBalance, estado de una firma recién enviada). @solana/kit (este sitio: 7.0.0) se sitúa ahí para los clientes. La indexación no reemplaza al RPC; descarga el historial y los análisis para que el RPC permanezca disponible para rutas sensibles a la latencia.

Por qué el sondeo falla a escala es mecánico. getSignaturesForAddress y getTransaction recorren el historial como muchos viajes de ida y vuelta HTTP; los endpoints limitan la tasa del historial masivo; no hay una unión duradera para "todos los depósitos de la semana pasada" a menos que escribas esas filas una vez. Conceptos básicos de indexado muestra el pipeline; el fundamento es escribir una vez en la punta, consultar muchas veces desde tu almacén.

Geyser es el gancho del lado del validador: un plugin de Agave (.so) recibe actualizaciones de cuentas y transacciones, a menudo filtradas por propietario o mención. Yellowstone gRPC expone ese "firehose" a través de la red sin requerir que ejecutes stake. Webhooks invierten la conexión: un proveedor coincide con los filtros y envía cargas útiles HTTP. Los tres alimentan el mismo pipeline; difieren en latencia, carga de operaciones y garantías de entrega.

Parsing es el contrato entre los bytes de la cadena y el lenguaje del producto: discriminadores de 8 bytes de Anchor, diseños Borsh o zero-copy, decodificadores IDL/Codama. Análisis es la última milla: vistas materializadas, métricas documentadas y dashboards que nunca llaman al RPC de mainnet por panel.

Mecánicas e Interacciones

Backfill y stream en vivo comparten un cursor

Los sistemas de producción casi siempre ejecutan dos modos en el mismo esquema.

1. Backfill recorre slots históricos o transacciones archivadas (getBlock / getTransaction de RPC, archivos de proveedores o exportaciones de ledger) hasta que un cursor almacenado llega cerca de la punta.
2. Stream en vivo sigue nuevos slots a través de Geyser, Yellowstone o webhooks, avanzando el mismo cursor.

  [slots históricos] ---- backfill ----+
                                       v
                                  cursor last_slot
                                       ^
  [stream de punta] -------- cola en vivo -----+
                                       |
                                       v
                              parse -> upsert -> API

La recuperación de fallos es "reproducir desde el último slot duradero con escrituras idempotentes". Las claves naturales como (signature, instruction_index) o (pubkey, write_version) hacen que las reproducciones sean seguras. Sin eso, los reintentos y las reconexiones de stream duplican el volumen y rompen las métricas financieras.

Rutas de ingesta: Geyser, Yellowstone, webhooks, RPC

Los plugins de Geyser se cargan en el proceso del validador en Agave 4.1.1 con un JSON de configuración y deben permanecer no bloqueantes; los hooks lentos arriesgan el retraso del validador. Los selectores sobre propietarios de programas y menciones de transacciones reducen el ancho de banda antes de que tu red pague por el "firehose" completo de mainnet. Detalles: Plugins de Geyser.

Yellowstone-style gRPC mueve el filtrado y la distribución fuera de tus servidores de producto mientras preserva los streams ordenados por slot. Los webhooks invierten la conexión: el proveedor te llama. Los ACKs 2xx rápidos más una cola evitan que los reintentos se conviertan en trabajo duplicado; siempre verifica HMAC o autenticación del proveedor. Detalles: Webhooks.

RPC sigue siendo el rellenador de huecos: después de las interrupciones, compara el cursor del stream con la punta de la cadena y haz backfill de los slots perdidos. El historial pesado de mainnet debe usar archivos o nodos dedicados, no endpoints públicos sin restricciones.

Analizar con diseños, no con cadenas de logs

Los datos de instrucciones y los blobs de cuentas son las entradas canónicas. Coincide con el ID del programa, luego con el discriminador o la etiqueta de enumeración, luego deserializa los campos. Recorre las instrucciones internas en los metadatos de la transacción para DeFi con muchas CPI; muchos eventos "de negocio" solo aparecen como invocaciones anidadas.

  transacción
    instrucciones externas  -->  ¿tu programa?
    meta.innerInstructions  -->  pila CPI (a menudo donde se mueven los valores)
    claves de cuenta (+ resolución ALT)  -->  metadatos para contexto de decodificación
    logs  -->  diagnósticos opcionales, nunca la única verdad

Fija las versiones de IDL o de diseño a las etiquetas de despliegue del programa para que las actualizaciones introduzcan una nueva versión del parser en lugar de decodificaciones erróneas silenciosas. Almacena filas unknown para discriminadores compatibles con versiones futuras. Ver Análisis de datos de programas.

Persistir, servir y luego analizar

Construcción de un Indexador centra el pipeline: ingesta → normalización → análisis → upsert → API. Las tablas de hechos (events, swaps, transfers) y las instantáneas opcionales de cuentas potencian los endpoints del producto con cursores en (slot, signature).

Análisis y Dashboards se asientan sobre esas tablas: vistas materializadas para el volumen diario, definiciones de métricas documentadas (DAU, tarifas, retención) y herramientas de BI en réplicas de solo lectura. Los gráficos que golpean JSON-RPC por actualización recrean el problema de límite de tasa que la indexación pretendía resolver.

Compromiso, reorganizaciones y "suficientemente fresco"

Los streams pueden entregar datos a velocidad processed o confirmed, mientras que las filas críticas para las finanzas solo deben marcarse como finalizadas según tu política. Diseña indicadores provisionales vs. finalizados o promoción retardada en lugar de asumir que cada carga útil de webhook es eterna. Las reorganizaciones son raras en Solana moderno después de la confirmación, pero las claves idempotentes y el manejo de retroceso de slots todavía pertenecen a los diseños de producción.

Cómo interactúan las piezas en un día de trabajo

1. Elige la ingesta: webhook MVP, Yellowstone para volumen, o Geyser auto-alojado si ya operas nodos.
2. Define el esquema y las claves naturales; implementa upserts antes que métricas sofisticadas.
3. Genera o prueba manualmente parsers contra transacciones de prueba (incluye ix internas).
4. Haz backfill de una ventana acotada; inicia el consumidor en vivo; almacena last_slot.
5. Expón una API delgada para el producto; conecta dashboards a una réplica.
6. Alerta sobre el retraso (slot de punta menos slot indexado), la tasa de error del parser y la profundidad de la cola.

Las lecturas del cliente de saldos actuales pueden permanecer en RPC a través de kit; el historial y los análisis de administración van a través del índice.

Consideraciones Avanzadas y Aplicaciones

Los equipos no necesitan un almacén completo desde el primer día. Empareja el riesgo del producto, el volumen y el tamaño del equipo con una ruta de ingesta y almacenamiento, y luego profundiza los parsers y análisis a medida que las preguntas se vuelven más difíciles.

RPC + caché ligera sigue siendo correcto cuando la pregunta es "¿qué es esta cuenta ahora mismo?". No indexes por el simple hecho de indexar.

Webhook + Postgres optimiza la velocidad del equipo. Empareja con trabajos de reconciliación periódicos para que el tiempo de inactividad no se convierta en agujeros permanentes.

Yellowstone / Geyser + indexador es la ruta seria por defecto una vez que el volumen de instrucciones o la complejidad del programa personalizado superan las plantillas de análisis del proveedor. Filtra temprano; mantén los hooks y los manejadores de stream delgados; pon la lógica de negocio en workers.

Pila de análisis completa trata las definiciones de métricas como producto: precios en USD a la hora del bloque, filtrado de bots, cohortes de retención y SLAs de actualización. Las herramientas públicas (estilo Dune) ayudan a los protocolos abiertos; los programas privados necesitan tu propia tienda.

No confundas capas: kit no es un indexador, los webhooks no son historial completo, DAS no es indexación arbitraria de instrucciones, y una consulta de dashboard verde no es prueba de que el stream esté al día. Para revisiones de diseño, responde primero: qué ruta de ingesta, qué claves naturales, qué compromiso para el dinero, qué presupuesto de retraso, y quién es responsable de las actualizaciones de la versión IDL después de la actualización del programa.

Conceptos Erróneos Comunes

• "Podemos potenciar el producto completamente con getSignaturesForAddress." La paginación y los límites de tasa colapsan bajo el historial real del usuario y los análisis; esa ruta es para clientes delgados y relleno de huecos, no para toda la base de datos del producto.
• "Los WebSockets por sí solos son un indexador." Las suscripciones entregan actualizaciones en vivo; sin almacenamiento duradero, cursores y parsers, todavía no puedes servir historial SQL después de reconectar.
• "Geyser es solo para operadores de validadores que se preocupan por el staking." Geyser es la interfaz de stream de bajo nivel; los equipos de producto lo consumen a través de plugins o Yellowstone, incluso cuando nunca ejecutan consenso.
• "Los mensajes de log tienen un esquema estable." Los logs cambian con las refactorizaciones del programa; los datos de instrucciones y los diseños de cuentas son el contrato duradero.
• "La idempotencia es opcional si el stream es confiable." Los reintentos, reinicios y la redelivación del proveedor insertarán duplicados sin claves naturales.
• "El backfill es una tarea de lanzamiento única." Los huecos por interrupciones, cambios de filtro y nuevos tipos de instrucciones requieren herramientas de reproducción continuas.
• "Las cargas útiles mejoradas del proveedor eliminan la necesidad de entender el programa." Aceleran los patrones SPL comunes; los programas personalizados todavía necesitan tus propias reglas de decodificación y política de actualización.
• "Los dashboards deberían consultar el RPC de mainnet para la frescura." La frescura pertenece al presupuesto de retraso del indexador; los dashboards deberían leer tablas con forma en una réplica.

Preguntas Frecuentes

Relacionados

• Conceptos básicos de indexado - por qué RPC solo falla y la forma del pipeline central
• Plugins de Geyser - hooks de streaming del lado del validador y selectores
• Webhooks - ingesta push HTTP y patrones de verificación
• Construcción de un Indexador - persistencia, upserts y APIs de servicio
• Análisis de datos de programas - IDL, discriminadores y reglas de decodificación
• Análisis y Dashboards - métricas, vistas materializadas y BI

Versiones de Stack: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, y @solana/kit 7.0.0.