블록체인 인덱서는 체인의 트랜잭션과 이벤트를 모아 도메인 모델로 바꾸고, 조회하기 좋은 DB에 쌓아 API로 내주는 오프체인 계층이다. 블록체인은 쓰기 무결성에는 강하지만 읽기 질의에는 불리해서 이 계층이 필요하다. 구조는 ETL 파이프라인이고, 설계의 중심은 처리 속도보다 다시 돌려도 같은 결과가 나오는 안정성이다.

핵심

  • “내 NFT 목록” 같은 질의를 체인 원본만으로 처리하면 전체 이력을 훑어야 한다. RPC 노드는 상태 조회와 트랜잭션 전송, 인덱서는 이력, 집계, 검색을 맡고, 대부분의 서비스는 둘 다 필요하다. 최소 구조는 Node Stream -> Parser -> DB -> API이고, Parser 품질이 곧 데이터 품질이다. 인덱서는 API에 밀리초 단위 읽기를 내주는, 프로덕션 데이터 제품의 기본 구성요소다.
  • 인덱서는 ETL이다. Extract는 주로 gRPC 스트리밍으로 시작 버전, 재연결, 백프레셔를 다루고, Transform은 관심 이벤트만 걸러 스키마 버전별로 파싱하되 실패를 격리하고, Load는 청크 분할과 트랜잭션 경계로 배치 적재한다. 운영에서는 마지막 처리 버전, 단계별 지연과 실패율, 파싱 실패 payload 샘플을 남기고, 범위 재처리(range replay) 복구 모드를 둔다.
  • DB는 이력 테이블과 스냅샷 테이블을 함께 쓴다. 이벤트마다 이력은 INSERT, 스냅샷은 버전 조건을 건 UPSERT로 갱신해 역전 업데이트를 막는다. 대규모 집계는 이력에서, 사용자 조회는 스냅샷에서 처리한다. PK는 이벤트 식별자와 버전으로 고정하고, 스냅샷 갱신에는 WHERE last_version < incoming_version을 건다. 인덱스는 이력 쪽이 시간, 주체 주소, 버전 중심이고 스냅샷 쪽이 소유자와 상태 같은 현재 조회 키 중심이다. 목표는 정규화가 아니라 질문 유형별 최적화다.
  • Rust SDK는 파이프라인 오케스트레이터, 도메인 핸들러 Trait, 채널로 이은 step, 설정과 헬스와 복구 인프라로 이뤄진다. 핸들러는 Some이면 다음 단계로 넘기고 None이면 버리며, 채널 연결로 단계별 병렬화와 백프레셔 전파와 장애 격리를 얻는다. SDK를 두는 이유는 인덱서마다 반복되는 gRPC 재연결, 버전 추적, 배치 저장 코드를 공통화하기 위해서다. 핸들러 인터페이스는 process(context) -> Result<Option<context>> 꼴이다. 시작 버전 결정 로직을 표준화하고, 재시작 때 정확히 이어받으며, 단계별 처리량·지연·실패율을 재고, 도메인 핸들러는 순수 로직에 집중시킨다. 좋은 SDK는 실패했을 때 예측 가능하게 동작한다.
  • Diesel로 대량 쓰기를 할 때는 PostgreSQL 파라미터 상한에 맞춰 청크를 나누고, 배치 INSERT로 왕복을 줄이고, ON CONFLICT DO UPDATE에 버전 비교를 넣고, 이력 INSERT와 스냅샷 UPSERT를 한 트랜잭션으로 묶는다. Diesel을 고른 이유는 컴파일 타임 타입 검증과 강한 Upsert 표현력이다. 청크 크기는 컬럼 수로 계산하고, 풀 크기는 DB 한계와 워크로드로 조정하며, 청크 실패 재시도는 멱등성이 보장될 때만 하고, 느린 쿼리는 SQL 로그와 실행계획으로 계속 본다.
  • 인덱서는 재시작, 네트워크 장애, 수동 복구 때 같은 트랜잭션을 다시 처리하므로 멱등성이 필수다. 이력은 복합 PK와 ON CONFLICT DO NOTHING, 스냅샷은 버전 가드를 건 UPSERT로 지키고, 값은 상대 연산보다 절대 상태로 반영한다. 재시작은 last_version + 1부터 하고, 범위 재처리 API는 정상 파이프라인과 같은 핸들러를 쓴다. 멱등성이 없으면 중복 데이터, 잔액 왜곡, 상태 오염이 생긴다. 프로세서별 마지막 처리 버전을 저장하고 배치 커밋 시점을 분명히 한다. 점검 질문은 셋이다. 같은 이벤트를 두 번 처리해도 결과가 같은가, 순서가 뒤바뀐 배치가 와도 최신 상태가 유지되는가, 부분 실패 뒤 재시도해도 중복 부작용이 없는가.

관련