Gambaran umum
LaserStream mendukung pemfilteran akun terkompresi melalui filter cuckoo. Alih-alih mengirim daftar pubkey eksplisit dalam permintaan berlangganan Anda (32 byte per akun), Anda mengirim filter probabilistik ringkas yang hanya memerlukan sekitar 3–4 byte per akun saat ditransmisikan. Dengan demikian, Anda dapat berlangganan ke ratusan ribu akun dalam satu stream — tanpa membagi akun ke beberapa koneksi dan tanpa permintaan berlangganan berukuran terlalu besar. Sebagai contoh, filter yang melacak 500.000 akun memiliki ukuran serialisasi sekitar 2,1 MB, dibandingkan dengan 16 MB jika menggunakan daftar pubkey mentah — sekitar 7,6x lebih kecil. Penghematan sebenarnya bergantung pada tingkat keterisian filter: makin mendekati kapasitas, makin sedikit byte yang diperlukan per akun.Ketersediaan
Kapan harus menggunakan filter cuckoo
Kasus penggunaan umum meliputi pemantauan setiap pemegang token, pelacakan semua posisi dalam protokol pinjaman, atau pemantauan kumpulan dompet besar untuk sistem perdagangan atau analitik.
Cara kerjanya
- Buat filter di sisi klien. Masukkan setiap pubkey yang dilacak ke dalam
CompressedAccountFilterSet. Seed hash diacak untuk setiap filter dan diserialisasi bersamanya, sehingga server melakukan hash pada akun masuk dengan seed yang sama seperti yang digunakan klien Anda. - Lampirkan filter ke permintaan berlangganan Anda.
insert_into_subscribe_request()menempatkan filter yang telah diserialisasi ke dalam stream akun dariSubscribeRequeststandar. - Server melakukan pencocokan secara probabilistik. Karena filter bersifat probabilistik, server mungkin mengirim pembaruan untuk akun yang tidak Anda lacak — positif palsu dibatasi hingga di bawah 1% saat terisi penuh. Tidak pernah ada negatif palsu: setiap pembaruan untuk akun yang dilacak akan dikirim.
- Periksa ulang setiap pembaruan secara lokal — langkah ini wajib dilakukan. Panggil
set.contains(pubkey)pada setiap akun masuk sebelum memprosesnya. Pemeriksaan ini bersifat akurat (didukung oleh hash set internal), sehingga setelah pemfilteran lokal tidak ada positif palsu.
Mulai cepat (Rust)
Tambahkan SDK ke proyek Anda:Cargo.toml
main.rs
rust/examples/cuckoo_account_filter.rs.
Mulai cepat (JavaScript/TypeScript)
Instal SDK (dukungan cuckoo memerlukanhelius-laserstream 0.4.0+):
javascript/examples/cuckoo-account-sub.ts.
Referensi API
CompressedAccountFilterSet membungkus filter cuckoo mentah bersama hash set yang akurat, sehingga mutasi dan pemeriksaan keanggotaan selalu aman dan akurat:
Nama metode di atas menggunakan konvensi Rust. SDK JavaScript/TypeScript menyediakan antarmuka yang sama dalam camelCase —
new CompressedAccountFilterSet(capacity), bukan with_capacity, insertIntoSubscribeRequest, isDirty, takeDirty, toProto, dan seterusnya. Di JavaScript, insert mengembalikan boolean (true jika baru ditambahkan) dan melempar TableFullError ketika filter telah jenuh. Pubkey dapat diteruskan sebagai string base58, 32 byte mentah, atau objek apa pun yang memiliki metode toBytes().
Selalu gunakan CompressedAccountFilterSet, bukan CuckooFilter mentah yang dibungkusnya. remove() milik filter mentah dapat menghapus item yang salah tanpa pemberitahuan — ini merupakan kekeliruan umum pada filter cuckoo yang telah didokumentasikan. Wrapper memasangkan filter dengan hash set yang akurat, sehingga operasi penyisipan, penghapusan, dan pemeriksaan keberadaan selalu benar.
Penentuan ukuran kapasitas
- Tentukan ukuran filter berdasarkan jumlah puncak akun yang diperkirakan akan Anda lacak melalui
with_capacity(n). - Penyisipan yang melampaui kapasitas akan gagal dengan aman dan menghasilkan
TableFullError— filter tidak pernah rusak. Dalam praktiknya, tabel dapat menoleransi sedikit kelebihan muatan sebelum menolak penyisipan, tetapi jangan mengandalkan kapasitas tambahan tersebut. - Ukuran serialisasi ditentukan oleh kapasitas, bukan oleh jumlah akun yang telah Anda masukkan — jadi filter yang terlalu besar memboroskan byte saat transmisi. Pilih kapasitas yang mendekati jumlah puncak sebenarnya.
Memperbarui kumpulan yang dilacak
Saat kumpulan yang Anda lacak berubah (akun baru yang perlu diikuti atau akun lama yang perlu dihapus):- Panggil
insert()/remove()padaCompressedAccountFilterSet. - Periksa
is_dirty()(atau gunakan flag dengantake_dirty()) untuk mengetahui apakah filter telah berubah sejak terakhir dikirim. - Jika berstatus dirty, buat ulang permintaan dengan
insert_into_subscribe_request(). Di JavaScript, Anda dapat mengirimkannya kembali melalui stream yang sama denganstream.write(request); di Rust, lakukan langganan ulang dengan permintaan yang telah dibuat ulang.
FAQ
Can I miss updates for accounts in my filter?
Can I miss updates for accounts in my filter?
Tidak. Filter cuckoo menghasilkan positif palsu (pembaruan tambahan untuk akun yang tidak dilacak), tetapi tidak pernah menghasilkan negatif palsu. Setiap pembaruan untuk akun yang dilacak akan dikirim.
How many extra (false-positive) updates will I receive?
How many extra (false-positive) updates will I receive?
Di bawah 1% saat terisi penuh, dan biasanya lebih sedikit ketika filter berada di bawah kapasitas. Satu panggilan
contains() lokal per pembaruan akan memfilternya secara akurat.Which clients support cuckoo filters?
Which clients support cuckoo filters?
SDK Rust (
helius-laserstream 0.2.0+), SDK JavaScript/TypeScript (helius-laserstream 0.4.0+), dan klien Yellowstone Rust (yellowstone-grpc-client 13.1.0+) mendukung filter cuckoo. SDK Go belum mendukungnya. Lihat tabel ketersediaan di atas.Can I still use explicit pubkey lists?
Can I still use explicit pubkey lists?
Ya. Filter
account: [...] standar tetap berfungsi tanpa perubahan dan masih menjadi pilihan yang tepat untuk kumpulan akun kecil (hingga sekitar 10.000 akun). Lihat panduan langganan akun.Do compressed filters work with matchMints?
Do compressed filters work with matchMints?
Ya. Ketika filter terkompresi dilampirkan ke langganan transaksi dan
matchMints: true ditetapkan, server juga menguji mint saldo token sebelum/sesudah transaksi terhadap filter, selain kunci akunnya. Lihat Pemfilteran Mint Token.Terkait
Account Subscriptions
Pemfilteran akun standar dengan filter pemilik, ukuran data, dan memcmp.
Clients & SDKs
SDK TypeScript, Rust, dan Go dengan pemutaran ulang serta koneksi ulang otomatis.
Token Mint Filtering
Cocokkan transaksi berdasarkan mint token dengan
matchMints, termasuk di dalam filter terkompresi.