Como Indexar Dados Solana

Visão Geral

O blockchain Solana armazena dados em um livro-razão sequencial e apenas de escrita. Isso é ótimo para integridade de dados e vazão de transações, mas tem um custo significativo: torna a consulta de dados históricos muito ineficiente e proibitivamente lenta. Operações complexas muitas vezes envolvem filtragem, agregação ou união de dados de várias fontes. Nesses casos, fazer consultas diretas no Solana é impraticável para a maioria das aplicações do mundo real. Para resolver isso, a maioria das empresas constrói índices privados dos dados históricos do Solana. Este guia cobre todo o ciclo de vida: preenchendo dados históricos com getTransactionsForAddress e outros métodos arquivais RPC, escolhendo um banco de dados e mantendo o índice atualizado com streaming em tempo real.

Quando usar isso

Construa um índice quando:

Seu produto precisar de consultas rápidas e filtradas que chamadas RPC diretas são muito lentas (por exemplo, contas de tokens e saldos de uma carteira, ou todo o histórico de um par de negociação).
Você precisa filtrar, agregar ou unir dados on-chain ou combiná-los com dados off-chain (preços CEX, KYC, rótulos).
Você está calculando coisas como PnL, análises de detentores ou histórico de vendas de NFT que requerem dados pré-processados e passíveis de consulta.
Está atendendo muitos usuários e não pode arcar com a latência por solicitação contra a cadeia.

Se você precisa apenas de dados padrão de carteira ou ativos, uma API gerenciada pode ser mais simples do que executar seu próprio índice. Veja Opções complementares abaixo.

O que significa indexar dados Solana?

Indexar é o processo de consultar dados do blockchain Solana e armazená-los em um banco de dados backend (por exemplo, PostgreSQL, ClickHouse) que pode então ser usado para atender prontamente a solicitações de clientes sem precisar consultar diretamente o blockchain usando chamadas RPC Solana. Um indexador normalmente faz quatro coisas:

Preencher dados históricos: usar métodos arquivais RPC para consultar todos os dados históricos
Transmitir novos dados: processar novos blocos quando confirmados pela rede
Analisar e transformar dados: extrair dados relevantes dos blocos confirmados (por exemplo, transações, alterações de estado, etc.)
Organizar dados em um banco de dados: atualizar o índice com os novos dados

Por que a maioria das empresas constrói índices Solana?

As empresas constroem índices Solana porque seus negócios dependem de fornecer acesso rápido e em tempo real a dados de blockchain específicos que os RPCs nativos não oferecem (por exemplo, histórico de vendas de NFT). As empresas também aproveitam índices personalizados para combinar dados off-chain (por exemplo, preços de bolsas centralizadas, informações KYC, etc.) com seus dados on-chain.

Exemplo de Carteira

Por exemplo, se uma carteira Solana precisa retornar rapidamente as contas e saldos de tokens de um usuário, consultar o Solana diretamente com getTokenAccountsByOwner e getTokenAccountBalance é muito lento e poderia tornar seu produto inutilizável. Em vez disso, as carteiras geralmente mantêm seus próprios índices de endereços de clientes, tokens e saldos de contas.

Exemplo de Negociação

Da mesma forma, uma empresa de negociação de criptomoedas pode querer registrar toda a atividade de negociação que acontece em um par específico (por exemplo, SOL-USDC) ou um mercado específico para testar retroativamente seus algoritmos de negociação. Consultar o blockchain diretamente para esses dados seria muito lento para qualquer análise prática de negociação. Em vez disso, traders quantitativos podem optar por construir índices para o mercado SOL-USDC e mantê-lo atualizado com as últimas negociações usando produtos de streaming em tempo real como LaserStream.

Exemplo de Filtragem

Imagine que um usuário deseja filtrar transações por critérios específicos em seu aplicativo frontend (por exemplo, por tipo de token, valor de transferência, data ou endereço de carteira). Sem um indexador, seu aplicativo precisaria escanear milhões de transações em centenas de milhares de blocos, verificando cada uma contra os critérios de filtro. Esse processo é muito lento para experiências modernas de usuário.

