인덱서 데이터 누락 공지, 원장 손실로 오해하지 않는 확인법

인덱서는 원본 블록과 event를 읽어 검색하기 쉬운 database로 변환한다. 대시보드 항목이 비거나 과거 통계가 줄었다고 원장 데이터가 삭제된 것은 아니다. indexer가 처리한 latest block과 chain head의 차이, 실패한 deployment와 block, mapping error, 원본 transaction receipt·log 존재 여부를 확인하고 재색인 완료 높이까지 기다려야 한다.

인덱스는 원장의 검색용 파생본이다

블록체인 node는 block, transaction, receipt와 log를 제공하지만 화면이 요구하는 사용자별 활동·거래량·누적 통계는 곧바로 주지 않는다. 인덱서는 지정 contract와 event를 순서대로 읽고 mapping을 실행해 entity database를 만든다. 따라서 파생 database가 뒤처져도 원본 block이 그대로 존재할 수 있다.

The Graph 문서는 subgraph를 blockchain data를 추출·처리·저장해 GraphQL로 질의하게 하는 open API로 설명한다. manifest는 network, contract, event와 mapping을 정한다. startBlock이나 contract address가 잘못되면 원본 데이터가 있어도 해당 entity가 만들어지지 않는다.

빈 대시보드는 파생 색인의 공백일 수 있으며 원본 원장의 삭제를 곧바로 뜻하지 않는다.

JOBCOIN 해설

VISUAL GUIDE뉴스·공시를 확인하는 세 가지 기준

1. 01
   인덱스는 원장의 검색용 파생본이다

   블록체인 node는 block, transaction, receipt와 log를 제공하지만 화면이 요구하는 사용자별 활동·거래량·누적 통계는 곧바로 주지 않는다.

2. 02
   indexed head와 chain head의 간격을 잰다

   공지에는 chain의 현재 head, indexer가 완료한 block, 실패 또는 pause된 block을 함께 적어야 한다.

3. 03
   오류가 있어도 응답이 나올 수 있다

   The Graph의 advanced 기능 문서는 indexing error가 생기면 기본적으로 sync가 멈출 수 있고, non-fatal error를 허용하면 문제가 된 handler 변화를 건너뛰면서 query를 제공할 수 있다고 설명한다.

AI로 제작한 개념도 · 실제 가격·거래 내역·통계가 아닙니다.

indexed head와 chain head의 간격을 잰다

공지에는 chain의 현재 head, indexer가 완료한 block, 실패 또는 pause된 block을 함께 적어야 한다. The Graph GraphQL API의 _meta는 latest indexed block과 deployment, hasIndexingErrors를 확인하는 정보를 제공한다. block 번호만 보지 말고 hash도 대조해 reorg 뒤 옛 fork를 색인한 상태인지 확인한다.

head gap이 일정하게 줄면 catch-up 중일 가능성이 크다. 같은 block에서 멈추면 deterministic mapping error나 누락된 provider 기능을 조사한다. head는 따라왔지만 특정 기간만 비었다면 잘못된 startBlock, handler 조건, poisoned cache, 재배포 migration을 확인한다.

오류가 있어도 응답이 나올 수 있다

The Graph의 advanced 기능 문서는 indexing error가 생기면 기본적으로 sync가 멈출 수 있고, non-fatal error를 허용하면 문제가 된 handler 변화를 건너뛰면서 query를 제공할 수 있다고 설명한다. 이 응답은 최신처럼 보여도 일부 entity가 불일치할 수 있다. hasIndexingErrors와 GraphQL errors를 함께 읽는다.

HTTP 200과 data 필드 존재는 완전성을 보증하지 않는다. API가 어느 deployment와 indexed block에서 응답했는지, 오류 허용 옵션을 사용했는지 표시해야 한다. 통계 화면은 마지막 완전 block과 잠정 data를 다른 색이나 문구로 구분하는 편이 안전하다.

원본 receipt와 log로 사건 존재를 확인한다

사용자가 본 transaction hash를 독립 RPC에서 조회해 receipt status, block number·hash, contract address와 logs를 확인한다. event topic과 data가 원본 receipt에 있는데 화면 entity가 없다면 색인·mapping 문제 가능성이 높다. transaction 자체가 canonical chain에서 사라졌다면 reorg나 잘못된 network·hash 가능성을 별도로 본다.

잔액은 current contract state를 eth_call로 읽은 값과 인덱서가 event 합산으로 계산한 값을 비교한다. rebasing token, internal accounting, proxy upgrade는 단순 transfer 합산과 다를 수 있으므로 contract가 정의한 공식 getter를 기준으로 삼는다.

• deployment ID와 schema version을 기록한다
• chain head·indexed head·실패 block을 비교한다
• 원본 receipt와 raw log를 보존한다
• hasIndexingErrors와 query error를 확인한다
• 완료 block까지 backfill된 뒤 통계를 다시 계산한다

재시도와 재색인은 같은 조치가 아니다

Graph Node 문서는 non-deterministic failure는 provider나 예상 밖 node 오류 때문에 생길 수 있어 backoff하며 재시도하지만 deterministic failure는 재시도로 해결되지 않는다고 구분한다. 후자는 mapping code나 configuration 변경이 필요할 수 있다. ‘자동 복구 중’이라는 공지에는 어떤 유형으로 판정했는지 근거가 있어야 한다.

provider가 잘못된 block 데이터를 준 뒤 cache에 남으면 새 요청도 같은 오류를 반복할 수 있다. Graph Node 문서는 cache block을 provider와 검사하고 불일치 자료를 제거한 뒤 affected subgraph를 rewind해 다시 가져오는 절차를 설명한다. cache 삭제만으로 빠진 entity가 자동 재생성됐다고 단정하지 않는다.

복구 완료는 데이터 완전성 검사로 선언한다

indexed head가 chain head를 따라잡은 것만으로 과거 공백이 채워졌는지 알 수 없다. 영향 block 범위의 event count, 대표 transaction 표본, 주소별 합계, 이전 snapshot과의 차이를 검증한다. reorg 처리 후 canonical hash에 맞는 entity가 남았는지도 본다.

공지에는 영향 deployment, 시작·종료 block, 누락 entity 유형, 재색인 시작과 완료 시각, 검증 query를 공개한다. 이용자에게는 화면 수치를 회계·청산·세금 신고에 사용하지 말아야 할 잠정 기간을 명시한다. 원장 정상과 통계 복구 완료를 별개의 상태로 갱신해야 한다.

앱은 불완전한 데이터를 조용히 숨기지 않는다

DApp은 indexed head가 허용 지연을 넘으면 마지막 갱신 block과 경고를 보여 주고 위험한 action의 계산 근거를 다시 조회한다. 청산·담보·claim 가능액처럼 결과 비용이 큰 값은 contract call과 교차한다. fallback indexer도 같은 provider와 deployment를 공유하면 독립 검증이 아니다.

개발자는 재색인 중 중복 event가 생겨도 합계가 두 번 더해지지 않도록 transaction hash와 log index를 고유 키로 사용한다. query cache에는 block·deployment 기준을 포함하고 복구 뒤 무효화한다. 장애를 숨긴 채 숫자만 바꾸는 것보다 데이터의 기준 block을 공개하는 편이 이용자 판단에 도움이 된다.

자주 묻는 질문