Skip to main content
Ao desenvolver aplicativos que precisam responder a alterações on-chain, sondar endpoints RPC para atualizações de conta é ineficiente e lento. As inscrições de contas resolvem isso fornecendo atualizações em tempo real sobre alterações de estado de conta diretamente para o seu aplicativo. Este guia cobre tudo o que você precisa saber sobre inscrições de contas: o que são, como funcionam e como otimizá-las para seu caso de uso específico.

Contexto do modelo de conta

Pule esta seção se você estiver familiarizado com contas Solana e sua estrutura.
Solana usa um modelo baseado em contas onde cada pedaço de dados vive em uma conta - um contêiner que armazena tanto dados quanto metadados. Cada conta possui:
  • Dados: Os bytes reais que armazenam o estado do programa, saldos de tokens ou outras informações
  • Proprietário: O programa que controla essa conta e pode modificar seus dados
  • Lamports: O saldo SOL da conta para isenção de aluguel
  • Executável: Se essa conta contém código de programa
Programas são sem estado - eles não armazenam dados internamente. Em vez disso, criam e gerenciam contas separadas para armazenar seu estado. Quando você interage com um programa, você passa as contas das quais ele deve ler ou para as quais deve escrever. Este design torna as inscrições de contas poderosas: você pode observar alterações em contas específicas, todas as contas pertencentes a um programa ou contas que correspondem a certos critérios.

Assinatura básica de conta

Vamos começar com um exemplo simples que assina alterações em contas de tokens. Este script notificará você sempre que os saldos de tokens mudarem:
Quando você executa essa assinatura básica, verá atualizações de conta em tempo real no seu console:
O que acabou de acontecer? Nossa assinatura funcionou perfeitamente! Pedimos ao Laserstream para nos notificar sobre alterações em contas de tokens, e ele forneceu uma atualização sobre a conta BKMHWYLAX4un3HUbR7a3u9jPmzCiLNa4mSj1RiX11eWF. Esta conta possui:
  • 2.039.280 lamports (~0,002 SOL de saldo - esta é a quantia isenta de aluguel para esta conta de token)
  • Programa proprietário TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA (este é o programa SPL Token)
  • Assinatura de transação 5C9Hr5nG2j8eQz6inxPmfyjbYdmXddzUDyR1iQgEnjYQ3RNvuP4Zzc8t1enLNy7Rk8KNCtQPEQztENYWxkt9GaVD mostrando qual transação específica causou essa mudança de conta
  • Slot 352366983 indicando quando essa atualização ocorreu na blockchain
  • Campo de dados contendo 165 bytes de dados de conta codificados como base58

Compreendendo a filtragem de contas com datasize

O campo de dados é crucial - ele contém a estrutura real da conta de token. Vamos usar esse entendimento para filtragem inteligente de contas.

Por que usar filtragem por datasize?

Para entender por que precisamos de filtragem, primeiro vamos entender o que são realmente as contas de token. Para cada token que uma carteira possui, há uma conta separada on-chain. Se sua carteira possui 3 tokens diferentes (USDC, BONK e SOL), você na verdade tem 1 conta de carteira (sua conta principal de SOL) mais 3 contas de token (uma para cada tipo de token). Cada conta de token tem exatamente 165 bytes e armazena: qual token ela contém (endereço de mint), quem a possui (endereço da sua carteira) e quanto desse token ela contém (quantidade). O Programa de Token possui milhões de contas na Solana, mas nem todas são o que consideramos “contas de token” com saldos de usuário. Aqui está o que acontece com e sem filtragem: Sem filtragem - A inundação:
Isso se inscreve em TODAS as contas pertencentes ao Programa de Token, o que inclui:
  • Contas de token (165 bytes) - Saldos de usuários: milhões de contas
  • Contas de mint (82 bytes) - Definições de tokens: centenas de milhares de contas
  • Contas multisig (355 bytes) - Controles de carteiras compartilhadas: dezenas de milhares de contas
  • Contas do Programa de Token Associado (vários tamanhos) - milhões de contas
Resultado: Seu aplicativo recebe milhões de atualizações de conta constantemente, a maioria das quais você não se importa.
Com filtragem inteligente - Precisão cirúrgica:
Isso filtra apenas as contas de 165 bytes, que são especificamente as contas de saldo de token de usuário - exatamente o que você quer para acompanhar transferências de tokens, mudanças de saldo e atualizações de portfólio. A diferença:
  • Sem filtragem: Milhões de atualizações de contas (criações de mint, mudanças multisig, etc.)
  • Com filtragem por datasize: Apenas mudanças de saldo de token
Isso é uma redução significativa no ruído, focando apenas nas contas que realmente representam posses de tokens de usuário.

De onde vêm os 165 bytes?

Isso não é mágica - vem da estrutura de conta do programa SPL Token. Olhando para o código-fonte, podemos ver que a struct Account define exatamente 165 bytes:
Esse tamanho fixo nos permite filtrar precisamente por contas de token padrão e excluir:
  • Contas de mint (82 bytes)
  • Contas multisig (355 bytes)
  • Contas de programa de token associado
  • Outras contas relacionadas a tokens com tamanhos diferentes
Para calcular os tamanhos de conta em outros programas, confira a Referência de Espaço do Anchor - ela mostra quanto espaço diferentes tipos de dados ocupam (Pubkey = 32 bytes, u64 = 8 bytes, etc.).

Decodificando a estrutura da conta

