Skip to main content

Visão Geral

O LaserStream suporta filtragem de contas comprimidas via filtros cuckoo. Em vez de enviar uma lista explícita de pubkey em sua solicitação de inscrição (32 bytes por conta), você envia um filtro probabilístico compacto que custa aproximadamente 3–4 bytes por conta na rede. Isso torna viável assinar centenas de milhares de contas em um único stream — sem fragmentação entre conexões, sem solicitações de inscrição grandes demais. Por exemplo, um filtro que rastreia 500.000 contas serializa para cerca de 2,1 MB, em comparação com 16 MB como uma lista de pubkey bruta — aproximadamente 7,6x menor. A economia exata depende de quão cheio está o filtro: quanto mais próximo da capacidade, menos bytes por conta.

Disponibilidade

Quando usar filtros cuckoo

Casos de uso típicos: monitorar cada titular de um token, rastrear todas as posições em um protocolo de empréstimo ou observar grandes conjuntos de carteiras para um sistema de negociação ou análise.

Como funciona

  1. Construa o filtro no lado do cliente. Insira cada pubkey rastreada em um CompressedAccountFilterSet. A semente de hash é randomizada por filtro e serializada junto com ele, para que o servidor faça hash das contas recebidas com a mesma semente que seu cliente usou.
  2. Anexe-o à sua solicitação de inscrição. insert_into_subscribe_request() coloca o filtro serializado no stream de contas de um SubscribeRequest padrão.
  3. O servidor faz a correspondência probabilística. Como o filtro é probabilístico, o servidor pode entregar atualizações para contas que você não rastreou — falsos positivos são limitados a menos de 1% sob carga total. Nunca há falsos negativos: toda atualização para uma conta rastreada é entregue.
  4. Verifique novamente cada atualização localmente — este passo é necessário. Chame set.contains(pubkey) em cada conta recebida antes de processá-la. Esta verificação é exata (suportada por um conjunto de hash interno), então após o filtro local você não vê falsos positivos.

Início Rápido (Rust)

Adicione o SDK ao seu projeto:
Cargo.toml
Construa um filtro, anexe-o a uma assinatura e elimine falsos positivos localmente:
main.rs
Uma versão completa executável acompanha o SDK: rust/examples/cuckoo_account_filter.rs.

Início Rápido (JavaScript/TypeScript)

Instale o SDK (suporte a cuckoo requer helius-laserstream 0.4.0+):
Construa o filtro, anexe e verifique novamente cada atualização localmente:
Uma versão completa executável acompanha o SDK: javascript/examples/cuckoo-account-sub.ts.

Referência de API

CompressedAccountFilterSet encapsula o filtro cuckoo bruto junto com um conjunto de hash exato, para que as mutações e verificações de associação sejam sempre seguras e exatas: Os nomes dos métodos acima usam convenções de Rust. O SDK JavaScript/TypeScript expõe a mesma superfície em camelCase — new CompressedAccountFilterSet(capacity) em vez de with_capacity, insertIntoSubscribeRequest, isDirty, takeDirty, toProto, e assim por diante. Em JavaScript insert retorna um booleano (true se recém-adicionado) e gera TableFullError quando o filtro está saturado. Uma pubkey pode ser passada como uma string base58, 32 bytes brutos ou qualquer objeto com um método toBytes(). Sempre use CompressedAccountFilterSet em vez do CuckooFilter bruto que ele encapsula. O remove() do filtro bruto pode remover silenciosamente o item errado — um conhecido problema documentado dos filtros cuckoo. O wrapper emparelha o filtro com um conjunto de hash exato, para que inserir, remover e contém sejam sempre corretos.

Dimensionamento de Capacidade

  • Dimensione o filtro para o número máximo de contas que você espera rastrear via with_capacity(n).
  • Inserir além da capacidade falha graciosamente com um TableFullError — o filtro nunca é corrompido. Na prática, a tabela tolera um leve excesso antes de rejeitar inserções, mas não confie nesse espaço extra.
  • O tamanho serializado é determinado pela capacidade, não pela quantidade de contas que você inseriu — então um filtro superdimensionado desperdiça bytes de rede. Escolha uma capacidade próxima ao seu pico real.

Atualizando o conjunto rastreado

Quando seu conjunto rastreado muda (novas contas a seguir, antigas a serem removidas):
  1. Chame insert() / remove() no CompressedAccountFilterSet.
  2. Verifique is_dirty() (ou consuma o sinalizador com take_dirty()) para ver se o filtro mudou desde que foi enviado pela última vez.
  3. Se estiver modificado, reconstrua a solicitação com insert_into_subscribe_request(). Em JavaScript, você pode reenvia-lo no mesmo stream com stream.write(request); em Rust, reinscreva-se com a solicitação reconstruída.

FAQ

Não. Os filtros cuckoo produzem falsos positivos (atualizações extras para contas não rastreadas), mas nunca falsos negativos. Toda atualização para uma conta rastreada é entregue.
Menos de 1% sob carga total, e geralmente menos quando o filtro está abaixo da capacidade. Uma chamada local contains() por atualização os filtra exatamente.
O SDK Rust (helius-laserstream 0.2.0+), o SDK JavaScript/TypeScript (helius-laserstream 0.4.0+), e o cliente Yellowstone Rust (yellowstone-grpc-client 13.1.0+). O SDK Go ainda não suporta. Veja a tabela de disponibilidade acima.
Sim. Os filtros padrão account: [...] funcionam inalterados e continuam sendo a escolha certa para conjuntos de contas pequenos (até cerca de 10.000 contas). Veja o guia de assinatura de contas.

Relacionados

Assinaturas de Contas

Filtragem padrão de contas com filtros de proprietário, tamanho de dados e memcmp.

Clientes & SDKs

SDKs TypeScript, Rust e Go com reprodução automática e reconexões.