메인 콘텐츠로 건너뛰기

​
목적 및 범위

이 문서는 클라이언트가 블록체인 데이터를 효율적으로 쿼리하고, 새 블록·트랜잭션·로그에 대한 실시간 알림을 받을 수 있도록 설계된 이벤트 필터링 및 구독 시스템을 설명합니다.
이 시스템은 전통적인 폴링 기반 필터와 WebSocket 기반 구독 방식을 모두 제공하여, 다양한 클라이언트 환경과 사용 패턴을 지원합니다. 일반 RPC API 구조 및 네임스페이스에 대한 정보는 API 서비스 및 네임스페이스을 참조하세요.

​
개요

필터링 및 구독 시스템을 통해 클라이언트는 다음 기능을 사용할 수 있습니다:
  • 특정 조건(컨트랙트 주소, 토픽, 블록 범위)에 일치하는 과거 로그 조회
  • 새 블록, pending 트랜잭션, 로그에 대한 실시간 이벤트 수신
  • 대규모 블록 범위 검색 시 Bloom 필터를 활용한 효율적인 로그 매칭
  • 필터 ID를 이용한 변경 사항 폴링 방식 지원
  • WebSocket을 통한 서버 푸시 기반 구독 지원
구현은 주로 eth/filters 패키지에 위치하며, 블록체인의 이벤트 피드 시스템과 밀접하게 통합됩니다.

​
필터 API 메서드

FilterAPI는 필터 생성, 조회, 제거를 위한 RPC 엔드포인트를 제공합니다.
이 API는 폴링 기반 필터와 WebSocket 구독 방식을 모두 지원합니다.

​
핵심 RPC 메서드

MethodDescriptionReturn Type
eth_newFilter조건 기반 로그 필터 생성Filter ID
eth_newBlockFilter새 블록 해시 필터 생성Filter ID
eth_newPendingTransactionFilterpending 트랜잭션 필터 생성Filter ID
eth_getFilterChanges마지막 호출 이후 변경 사항 조회Logs / Hashes
eth_getFilterLogs필터 조건에 맞는 전체 로그 조회Logs array
eth_getLogs단발성 로그 조회Logs array
eth_uninstallFilter필터 제거Boolean

​
구독 메서드(WebSocket)

MethodDescriptionEvent Type
eth_subscribe("newHeads")새 블록 헤더 구독Header
eth_subscribe("logs", criteria)조건 기반 로그 구독Log
eth_subscribe("newPendingTransactions")pending 트랜잭션 구독Tx hash / object
eth_unsubscribe구독 해지Boolean

​
시스템 아키텍처

​
구성 요소 개요

이벤트 필터링 시스템은 크게 FilterSystem과 EventSystem으로 구성됩니다.

​
FilterSystem

FilterSystem은 모든 필터 인스턴스가 공유하는 리소스를 관리하며, 필터 생성의 진입점 역할을 합니다. 주요 필드:
  • backend Backend – 블록체인 데이터 접근 인터페이스
  • logsCache *lru.Cache[common.Hash, *logCacheElem] – 최근 블록 로그 캐시
  • cfg *Config – 캐시 크기 및 타임아웃 설정
로그 캐시는 최근 접근한 블록의 로그를 저장하여, 반복적인 데이터베이스 접근을 줄이고 응답 지연을 최소화합니다.

​
EventSystem

EventSystem은 활성화된 모든 구독을 관리하고, 블록체인 이벤트를 적절한 구독자로 전달하는 중앙 이벤트 디스패처입니다.
여러 이벤트 피드에서 이벤트를 수신한 뒤, 구독 조건에 따라 필터링하여 전달합니다.

​
필터 타입 및 실행

​
로그 필터

로그 필터는 지정된 블록 범위 또는 특정 블록 내에서 조건과 일치하는 로그 이벤트를 검색합니다. FilterCriteria 구조:
FieldTypeDescription
FromBlock*big.Int시작 블록(nil이면 latest)
ToBlock*big.Int종료 블록(nil이면 latest)
BlockHash*common.Hash단일 블록 지정
Addresses[]common.Address컨트랙트 주소 목록
Topics[][]common.Hash토픽 필터
토픽 매칭 규칙:
  • 각 위치는 OR 조건으로 여러 토픽을 가질 수 있습니다
  • 위치가 nil이면 해당 위치는 무조건 매칭됩니다
  • 위치 간에는 AND 조건이 적용됩니다
  • 최대 4개의 토픽 위치를 지원합니다

​
Bloom 필터 최적화

대규모 로그 검색 시 성능을 개선하기 위해 2단계 Bloom 필터링을 사용합니다.
  1. 블록 헤더 Bloom – 각 블록 헤더에 포함된 2048비트 Bloom
  2. 섹션 Bloom 인덱스 – 블록을 섹션 단위로 묶어 비트 단위 검색 지원
Bloom 필터 알고리즘 개요: 
Hash = Keccak256(data)
For i in [0, 2, 4]:
  BitIndex  = (Uint16(Hash[i:i+2]) & 0x7FF) >> 3
  BitOffset = Hash[i+1] & 0x7
  Bloom[BitIndex] |= (1 << BitOffset)

​
구독 라이프사이클

​
폴링 기반 필터

WebSocket을 사용할 수 없는 환경에서는 서버가 필터 상태를 유지하고, 클라이언트는 주기적으로 변경 사항을 폴링합니다. 필터 타임아웃 관리:
  • 기본 타임아웃은 5분입니다
  • eth_getFilterChanges 호출 시 타이머가 갱신됩니다
  • 일정 시간 활동이 없으면 필터는 자동으로 제거됩니다
이는 장기간 방치된 필터로 인한 리소스 누수를 방지하기 위한 장치입니다.

​
이벤트 전달 및 필터링

​
체인 재구성 처리

체인 재구성이 발생하면 시스템은 RemovedLogsEvent를 생성하여 구독자에게 전달합니다. 처리 흐름은 다음과 같습니다:
  1. 블록 삽입 중 체인 재구성 감지
  2. 제거된 블록의 로그와 함께 이벤트 생성
  3. 로그 객체에 Removed: true 플래그 설정
  4. 클라이언트는 해당 로그를 기반으로 상태를 조정

​
백엔드와의 통합

필터 시스템은 Backend 인터페이스를 통해 블록체인 데이터 접근을 추상화합니다.
이를 통해 전체 노드 구현에 종속되지 않고 동일한 필터 로직을 재사용할 수 있습니다. 주요 백엔드 구현체는 다음 구성 요소에 위임합니다:
  • 과거 블록 데이터 – BlockChain
  • pending 트랜잭션 – TxPool
  • pending 블록 구성 – Miner
  • Bloom 비트 검색 – BloomIndexer

​
오류 처리 및 엣지 케이스

ErrorCauseHandling
errInvalidBlockRange시작 블록이 종료 블록보다 큼필터 생성 거부
errFilterNotFound존재하지 않는 필터 ID빈 결과 반환
errExceedMaxTopics토픽 위치 초과필터 생성 거부
unknown block블록 해시 없음오류 반환
Context cancel연결 종료쿼리 중단
이와 같은 오류 처리 로직을 통해 시스템은 안정적인 이벤트 전달을 보장합니다.