Blueprint de Indexação

A indexação Solana é a prática de transformar eventos de cadeia ordenados por slots em dados de aplicativos duráveis e consultáveis para que os produtos possam responder "quem fez o quê, quando e quanto?" sem usar JSON-RPC para todas as telas. Depois de separar o acesso à cadeia ativa (RPC, WebSockets) do histórico moldado (seu banco de dados e API), os plug-ins Geyser, gRPC do Yellowstone, webhooks, analisadores IDL e painéis de BI param de parecer ferramentas não relacionadas e começam a parecer camadas de um plano de dados.

Indexing Basics é a entrada prática; Geyser Plugins, Yellowstone gRPC, Webhooks, Construindo um Indexer, Parsing Program Data e Analytics & Dashboards ampliam cada um em um estágio. Esta página fica abaixo: por que existem indexadores, como as peças se conectam e quando o RPC direto ainda é a resposta certa.

Resumo

• Ideia principal: Um indexador ingere continuamente transações Solana e atualizações de contas, analisa-as com layouts de programas e persiste linhas de domínio para que aplicativos e análises consultem um banco de dados em vez de reproduzir a cadeia em cada solicitação.
• Por que é importante: A pesquisa e paginação RPC não podem potencializar o volume SQL, o histórico da carteira em grande escala ou APIs de produtos multilocatários; sem indexação, os recursos do produto entram em colapso em limites de taxa, histórico incompleto e frágil eliminação de registros.
• Conceitos principais: preenchimento vs transmissão ao vivo, Geyser/Yellowstone, webhooks, cursor de slot, upserts idempotentes, discriminadores IDL, instruções internas, compromisso e reorganizações, API de serviço, armazém de análise.
• Quando usar: UIs de pesquisa e histórico de produtos, métricas DeFi, instantâneos de portfólio além de DAS, alertas e painéis de operações ou qualquer recurso que precise de junções, agregações ou retenção de vários dias sobre a atividade do programa.
• Limitações/Compensações: Você possui esquema, atraso, controle de versão do analisador e custo operacional; fluxos adicionam infra; webhooks podem perder eventos; o Geyser auto-hospedado vincula você ao ciclo de vida do validador; o RPC direto permanece melhor para leituras simples de "saldo atual".
• Tópicos relacionados: noções básicas de indexação, plug-ins Geyser, gRPC Yellowstone, webhooks, construção de um indexador, análise de dados de programas, análises e painéis.

Fundações

Solana RPC responde a perguntas pontuais: dados da conta atual, status de assinatura, bloqueio recente ou página de assinaturas de um endereço. Esse modelo é correto para carteiras e envio de transações. É um modelo ruim para histórico de produtos, agregações e consultas entre entidades.

Um indexador existe porque a cadeia é um log de execução somente anexado otimizado para validadores, não para o formato SQL ou GraphQL do seu aplicativo. Você precisa de um segundo armazenamento que reescreva “slots e bytes brutos” em “swaps, depósitos, cunhagens, posições” com índices que seu produto possa consultar.

Pense no plano de dados como camadas que vão desde o consenso até as superfícies do produto:

 
  +------------------------------------------+
  |  Analytics & dashboards (BI, metrics)    |  <- reads shaped tables
  +------------------------------------------+
  |  Serving API (REST / GraphQL / workers)  |
  +------------------------------------------+
  |  Durable store (Postgres, warehouse)     |  <- idempotent domain rows
  +------------------------------------------+
  |  Parser (IDL, Borsh, Codama, events)     |
  +------------------------------------------+
  |  Ingest (Geyser, Yellowstone, webhooks,  |
  |          RPC backfill / archives)        |
  +------------------------------------------+
  |  Chain (Agave validators, slots, txs)    |
  +------------------------------------------+
 

RPC direto ainda é essencial para envio, confirmação e pequenas leituras interativas (getAccountInfo, getBalance, status de uma assinatura recém-enviada). @solana/kit (este site: 7.0.0) fica lá para os clientes. A indexação não substitui o RPC; ele descarrega histórico e análise para que o RPC permaneça disponível para caminhos sensíveis à latência.

Por que o polling falha em grande escala é mecânico. getSignaturesForAddress e getTransaction percorrem o histórico como muitas viagens de ida e volta HTTP; histórico em massa de limite de taxa de endpoints; não há junção durável para "todos os depósitos da semana passada", a menos que você escreva essas linhas uma vez. Indexing Basics mostra o pipeline; a base é escreva uma vez na ponta, consulte muitas da sua loja.

