Plasma Docs - Build on Plasma

비검증 노드는 합의 클라이언트를 모니터링하고 애플리케이션 요청을 제공하여 Plasma 네트워크에 RPC 접근을 제공합니다. 이 가이드는 공식 non-validator-templates 저장소를 사용한 배포를 다룹니다.

사전 요구 사항

기본 Linux 관리 기술

Docker 및 Docker Compose 설치

하드웨어 요구 사항을 충족하는 서버

사용 가능한 네트워크

네트워크	체인 ID	합의 버전	실행 버전
mainnet	9745	0.15.0	Reth v1.8.3
testnet	9746	0.15.0	Reth v1.8.3
devnet	9747	0.15.0	Reth v1.8.3

모든 네트워크는 공개 plasma-consensus-public 이미지를 사용합니다 — GHCR 인증이 필요하지 않습니다.

빠른 시작

Docker 설치

서버에 연결하고 Docker와 Docker Compose가 설치되어 있는지 확인합니다.

템플릿 저장소 복제

git clone https://github.com/PlasmaLaboratories/non-validator-templates.git
cd non-validator-templates

노드 시작

{network}를 mainnet, testnet 또는 devnet으로 바꿉니다:

cd {network}/docker-compose
docker compose up -d

컨테이너 실행 확인

docker compose ps
docker compose logs -f plasma-consensus

모니터링 시작 (선택 사항)

docker compose -f monitoring.yml up -d

아키텍처 개요

비검증 노드는 두 가지 주요 구성 요소로 구성됩니다:

Plasma 실행 클라이언트

Reth 기반. 트랜잭션 실행, 상태 관리를 처리하며 애플리케이션을 위한 JSON-RPC 엔드포인트를 제공합니다.

Plasma 옵저버 클라이언트

블록 생성이나 검증에 참여하지 않고 Plasma 합의 네트워크를 모니터링하는 가벼운 클라이언트입니다.

Docker Compose 설정은 JWT 시크릿 생성, 키 생성 및 데이터베이스 설정을 자동으로 처리하는 초기화 컨테이너와 함께 이러한 구성 요소를 조율합니다.

디렉터리 구조

각 네트워크 디렉터리는 동일한 레이아웃을 따릅니다:

{network}/
├── docker-compose/
│   ├── docker-compose.yml        # 서비스 정의
│   ├── .env                      # 이미지 버전 및 태그 (단일 소스)
│   ├── non-validator.toml        # 합의 구성
│   ├── enodes.txt                # 실행 부트스트랩 노드
│   ├── monitoring.yml            # 모니터링 스택
│   └── monitoring/               # Prometheus & Grafana 구성
└── shared/                       # 검증자 키 & 신원 (읽기 전용)
    ├── keys/                     # BLS12-381 검증자 공개 키
    └── identities/               # 검증자 신원 파일

설정 프로세스 설명

Docker Compose 파일은 순차적으로 실행되는 네 가지 서비스를 정의합니다:

OpenSSL 초기화

안전한 Engine API 통신을 위한 JWT 시크릿을 생성하고 노드의 네트워크 신원을 위한 secp256k1 키를 만듭니다. 이는 한 번만 생성되고 재시작 시에도 유지됩니다.

합의 데이터베이스 초기화

선택한 네트워크의 제네시스 구성으로 합의 데이터베이스를 초기화하고 노드용 피어 ID를 생성합니다.

실행 데이터베이스 초기화

제네시스 상태로 Reth 실행 데이터베이스를 초기화합니다.

컨테이너 배포

초기화가 완료되면 실행 및 합의 클라이언트가 시작됩니다. **실행 클라이언트(Reth)**가 먼저 시작되어 JSON-RPC API와 Engine API를 노출합니다. 합의 옵저버 클라이언트는 실행 클라이언트가 정상 상태가 된 후 시작되어 합의 네트워크에 연결됩니다.

구성

모든 버전 번호와 이미지 태그는 각 네트워크의 .env 파일에 정의되어 있으며, 이는 소프트웨어 버전의 단일 진실 원천입니다. 합의 클라이언트는 non-validator.toml을 통해 구성됩니다.

합의 구성 참조 (non-validator.toml)