Exemplo de PnL

Para calcular o lucro e perda (PnL) de um trader, você precisaria:

Encontrar todas as transações associadas à sua carteira em um determinado período de tempo
Filtrar transações de troca e rotulá-las como compras ou vendas
Determinar quantas taxas o usuário pagou durante cada troca
Obter os dados de preço histórico de cada token no momento de cada negociação
Agregar o PnL de cada transação para calcular o PnL total do trader

Calcular tudo isso em tempo real é impraticável e requer uma solução mais rápida e escalável. Com um índice, todas essas informações já estão processadas e armazenadas em um banco de dados consultável. Agora, calcular o PnL de um trader torna-se uma única chamada de API que é atendida instantaneamente. Vamos analisar três abordagens para preencher um índice Solana e mantê-lo atualizado.

Passo 1: Obter os dados históricos

A primeira etapa para construir um índice Solana é obter todos os dados históricos de que você precisa. Existem três maneiras principais de fazer isso:

getTransactionsForAddress (recomendado)
getSignaturesForAddress e getTransaction
getBlock

Método 1: getTransactionsForAddress (recomendado)

O método RPC getTransactionsForAddress permite buscar os detalhes completos da transação para um segmento arbitrário de dados de blockchain. Devido às suas poderosas habilidades de filtragem, você não perderá tempo recuperando dados que não são necessários para o seu índice, e graças à funcionalidade de busca reversa, você pode obter transações em ordem cronológica.

Etapas para usar este método

Determine o período de tempo do qual você precisa dos dados e defina o filtro de acordo
Defina transactionDetails como full para obter todos os detalhes da transação
Configure o filtro tokenAccounts para incluir transações de contas de token associadas, se necessário
Paginar pelos resultados usando paginationToken
Em cada iteração, extraia os dados necessários e armazene-os em seu banco de dados

Benefícios de usar getTransactionsForAddress

As principais vantagens de usar o endpoint gTFA são a velocidade e a simplicidade. Com filtros baseados em slot e tempo, suporte a contas de token, busca reversa e paginação, você pode obter qualquer dado que quiser, de qualquer momento na história do Solana, tudo com uma única chamada, sem loops complexos ou lógica de tentativa novamente. Ao contrário de getSignaturesForAddress, ele também pode incluir transações envolvendo contas de token associadas de propriedade do endereço. Se o seu índice for especificamente sobre movimentação de tokens e SOL nativo (pagamentos, livros-razão, reconciliação de saldo), getTransfersByAddress retorna linhas de transferência prontas para reconciliação, em vez de transações completas, o que pode economizar uma etapa de análise.

Método 2: getSignaturesForAddress e getTransaction

Antes do lançamento do gTFA, a abordagem padrão para consultar dados históricos era fazer um loop recursivo sobre assinaturas usando getSignaturesForAddress (do mais recente para o mais antigo) e, em seguida, chamar getTransaction para extrair os detalhes completos da transação.

Etapas para usar este método

Aqui estão as etapas básicas para usar este método:

Chame getSignaturesForAddress
Armazene a assinatura da última transação recebida dessa chamada
Para a próxima chamada de getSignaturesForAddress, defina o parâmetro before para esta assinatura
Repita isso em um loop pelo tempo necessário
Para cada assinatura de transação recuperada dessa maneira, chame getTransaction para obter seus detalhes completos da transação
Insira os dados relevantes em seu banco de dados

Desvantagens deste método

Infelizmente, para usar este método você precisa:

Começar pela transação mais recente e trabalhar retroativamente
Fazer uma chamada RPC adicional para cada transação
Construir uma fila segura para threads para lidar com processamento simultâneo
Criar lógica para tentativas novamente e atrasos para evitar dados perdidos e limitações de taxa
Não inclui transações envolvendo contas de token associadas de propriedade do endereço

