Plugins Geyser

Q: Quais linguagens para plugins?

Bibliotecas dinâmicas Rust/C++ .so conforme interface de plugin geyser do Agave.

Q: Plugins podem filtrar apenas transações?

Sim - transaction_selector com mentions de program IDs.

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 8899

O que isso demonstra:

Plugin .so carrega 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 geyser

Armadilhas

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.

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 8899

O que isso demonstra:

Plugin .so carrega 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 geyser

Armadilhas

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.

Plugins Geyser

Buscar na documentação

Plugins Geyser