> ## 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. # 체인 동기화 ## 목적 및 범위 체인 동기화는 네트워크 피어로부터 블록체인 데이터(블록, 헤더, 영수증, 상태)를 다운로드하고 검증하여 노드를 체인 헤드와 최신 상태로 맞추는 과정입니다.\ 이 문서는 StableNet에서 사용되는 동기화 아키텍처와 내부 흐름을 설명합니다. 핵심 구성 요소: * **`downloader.Downloader`** – 메인 동기화 엔진 * **`chainSyncer`** – 동기화 작업 오케스트레이션 * **`queue`** – 병렬 다운로드 스케줄링 및 결과 캐싱 * **`peerSet`** – 동기화 참여 피어 관리 이 문서에서는 동기화 모드, 공통 조상 탐색, 헤더·본문·영수증 병렬 다운로드, Snap 동기화 상태 다운로드, 큐 제한, 피어 관리 흐름을 다룹니다. 피어 발견은 [발견 메커니즘](/ko/networking/7.2-discovery-mechanisms)을 참조하세요.\ 블록 삽입 및 체인 관리 로직은 [블록체인 관리](/ko/core-architecture/3.2-blockchain-management)을 참조하세요. ## 동기화 모드 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단계 조상 탐색 1. **Span Search**\ 간격을 두고 헤더를 요청하여 빠르게 포크 범위를 좁힙니다. 2. **Binary Search**\ 후보 구간 내에서 이진 탐색으로 정확한 공통 조상을 찾습니다. ### 포크 보호 깊은 체인 재구성을 방지하기 위해 보호용 floor를 두어, 특정 깊이 이하의 조상 탐색은 제한됩니다. ## 헤더 동기화 헤더는 본문과 영수증보다 먼저 동기화됩니다. ### 헤더 가져오기 모드 * **레거시 모드** – 네트워크 피어로부터 헤더 요청 ### 헤더 처리 다운로드된 헤더는 여러 고루틴에서 병렬로 검증·정렬되며, 재구성 보호 상수를 통해 체인 안정성이 유지됩니다. ## 본문 및 영수증 가져오기 헤더가 준비되면 본문과 영수증이 `queue`를 통해 병렬로 다운로드됩니다. * 본문과 영수증은 각각 독립적인 작업 큐와 펜딩 풀을 가집니다 * 작업은 피어 용량에 따라 동적으로 할당됩니다 * 검증 실패 시 해당 피어는 페널티 또는 드롭 대상이 됩니다 ## 상태 동기화 (Snap Sync) Snap 동기화는 전체 트랜잭션 실행을 생략하고 상태 스냅샷을 다운로드하여 초기 동기화를 가속합니다. ### Snap 동기화 단계 1. 피벗 블록 선택 2. 상태 스냅샷 다운로드 3. 누락된 trie 노드 및 코드 보완 4. 피벗 커밋 5. 이후 블록을 FullSync 방식으로 처리 ### 피벗 블록 피벗 블록은 상태 루트 기준점입니다. * 레거시 모드 – 피어로부터 최신 헤드 요청 피벗 번호는 데이터베이스에 기록됩니다. ### SnapSyncer 역할 SnapSyncer는 다음 데이터를 가져옵니다. * 계정 trie 세그먼트 * 컨트랙트 저장소 데이터 * 컨트랙트 바이트코드 * 누락된 trie 노드 ### Ancient Store 처리 Snap 동기화 중 오래된 블록은 직접 ancient store로 이동될 수 있습니다. * 기준은 최종화된 블록 또는 `head - 90000` * 기준 아래 블록은 즉시 freezer로 이동 * 최근 블록은 활성 DB에 유지 ## 큐 작업 스케줄링 `queue`는 병렬 다운로드를 제어하고 결과를 캐시합니다. | Field | Purpose | | ------------------ | ---------- | | `blockTaskPool` | 본문 대기 작업 | | `blockTaskQueue` | 본문 우선순위 큐 | | `blockPendPool` | 진행 중 본문 요청 | | `receiptTaskPool` | 영수증 대기 작업 | | `receiptTaskQueue` | 영수증 우선순위 큐 | | `resultCache` | 완료된 결과 캐시 | ### 캐시 제한 결과 캐시는 다음 조건 중 하나를 초과하면 throttle 됩니다. * 항목 수 제한 초과 * 총 메모리 사용량 초과 이 경우 fetcher는 프로세서가 결과를 소비할 때까지 대기합니다. ## 피어 관리 ### peerConnection 각 피어는 처리량과 응답 지연을 추적합니다. * 헤더, 본문, 영수증별 처리 용량 * 지수 이동 평균 기반 성능 추정 ### peerSet `peerSet`은 동기화에 참여 가능한 피어 집합을 관리합니다. ### 피어 등록 새 피어는 동기화 핸드셰이크 완료 후 `RegisterPeer()`를 통해 등록됩니다. ### 오류 처리 및 드롭 * 데이터 누락 시 `MarkLacking()`으로 표시 * 반복 오류, 타임아웃, 잘못된 응답 시 피어 드롭 * 레거시 동기화 경로에서는 오류 즉시 드롭 가능 ## 동기화 워크플로우 요약 1. 피어 선택 및 모드 결정 2. 공통 조상 탐색 3. 헤더 다운로드 및 검증 4. 본문·영수증 병렬 다운로드 5. SnapSync 상태 동기화(필요 시) 6. 피벗 커밋 및 FullSync 전환 7. 체인 헤드 도달 후 정상 동작 이 워크플로우는 노드가 네트워크에 합류한 시점부터 최신 체인 상태에 도달할 때까지의 전체 동기화 주기를 나타냅니다.