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
- 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. - Anexe-o à sua solicitação de inscrição.
insert_into_subscribe_request()coloca o filtro serializado no stream de contas de umSubscribeRequestpadrão. - 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.
- 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
main.rs
rust/examples/cuckoo_account_filter.rs.
Início Rápido (JavaScript/TypeScript)
Instale o SDK (suporte a cuckoo requerhelius-laserstream 0.4.0+):
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):- Chame
insert()/remove()noCompressedAccountFilterSet. - Verifique
is_dirty()(ou consuma o sinalizador comtake_dirty()) para ver se o filtro mudou desde que foi enviado pela última vez. - Se estiver modificado, reconstrua a solicitação com
insert_into_subscribe_request(). Em JavaScript, você pode reenvia-lo no mesmo stream comstream.write(request); em Rust, reinscreva-se com a solicitação reconstruída.
FAQ
Posso perder atualizações para contas no meu filtro?
Posso perder atualizações para contas no meu filtro?
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.
Quantas atualizações extras (falsos positivos) receberei?
Quantas atualizações extras (falsos positivos) receberei?
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.Quais clientes suportam filtros cuckoo?
Quais clientes suportam filtros cuckoo?
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.Posso ainda usar listas explícitas de pubkey?
Posso ainda usar listas explícitas de pubkey?
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.