Embora este método funcione, é mais complicado, menos flexível e consome muito mais créditos. Para histórico completo de carteira, incluindo contas de token, use getTransactionsForAddress em vez.

Método 3: Usar getBlock

O método getBlock é mais eficaz quando uma alta porcentagem de transações em seus blocos-alvo é relevante para sua análise, como indexar as transações de programas Solana usados com frequência como o Agregador do DFlow, o programa Pump.fun ou o programa de Token do Solana.

Etapas para usar este método

O processo básico para consultar dados históricos com getBlock inclui:

Decidir sobre um intervalo de tempo para consulta
Converter esse intervalo de tempo em números de slot
Buscar os blocos correspondentes sequencialmente (para frente ou para trás)
Para cada bloco, filtrar as transações que são relevantes para seu índice
Armazenar as informações relevantes em seu índice

Para a maioria dos casos de uso, esse método é inerentemente desperdiçador, já que você está recuperando todas as transações em um bloco, quando, tipicamente, apenas uma pequena fração será relevante para sua análise. Use este método apenas quando estiver examinando as transações de programas utilizados com frequência ou quando a filtragem baseada em endereço não puder capturar seus dados-alvo.

Passo 2: Sincronizar dados Solana com seu banco de dados

Depois de buscar dados históricos, você precisa transformá-los e armazená-los de maneira eficiente em um banco de dados. Sua escolha de armazenamento deve ser adaptada ao seu caso de uso específico — não há uma solução única para todos. O banco de dados certo depende do tamanho do seu conjunto de dados, requisitos de latência, padrões de consulta e expertise da equipe.

Opção 1: Bancos de Dados SQL

Armazenar dados Solana em bancos de dados relacionais como o PostgreSQL é recomendado para a maioria dos casos de uso. SQL é flexível, ubíquo e fácil de aprender. Os bancos de dados relacionais modernos podem escalar além de 100M+ linhas, oferecendo ainda os benefícios da conformidade ACID, junções complexas e poderosos índices secundários. Use SQLite para prototipagem, desenvolvimento local ou quando você quiser configuração zero com um banco de dados de arquivo único. É ideal quando seu conjunto de dados permanece abaixo de alguns gigabytes. Use PostgreSQL para aplicações de produção que precisam de replicação de dados, acesso simultâneo de vários clientes ou recursos avançados como busca de texto completo e operadores JSON. Para a maioria dos indexadores Solana em nível de produção, o PostgreSQL é nossa escolha recomendada.

Exemplo de implementação:

Como exemplo, mostraremos como armazenar transferências de tokens em um banco de dados PostgreSQL. Primeiro, crie uma tabela:

CREATE TABLE token_transfers (
    id BIGSERIAL PRIMARY KEY,
    slot BIGINT NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    signature BYTEA NOT NULL UNIQUE,
    token_mint BYTEA NOT NULL,
    source_address BYTEA NOT NULL,
    destination_address BYTEA NOT NULL,
    amount BIGINT NOT NULL,
    decimals SMALLINT NOT NULL,
    program_id BYTEA
);

Em seguida, adicione índices em colunas consultadas com frequência:

CREATE INDEX idx_source_address ON token_transfers (source_address);
CREATE INDEX idx_destination_address ON token_transfers (destination_address);
CREATE INDEX idx_token_mint ON token_transfers (token_mint);

Você também pode criar índices parciais caso apenas um subconjunto dos dados seja consultado com frequência. É assim que você cria um índice apenas para transferências de alto valor:

CREATE INDEX idx_large_transfers ON token_transfers(amount) WHERE amount > 1000000;

Ao preencher dados, certifique-se de usar INSERTs em massa e declarações preparadas para otimizar a velocidade de gravação.

Opção 2: Bancos de Dados Columnar