섹션	필드	설명
(최상위)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	실행 엔진 연결
`[persistence]`	`data_dir`	합의 데이터 저장 경로
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	P2P 네트워킹 및 피어 디스커버리
`[api]`	`enabled`, `host`, `port`	합의 API 엔드포인트
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	검증자 위원회
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	합의 부트스트랩 피어

NAT / 외부 주소

NAT 뒤에 있는 노드의 경우, 피어가 노드를 발견하고 연결할 수 있도록 외부 주소를 구성하세요:

[network]
external_address = "node.example.com:34070"

--p2p.external-address node.example.com:34070

포트 구성

포트	서비스	프로토콜	설명
`8545`	실행 RPC	HTTP	JSON-RPC API 엔드포인트
`8551`	실행 인증	HTTP	Engine API (내부)
`30303`	실행 P2P	TCP/UDP	P2P 네트워킹
`34070`	합의 P2P	TCP	합의 네트워킹
`35070`	합의 API	HTTP	합의 상태/API 엔드포인트
`9001`	메트릭	HTTP	Prometheus 메트릭

방화벽 요구 사항: 실행 P2P를 위해 포트 30303(TCP/UDP)의 인바운드/아웃바운드를, 합의 P2P를 위해 포트 34070(TCP)의 인바운드를, Engine API를 위해 포트 8551의 내부 통신을 보장하세요. JSON-RPC 인터페이스(포트 8545)는 기본적으로 노출되며 — 프로덕션에서는 접근 제한을 고려하세요.

일반 작업

cd {network}/docker-compose

docker compose up -d                              # 시작
docker compose -f monitoring.yml up -d            # 모니터링 시작
docker compose logs -f                            # 로그
docker compose down                               # 중지
docker compose -f monitoring.yml down             # 모니터링 중지
docker compose down -v && docker compose up -d    # 클린 재시작

노드 모니터링

노드가 운영되면 상태와 동기화 상태를 모니터링할 수 있습니다. 종합적인 모니터링 설정과 모범 사례는 모니터링 가이드를 참조하세요.

상태 확인
동기화 상태
엔드포인트

# 컨테이너 상태 확인
docker compose ps

# 실행 클라이언트 로그 보기
docker compose logs -f plasma-execution

# 합의 옵저버 클라이언트 로그 보기
docker compose logs -f plasma-consensus

# 실행 클라이언트 동기화 상태 확인
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545

엔드포인트	URL
실행 RPC	`http://localhost:8545`
합의 API	`http://localhost:35070`
메트릭	`http://localhost:9001/metrics`

노드는 즉시 동기화를 시작합니다. 초기 동기화는 네트워크 조건과 하드웨어 사양에 따라 수 분이 걸릴 수 있습니다.

데이터베이스 스냅샷

Plasma는 mainnet과 testnet에 대해 일일 데이터베이스 스냅샷을 게시합니다. 스냅샷은 제네시스부터 동기화하는 대신 새 노드를 몇 시간 안에 부트스트랩할 수 있게 해주며, 제네시스부터 동기화는 상당히 더 오래 걸릴 수 있습니다. 각 스냅샷에는 두 개의 파일 — 합의 계층 데이터베이스와 실행 계층 데이터베이스 — 이 포함되어 있으며, 요청자 지불 S3 버킷에 업로드됩니다. AWS 계정이 필요하며 표준 S3 데이터 전송 요금이 적용됩니다.

스냅샷 사전 요구 사항

요구 사항	세부 사항
AWS 계정	`aws configure` 또는 환경 변수를 통해 구성된 자격 증명
AWS CLI	v2 권장 (`aws --version`)
디스크 공간	Mainnet: 약 400 GB 여유 • Testnet: 약 100 GB 여유

us-east-2에서의 데이터 전송 비용은 첫 10 TB/월에 대해 약 $0.09/GB입니다. 같은 리전의 EC2 인스턴스에서 전송하는 것은 무료이므로 — us-east-2에서 노드를 실행하는 것이 가장 비용 효율적입니다.

스냅샷 버킷

