> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 이벤트 필터링 및 구독

## 목적 및 범위

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

일반 RPC API 구조 및 네임스페이스에 대한 정보는 [API 서비스 및 네임스페이스](/ko/rpc-and-apis/8.1-api-services-and-namespaces)을 참조하세요.

## 개요

필터링 및 구독 시스템을 통해 클라이언트는 다음 기능을 사용할 수 있습니다:

* 특정 조건(컨트랙트 주소, 토픽, 블록 범위)에 일치하는 과거 로그 조회
* 새 블록, pending 트랜잭션, 로그에 대한 실시간 이벤트 수신
* 대규모 블록 범위 검색 시 Bloom 필터를 활용한 효율적인 로그 매칭
* 필터 ID를 이용한 변경 사항 폴링 방식 지원
* WebSocket을 통한 서버 푸시 기반 구독 지원

구현은 주로 `eth/filters` 패키지에 위치하며, 블록체인의 이벤트 피드 시스템과 밀접하게 통합됩니다.

## 필터 API 메서드

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

### 핵심 RPC 메서드

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

### 구독 메서드(WebSocket)

| Method                                    | Description     | Event 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 구조:**

| Field       | Type               | Description         |
| ----------- | ------------------ | ------------------- |
| `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 필터 알고리즘 개요:**

```text theme={null}
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`

## 오류 처리 및 엣지 케이스

| Error                  | Cause            | Handling |
| ---------------------- | ---------------- | -------- |
| `errInvalidBlockRange` | 시작 블록이 종료 블록보다 큼 | 필터 생성 거부 |
| `errFilterNotFound`    | 존재하지 않는 필터 ID    | 빈 결과 반환  |
| `errExceedMaxTopics`   | 토픽 위치 초과         | 필터 생성 거부 |
| `unknown block`        | 블록 해시 없음         | 오류 반환    |
| Context cancel         | 연결 종료            | 쿼리 중단    |

이와 같은 오류 처리 로직을 통해 시스템은 안정적인 이벤트 전달을 보장합니다.