이 유틸리티는 파일 기반 체인 동기화, 블록체인 백업, 과거 데이터 아카이빙, 데이터베이스 조작을 가능하게 합니다. P2P 네트워크를 통한 라이브 체인 동기화에 대한 정보는 체인 동기화를 참고하세요. 데이터베이스 아키텍처 및 저장소 메커니즘은 데이터베이스 레이어 및 Merkle Patricia Trie와 고대 저장소 및 데이터 라이프사이클을 참고하세요.
개요
StableNet은 다양한 유형의 블록체인 데이터를 가져오고 내보내기 위한 명령줄 유틸리티 세트를 제공합니다.이 유틸리티는 네트워크 연결이 아닌 파일 기반으로 동작하며 다음과 같은 목적을 가집니다.
- 오프라인 동기화: 신뢰된 체인 덤프를 통한 노드 부트스트랩
- 백업 및 복구: 재해 복구를 위한 체인 상태 백업
- 과거 아카이빙: Era1 형식을 사용한 과거 블록 데이터 보관
- 데이터베이스 마이그레이션: 노드 간 원시 DB 데이터 이동
- 테스트 및 개발: 특정 체인 구간의 선택적 가져오기/내보내기
.gz 확장자를 통해 gzip 압축을 자동 감지하며,장시간 실행 작업에 대해 인터럽트 기반 중단을 지원합니다.
체인 가져오기 및 내보내기
ImportChain
ImportChain은 RLP 인코딩된 파일에서 블록을 읽어 블록체인에 삽입합니다.메모리 사용을 제한하기 위해 배치 단위로 처리됩니다.
- 배치 크기: 2500 블록
- 제네시스 블록은 자동으로 건너뜁니다
- 이미 존재하는 블록은 삽입하지 않습니다
- SIGINT / SIGTERM 신호를 감지하여 안전하게 중단합니다
- 현재 헤드 이하:
HasBlock - 현재 헤드 초과:
HasBlockAndState
ExportChain
ExportChain은 전체 블록체인을 단일 RLP 파일로 내보냅니다.
- 기존 파일이 있으면 덮어씁니다
.gz확장자 사용 시 gzip 압축 적용- 내부적으로
blockchain.Export를 사용합니다
ExportAppendChain
ExportAppendChain은 지정한 블록 범위를 기존 파일 뒤에 추가로 기록합니다.
- 증분 백업 또는 구간 분리 내보내기에 적합
first부터last까지(포함) 블록을 기록합니다
Era1 히스토리 형식
Era1은 Ethereum Portal Network 사양에 정의된 표준 과거 데이터 포맷입니다.하나의 Era1 파일은 약 8192개 블록(1 epoch)과 다음 데이터를 포함합니다.
- 블록 헤더 및 본문
- 영수증
- 총 난이도
ImportHistory
Era1 디렉터리를 사용해 체인을 제네시스부터 복원합니다. 요구 조건:- 현재 블록 높이는 반드시 0
checksums.txt파일 존재- Era1 파일 명명 규칙 준수
- 디렉터리 내 Era1 파일 나열
- SHA256 체크섬 검증
- Era1 파일 단위로 블록 반복 처리
- 제네시스 블록 제외
- HeaderChain → ReceiptChain 순서로 삽입
- 주기적 진행 로그 출력
ExportHistory
체인 데이터를 Era1 형식으로 내보냅니다.step값은 일반적으로 8192- 파일명에 누적기 루트 해시 포함
checksums.txt자동 생성
Preimage 가져오기 및 내보내기
Preimage는 상태 트라이에서 해시되기 전의 원본 키 데이터입니다.ImportPreimages
RLP 파일에서 preimage 데이터를 데이터베이스로 복원합니다.- 배치 단위(1024개)로 처리
- Keccak256 해시를 키로 사용
- 해당 기능은 향후 제거 예정(deprecated)
ExportPreimages
DB에 저장된 모든 preimage를 파일로 내보냅니다.ExportSnapshotPreimages
특정 스냅샷 루트 기준으로 필요한 preimage만 추출합니다.- 계정 주소 preimage
- 해당 계정의 모든 저장소 키 preimage
- 누락된 preimage가 있으면 오류 발생
LevelDB 데이터 가져오기 및 내보내기
저수준 DB 조작을 통해 노드 간 상태 이전이나 복구를 지원합니다.LDB Export 헤더 구조
- Magic:
"gethdbdump" - Version: 0
- Kind: 데이터 타입
- UnixTime: 내보내기 시각
ImportLDBData
원시 키-값 쌍을 DB로 가져옵니다.- 작업 코드: Add / Delete
- 배치 크기 초과 시 즉시 플러시
- 1000개 단위로 인터럽트 확인
ExportChaindata
일반화된 DB 내보내기 유틸리티입니다.ChainDataIterator 인터페이스를 통해 다양한 데이터 소스를 처리합니다.
데이터 무결성 및 검증
체크섬 검증
Era1 가져오기 시 파일 전체를 SHA256으로 검증한 후 처리합니다.파싱 이전 단계에서 무결성을 보장합니다.
블록 검증
- 중복 블록 제거
- 합의 엔진을 통한 헤더/본문 검증
- 상태 가용성 확인
인터럽트 처리
모든 장시간 작업은 다음 패턴을 따릅니다.- 인터럽트 채널 생성
- SIGINT / SIGTERM 핸들링
- 신호 수신 시 채널 종료
- 메인 루프에서 주기적 확인
파일 형식 요약
| Format | Extension | Compression | Content | Use Case |
|---|---|---|---|---|
| RLP Chain | .rlp | Optional .gz | Block sequence | Full backup |
| Era1 | .era1 | None | Epoch blocks | History archive |
| LDB | .ldb | Optional .gz | Raw KV | DB migration |
| Preimages | .rlp | Optional .gz | Trie preimage | State recovery |
자동 압축 감지 로직
진행 상황 보고
- 기본 로그 주기: 8초
- 출력 정보:
- 작업 유형
- 현재 위치
- 누적 경과 시간
명령줄 통합
| Command | Function | Description |
|---|---|---|
| gstable import | ImportChain | Import RLP chain |
| gstable export | ExportChain | Export full chain |
| gstable export ‘first’ ‘last’ | ExportAppendChain | Export range |
| gstable import-history | ImportHistory | Import Era1 |
| gstable export-history | ExportHistory | Export Era1 |
| gstable import-preimages | ImportPreimages | Import preimages |
| gstable export-preimages | ExportPreimages | Export preimages |
| gstable db import | ImportLDBData | Import raw DB |
| gstable db export | ExportChaindata | Export raw DB |