속성	Mainnet	Testnet
버킷	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
리전	`us-east-2` (Ohio)	`us-east-2` (Ohio)
액세스 모델	요청자 지불	요청자 지불
백업 주기	일일	매일 02:00 UTC
보존	롤링 (오래된 백업은 자동으로 제거됨)	3일

백업은 날짜 스탬프 폴더(MM-DD-YY)로 정리됩니다. 각 폴더에는 두 개의 파일이 포함됩니다:

파일	설명
합의 데이터베이스 (mainnet은 `.db`, testnet은 `.mdb`)	전체 합의 계층 상태
실행 데이터베이스 (`.tar.gz`)	Reth 실행 `data/` 디렉터리의 Tar 아카이브

스냅샷 다운로드

# 대상 네트워크의 버킷 설정
BUCKET="plasma-mainnet-db-backups"   # 또는 "plasma-testnet-db-backups"

# 사용 가능한 스냅샷 목록
aws s3 ls "s3://${BUCKET}/" \
  --region us-east-2 \
  --request-payer requester

# 최신 스냅샷 다운로드
DATE="MM-DD-YY"   # 최신 날짜 폴더로 교체 (예: 03-23-26)

aws s3 cp \
  "s3://${BUCKET}/${DATE}/" \
  ./backups/ \
  --recursive \
  --region us-east-2 \
  --request-payer requester

스냅샷에서 복원

노드 중지

cd {network}/docker-compose
docker compose down

합의 데이터베이스 복원

스냅샷을 합의 데이터 디렉터리에 복사합니다:

# Mainnet (.db)
cp backups/consensus-backup-*.db /path/to/plasma-data-dir/

# Testnet (.mdb)
cp backups/consensus-backup-*.mdb /path/to/plasma-data-dir/

실행 데이터베이스 복원

아카이브를 실행 데이터 디렉터리로 추출합니다:

tar -xzf backups/execution-backup-*.tar.gz -C /path/to/execution-data-dir/

노드 재시작

docker compose up -d

스냅샷 문제 해결

문제	원인 / 해결
`Access Denied`	모든 명령에 `--request-payer requester`를 포함해야 합니다. 버킷은 그것 없이는 요청을 거부합니다.
`403 Forbidden`	AWS 자격 증명이 구성되지 않았습니다. 유효한 세션이 있는지 확인하려면 `aws sts get-caller-identity`를 실행하세요.
빈 버킷 목록	오래된 백업은 자동으로 정리됩니다. 버킷이 비어 있어 보이면 백업 주기가 진행 중일 수 있습니다 — 나중에 다시 확인하세요.
잘못된 파일 확장자	Mainnet은 `.db`를 사용하고 testnet은 `.mdb`를 사용합니다. 네트워크에 맞는 파일을 복사하세요.

설정 및 구성

유지관리

컨센서스 노드

비검증 노드 설정

사전 요구 사항

사용 가능한 네트워크

빠른 시작

아키텍처 개요

Plasma 실행 클라이언트

Plasma 옵저버 클라이언트

디렉터리 구조

설정 프로세스 설명

구성

NAT / 외부 주소

포트 구성

일반 작업

노드 모니터링

데이터베이스 스냅샷

스냅샷 사전 요구 사항

스냅샷 버킷

스냅샷 다운로드

스냅샷에서 복원

스냅샷 문제 해결

​사전 요구 사항

​사용 가능한 네트워크

​빠른 시작

​아키텍처 개요

Plasma 실행 클라이언트

Plasma 옵저버 클라이언트

​디렉터리 구조

​설정 프로세스 설명

​구성

​NAT / 외부 주소

​포트 구성

​일반 작업

​노드 모니터링

​데이터베이스 스냅샷

​스냅샷 사전 요구 사항

​스냅샷 버킷

​스냅샷 다운로드

​스냅샷에서 복원

​스냅샷 문제 해결

사전 요구 사항

사용 가능한 네트워크

빠른 시작

아키텍처 개요

디렉터리 구조

설정 프로세스 설명

구성

NAT / 외부 주소

포트 구성

일반 작업

노드 모니터링

데이터베이스 스냅샷

스냅샷 사전 요구 사항

스냅샷 버킷

스냅샷 다운로드

스냅샷에서 복원

스냅샷 문제 해결