Bancos de dados columnar são otimizados para consultas analíticas, agregações e dados de séries temporais de alto volume. Se você precisa indexar vários bilhões de transações, bancos de dados columnar como ClickHouse ou Cassandra são sua melhor opção. Use ClickHouse quando precisar de consultas analíticas em tempo real em grandes conjuntos de dados — é otimizado para leituras rápidas, agregações e análise de séries temporais. Use Cassandra quando precisar de uma taxa de escrita extremamente alta, escalabilidade horizontal sem esforço e alta tolerância a falhas. Isso o torna ideal para ingerir continuamente volumes massivos de dados Solana.

Exemplo de implementação:

Mostraremos como armazenar transferências de tokens em um banco de dados ClickHouse. Para isso, crie uma tabela que use o motor de tabela MergeTree. Ele é projetado para altas taxas de ingestão, portanto, é ideal para indexação. Use este comando:

CREATE TABLE token_transfers (
    block_time DateTime,
    slot UInt64,
    signature FixedString(64),
    token_mint FixedString(32),
    source_address FixedString(32),
    destination_address FixedString(32),
    amount UInt64,
    decimals UInt8,
    program_id FixedString(32),
    date Date DEFAULT toDate(block_time)
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(date)
ORDER BY (token_mint, date)
SETTINGS index_granularity = 8192;

Nesta configuração, (token_mint, date) é definido como chave primária e de ordenação. ClickHouse ordenará os dados em disco de acordo com sua chave de ordenação. Isso é ótimo para consultar um único mint de token e restringir a resposta por intervalos de data. Aqui está um exemplo de consulta:

SELECT date, signature, source_address, destination_address, amount
FROM token_transfers
WHERE token_mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
AND block_time BETWEEN '2025-01-01' AND '2025-01-31'

Assinaturas de transações e endereços são armazenados usando o formato de dados FixedString(N), que armazena exatamente N bytes. O ClickHouse comprime automaticamente os dados, o que reduz os custos de armazenamento em 10-20x e melhora o desempenho da consulta. Para otimizar o desempenho das consultas, use Visualizações Materializadas para pré-computar agregações comuns. Por exemplo, você poderia pré-calcular o volume de transferência diário de tokens para ser usado por gráficos relacionados a volume em um painel de controle.

Opção 3: Data Lakes

Data lakes são ideais para armazenar quantidades massivas de dados brutos e processados de blockchain para arquivamento de longo prazo e consultas analíticas. Uma implementação simples usa o formato de dados Parquet com Amazon Athena. Parquet é um formato de arquivo de dados orientado a colunas projetado para armazenamento e recuperação de dados eficientes. Amazon Athena é um serviço de consulta interativa que permite analisar dados armazenados no Amazon S3 usando SQL padrão sem a necessidade de configurar infraestrutura ou carregar dados em um banco de dados separado.

Data lakes são recomendados apenas se você precisa consultar grandes quantidades de dados não estruturados. Para a maioria dos casos de uso, recomendamos usar um banco de dados SQL (Opção 1).

Exemplo de implementação:

Queremos criar um arquivo de transferências de tokens e consultá-los. Primeiro, precisamos armazená-los no S3: Crie um bucket chamado solana_index e particione seus dados de transferência de tokens por tempo usando esta estrutura de chave:

s3://solana_index/token_transfers/YYYY/MM/DD/part-00000.parquet

As transferências diárias são armazenadas em um arquivo Parquet separado na pasta de data correspondente. À medida que você processa transferências do Solana, transforme-as no formato Parquet e grave-as no objeto S3 correspondente. Depois, você cria uma tabela no Athena e conecta ao bucket. Isso permite que você execute consultas como esta diretamente nos dados no bucket:

SELECT block_time, signature, source_address, destination_address, amount
FROM token_transfers
WHERE token_mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' AND block_time BETWEEN TIMESTAMP '2025-01-01 00:00:00' AND TIMESTAMP '2025-01-31 23:59:59';

Use Frameworks de Indexação

Use Carbon e frameworks semelhantes para evitar escrever código repetitivo e configurar seu indexador em horas, em vez de dias.

Principais características:

Decodificadores pré-construídos para programas populares (programa de Token, protocolos DeFi, Metaplex)
Fontes de dados configuráveis (RPC, LaserStream, WebSockets Aprimorados)
Suporte integrado tanto para preenchimento quanto para streaming em tempo real
Saídas para vários backends de armazenamento (Postgres vem pronto para uso)
Totalmente personalizável: você pode configurar suas próprias fontes de dados, decodificadores e sumidouros de dados.

Passo 3: Mantenha seu índice atualizado

Após preencher dados históricos, você precisa de uma solução de streaming em tempo real para manter seu índice atualizado com a nova atividade do blockchain. Sem isso, seu índice se torna obsoleto.

Método 1: LaserStream (recomendado)

Recomendamos LaserStream gRPC como sua escolha padrão para todos os casos de uso de indexação em produção. É construído especificamente para streaming de dados confiável, com ultrabaixa latência e tolerância a falhas. Alguns benefícios de usar o LaserStream incluem:

Repetição histórica de 24 horas: se seu indexador se desconectar, o LaserStream reproduz automaticamente todas as transações perdidas de onde você parou
Reconexão automática: nossos SDKs LaserStream (Rust, Go, JS/TS) lidam perfeitamente com interrupções de rede para você
Falha de nó: sua conexão LaserStream agrega dados de vários nós simultaneamente, garantindo o máximo de uptime

Combinando velocidade e confiabilidade, o LaserStream é ideal para aplicações em tempo real como feeds de transação ao vivo, painéis de negociação e atualizações instantâneas de saldo.

Como Usar o LaserStream para Indexação

Use o método subscribe para se inscrever em eventos do blockchain. Aqui estão algumas práticas recomendadas:

Aperte seu filtro o máximo possível: Inscreva-se apenas nos dados que você realmente precisa indexar para minimizar o consumo de largura de banda e o processamento necessário.
Use o nível de compromisso confirmed: Isso equilibra latência e finalização. O nível processed pode ser muito pouco confiável, enquanto finalized adiciona ~13 segundos de latência
Defina failed: false a menos que você especificamente precise rastrear transações falhas
Exclua transações de voto (vote: false), pois não são relevantes para indexação

Vamos ver um exemplo. Use a seguinte assinatura para indexar todas as novas transferências de tokens:

{
  transactions: {
    "transfers": {
      vote: false,
      failed: false,
      accountsInclude: [
        '​​TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
        'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'
      ]
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {},
  slots: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  accountsDataSlice: []
}

Método 2: Use LaserStream WebSocket

LaserStream WebSocket — a variante WebSocket do LaserStream, incluindo a extensão transactionSubscribe específica do Helius — é executada na mesma infraestrutura que o LaserStream gRPC e é uma alternativa de streaming em tempo real econômica quando você não precisa de gRPC. Você deve usar LaserStream WebSocket quando:

Sua aplicação pode tolerar lacunas ocasionais de dados
Atualizações em tempo real são importantes, mas não críticas
Você tem infraestrutura existente para detectar e preencher dados ausentes
Restrições de orçamento são significativas e você precisa minimizar os custos de streaming
Você está prototipando ou testando antes de se comprometer com LaserStream

No entanto, há alguns trade-offs a considerar ao escolher WebSockets:

Velocidade: O LaserStream WebSocket é executado na mesma infraestrutura que o LaserStream gRPC, mas o protocolo WebSocket adiciona framing JSON e sobrecarga por mensagem — para a menor latência possível nos mesmos dados, use LaserStream gRPC
Confiabilidade: Sem garantia de repetição histórica. Se o seu WebSocket se desconectar, você precisará detectar e preencher manualmente as lacunas usando métodos RPC
Complexidade: Requer infraestrutura adicional de monitoramento para garantir a completude dos dados

Como Usar WebSockets para Indexação

Para atualizar um índice que armazena todas as transferências de tokens, você se inscreveria em transactionSubscribe assim:

{
  jsonrpc: '2.0',
  id: 1,
  method: 'transactionSubscribe',
  params: [
    {
      failed: false,
      accountInclude: [
        '​​TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
        'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'
      ]
    },
    {
      commitment: 'confirmed',
      encoding: 'jsonParsed',
      transactionDetails: 'full',
      maxSupportedTransactionVersion: 0
    }
  ]
}

Comece agora

Construir um índice Solana robusto e preencher dados requer resolver três desafios principais:

Buscar dados históricos de maneira eficiente
Transformar e armazenar dados para recuperações rápidas
Manter os dados Solana indexados atualizados em tempo real

Com nosso novo sistema arquival de ponta, chamadas arquivais como getTransactionsForAddress e soluções de streaming de dados líderes da indústria como LaserStream, construir um índice Solana é mais fácil e mais prático do que nunca.

Opções complementares

Executar seu próprio índice dá a você controle total, mas nem sempre é necessário. Para necessidades comuns, uma API gerenciada Helius pode substituir ou complementar um índice personalizado:

DAS API — consulte NFTs, tokens fungíveis e ativos compactados (metadados, propriedade, saldos, por proprietário/coleção/criador) sem indexar dados de ativos você mesmo.
Wallet API — endpoints REST de alto nível para saldos de carteiras, histórico, transferências e identidade, com valores em USD e formato de resposta mais simples.

Muitas equipes usam isso para dados de portfólio, tokens e carteiras, e reservam um índice personalizado para dados específicos que as APIs gerenciadas não cobrem.

Próximos passos

Registre-se para uma conta gratuita Helius para obter acesso à API
Leia o guia getTransactionsForAddress para preenchimento
Explore a visão geral do LaserStream para streaming em tempo real
Revise a visão geral dos dados históricos para todos os métodos arquivais

​Visão Geral

​Quando usar isso

​O que significa indexar dados Solana?

​Por que a maioria das empresas constrói índices Solana?

​Exemplo de Carteira

​Exemplo de Negociação

​Exemplo de Filtragem

​Exemplo de PnL

​Passo 1: Obter os dados históricos

​Método 1: getTransactionsForAddress (recomendado)

​Etapas para usar este método

​Benefícios de usar getTransactionsForAddress

​Método 2: getSignaturesForAddress e getTransaction

​Etapas para usar este método

​Desvantagens deste método

​Método 3: Usar getBlock

​Etapas para usar este método

​Passo 2: Sincronizar dados Solana com seu banco de dados

​Opção 1: Bancos de Dados SQL

​Exemplo de implementação:

​Opção 2: Bancos de Dados Columnar

​Exemplo de implementação:

​Opção 3: Data Lakes

​Exemplo de implementação:

​Use Frameworks de Indexação

​Principais características:

​Passo 3: Mantenha seu índice atualizado

​Método 1: LaserStream (recomendado)

​Como Usar o LaserStream para Indexação

​Método 2: Use LaserStream WebSocket

​Como Usar WebSockets para Indexação

​Comece agora

​Opções complementares

​Próximos passos

Visão Geral

Quando usar isso

O que significa indexar dados Solana?

Por que a maioria das empresas constrói índices Solana?

Exemplo de Carteira

Exemplo de Negociação

Exemplo de Filtragem

Exemplo de PnL

Passo 1: Obter os dados históricos

Método 1: getTransactionsForAddress (recomendado)

Etapas para usar este método

Benefícios de usar getTransactionsForAddress

Método 2: getSignaturesForAddress e getTransaction

Etapas para usar este método

Desvantagens deste método

Método 3: Usar getBlock

Etapas para usar este método

Passo 2: Sincronizar dados Solana com seu banco de dados

Opção 1: Bancos de Dados SQL

Exemplo de implementação:

Opção 2: Bancos de Dados Columnar

Exemplo de implementação:

Opção 3: Data Lakes

Exemplo de implementação:

Use Frameworks de Indexação

Principais características:

Passo 3: Mantenha seu índice atualizado

Método 1: LaserStream (recomendado)

Como Usar o LaserStream para Indexação

Método 2: Use LaserStream WebSocket

Como Usar WebSockets para Indexação

Comece agora

Opções complementares

Próximos passos