Optimism Documentation

op-geth는 지원이 종료되었으며(2026-05-31) 현재 활성화된 Karst 하드포크를 지원하지 않으므로, op-geth node는 더 이상 정식(canonical) 체인을 따라갈 수 없습니다. 주요 지원 실행 클라이언트인 op-reth로 마이그레이션하십시오. 전체 마이그레이션 계획은 op-geth 지원 중단 공지를 참조하십시오.

OP Stack 배우기 — 14단계 중 14단계. 지금까지 개념부터 계층 간 흐름까지 스택 전체를 학습했습니다. 이 마지막 단계에서는 공식 Docker 이미지를 사용하여 실제 네트워크에서 OP Stack node를 실행합니다. node가 동기화되면 트랙을 완료한 것입니다. 다음 단계는 OP Stack 배우기로 돌아가 확인하십시오.

이 튜토리얼에서는 하나의 docker-compose.yml에서 공식 op-reth 및 op-node Docker 이미지를 사용하여 OP Stack node를 실행합니다. 소스 빌드는 필요하지 않습니다.

op-node 대신 Rust 합의 클라이언트를 실행하려면 kona-node Docker 가이드를 참고하십시오. 이 가이드는 kona-node + op-reth 스택을 위한 자체 docker-compose 레시피를 제공합니다.

OP Mainnet은 Bedrock 이전(pre-Bedrock) 상태를 1회 가져와야(import) 합니다. OP Sepolia는 필요하지 않습니다. 새 datadir에서 이 튜토리얼을 OP Mainnet으로 실행하면 op-reth가 시작 시 Op-mainnet has been launched without importing the pre-Bedrock state 오류와 함께 실패합니다. OP Mainnet을 실행하기 전에 op-reth sync-op-mainnet 가이드를 따라 사전 동기화된 스냅샷에서 복원하거나 최소 부트스트랩(minimal-bootstrap) import를 실행하십시오. OP Sepolia는 추가 단계 없이 snap sync로 부트스트랩되므로, 설정을 테스트하는 경우에는 OP Sepolia로 시작하십시오.

의존성

Docker
Docker Compose (v2)
L1 실행 RPC 엔드포인트(OP Mainnet의 경우 Ethereum mainnet, OP Sepolia의 경우 Ethereum Sepolia).
같은 L1 체인의 L1 Beacon API 엔드포인트. op-node가 Ecotone 이후 blob 데이터를 가져오는 데 필요합니다.

빠른 시작

작업 디렉터리 만들기

mkdir op-stack-node && cd op-stack-node

JWT secret 생성하기

두 컨테이너는 bind mount를 통해 JWT secret을 공유합니다.

openssl rand -hex 32 > jwt.txt

.env 파일 만들기

네트워크와 L1 엔드포인트를 구성합니다. 네트워크 블록(Sepolia 또는 Mainnet) 중 하나를 선택하고 L1 RPC 및 Beacon URL을 입력하십시오.

cat > .env <<'EOF'
# --- Network: OP Sepolia (default) ---
OP_RETH_CHAIN=optimism_sepolia
OP_NODE_NETWORK=op-sepolia
OP_RETH_SEQUENCER=https://sepolia-sequencer.optimism.io

# --- Network: OP Mainnet (uncomment to use instead) ---
# OP_RETH_CHAIN=optimism
# OP_NODE_NETWORK=op-mainnet
# OP_RETH_SEQUENCER=https://mainnet-sequencer.optimism.io

# --- L1 endpoints (required) ---
L1_RPC_URL=https://your-l1-rpc-endpoint
L1_RPC_KIND=basic
L1_BEACON_URL=https://your-l1-beacon-endpoint
EOF

L1_RPC_KIND의 유효한 값: alchemy, quicknode, infura, parity, nethermind, debug_geth, erigon, basic, any. 확실하지 않으면 basic을 사용하십시오.

OP_RETH_CHAIN과 OP_NODE_NETWORK는 superchain-registry에 있는 모든 체인(예: unichain / unichain-mainnet, soneium / soneium-mainnet)을 허용합니다. 각 체인에 대해 L1_RPC_URL / L1_BEACON_URL이 해당 L1(Ethereum Mainnet 또는 Sepolia)을 가리키도록 하고, OP_RETH_SEQUENCER를 해당 체인의 sequencer 엔드포인트로 변경하십시오.

docker-compose.yml 만들기

services:
  op-reth:
    image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:v2.2.5
    container_name: op-reth
    ports:
      - "8545:8545"          # JSON-RPC HTTP
      - "8546:8546"          # JSON-RPC WebSocket
      - "9001:9001"          # Prometheus metrics
      - "30303:30303"        # P2P TCP
      - "30303:30303/udp"    # P2P UDP
    volumes:
      - ./reth-data:/data
      - ./jwt.txt:/jwt.txt:ro
    command:
      - node
      - --chain=${OP_RETH_CHAIN}
      - --datadir=/data
      - --http
      - --http.addr=0.0.0.0
      - --http.port=8545
      - --ws
      - --ws.addr=0.0.0.0
      - --ws.port=8546
      - --authrpc.addr=0.0.0.0
      - --authrpc.port=8551
      - --authrpc.jwtsecret=/jwt.txt
      - --rollup.sequencer=${OP_RETH_SEQUENCER}
      - --metrics=0.0.0.0:9001
    restart: unless-stopped

  op-node:
    image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.18.2
    container_name: op-node
    depends_on:
      - op-reth
    ports:
      - "9545:7000"          # JSON-RPC HTTP (host 9545 → container 7000; macOS uses 7000 for AirPlay)
      - "7300:7300"          # Prometheus metrics
      - "9222:9222"          # P2P TCP
      - "9222:9222/udp"      # P2P UDP
    volumes:
      - ./jwt.txt:/jwt.txt:ro
    command:
      - op-node
      - --l1=${L1_RPC_URL}
      - --l1.rpckind=${L1_RPC_KIND}
      - --l1.beacon=${L1_BEACON_URL}
      - --l2=ws://op-reth:8551
      - --l2.jwt-secret=/jwt.txt
      - --network=${OP_NODE_NETWORK}
      - --syncmode=execution-layer
      - --l2.enginekind=reth
      - --rpc.addr=0.0.0.0
      - --rpc.port=7000
      - --metrics.enabled
      - --metrics.addr=0.0.0.0
      - --metrics.port=7300
    restart: unless-stopped

