Plugins de Geyser
Los plugins de Geyser permiten a los validadores de Agave transmitir actualizaciones de cuentas y transacciones a destinos externos para indexación sin necesidad de consultar JSON-RPC.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
{
"libpath": "/ruta/a/libgeyser_plugin.so",
"accounts_selector": { "owners": ["TU_PROGRAM_ID"] },
"transaction_selector": { "mentions": ["TU_PROGRAM_ID"] }
}agave-validator --geyser-plugin-config geyser.json ...Cuándo usar esto:
- Validador autoalojado con pipeline de indexación personalizado.
- Acceso al nivel más bajo a actualizaciones de cuentas ordenadas por slot.
- Creación de productos de datos propietarios sobre tu propia participación.
- Filtrado en origen antes de los costos de salida de red.
Ejemplo de Trabajo
# geyser.json (ilustrativo - coincide con el esquema de tu plugin)
cat > geyser.json <<'EOF'
{
"libpath": "/opt/geyser/libmy_sink.so",
"kafka": { "bootstrap.servers": "localhost:9092", "topic": "solana-events" },
"accounts_selector": {
"owners": ["TU_PROGRAM_ID"]
}
}
EOF
agave-validator \
--ledger /data/ledger \
--geyser-plugin-config geyser.json \
--rpc-port 8899Lo que esto demuestra:
- El plugin
.sose carga en el espacio de proceso del validador. - Los selectores limitan el "firehose" a los propietarios/menciones relevantes.
- Los consumidores de Kafka/Postgres posteriores procesan eventos normalizados.
Análisis Profundo
Cómo Funciona
- El validador llama a los hooks del plugin en escrituras de cuentas y transacciones confirmadas.
- Las actualizaciones transportan el slot, la versión de escritura y las claves públicas/datos de la cuenta.
- El plugin debe ser rápido: un bloqueo ralentiza el validador si se implementa incorrectamente.
- Yellowstone gRPC es un patrón de distribución popular basado en las interfaces de Geyser.
Responsabilidades del Plugin
| Preocupación | Plugin | Tu indexador |
|---|---|---|
| Filtrado | selectores de propietario/mención | lógica de negocio |
| Durabilidad | enviar a cola | confirmaciones de DB |
| Repetición | puntos de control de slot | inserciones idempotentes |
| Actualizaciones | .so versionado | migraciones de esquema |
Notas de bash
# Verifica que el plugin se carga al inicio del validador - revisa los logs en busca de líneas de inicialización de geyser
tail -f /data/validator.log | grep -i geyserTrampas Comunes
- Callbacks lentos del plugin: el validador se retrasa en los slots. Solución: transferencia asíncrona a la cola, trabajo mínimo en el hook.
- Sin selector: el "firehose" completo de mainnet satura la red. Solución: filtros estrictos de propietario.
- Desfase de plugin/versión: Agave 4.1.1 requiere una ABI de plugin coincidente. Solución: reconstruye el plugin en las actualizaciones del validador.
- Asumir garantías de entrega: los bloqueos pierden eventos en tránsito sin puntos de control. Solución: almacena el último slot en una cola duradera.
- Ejecutar el plugin solo en RPC público: no controlas los plugins de proveedores alojados. Solución: autoalojamiento o uso de un proveedor de Yellowstone.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Yellowstone gRPC | Streaming gestionado | Ya operas un validador |
| Webhooks | Simplicidad de push HTTP | Necesidades de latencia ultra baja |
| Relleno RPC | Historial pequeño | Programas de alto volumen en vivo |
| API DAS | Solo lecturas de activos | Indexación de instrucciones arbitrarias |
Preguntas Frecuentes
¿Necesito mi propio validador?
Para plugins personalizados, sí; Yellowstone gestionado proporciona gRPC sin operar participación.
¿Qué idiomas para los plugins?
Bibliotecas dinámicas Rust/C++ .so según la interfaz del plugin geyser de Agave.
¿Pueden los plugins filtrar solo transacciones?
Sí - transaction_selector con menciones de IDs de programa.
¿Cómo me recupero de un bloqueo?
Repite desde el último slot confirmado almacenado en tu DB usando el relleno de huecos de RPC.
¿Están comprimidas las actualizaciones de cuentas?
El plugin recibe datos completos de la cuenta en escrituras relevantes para el selector; planifica el ancho de banda.
¿Pruebas de plugins en Devnet?
Ejecuta un validador de prueba con el plugin contra un clon del ledger de devnet para una carga más ligera.
¿Relación con Yellowstone?
Yellowstone expone flujos estilo Geyser sobre gRPC a clientes remotos.
¿Preocupaciones de seguridad?
El plugin se ejecuta dentro del validador; la cadena de suministro es crítica; audita las fuentes de .so.
¿Puede un plugin distribuir a Kafka?
Patrón común: el plugin produce; los consumidores escalan horizontalmente.
Costo de operaciones vs proveedor?
Las operaciones del plugin autoalojado son intensivas; los webhooks/Yellowstone del proveedor son más baratos para equipos pequeños.
Relacionado
- Yellowstone gRPC - streaming remoto
- Construcción de un Indexador - lógica del consumidor
- Conceptos Básicos de Indexación - por qué indexar
- Proveedores RPC - opciones alojadas
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, y LiteSVM 0.6.x.