목적 및 범위
체인 동기화는 네트워크 피어로부터 블록체인 데이터(블록, 헤더, 영수증, 상태)를 다운로드하고 검증하여 노드를 체인 헤드와 최신 상태로 맞추는 과정입니다.이 문서는 StableNet에서 사용되는 동기화 아키텍처와 내부 흐름을 설명합니다. 핵심 구성 요소:
downloader.Downloader– 메인 동기화 엔진chainSyncer– 동기화 작업 오케스트레이션queue– 병렬 다운로드 스케줄링 및 결과 캐싱peerSet– 동기화 참여 피어 관리
블록 삽입 및 체인 관리 로직은 블록체인 관리을 참조하세요.
동기화 모드
StableNet은 세 가지SyncMode를 지원합니다.
| Mode | Value | Behavior |
|---|---|---|
FullSync | 0 | 모든 블록을 다운로드하고 모든 트랜잭션을 실행 |
SnapSync | 1 | 헤더 + 최근 상태 스냅샷 다운로드 후 히스토리 백필 |
LightSync | 2 | 헤더만 다운로드, 최소 검증 |
Downloader.mode에 원자적으로 저장됩니다.
모드 선택 로직
chainSyncer.modeAndLocalHead()는 다음 규칙으로 동기화 모드를 결정합니다.
- SnapSync 플래그가 활성화된 경우 SnapSync
- 헤드 상태가 없는 경우 SnapSync 강제
- SnapSync 피벗 아래로 체인이 되감긴 경우 SnapSync 재활성화
- 그 외의 경우 FullSync
Downloader 아키텍처
Downloader는 전체 동기화 파이프라인의 중심 컴포넌트입니다.
| Field | Type | Purpose |
|---|---|---|
mode | atomic.Uint32 | 현재 동기화 모드 |
queue | *queue | 다운로드 작업 스케줄러 |
peers | *peerSet | 피어 추적 및 선택 |
blockchain | BlockChain | FullSync 대상 |
lightchain | LightChain | LightSync 대상 |
SnapSyncer | *snap.Syncer | 상태 스냅샷 동기화 |
skeleton | *skeleton | Beacon 헤더 백필 |
cancelCh | chan struct{} | 중단 신호 |
Downloader는 eth 프로토콜 핸들러에서 생성되어 chainSyncer에 의해 제어됩니다.
동기화 오케스트레이션
chainSyncer 제어 루프
chainSyncer.loop()는 상태 머신 형태로 동작하며 다음을 반복 수행합니다.
- 현재 로컬 헤드와 원격 피어 상태 평가
- 다음 동기화 작업 결정
- 동기화 실행 및 결과 처리
- 오류 발생 시 재시도 또는 모드 전환
동기화 실행
doSync()는 선택된 모드에 따라 다음 중 하나를 실행합니다.
- FullSync – 전체 헤더·본문·영수증 다운로드
- SnapSync – 상태 스냅샷 다운로드 후 히스토리 백필
공통 조상 찾기
동기화는 로컬 체인과 원격 체인의 공통 조상을 찾는 것부터 시작합니다.2단계 조상 탐색
-
Span Search
간격을 두고 헤더를 요청하여 빠르게 포크 범위를 좁힙니다. -
Binary Search
후보 구간 내에서 이진 탐색으로 정확한 공통 조상을 찾습니다.
포크 보호
깊은 체인 재구성을 방지하기 위해 보호용 floor를 두어, 특정 깊이 이하의 조상 탐색은 제한됩니다.헤더 동기화
헤더는 본문과 영수증보다 먼저 동기화됩니다.헤더 가져오기 모드
- 레거시 모드 – 네트워크 피어로부터 헤더 요청
헤더 처리
다운로드된 헤더는 여러 고루틴에서 병렬로 검증·정렬되며, 재구성 보호 상수를 통해 체인 안정성이 유지됩니다.본문 및 영수증 가져오기
헤더가 준비되면 본문과 영수증이queue를 통해 병렬로 다운로드됩니다.
- 본문과 영수증은 각각 독립적인 작업 큐와 펜딩 풀을 가집니다
- 작업은 피어 용량에 따라 동적으로 할당됩니다
- 검증 실패 시 해당 피어는 페널티 또는 드롭 대상이 됩니다
상태 동기화 (Snap Sync)
Snap 동기화는 전체 트랜잭션 실행을 생략하고 상태 스냅샷을 다운로드하여 초기 동기화를 가속합니다.Snap 동기화 단계
- 피벗 블록 선택
- 상태 스냅샷 다운로드
- 누락된 trie 노드 및 코드 보완
- 피벗 커밋
- 이후 블록을 FullSync 방식으로 처리
피벗 블록
피벗 블록은 상태 루트 기준점입니다.- 레거시 모드 – 피어로부터 최신 헤드 요청
SnapSyncer 역할
SnapSyncer는 다음 데이터를 가져옵니다.- 계정 trie 세그먼트
- 컨트랙트 저장소 데이터
- 컨트랙트 바이트코드
- 누락된 trie 노드
Ancient Store 처리
Snap 동기화 중 오래된 블록은 직접 ancient store로 이동될 수 있습니다.- 기준은 최종화된 블록 또는
head - 90000 - 기준 아래 블록은 즉시 freezer로 이동
- 최근 블록은 활성 DB에 유지
큐 작업 스케줄링
queue는 병렬 다운로드를 제어하고 결과를 캐시합니다.
| Field | Purpose |
|---|---|
blockTaskPool | 본문 대기 작업 |
blockTaskQueue | 본문 우선순위 큐 |
blockPendPool | 진행 중 본문 요청 |
receiptTaskPool | 영수증 대기 작업 |
receiptTaskQueue | 영수증 우선순위 큐 |
resultCache | 완료된 결과 캐시 |
캐시 제한
결과 캐시는 다음 조건 중 하나를 초과하면 throttle 됩니다.- 항목 수 제한 초과
- 총 메모리 사용량 초과
피어 관리
peerConnection
각 피어는 처리량과 응답 지연을 추적합니다.- 헤더, 본문, 영수증별 처리 용량
- 지수 이동 평균 기반 성능 추정
peerSet
peerSet은 동기화에 참여 가능한 피어 집합을 관리합니다.
피어 등록
새 피어는 동기화 핸드셰이크 완료 후RegisterPeer()를 통해 등록됩니다.
오류 처리 및 드롭
- 데이터 누락 시
MarkLacking()으로 표시 - 반복 오류, 타임아웃, 잘못된 응답 시 피어 드롭
- 레거시 동기화 경로에서는 오류 즉시 드롭 가능
동기화 워크플로우 요약
- 피어 선택 및 모드 결정
- 공통 조상 탐색
- 헤더 다운로드 및 검증
- 본문·영수증 병렬 다운로드
- SnapSync 상태 동기화(필요 시)
- 피벗 커밋 및 FullSync 전환
- 체인 헤드 도달 후 정상 동작