op-reth datadir은 호스트의 ./reth-data에서 bind mount되므로 스냅샷을 직접 검사하거나 복원할 수 있습니다(아래 스냅샷에서 부트스트랩하기 참고).표시된 이미지 태그는 작성 시점의 최신 버전입니다. 현재 태그는 op-reth 릴리스와 op-node 릴리스를 참고하십시오.

node 시작하기

docker compose up -d

다음 명령으로 로그를 확인합니다.

docker compose logs -f

검증

node가 실행 중이며 진행하고 있는지 확인합니다.

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

예상 결과: 현재 블록이 16진수로 담긴 {"jsonrpc":"2.0","id":1,"result":"0x..."}. 1분 후 다시 실행해 보십시오. 동기화가 진행됨에 따라 숫자가 증가해야 합니다. op-node 동기화 상태(unsafe, safe, finalized head를 한 번의 호출로 확인):

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

초기 EL 기반 동기화(--syncmode=execution-layer) 중에는 unsafe_l2가 libp2p gossip을 통해 tip을 따라가는 반면, safe_l2와 finalized_l2는 0으로 유지됩니다. 이는 예상된 동작입니다. op-node는 op-reth가 단계별 동기화(staged sync)를 마칠 때까지 L1 derivation을 미룹니다. EL이 따라잡으면 derivation이 시작되고 safe/finalized head가 진행되기 시작합니다.

op-node 로그를 직접 확인할 수도 있습니다.

docker compose logs op-node | grep -E "Sync progress|Finished EL sync"

스냅샷에서 부트스트랩하기

처음부터 동기화하는 것은 OP Sepolia(~30–50 GB, 수 시간)에서는 괜찮지만 OP Mainnet(~700 GB, 수 일)에서는 느립니다. Mainnet의 경우, 또는 초기 동기화를 건너뛰고 싶을 때는 언제든지 사전 동기화된 스냅샷에서 op-reth를 부트스트랩하십시오.

OP Mainnet의 경우 스냅샷을 사용하면 Bedrock 이전 상태 요구 사항(이 페이지 상단의 경고 참고)도 한 번에 처리됩니다.

컨테이너 중지하기

docker compose down
rm -rf reth-data       # only if you previously synced and want to start clean

스냅샷 다운로드하기

datadirs.optimism.io에서 네트워크에 맞는 스냅샷을 찾아 최신 파일을 선택하십시오. 그런 다음 다운로드하고 SHA256을 검증합니다.

curl -fLO https://datadirs.optimism.io/<snapshot-file>.tar.zst

# Verify checksum against the value on the index page
sha256sum <snapshot-file>.tar.zst   # Linux
shasum -a 256 <snapshot-file>.tar.zst   # macOS

datadir에 압축 해제하기

bind mount된 디렉터리는 ./reth-data(docker-compose.yml 기준 상대 경로)입니다.

mkdir -p reth-data
tar -I zstd -xvf <snapshot-file>.tar.zst -C reth-data --strip-components=1

--strip-components=1은 tarball 내부의 최상위 래핑 디렉터리를 제거합니다. 먼저 tar -tf <snapshot-file>.tar.zst | head -3을 실행하여 확인하십시오. 파일이 이미 아카이브 루트에 있다면 --strip-components를 생략하십시오.

node 시작하기

docker compose up -d
docker compose logs -f op-reth

op-reth는 시작 시 기존 datadir을 인식하고 스냅샷의 tip부터 이어서 진행합니다. latest_block은 0이 아니라 스냅샷의 높이여야 합니다. 그런 다음 해당 tip에서 현재까지 따라잡습니다(스냅샷의 생성 시기에 따라 Sepolia는 수 분, Mainnet은 수 시간).

다음 단계

Node 메트릭 및 모니터링 가이드 — 메트릭 포트에 Prometheus/Grafana를 연결합니다.
Node 문제 해결 가이드 — 문제가 발생한 경우 참고하십시오.
소스에서 OP Stack node 빌드 및 실행하기 — 사용자 정의 빌드가 필요하거나 소스를 살펴보려는 경우 참고하십시오.

노드 실행

가이드

튜토리얼

클라이언트

참조

Docker로 node 실행하기

의존성

빠른 시작

검증

스냅샷에서 부트스트랩하기

다음 단계

​의존성

​빠른 시작

​검증

​스냅샷에서 부트스트랩하기

​다음 단계

의존성

빠른 시작

검증

스냅샷에서 부트스트랩하기

다음 단계