Geyser é o gancho do lado do validador: um plugin Agave (.so) recebe atualizações de contas e transações, geralmente filtradas por proprietário ou menção. Yellowstone gRPC expõe esse firehose na rede sem exigir que você opere stake. Webhooks invertem a conexão: um provedor combina filtros e cargas HTTP POSTs. Todos os três alimentam o mesmo pipeline; eles diferem em latência, carga operacional e garantias de entrega.

Análise é o contrato entre os bytes da cadeia e a linguagem do produto: discriminadores anchor de 8 bytes, layouts Borsh ou de cópia zero, decodificadores IDL/Codama. Analytics é a última etapa: visualizações materializadas, métricas documentadas e painéis que nunca chamam RPC da rede principal por painel.

Mecânica e interações

Preenchimento e transmissão ao vivo compartilham um cursor

Os sistemas de produção quase sempre executam dois modos no mesmo esquema.

1. Backfill percorre slots históricos ou transações arquivadas (RPC getBlock / getTransaction, arquivos de provedor ou exportações de razão) até que um cursor armazenado chegue perto da ponta.
2. Transmissão ao vivo segue novos slots via Geyser, Yellowstone ou webhooks, avançando o mesmo cursor.

 
  [historical slots] ---- backfill ----+
                                       v
                                  last_slot cursor
                                       ^
  [tip stream] -------- live tail -----+
                                       |
                                       v
                              parse -> upsert -> API
 

recuperação de falhas é "repetição do último slot durável com gravações idempotentes". Chaves naturais como (signature, instruction_index) ou (pubkey, write_version) tornam os replays seguros. Sem isso, as novas tentativas e o fluxo reconectam o volume de contagem dupla e quebram as métricas financeiras.

Caminhos de ingestão: Geyser, Yellowstone, webhooks, RPC

Os plug-ins Geyser são carregados no processo validador no Agave 4.1.1 com uma configuração JSON e devem permanecer sem bloqueio; ganchos lentos correm o risco de atraso do validador. Os seletores nos proprietários do programa e nas menções às transações cortam a largura de banda antes que sua rede pague pelo firehose completo da mainnet. Detalhes: Geyser Plugins.

O gRPC no estilo Yellowstone move a filtragem e a distribuição dos servidores do produto, preservando os fluxos ordenados por slot. Webhooks invertem a conexão: o provedor liga para você. ACKs 2xx rápidos mais uma fila evitam que novas tentativas se tornem trabalhos duplicados; sempre verifique o HMAC ou a autenticação do provedor. Detalhes: Webhooks.

O RPC continua sendo o preenchimento de lacunas: após interrupções, compare o cursor do fluxo com a ponta da cadeia e preencha os slots ausentes. O histórico pesado da rede principal deve usar arquivos ou nós dedicados, e não endpoints públicos irrestritos.

Analise com layouts, não com strings de log

Os dados de instrução e os blobs de conta são as entradas canônicas. Combine o ID do programa, depois o discriminador ou a tag enum e, em seguida, desserialize os campos. Siga instruções internas na meta de transação para DeFi com alto CPI; muitos eventos de "negócios" aparecem apenas como invocações aninhadas.

 
  transaction
    outer instructions  -->  your program?
    meta.innerInstructions  -->  CPI stack (often where value moves)
    account keys (+ ALT resolution)  -->  metas for decode context
    logs  -->  optional diagnostics, never sole truth
 

versões de IDL ou de layout nas tags de implantação do programa para que as atualizações introduzam uma nova versão do analisador em vez de decodificações incorretas silenciosas. Armazene linhas unknown para discriminadores compatíveis com versões futuras. Consulte Analisando dados do programa.

Persista, sirva e depois analise

Construindo um indexador centraliza o pipeline: ingerir → normalizar → analisar → upsert → API. Tabelas de fatos (events, swaps, transfers) e instantâneos de contas opcionais alimentam os endpoints do produto com cursores em (slot, signature).

Analytics & Dashboards ficam no topo dessas tabelas: visualizações materializadas para volume diário, definições de métricas documentadas (DAU, taxas, retenção) e ferramentas de BI em réplicas somente leitura. Os gráficos que atingem JSON-RPC por atualização recriam o problema de limite de taxa que a indexação deveria resolver.

Compromisso, reorganizações e "fresco o suficiente"

Os fluxos podem fornecer dados na velocidade processed ou confirmed, enquanto as linhas críticas para finanças devem ser marcadas como finalizadas apenas de acordo com sua política. Projete sinalizadores provisórios versus finalizados ou promoção atrasada, em vez de presumir que cada carga útil do webhook é eterna. As reorganizações são raras no Solana moderno após a confirmação, mas as chaves idempotentes e o tratamento de reversão de slot ainda pertencem aos designs de produção.

