Optimism Documentation

이 튜토리얼은 정상적으로 작동하는 op-reth node 위에 proofs-history historical proof 저장소를 추가합니다. 먼저 소스에서 OP Stack node 빌드 및 실행하기를 따라 op-reth와 op-node를 빌드한 다음, 이 페이지로 돌아와 proofs-history를 활성화하십시오.

이 튜토리얼이 필요합니까? op-reth에서의 출금 증명은 과거 L2 상태에 대해 eth_getProof를 사용하므로, 허가형(permissioned) 체인과 무허가형(permissionless) 체인 모두 과거 상태를 노출해야 합니다. 다만 필요한 조회 범위(lookback)는 크게 다릅니다.

허가형 체인은 몇 시간의 조회 범위만 있으면 됩니다(분쟁 게임(dispute game) 게시 주기에 여유분을 더한 범위). 더 가벼운 --rpc.eth-proof-window <num_blocks> 플래그만으로 충분하며, 별도의 proofs 데이터베이스가 필요하지 않으므로 이 튜토리얼은 해당되지 않습니다. 해당 플래그는 op-reth 구성 레퍼런스를 참고하십시오.
무허가형 체인은 약 28일의 조회 범위가 필요합니다. 이 범위에서는 --rpc.eth-proof-window가 너무 느리고 메모리를 많이 사용하므로, 이 튜토리얼을 따라 --proofs-history를 설정하십시오.

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 구성 레퍼런스를 참고하십시오.

사전 요구 사항

v2.2.3 이상으로 빌드된 op-reth 바이너리. op-node 및 실행 클라이언트 빌드하기를 참고하십시오.
genesis에서 초기화했거나 스냅샷에서 복원한 op-reth datadir(아래에서 설명).
충분한 디스크: proofs 데이터베이스에 chain_size + 20% buffer를 예상하십시오(예: 2초 블록 시간의 Base에서 4주 기준 약 1 TB).
NVMe SSD 권장.

초기화

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

1. op-reth 초기화하기

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

./target/release/op-reth init \
  --datadir="/path/to/datadir" \
  --chain="optimism"

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

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

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

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

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

./target/release/op-reth proofs init \
  --datadir="/path/to/datadir" \
  --chain="optimism" \
  --proofs-history.storage-path="/path/to/proofs-db"

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

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

실행 클라이언트 시작하기의 표준 op-reth 시작 명령에 아래의 --proofs-history.* 플래그를 추가하십시오. proofs-history 관련 추가 항목은 다음과 같습니다.

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

기본 --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 구성 레퍼런스를 참고하십시오.

op-node 실행하기

op-node 시작하기에 설명된 대로 op-node를 시작하십시오. 합의 클라이언트에는 proofs-history 관련 변경이 필요하지 않습니다.

검증

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

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

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

{"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 시작 로그에서 확인할 수도 있습니다.

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 구성 레퍼런스를 참고하십시오.

운영 명령

수동 prune

pruning은 새 블록이 커밋될 때 engine 작업에 의해 백그라운드에서 자동으로 실행되며, 보존 범위 밖의 데이터를 제거합니다. 정상 운영 중에는 op-reth proofs prune을 호출할 필요가 없습니다. 수동 prune은 한 가지 상황에서만 필요합니다. 시작 시 proofs 데이터베이스에 구성된 --proofs-history.window를 1000 블록 넘게 초과하는 기록이 있으면, node는 대규모 prune 작업으로 멈추는 대신 시작을 거부합니다. 이는 일반적으로 구성된 범위가 크게 이동할 만큼 node가 오래 오프라인 상태였거나, --proofs-history.window를 이전에 사용하던 값보다 작게 줄인 후에 발생합니다. 이 경우 op-reth는 prune해야 할 블록 수를 나타내는 오류와 함께 종료됩니다. prune 명령을 한 번 실행하여 데이터베이스를 안전 임계값 내로 되돌린 다음 node를 다시 시작하십시오.

op-reth proofs prune \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --proofs-history.window 1296000

Unwind

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

op-reth proofs unwind \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --target <BLOCK_NUMBER>

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

성능

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

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

다음 단계

op-reth v2.2.3 릴리스 노트 — 현재의 historical proof 저장소를 도입한 릴리스입니다.
op-reth historical proof 구성 레퍼런스 — 전체 --proofs-history.* 플래그, RPC 엔드포인트, Prometheus 메트릭을 다룹니다.
op-reth 구성 레퍼런스 — 모든 표준 op-reth 플래그를 다룹니다.

노드 실행

가이드

튜토리얼

클라이언트

참조

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

작동 방식

사전 요구 사항

초기화

1. op-reth 초기화하기

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

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

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

op-node 실행하기

검증

모니터링

운영 명령

수동 prune

Unwind

성능

다음 단계

​작동 방식

​사전 요구 사항

​초기화

​1. op-reth 초기화하기

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

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

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

​op-node 실행하기

​검증

​모니터링

​운영 명령

​수동 prune

​Unwind

​성능

​다음 단계

작동 방식

사전 요구 사항

초기화

1. op-reth 초기화하기

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

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

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

op-node 실행하기

검증

모니터링

운영 명령

수동 prune

Unwind

성능

다음 단계