Plugins Geyser
Plugins Geyser permitem que validators Agave transmitam atualizações de conta e transação para sinks externos para indexação sem polling JSON-RPC.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
{
"libpath": "/path/to/libgeyser_plugin.so",
"accounts_selector": { "owners": ["YOUR_PROGRAM_ID"] },
"transaction_selector": { "mentions": ["YOUR_PROGRAM_ID"] }
}agave-validator --geyser-plugin-config geyser.json ...Quando usar isso:
- Validator auto-hospedado com pipeline de indexação customizado.
- Acesso de mais baixo nível a atualizações de conta ordenadas por slot.
- Construir produtos de dados proprietários no seu próprio stake.
- Filtrar na origem antes dos custos de egress de rede.
Exemplo de Trabalho
# geyser.json (ilustrativo - combine com o schema do seu plugin)
cat > geyser.json <<'EOF'
{
"libpath": "/opt/geyser/libmy_sink.so",
"kafka": { "bootstrap.servers": "localhost:9092", "topic": "solana-events" },
"accounts_selector": {
"owners": ["YOUR_PROGRAM_ID"]
}
}
EOF
agave-validator \
--ledger /data/ledger \
--geyser-plugin-config geyser.json \
--rpc-port 8899O que isso demonstra:
- Plugin
.socarrega no espaço de processo do validator. - Seletores limitam o firehose a owners/mentions relevantes.
- Consumidores downstream Kafka/Postgres processam eventos normalizados.
Deep Dive
Como Funciona
- O validator chama hooks do plugin em escritas de conta e transações confirmadas.
- Atualizações trazem slot, write version e pubkeys/dados de conta.
- O plugin deve ser rápido - bloqueio atrasa o validator se mal implementado.
- Yellowstone gRPC é um padrão popular de distribuição construído sobre interfaces Geyser.
Responsabilidades do Plugin
| Preocupação | Plugin | Seu indexador |
|---|---|---|
| Filtragem | seletores owner/mention | lógica de negócio |
| Durabilidade | encaminhar para fila | commits no DB |
| Replay | checkpoints de slot | upserts idempotentes |
| Upgrades | .so versionado | migrações de schema |
Notas bash
# Verifique carregamento do plugin na inicialização do validator - cheque logs de init geyser
tail -f /data/validator.log | grep -i geyserArmadilhas
- Callbacks lentos do plugin - validator fica atrás nos slots. Correção: handoff assíncrono para fila, trabalho mínimo no hook.
- Sem seletor - firehose completo da mainnet sobrecarrega a rede. Correção: filtros rigorosos de owner.
- Skew plugin/versão - Agave 4.1.1 exige ABI de plugin compatível. Correção: recompile o plugin em upgrades do validator.
- Assumir garantias de entrega - crashes perdem eventos em voo sem checkpoint. Correção: armazene último slot em fila durável.
- Rodar plugin apenas em RPC público - você não controla plugins de provedor hospedado. Correção: auto-hospede ou use provedor Yellowstone.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Yellowstone gRPC | Streaming gerenciado | Você já opera validator |
| Webhooks | Simplicidade HTTP push | Necessidade de latência ultra-baixa |
| RPC backfill | Histórico pequeno | Programas ao vivo de alto volume |
| DAS API | Apenas leituras de ativos | Indexação arbitrária de instruções |
FAQs
Preciso do meu próprio validator?
Para plugins customizados sim; Yellowstone gerenciado oferece gRPC sem operar stake.
Quais linguagens para plugins?
Bibliotecas dinâmicas Rust/C++ .so conforme interface de plugin geyser do Agave.
Plugins podem filtrar apenas transações?
Sim - transaction_selector com mentions de program IDs.
Como recuperar de um crash?
Replay a partir do último slot commitado armazenado no seu DB usando RPC backfill para preencher lacunas.
Atualizações de conta são comprimidas?
O plugin recebe dados completos de conta em escritas relevantes ao seletor - planeje largura de banda.
Teste de plugin em devnet?
Execute test validator com plugin contra clone de ledger devnet para carga menor.
Relação com Yellowstone?
Yellowstone expõe streams estilo Geyser via gRPC para clientes remotos.
Preocupações de segurança?
Plugin roda dentro do validator - supply chain crítico; audite fontes do .so.
Um plugin pode fazer fan-out para Kafka?
Padrão comum - plugin produz; consumidores escalam horizontalmente.
Custo ops vs provedor?
Ops de plugin auto-hospedado é pesado - webhooks/Yellowstone do provedor são mais baratos para equipes pequenas.
Relacionado
- Yellowstone gRPC - streaming remoto
- Construindo um Indexador - lógica do consumidor
- Noções Básicas de Indexação - por que indexar
- Provedores RPC - opções hospedadas
Versões da stack: Esta página foi 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 e LiteSVM 0.6.x.