Agora que entendemos por que filtramos por 165 bytes, vamos decodificar o que há dentro da nossa conta de exemplo:
Os 165 bytes dividem-se em:
  • Bytes 0-31: Endereço de mint (qual token esta conta contém)
  • Bytes 32-63: Endereço do proprietário (quem possui esta conta de token)
  • Bytes 64-71: Quantidade de tokens (quantos tokens estão na conta)
  • Bytes 72-164: Metadados adicionais (delegado, estado, autoridade de fechamento, etc.)
Essa abordagem estruturada nos dá precisão cirúrgica: recebemos apenas atualizações para contas de token padrão, não o ruído de outros tipos de conta.

Combinando filtros: datasize + memcmp para precisão laser

Agora que sabemos que o endereço de mint está nos bytes 0-31, podemos ser ainda mais específicos. Digamos que queremos monitorar apenas contas de token USDC. Podemos combinar nosso filtro datasize com um filtro memcmp para direcionar o endereço de mint exato:
Estratégia de filtragem progressiva:
  1. Filtro de proprietário: “Dê-me contas pertencentes ao Programa de Token” (milhões de contas)
  2. Filtro de datasize: “Mas apenas contas de token padrão de 165 bytes” (centenas de milhares)
  3. Filtro de memcmp: “E apenas aquelas que contém USDC” (milhares)
Essa progressão do amplo ao específico é a chave para o monitoramento eficiente de contas. Cada filtro reduz o conjunto de resultados, para que você receba apenas as atualizações exatas que lhe interessam. Importante: Todos os filtros usam lógica AND - todas as condições devem ser atendidas para que uma atualização de conta seja acionada.

Lendo atualizações de conta USDC: Quem, Quanto, Onde?

Agora vamos ver o que essas atualizações filtradas realmente contêm. Vamos criar um monitor específico para USDC que responde às perguntas-chave quando uma conta de token muda:
  • Quem possui esta conta de token?
  • Quanto USDC ela contém agora?
  • Onde (qual conta específica) mudou?
  • Quando essa mudança aconteceu?
  • Que transação causou a mudança?
As atualizações brutas de conta contêm dados binários que precisamos decodificar. Como Solana usa codificação base58 para endereços e assinaturas, usamos a função bs58.encode() para converter objetos Buffer binários em strings legíveis.
Quando você executa este monitor USDC, verá uma saída limpa e estruturada como esta:
Cada bloco representa uma conta USDC que mudou de estado. A primeira conta agora possui 1.500 USDC, enquanto a segunda conta foi esvaziada para 0 USDC. Você obtém o saldo atual imediatamente após cada transação, junto com qual conta específica mudou e quando. As inscrições de conta mostram o resultado final do que aconteceu com cada conta, não os detalhes da transação. Se você precisar entender o contexto completo da transação (quem enviou para quem, taxas, etc.), precisaria buscar a transação completa usando a assinatura mostrada.

Referência completa de filtragem

Além dos filtros básicos owner, datasize e memcmp que usamos, as inscrições de conta suportam opções de filtragem adicionais para restringir ainda mais seus resultados:

Filtragem de contas específicas

Monitore contas exatas por suas chaves públicas:
Esta abordagem funciona bem quando você sabe exatamente quais contas são importantes para seu aplicativo - como monitorar as contas do tesouro de seu aplicativo ou contas específicas de usuários. Para conjuntos de contas muito grandes, listas explícitas de pubkey se tornam caras — 32 bytes por conta no pedido de inscrição. Para mais de ~10.000 contas, use um filtro cuckoo comprimido (~3–4 bytes por conta) para rastrear centenas de milhares de contas em um único stream. Disponível nos SDKs Rust e JavaScript.

Estratégias de filtragem combinadas

O poder vem da combinação de vários tipos de filtro. Aqui está o modelo mental:
  1. Lance uma rede ampla com owner - “Dê-me todas as contas geridas por este programa”
  2. Filtre por estrutura com datasize - “Mas apenas contas deste tipo específico”
  3. Mire em dados específicos com memcmp - “E apenas aquelas contendo esta informação específica”
  4. Monitore contas conhecidas com account - “Ou apenas observe estas contas exatas que me importam”
Por exemplo, monitorando contas de USDC de alto valor:
O principal insight é que cada filtro reduz o volume de atualizações que você recebe. Sem filtragem, você pode receber quantidades esmagadoras de atualizações de conta. Com filtragem inteligente, você recebe apenas as atualizações que importam para seu caso de uso específico.

Compreendendo o quadro geral

Pense nas inscrições de contas como assistir a um feed ao vivo de alterações de banco de dados. O estado da Solana é essencialmente um enorme armazenamento de chave-valor onde cada conta é uma entrada. Quando programas são executados, eles modificam essas contas. Sua inscrição permite que você veja entradas específicas mudando em tempo real. O sistema de filtragem funciona como índices de banco de dados - você não está apenas assistindo “todas as mudanças”, mas sim “mudanças nas contas que correspondem a esses critérios”. Isso torna possível construir aplicativos responsivos que reagem imediatamente a eventos on-chain relevantes sem sobrecarregar seu sistema com dados irrelevantes.

Aplicando este padrão a outros programas

A abordagem que aprendemos funciona para qualquer programa Solana. Aqui está o padrão geral:
  1. Pesquise a estrutura da conta - Verifique o código-fonte ou a documentação do programa
  2. Comece com filtragem de proprietário - Direcione o programa que gerencia as contas
  3. Aplique filtros estruturais - Use tamanho da conta, padrões de dados ou outras características para reduzir a tipos específicos de conta
  4. Adicione filtros direcionados - Foque em contas específicas, estados ou valores de dados que importam para seu aplicativo