개요
LaserStream은 쿠쿠 필터를 통한 압축된 계정 필터링을 지원합니다. 구독 요청에서 명시적인 pubkey 목록(계정당 32바이트)을 보내는 대신 대략 계정당 3–4바이트의 비용이 드는 compact 확률 필터를 보냅니다. 이를 통해 단일 스트림에서 수십만 개의 계정에 가입하는 것이 실용적입니다 — 연결 간 샤딩이 없고 지나치게 큰 구독 요청도 없습니다. 예를 들어, 500,000개의 계정을 추적하는 필터는 약 2.1MB로 직렬화되며, 이는 원시 pubkey 목록의 16MB에 비해 대략 7.6배 작습니다. 정확한 절감 효과는 필터의 용량에 따라 달라지며, 용량에 가까울수록 계정당 바이트 수가 적습니다.가용성
쿠쿠 필터 사용 시기
일반적인 사용 사례: 토큰 소유자 모니터링, 대출 프로토콜의 모든 위치 추적, 거래 또는 분석 시스템을 위한 대규모 지갑 세트 감시.
작동 방식
- 클라이언트 측에서 필터를 구축하세요. 각 추적된 pubkey를
CompressedAccountFilterSet에 삽입합니다. 해시 시드는 필터마다 무작위로 설정되어 직렬화됩니다. 따라서 서버는 귀하의 클라이언트가 사용한 동일한 시드로 들어오는 계정을 해시합니다. - 구독 요청에 첨부하세요.
insert_into_subscribe_request()는 표준SubscribeRequest의 계정 스트림에 직렬화된 필터를 배치합니다. - 서버가 확률적으로 일치합니다. 필터가 확률적이기 때문에 서버는 추적하지 않은 계정에 대한 업데이트를 제공할 수 있습니다 — 오탐지가 풀 로드 시 1% 미만으로 제한됩니다. 오인식은 절대 없습니다: 추적된 계정에 대한 모든 업데이트가 전달됩니다.
- 각 업데이트를 로컬에서 다시 확인하세요 — 이 단계는 필수입니다. 처리를 하기 전에 들어오는 계정마다
set.contains(pubkey)를 호출하세요. 이 확인은 정확합니다 (내부 해시 세트로 지원됨), 따라서 로컬 필터링 후 오탐지가 없습니다.
빠른 시작 (Rust)
프로젝트에 SDK를 추가하세요:Cargo.toml
main.rs
rust/examples/cuckoo_account_filter.rs.
빠른 시작 (JavaScript/TypeScript)
SDK를 설치하세요 (쿠쿠 지원은helius-laserstream 0.4.0+ 버전 필요):
javascript/examples/cuckoo-account-sub.ts.
API 참조
CompressedAccountFilterSet는 원시 쿠쿠 필터와 정확한 해시 세트를 함께 래핑하므로 변형 및 멤버십 확인이 항상 안전하고 정확합니다:
위 메서드 이름은 Rust 관례를 사용합니다. JavaScript/TypeScript SDK는 같은 표면을 camelCase로 제공합니다 —
new CompressedAccountFilterSet(capacity) 대신 with_capacity, insertIntoSubscribeRequest, isDirty, takeDirty, toProto 등이 포함됩니다. JavaScript에서 insert는 boolean을 반환하며 (새로 추가된 경우 true), 필터가 포화 상태일 때는 TableFullError를 던집니다. pubkey는 base58 문자열, raw 32바이트 또는 toBytes() 메서드가 있는 객체로 전달할 수 있습니다.
항상 CuckooFilter을 래핑하는 CompressedAccountFilterSet를 사용하세요. 원시 필터의 remove()는 잘못된 항목을 조용히 제거할 수 있습니다 — 쿠쿠 필터의 문서화된 위험성입니다. 래퍼는 필터와 정확한 해시 세트를 결합하므로 삽입, 제거 및 포함이 항상 정확합니다.
용량 크기 조정
with_capacity(n)를 통해 추적할 것으로 예상되는 계정의 최대 수에 맞춰 필터의 크기를 조정하세요.- 용량을 초과하는 삽입은
TableFullError로 우아하게 실패하며 필터가 손상되지 않습니다. 실제로 테이블은 튕겨나기 전에 약간의 초과 채움을 허용하지만, 그 여유 공간에 의존하지 마세요. - 직렬화 크기는 얼마나 많은 계정을 삽입했는가가 아니라 용량에 의해 결정됩니다 — 따라서 과대 용량의 필터는 전송 바이트를 낭비합니다. 실제 최고치에 가까운 용량을 선택하세요.
추적 집합 업데이트
추적 집합이 변경될 때 (새 계정을 팔로우, 이전 계정을 삭제):CompressedAccountFilterSet에서insert()/remove()를 호출하세요.- 마지막으로 보낸 이후 필터가 변경되었는지 확인하려면
is_dirty()(또는take_dirty()로 플래그를 소모)를 확인하세요. - 더러워진 경우
insert_into_subscribe_request()로 요청을 다시 작성하세요. JavaScript에서는stream.write(request)로 동일한 스트림에서 다시 보낼 수 있고, Rust에서는 다시 작성된 요청으로 다시 구독할 수 있습니다.
FAQ
내 필터에 있는 계정의 업데이트를 놓칠 수 있나요?
내 필터에 있는 계정의 업데이트를 놓칠 수 있나요?
아니요. 쿠쿠 필터는 false positives (추적되지 않은 계정에 대한 추가 업데이트)를 생성하지만 false negatives는 절대 없습니다. 추적된 계정에 대한 모든 업데이트가 전달됩니다.
얼마나 많은 추가 (오탐) 업데이트를 받을까요?
얼마나 많은 추가 (오탐) 업데이트를 받을까요?
풀 로드 시 1% 미만이며, 필터가 용량보다 작을 때는 일반적으로 더 적습니다. 로컬
contains() 호출 한 번으로 이들을 정확하게 필터링합니다.어떤 클라이언트가 쿠쿠 필터를 지원하나요?
어떤 클라이언트가 쿠쿠 필터를 지원하나요?
Rust SDK (
helius-laserstream 0.2.0+), JavaScript/TypeScript SDK (helius-laserstream 0.4.0+), 그리고 Yellowstone Rust 클라이언트 (yellowstone-grpc-client 13.1.0+). Go SDK는 아직 지원되지 않습니다. 위의 가용성 표를 참조하세요.명시적인 pubkey 목록을 여전히 사용할 수 있나요?
명시적인 pubkey 목록을 여전히 사용할 수 있나요?
네. 표준
account: [...] 필터는 변경되지 않으며 작은 계정 집합(약 10,000개 계정까지)에는 여전히 적합한 선택입니다. 계정 구독 가이드를 참조하세요.관련 항목
계정 구독
소유자, 데이터 크기 및 memcmp 필터를 사용한 표준 계정 필터링.
클라이언트 및 SDK
자동 재생 및 다시 연결 기능을 갖춘 TypeScript, Rust 및 Go SDK.