> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical Proofs와 함께 op-reth 실행하기

> 무허가(permissionless) 출금 증명을 위해 과거 eth_getProof 응답을 효율적으로 제공하도록 op-reth의 proofs-history 저장소를 구성합니다.

이 튜토리얼은 정상적으로 작동하는 op-reth node 위에 **proofs-history** historical proof 저장소를 추가합니다. 먼저 [소스에서 OP Stack node 빌드 및 실행하기](https://docs.optimism.io/ko/node-operators/tutorials/run-node-from-source.md)를 따라 op-reth와 op-node를 빌드한 다음, 이 페이지로 돌아와 proofs-history를 활성화하십시오.

> [!NOTE]
>
> **이 튜토리얼이 필요합니까?** op-reth에서의 출금 증명은 과거 L2 상태에 대해 `eth_getProof`를 사용하므로, 허가형(permissioned) 체인과 무허가형(permissionless) 체인 모두 과거 상태를 노출해야 합니다. 다만 필요한 조회 범위(lookback)는 크게 다릅니다.
>
> * **허가형 체인**은 몇 시간의 조회 범위만 있으면 됩니다(분쟁 게임(dispute game) 게시 주기에 여유분을 더한 범위). 더 가벼운 `--rpc.eth-proof-window <num_blocks>` 플래그만으로 충분하며, 별도의 proofs 데이터베이스가 필요하지 않으므로 **이 튜토리얼은 해당되지 않습니다**. 해당 플래그는 [op-reth 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/op-reth/cli/op-reth/node.md)를 참고하십시오.
> * **무허가형 체인**은 약 28일의 조회 범위가 필요합니다. 이 범위에서는 `--rpc.eth-proof-window`가 너무 느리고 메모리를 많이 사용하므로, 이 튜토리얼을 따라 `--proofs-history`를 설정하십시오.

> [!WARNING]
>
> op-reth v2.6.x 이하 버전에서는 proofs 저장소의 기본값이 지원 중단(deprecated)된 v1 형식입니다. 이 튜토리얼의 `op-reth node`와 모든 `op-reth proofs` 하위 명령에 `--proofs-history.storage-version=v2`를 전달하십시오. 이후 릴리스는 v2 형식만 지원하며, `--proofs-history.storage-version=v2`는 아무 동작도 하지 않는 값(no-op)으로 허용하고 그 외의 값은 거부합니다. 레거시 v1 테이블은 비어 있든 데이터가 있든 그대로 남겨집니다. 해당 데이터는 무시되며 계속 디스크 공간을 차지합니다. 데이터베이스에 v1 proof 데이터만 있다면 이를 삭제(또는 새 `--proofs-history.storage-path` 사용)하고 `op-reth proofs init`를 실행하십시오.

## 작동 방식

reth의 기본 `eth_getProof`는 tip에서부터 메모리 내 상태 diff를 거꾸로 되돌리는 방식이므로, 여러 날에 걸친 조회 범위에서는 감당하기 어려울 정도로 비용이 커집니다. **proofs-history** 하위 시스템은 블록별로 버전 관리되는 중간 Merkle Patricia Trie node를 추적하는 별도의 MDBX 데이터베이스를 유지하여, 구성 가능한 보존 범위(retention window) 내 모든 블록의 proof를 O(1)로 조회할 수 있게 합니다. 백그라운드 pruner가 범위 밖의 데이터를 제거합니다.

이 하위 시스템은 reth의 ExEx(Execution Extension) 훅을 통해 블록을 비동기적으로 처리하므로, 동기화 속도에 오버헤드를 전혀 추가하지 않으며 tip 지연에 미치는 영향도 무시할 수 있는 수준입니다. 스토리지 테이블, RPC 재정의, 조정 가능한 파라미터는 [historical proof 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/reference/op-reth-historical-proof-config.md)를 참고하십시오.

## 사전 요구 사항

* v2.2.3 이상으로 빌드된 `op-reth` 바이너리. [op-node 및 실행 클라이언트 빌드하기](https://docs.optimism.io/ko/node-operators/tutorials/run-node-from-source.md#build-op-node-and-the-execution-client)를 참고하십시오.
* genesis에서 초기화했거나 [스냅샷](https://datadirs.optimism.io/)에서 복원한 op-reth datadir(아래에서 설명).
* 충분한 디스크: proofs 데이터베이스에 `chain_size + 20% buffer`를 예상하십시오(예: 2초 블록 시간의 Base에서 4주 기준 약 1 TB).
* NVMe SSD 권장.

## 초기화

historical proofs와 함께 `op-reth`를 실행하려면 두 단계의 초기화가 필요합니다.

### 1. op-reth 초기화하기

체인의 genesis 파일(예: `optimism`)로 핵심 데이터베이스를 초기화합니다.

```bash theme={null}
./target/release/op-reth init \
  --datadir="/path/to/datadir" \
  --chain="optimism"
```

#### 옵션: 스냅샷에서 시작하기

genesis부터 동기화하는 대신 사전 동기화된 데이터베이스 스냅샷에서 시작하려면 다음을 수행하십시오.

1. [datadirs.optimism.io](https://datadirs.optimism.io/)에서 `op-reth` 스냅샷을 다운로드하여 `datadir`에 압축을 풉니다.
2. 위의 `op-reth init` 명령을 건너뜁니다.
3. 아래의 **Proofs 스토리지 초기화하기**로 진행합니다. `proofs init` 명령은 스냅샷의 체인 tip에서 proofs 데이터베이스를 초기화하며, 스냅샷에 이미 포함된 블록에 대한 proofs를 소급하여 채우지는 않습니다.

### 2. Proofs 스토리지 초기화하기

historical proof 저장소가 사용하는 별도의 스토리지를 초기화합니다. 이 작업은 기존 op-reth datadir을 재사용하거나 스냅샷에서 복원하는 경우에도 `--proofs-history`와 함께 node를 시작하기 전에 **필수**입니다.

```bash theme={null}
./target/release/op-reth proofs init \
  --datadir="/path/to/datadir" \
  --chain="optimism" \
  --proofs-history.storage-path="/path/to/proofs-db"
```

> [!NOTE]
>
> `proofs init`를 처음 실행하면 몇 분에서 몇 시간이 걸립니다. 이후 실행은 몇 초면 완료됩니다. 이 명령은 과거 proofs를 백필(backfill)하지 **않으며**, 현재 체인 tip을 proofs 데이터베이스의 시작 지점으로 표시합니다. node가 `--proofs-history`와 함께 실행되면 새 블록이 커밋될 때마다 proofs 데이터베이스가 앞쪽으로 채워집니다. 전체 보존 범위(예: 기본 설정에서 무허가 결함 증명(fault proof)의 경우 30일)에 걸쳐 proofs를 제공하려면 node가 초기화 후 최소한 그 기간 동안 계속 실행되어야 합니다. 이러한 이유로 필요한 시간 범위를 충족할 만큼 tip이 충분히 오래된 스냅샷에서 시작하는 것을 권장합니다.

## proofs-history와 함께 op-reth 실행하기

[실행 클라이언트 시작하기](https://docs.optimism.io/ko/node-operators/tutorials/run-node-from-source.md#start-the-execution-client)의 표준 op-reth 시작 명령에 아래의 `--proofs-history.*` 플래그를 추가하십시오. proofs-history 관련 추가 항목은 다음과 같습니다.

```bash theme={null}
./target/release/op-reth node \
  # ... your standard flags from Tutorial A ...
  --proofs-history \
  --proofs-history.storage-path="/path/to/proofs-db"
```

> [!NOTE]
>
> 기본 `--proofs-history.window`는 **1,296,000 블록**이며, 2초 블록 시간 기준 약 30일에 해당합니다. 블록 시간이 다른 체인의 경우 `target_retention_seconds / block_time_seconds`를 사용하여 `--proofs-history.window=<num_blocks>`를 명시적으로 설정하십시오.

`--proofs-history.*` 플래그 전체 목록(window, prune-interval, metrics 등)은 [historical proof 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/reference/op-reth-historical-proof-config.md)를 참고하십시오.

## op-node 실행하기

[op-node 시작하기](https://docs.optimism.io/ko/node-operators/tutorials/run-node-from-source.md#start-op-node)에 설명된 대로 `op-node`를 시작하십시오. 합의 클라이언트에는 proofs-history 관련 변경이 필요하지 않습니다.

## 검증

두 클라이언트를 시작한 후 `debug_proofsSyncStatus` RPC 메서드로 proofs 저장소의 동기화 상태를 조회합니다.

```bash theme={null}
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_proofsSyncStatus","params":[],"id":1}' \
  http://localhost:8545
```

응답 형태는 다음과 같습니다.

```json theme={null}
{"jsonrpc":"2.0","id":1,"result":{"earliest":<block>,"latest":<block>}}
```

`proofs init` 직후에는 `earliest`와 `latest`가 모두 체인 tip에 위치하며, 이후 새 블록이 커밋될 때마다 범위가 앞쪽으로 채워집니다. `[earliest, latest]` 범위 내 모든 블록에 대한 `eth_getProof` 호출은 버전 관리형 저장소에서 처리됩니다. `earliest`보다 오래된 블록에 대한 요청은 실패하거나 기본 reth 구현으로 대체(fallback)됩니다.

proofs-history ExEx가 연결되었는지 확인하는 메시지를 op-reth 시작 로그에서 확인할 수도 있습니다.

```text theme={null}
INFO reth::cli: Using on-disk storage for proofs history
INFO reth::cli: Installing proofs-history RPC overrides (eth_getProof, debug_executePayload)
INFO reth::cli eth_replaced=true debug_replaced=true: Proofs-history RPC overrides installed
```

## 모니터링

op-reth를 `--metrics=<addr>:<port>` 플래그와 함께 실행하면, proofs-history ExEx가 proofs DB 동기화 상태(`optimism_trie_block_*`), 백그라운드 pruner(`optimism_trie_pruner_*`), `eth_getProof` RPC 트래픽(`optimism_rpc_eth_api_ext_*`)을 다루는 Prometheus 메트릭을 노출합니다. 전체 목록은 [historical proof 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/reference/op-reth-historical-proof-config.md#metrics)를 참고하십시오.

## 운영 명령

### 수동 prune

pruning은 새 블록이 커밋될 때 engine 작업에 의해 백그라운드에서 자동으로 실행되며, 보존 범위 밖의 데이터를 제거합니다. 정상 운영 중에는 `op-reth proofs prune`을 호출할 필요가 없습니다.

수동 prune은 한 가지 상황에서만 필요합니다. 시작 시 proofs 데이터베이스에 구성된 `--proofs-history.window`를 **1000 블록** 넘게 초과하는 기록이 있으면, node는 대규모 prune 작업으로 멈추는 대신 시작을 거부합니다. 이는 일반적으로 구성된 범위가 크게 이동할 만큼 node가 오래 오프라인 상태였거나, `--proofs-history.window`를 이전에 사용하던 값보다 작게 줄인 후에 발생합니다.

이 경우 op-reth는 prune해야 할 블록 수를 나타내는 오류와 함께 종료됩니다. prune 명령을 한 번 실행하여 데이터베이스를 안전 임계값 내로 되돌린 다음 node를 다시 시작하십시오.

```bash theme={null}
op-reth proofs prune \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --proofs-history.window 1296000
```

### Unwind

proofs 데이터베이스를 특정 블록으로 되돌려 데이터 손상에서 복구합니다.

```bash theme={null}
op-reth proofs unwind \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --target <BLOCK_NUMBER>
```

> [!NOTE]
>
> 데이터베이스의 가장 이른 블록 번호 이후의 블록으로만 unwind할 수 있습니다. 가장 이른 블록보다 이전 블록으로 unwind하면 실패합니다.

## 성능

Base Sepolia(약 700k 블록 범위, WETH 컨트랙트)에서 벤치마크한 결과입니다.

| 메트릭 | 값 |
| - | - |
| 평균 지연 시간 | `eth_getProof`당 약 15 ms |
| 처리량 | 약 5,000 req/s(동시 worker 10개) |
| 동기화 오버헤드 | 없음(ExEx가 비동기적으로 처리) |
| 메모리 | 범위 크기에 따라 제한됨 — OOM 위험 없음 |

## 다음 단계

* [op-reth v2.2.3 릴리스 노트](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth%2Fv2.2.3) — 현재의 historical proof 저장소를 도입한 릴리스입니다.
* [op-reth historical proof 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/reference/op-reth-historical-proof-config.md) — 전체 `--proofs-history.*` 플래그, RPC 엔드포인트, Prometheus 메트릭을 다룹니다.
* [op-reth 구성 레퍼런스](https://docs.optimism.io/ko/node-operators/reference/op-reth-config.md) — 모든 표준 op-reth 플래그를 다룹니다.