인덱서는 원본 블록과 이벤트를 읽어 검색하기 쉬운 데이터베이스로 바꿉니다. 대시보드 항목이 비거나 과거 통계가 줄었다고 해서 원장 데이터가 지워진 것은 아닙니다. 인덱서가 처리한 최신 블록과 체인 최신 블록의 차이, 실패한 배포본과 블록, 매핑 오류, 원본 거래 영수증과 로그가 있는지 확인하고, 재색인이 끝난 높이까지 기다려야 합니다.
인덱스는 원장의 검색용 파생본입니다
블록체인 노드는 블록, 거래, 영수증, 로그를 제공하지만 화면에 필요한 사용자별 활동·거래량·누적 통계를 바로 내주지는 않습니다. 인덱서는 지정한 계약과 이벤트를 차례로 읽고 매핑(mapping)을 실행해 엔터티 데이터베이스를 만듭니다. 그래서 파생 데이터베이스가 뒤처져도 원본 블록은 그대로 있을 수 있습니다.
The Graph 문서는 서브그래프(subgraph)를 블록체인 데이터를 뽑아 처리·저장한 뒤 GraphQL로 조회하게 해 주는 공개 API로 설명합니다. 매니페스트는 네트워크, 계약, 이벤트, 매핑을 정합니다. startBlock이나 계약 주소가 틀리면 원본 데이터가 있어도 해당 엔터티는 만들어지지 않습니다.
빈 대시보드는 파생 색인의 공백일 수 있으며, 곧바로 원본 원장이 지워졌다는 뜻은 아닙니다.
JOBCOIN 해설
그림은 이 주제의 공통 개념을 단순화한 설명입니다. 아래 항목에서 이 글의 구체적인 조건과 예외를 함께 읽어보세요.
- 인덱스는 원장의 검색용 파생본입니다
블록체인 노드는 블록, 거래, 영수증, 로그를 제공하지만 화면에 필요한 사용자별 활동·거래량·누적 통계를 바로 내주지는 않습니다.
- 색인 최신 블록과 체인 최신 블록의 간격을 잽니다
공지에는 체인의 현재 최신 블록, 인덱서가 처리를 마친 블록, 실패하거나 멈춘 블록을 함께 적어야 합니다.
- 오류가 있어도 응답은 나올 수 있습니다
The Graph의 고급 기능 문서에 따르면, 색인 오류가 생기면 기본적으로 동기화가 멈출 수 있습니다.
설명을 위한 개념도 · 실제 가격·거래 내역·통계가 아닙니다.
색인 최신 블록과 체인 최신 블록의 간격을 잽니다
공지에는 체인의 현재 최신 블록, 인덱서가 처리를 마친 블록, 실패하거나 멈춘 블록을 함께 적어야 합니다. The Graph GraphQL API의 _meta는 최신 색인 블록, 배포본, hasIndexingErrors를 확인할 수 있는 정보를 줍니다. 블록 번호만 보지 말고 해시도 맞춰 보며 재편성(reorg) 뒤 옛 분기를 색인한 상태인지 확인합니다.
최신 블록과의 간격이 꾸준히 줄어든다면 따라잡는 중일 가능성이 큽니다. 같은 블록에서 멈춰 있다면 결정적(deterministic) 매핑 오류나 빠진 제공자 기능을 조사합니다. 최신 블록은 따라왔는데 특정 기간만 비어 있다면 잘못된 startBlock, 핸들러 조건, 오염된 캐시, 재배포 이전 작업을 확인합니다.
| 패턴 | 가능한 원인 | 원본 대조 |
|---|---|---|
| 최신 구간 전체 지연 | 제공자 문제·처리량 부족 | 체인 최신 블록과 간격 |
| 특정 블록에서 정지 | 결정적 오류 | 영수증·핸들러 입력 |
| 일부 이벤트만 누락 | 매핑·ABI·필터 | 원본 로그 토픽 |
| 과거 통계만 감소 | 재배포·스키마 변경 | 배포본 ID |
| 해시가 다른 블록 | 재편성·캐시 불일치 | 정식 체인 블록 해시 |
오류가 있어도 응답은 나올 수 있습니다
The Graph의 고급 기능 문서에 따르면, 색인 오류가 생기면 기본적으로 동기화가 멈출 수 있습니다. 치명적이지 않은 오류를 허용하면 문제가 된 핸들러의 변경을 건너뛴 채 조회를 계속 제공할 수 있습니다. 이런 응답은 최신처럼 보여도 일부 엔터티가 어긋나 있을 수 있으니, hasIndexingErrors와 GraphQL 오류를 함께 읽습니다.
HTTP 200과 데이터 항목이 있다는 사실이 완전성을 보증하지는 않습니다. API가 어느 배포본, 어느 색인 블록 기준으로 응답했는지, 오류 허용 옵션을 썼는지 표시해야 합니다. 통계 화면은 마지막으로 완전한 블록과 잠정 데이터를 다른 색이나 문구로 구분하는 편이 안전합니다.
원본 영수증과 로그로 사건이 있었는지 확인합니다
사용자가 본 거래 해시를 독립된 RPC에서 조회해 영수증 상태, 블록 번호와 해시, 계약 주소, 로그를 확인합니다. 이벤트 토픽과 데이터가 원본 영수증에 있는데 화면에 엔터티가 없다면 색인이나 매핑 문제일 가능성이 높습니다. 거래 자체가 정식 체인에서 사라졌다면 재편성이나 잘못된 네트워크·해시 가능성을 따로 봅니다.
잔액은 현재 계약 상태를 eth_call로 읽은 값과 인덱서가 이벤트를 합산해 낸 값을 비교합니다. 리베이스 토큰, 내부 회계, 프록시 업그레이드는 단순한 전송 합산과 다를 수 있으므로 계약이 정한 공식 조회 함수를 기준으로 삼습니다.
- 배포본 ID와 스키마 버전을 기록합니다
- 체인 최신 블록·색인 최신 블록·실패 블록을 비교합니다
- 원본 영수증과 로그를 보존합니다
- hasIndexingErrors와 조회 오류를 확인합니다
- 완료 블록까지 과거 데이터가 채워진 뒤 통계를 다시 계산합니다
재시도와 재색인은 같은 조치가 아닙니다
Graph Node 문서는 두 가지 실패를 구분합니다. 비결정적 실패는 제공자나 예상치 못한 노드 오류 때문에 생길 수 있어 간격을 늘려 가며 재시도하지만, 결정적 실패는 재시도로 풀리지 않습니다. 후자는 매핑 코드나 설정을 바꿔야 할 수 있습니다. ‘자동 복구 중’이라는 공지에는 어떤 유형으로 판정했는지 근거가 있어야 합니다.
제공자가 잘못된 블록 데이터를 준 뒤 그것이 캐시에 남으면 새 요청도 같은 오류를 되풀이할 수 있습니다. Graph Node 문서는 캐시된 블록을 제공자와 대조하고, 어긋난 자료를 지운 뒤 영향을 받은 서브그래프를 되감아 다시 가져오는 절차를 설명합니다. 캐시를 지웠다고 빠진 엔터티가 저절로 다시 만들어졌다고 단정하지 않습니다.
복구 완료는 데이터 완전성 검사로 선언합니다
색인 최신 블록이 체인 최신 블록을 따라잡았다는 것만으로는 과거 공백이 채워졌는지 알 수 없습니다. 영향 받은 블록 범위의 이벤트 수, 대표 거래 표본, 주소별 합계, 이전 스냅숏과의 차이를 검증합니다. 재편성 처리 뒤 정식 체인 해시에 맞는 엔터티가 남았는지도 봅니다.
공지에는 영향 받은 배포본, 시작·종료 블록, 빠진 엔터티 유형, 재색인 시작과 완료 시각, 검증용 조회문을 공개합니다. 이용자에게는 화면 수치를 회계·청산·세금 신고에 쓰지 말아야 할 잠정 기간을 분명히 알립니다. 원장 정상과 통계 복구 완료는 서로 다른 상태로 갱신해야 합니다.
앱은 불완전한 데이터를 조용히 숨기지 않습니다
탈중앙화 앱은 색인 최신 블록이 허용 지연을 넘으면 마지막 갱신 블록과 경고를 보여 주고, 위험한 동작의 계산 근거를 다시 조회합니다. 청산·담보·청구 가능액처럼 결과 비용이 큰 값은 계약 호출로 교차 확인합니다. 예비 인덱서라도 같은 제공자와 배포본을 쓴다면 독립 검증이 아닙니다.
개발자는 재색인 중 이벤트가 중복으로 들어와도 합계가 두 번 더해지지 않도록 거래 해시와 로그 순번을 고유 키로 씁니다. 조회 캐시에는 블록·배포본 기준을 넣고 복구 뒤 무효화합니다. 장애를 숨긴 채 숫자만 바꾸기보다 데이터의 기준 블록을 공개하는 편이 이용자의 판단에 도움이 됩니다.
자주 묻는 질문
대시보드 거래가 사라지면 온체인 거래도 취소된 건가요?
아닙니다. 독립된 RPC나 탐색기에서 거래 영수증과 정식 체인 블록 해시를 먼저 확인합니다.
색인 최신 블록이 최신이면 모든 데이터가 복구됐나요?
그렇지 않을 수 있습니다. 과거 오류 구간의 이벤트 수와 대표 거래가 다시 채워졌는지 검증해야 합니다.
HTTP 200 응답이면 인덱스가 정상인가요?
응답에 색인 오류나 불완전한 데이터가 함께 올 수 있으니 _meta와 오류 항목을 확인합니다.
더 깊이 읽기
본문에서 다룬 개념과 확인 절차를 다음 글에서 이어서 살펴보세요.
