> ## 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에서 제공하는 데이터 가져오기 및 내보내기 유틸리티를 설명합니다.\
이 유틸리티는 파일 기반 체인 동기화, 블록체인 백업, 과거 데이터 아카이빙, 데이터베이스 조작을 가능하게 합니다.

P2P 네트워크를 통한 라이브 체인 동기화에 대한 정보는 [체인 동기화](/ko/networking/7.3-chain-synchronization)를 참고하세요.

데이터베이스 아키텍처 및 저장소 메커니즘은 [데이터베이스 레이어 및 Merkle Patricia Trie](/ko/storage-architecture/9.1-database-layer-and-merkle-patricia-tries)와 [고대 저장소 및 데이터 라이프사이클](/ko/storage-architecture/9.3-ancient-store-and-data-lifecycle)을 참고하세요.

## 개요

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 파일 명명 규칙 준수

처리 흐름:

1. 디렉터리 내 Era1 파일 나열
2. SHA256 체크섬 검증
3. Era1 파일 단위로 블록 반복 처리
4. 제네시스 블록 제외
5. HeaderChain → ReceiptChain 순서로 삽입
6. 주기적 진행 로그 출력

### 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` 인터페이스를 통해 다양한 데이터 소스를 처리합니다.

```
type ChainDataIterator interface {
  Next() (byte, []byte, []byte, bool)
  Release()
}
```

## 데이터 무결성 및 검증

### 체크섬 검증

Era1 가져오기 시 파일 전체를 SHA256으로 검증한 후 처리합니다.\
파싱 이전 단계에서 무결성을 보장합니다.

### 블록 검증

* 중복 블록 제거
* 합의 엔진을 통한 헤더/본문 검증
* 상태 가용성 확인

## 인터럽트 처리

모든 장시간 작업은 다음 패턴을 따릅니다.

1. 인터럽트 채널 생성
2. SIGINT / SIGTERM 핸들링
3. 신호 수신 시 채널 종료
4. 메인 루프에서 주기적 확인

## 파일 형식 요약

| 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  |

### 자동 압축 감지 로직

```
if strings.HasSuffix(fn, ".gz") {
  reader, _ = gzip.NewReader(reader)
  writer = gzip.NewWriter(writer)
}
```

## 진행 상황 보고

* 기본 로그 주기: 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     |