Como as peças interagem em um dia de trabalho

1. Escolha ingestão: webhook MVP, Yellowstone para volume ou Geyser auto-hospedado se você já opera nós.
2. Definir esquema e chaves naturais; implementar upserts antes de métricas sofisticadas.
3. Gere ou teste manualmente analisadores em transações de fixtures (inclua ix interno).
4. Preencha uma janela local; inicie o consumidor ao vivo; armazenar last_slot.
5. Expor uma API fina para o produto; conectar painéis a uma réplica.
6. Alerta sobre atraso (slot de ponta menos slot indexado), taxa de erro de análise e profundidade da fila.

As leituras dos saldos atuais do cliente podem permanecer no RPC via kit; portfólio histórico e análises administrativas passam pelo índice.

Considerações e aplicações avançadas

As equipes não precisam de um armazém cheio no primeiro dia. Combine risco do produto, volume e tamanho da equipe com um caminho de ingestão e armazenamento e, em seguida, aprofunde os analisadores e análises à medida que as perguntas ficam mais difíceis.

RPC + light cache ainda está correto quando a pergunta é "o que é esta conta agora?" Não indexe por si só.

Webhook + Postgres otimiza a velocidade da equipe. Combine com trabalhos de reconciliação periódicos para que o tempo de inatividade não se torne buracos permanentes.

Yellowstone/Geyser + indexador é o caminho sério padrão quando o volume de instruções ou a complexidade do programa personalizado supera os modelos de análise do provedor. Filtre antecipadamente; mantenha ganchos e manipuladores de fluxo finos; colocar lógica de negócios nos trabalhadores.

Pilha de análise completa trata as definições de métricas como produtos: preços em dólares americanos no momento do bloqueio, filtragem de bot, coortes de retenção e atualização de SLAs. Ferramentas públicas (estilo Dune) ajudam a abrir protocolos; programas privados precisam de sua própria loja.

Não confunda camadas: o kit não é um indexador, os webhooks não são um histórico completo, o DAS não é uma indexação arbitrária de instruções e uma consulta no painel verde não é uma prova de que o fluxo foi alcançado. Para análises de design, responda primeiro: qual caminho de ingestão, quais chaves naturais, qual compromisso com o dinheiro, qual orçamento atrasado e quem possui a versão IDL após a atualização do programa.

Equívocos comuns

• "Podemos potencializar o produto inteiramente com getSignaturesForAddress." A paginação e os limites de taxa entram em colapso sob o histórico e análises reais do usuário; esse caminho é para thin clients e preenchimento de lacunas, não para todo o banco de dados do produto.
• "WebSockets sozinhos são um indexador." As assinaturas fornecem atualizações ao vivo; sem armazenamento durável, cursores e analisadores, você ainda não poderá servir o histórico SQL após a reconexão.
• "Geyser é apenas para operadores validadores que se preocupam com staking." Geyser é a interface de fluxo de baixo nível; as equipes de produto o consomem por meio de plug-ins ou Yellowstone, mesmo quando nunca chegam a um consenso.
• "As mensagens de log são um esquema estável." Os logs mudam com refatoradores de programa; dados de instrução e layouts de conta são o contrato durável.
• "A idempotência é opcional se o fluxo for confiável." Novas tentativas, reinicializações e nova entrega do provedor serão inseridas duas vezes sem chaves naturais.
• "O preenchimento é uma tarefa de inicialização única." Lacunas causadas por interrupções, alterações de filtros e novos tipos de instruções exigem ferramentas de reprodução contínuas.
• "Cargas aprimoradas do provedor eliminam a necessidade de entender o programa." Elas aceleram padrões SPL comuns; programas personalizados ainda precisam de suas próprias regras de decodificação e política de atualização.
• "Os painéis devem consultar o RPC da rede principal para atualização." A atualização pertence ao orçamento de atraso do indexador; os painéis devem ler tabelas moldadas em uma réplica.

Perguntas frequentes

Relacionado

• Indexing Basics - por que o RPC sozinho falha e o formato do pipeline principal
• Geyser Plugins - ganchos e seletores de streaming do lado do validador
• Webhooks - Ingestão de push HTTP e padrões de verificação
• Construindo um indexador - persistência, upserts e APIs de serviço
• Parsing Program Data - IDL, discriminadores e regras de decodificação
• Analytics & Dashboards - métricas, visualizações materializadas e BI

Versões Stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.