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.
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.
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:
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.
Os sistemas de produção quase sempre executam dois modos no mesmo esquema.
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.
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.
Atualização, preenchimento de lacunas, pequenas histórias
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.
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.
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.
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.
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.
Caminho
O que você executa
Pontos fortes
Fraquezas
Melhor ajuste
RPC + cache leve
kit/RPC, cache TTL curto, pouca história
Operações mínimas; bom para UIs "agora"
Nenhuma história profunda; limites de taxas para baleias
MVPs, carteiras com histórico apoiado pelo provedor, verificações únicas de status
Webhook + Postgres
Webhooks do provedor, fila, Postgres, API
Rápido para enviar; operações HTTP simples
Filtros e limites do provedor; risco de lacuna
Alertas, atividade moderada do programa, equipes sem servidor
Yellowstone / Geyser + indexador
Consumidor de fluxo, analisadores, banco de dados durável, monitores de atraso
Rendimento; controle ordenado por slot; programas personalizados
Propriedade de infra e analisador; Acoplamento ABI/versão para plugins
DeFi de alto volume, métricas proprietárias, produtos multilocatários
Pilha de análises completa
Acima + armazém/MVs, camada métrica, BI
Métricas de negócios confiáveis; junta-se em escala
Desvio de definição; custo de SLAs de armazenamento e frescor
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.
"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.
Qual é a ideia mais importante na indexação Solana?
Separe o acesso à cadeia ao vivo (RPC para veracidade e envio atuais) de um armazenamento durável, analisado e consultável para que os produtos sejam escalonados sem repetir o registro em cada solicitação.
Quando o RPC direto é suficiente sem um indexador?
Quando você só precisa de saldos atuais, pequenas leituras de contas, envio/confirmação de transações ou pequenos históricos que se ajustem às APIs do provedor e aos limites de taxa.
Como o Geyser se relaciona com Yellowstone?
Geyser é a interface do plugin validador para atualizações de contas e transações; Os sistemas gRPC estilo Yellowstone distribuem esses fluxos para consumidores remotos com filtros.
Preciso de meu próprio validador para indexar a mainnet?
Não. Yellowstone gerenciado, webhooks e RPC de arquivo cobrem a maioria das equipes; O Geyser auto-hospedado é para controle, coletores personalizados ou operações de nó existentes.
O que é um cursor de slot?
Um registro durável do último slot totalmente processado (por origem), para que as reinicializações e os preenchimentos de lacunas sejam retomados sem reprocessar toda a cadeia.
Por que as chaves primárias na assinatura mais o índice de instruções são comuns?
As assinaturas identificam transações; o índice de instrução (incluindo o tratamento cuidadoso do ix interno) identifica um único evento lógico para upserts idempotentes.
Devo analisar instruções internas?
Sim para programas com alto CPI. Movimentos de token e chamadas de programa relevantes para os negócios geralmente aparecem apenas dentro de meta.innerInstructions.
Como os webhooks diferem de um indexador completo?
Webhooks são um transporte de ingestão. Você ainda precisa de análise, armazenamento, reconciliação de lacunas e uma camada de serviço para obter o histórico completo do produto.
O que falha quando um programa é atualizado?
Novos discriminadores, layouts de conta ou padrões de CPI podem falhar em analisadores antigos. Fixe IDL por implantação, linhas de eventos de versão e analisadores de execução dupla durante migrações.
Como devo lidar com o atraso da transmissão?
Monitore o slot de dicas menos o slot indexado, alerta sobre limites e lacunas de preenchimento automático, em vez de servir APIs obsoletas silenciosamente, como se estivessem ativas.
O Postgres é suficiente para análises?
Frequentemente para escala inicial e média. Mova agregações pesadas para um warehouse ou mecanismo OLAP quando as consultas e a retenção do painel ultrapassarem a réplica OLTP.
Onde @solana/kit se encaixa nesse projeto?
O Kit orienta caminhos de cliente RPC para auxiliares de preenchimento, confirmação e leituras de aplicativos do estado atual. Os consumidores de fluxo de alto volume geralmente são Rust ou SDKs de provedor ao lado do kit.
O DAS pode substituir um indexador personalizado?
O DAS é excelente em leituras de ativos digitais e superfícies NFT compactadas. Ele não substitui a indexação arbitrária de instruções de programas personalizados ou suas definições de métricas privadas.
Qual nível de compromisso as linhas financeiras indexadas devem usar?Documente uma política: muitos sistemas fazem a ingestão antecipada para UX, mas só tratam as linhas como finais depois de confirmadas ou finalizadas, com tratamento explícito para reversões raras.
Como posso começar se só preciso de alertas hoje?
Envie webhooks com assinaturas verificadas, manipuladores idempotentes e uma pequena tabela de eventos; adicione Yellowstone e analisadores mais profundos quando os requisitos de volume ou histórico aumentarem.