Plasma Docs - Build on Plasma

Non-Validator-Nodes bieten RPC-Zugriff auf das Plasma-Netzwerk, indem sie Konsens-Clients überwachen und Anwendungsanfragen bedienen. Dieser Leitfaden behandelt das Deployment mit dem offiziellen non-validator-templates-Repository.

Voraussetzungen

Grundlegende Linux-Administrationskenntnisse

Docker und Docker Compose installiert

Ein Server, der die Hardware-Anforderungen erfüllt

Verfügbare Netzwerke

Netzwerk	Chain ID	Konsens-Version	Ausführungs-Version
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

Alle Netzwerke nutzen das öffentliche plasma-consensus-public-Image — es ist keine GHCR-Authentifizierung erforderlich.

Schnellstart

Docker installieren

Verbinden Sie sich mit Ihrem Server und stellen Sie sicher, dass Docker und Docker Compose installiert sind.

Templates-Repository klonen

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

Ihren Node starten

Ersetzen Sie {network} durch mainnet, testnet oder devnet:

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

Container-Status überprüfen

docker compose ps
docker compose logs -f plasma-consensus

Monitoring starten (optional)

docker compose -f monitoring.yml up -d

Architekturüberblick

Ihr Non-Validator-Node besteht aus zwei Hauptkomponenten:

Plasma Execution Client

Basiert auf Reth. Behandelt Transaktionsausführung, State-Verwaltung und stellt JSON-RPC-Endpunkte für Anwendungen bereit.

Plasma Observer Client

Ein leichtgewichtiger Client, der das Plasma-Konsensnetzwerk überwacht, ohne an der Blockproduktion oder Validierung teilzunehmen.

Das Docker-Compose-Setup orchestriert diese Komponenten zusammen mit Initialisierungscontainern, die JWT-Geheimnisgenerierung, Schlüsselgenerierung und Datenbank-Setup automatisch übernehmen.

Verzeichnisstruktur

Jedes Netzwerkverzeichnis folgt demselben Layout:

{network}/
├── docker-compose/
│   ├── docker-compose.yml        # Service definitions
│   ├── .env                      # Image versions and tags (source of truth)
│   ├── non-validator.toml        # Consensus configuration
│   ├── enodes.txt                # Execution bootstrap nodes
│   ├── monitoring.yml            # Monitoring stack
│   └── monitoring/               # Prometheus & Grafana configs
└── shared/                       # Validator keys & identities (read-only)
    ├── keys/                     # BLS12-381 validator public keys
    └── identities/               # Validator identity files

Setup-Prozess erklärt

Die Docker-Compose-Datei definiert vier Dienste, die sequenziell ausgeführt werden:

OpenSSL-Initialisierung

Generiert das JWT-Geheimnis für sichere Engine-API-Kommunikation und erstellt secp256k1-Schlüssel für die Netzwerkidentität Ihres Nodes. Diese werden nur einmal generiert und bleiben über Neustarts hinweg bestehen.

Konsens-Datenbank-Initialisierung

Initialisiert die Konsens-Datenbank mit der Genesis-Konfiguration für Ihr gewähltes Netzwerk und generiert eine Peer-ID für Ihren Node.

Ausführungs-Datenbank-Initialisierung

Initialisiert die Reth-Ausführungsdatenbank mit dem Genesis-State.

Container-Deployment

Sobald die Initialisierung abgeschlossen ist, starten die Ausführungs- und Konsens-Clients. Execution Client (Reth) startet zuerst und stellt die JSON-RPC-API und Engine-API bereit. Consensus Observer Client startet, nachdem der Execution Client gesund ist, und verbindet sich mit dem Konsensnetzwerk.

Konfiguration

Alle Versionsnummern und Image-Tags sind in der .env-Datei jedes Netzwerks definiert — dies ist die einzige Quelle der Wahrheit für Software-Versionen. Der Konsens-Client wird über non-validator.toml konfiguriert.

Konsens-Konfigurationsreferenz (non-validator.toml)

Abschnitt	Felder	Beschreibung
(top-level)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	Verbindung zur Ausführungs-Engine
`[persistence]`	`data_dir`	Speicherpfad für Konsensdaten
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	P2P-Networking und Peer-Discovery
`[api]`	`enabled`, `host`, `port`	Konsens-API-Endpunkt
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	Validator-Komitee
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	Konsens-Bootstrap-Peers

NAT / Externe Adresse

Für Nodes hinter NAT konfigurieren Sie eine externe Adresse, damit Peers Ihren Node entdecken und sich verbinden können:

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

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

Port-Konfiguration

Port	Service	Protokoll	Beschreibung
`8545`	Execution RPC	HTTP	JSON-RPC-API-Endpunkt
`8551`	Execution Auth	HTTP	Engine-API (intern)
`30303`	Execution P2P	TCP/UDP	Peer-to-Peer-Networking
`34070`	Consensus P2P	TCP	Konsens-Networking
`35070`	Consensus API	HTTP	Konsens-Health/API-Endpunkt
`9001`	Metrics	HTTP	Prometheus-Metriken

Firewall-Anforderungen: Stellen Sie eingehenden/ausgehenden Verkehr auf Port 30303 (TCP/UDP) für Execution-P2P, eingehenden Verkehr auf Port 34070 (TCP) für Konsens-P2P und interne Kommunikation auf Port 8551 für die Engine-API sicher. Die JSON-RPC-Schnittstelle auf Port 8545 ist standardmäßig exponiert — erwägen Sie, den Zugriff in der Produktion einzuschränken.

Häufige Operationen

cd {network}/docker-compose

docker compose up -d                              # Start
docker compose -f monitoring.yml up -d            # Start monitoring
docker compose logs -f                            # Logs
docker compose down                               # Stop
docker compose -f monitoring.yml down             # Stop monitoring
docker compose down -v && docker compose up -d    # Clean restart

Ihren Node überwachen

Sobald Ihr Node in Betrieb ist, können Sie Gesundheit und Synchronisierungsstatus überwachen. Für umfassende Monitoring-Einrichtung und bewährte Praktiken siehe den Monitoring-Leitfaden.

Statusprüfungen
Sync-Status
Endpunkte

# Check container status
docker compose ps

# View execution client logs
docker compose logs -f plasma-execution

# View consensus observer client logs
docker compose logs -f plasma-consensus

# Check execution client sync status
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545

Endpunkt	URL
Execution RPC	`http://localhost:8545`
Consensus API	`http://localhost:35070`
Metrics	`http://localhost:9001/metrics`

Ihr Node beginnt sofort mit der Synchronisierung. Die initiale Sync kann je nach Netzwerkbedingungen und Hardware mehrere Minuten dauern.

Datenbank-Snapshots

Plasma veröffentlicht tägliche Datenbank-Snapshots für Mainnet und Testnet. Snapshots ermöglichen es Ihnen, einen neuen Node in Stunden statt in deutlich längerer Zeit ab Genesis hochzufahren. Jeder Snapshot enthält zwei Dateien — die Konsens-Schicht-Datenbank und die Ausführungs-Schicht-Datenbank — hochgeladen in einen Requester-Pays-S3-Bucket. Sie benötigen ein AWS-Konto; es gelten Standard-S3-Datenübertragungsraten.

Snapshot-Voraussetzungen

Voraussetzung	Details
AWS-Konto	Anmeldedaten über `aws configure` oder Umgebungsvariablen konfiguriert
AWS CLI	v2 empfohlen (`aws --version`)
Speicherplatz	Mainnet: ~400 GB frei • Testnet: ~100 GB frei

Der Datenausgangstransfer aus us-east-2 kostet ~0,09 $/GB für die ersten 10 TB/Monat. Der Transfer von einer EC2-Instanz in derselben Region ist kostenlos — Ihren Node in us-east-2 zu betreiben, ist die kostengünstigste Option.

Snapshot-Buckets

Eigenschaft	Mainnet	Testnet
Bucket	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
Region	`us-east-2` (Ohio)	`us-east-2` (Ohio)
Zugangsmodell	Requester-Pays	Requester-Pays
Backup-Frequenz	Täglich	Täglich um 02:00 UTC
Aufbewahrung	Rollend (ältere Backups werden automatisch entfernt)	3 Tage

Backups sind in datums-gestempelten Ordnern (MM-DD-YY) organisiert. Jeder Ordner enthält zwei Dateien:

Datei	Beschreibung
Konsens-Datenbank (`.db` auf Mainnet, `.mdb` auf Testnet)	Vollständiger Konsens-Schicht-State
Ausführungs-Datenbank (`.tar.gz`)	Tar-Archiv des Reth-Ausführungs-`data/`-Verzeichnisses

Snapshot herunterladen

# Set your target network's bucket
BUCKET="plasma-mainnet-db-backups"   # or "plasma-testnet-db-backups"

# List available snapshots
aws s3 ls "s3://${BUCKET}/" \
  --region us-east-2 \
  --request-payer requester

# Download the most recent snapshot
DATE="MM-DD-YY"   # replace with the latest date folder (e.g. 03-23-26)

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

Aus Snapshot wiederherstellen

Ihren Node stoppen

cd {network}/docker-compose
docker compose down

Konsens-Datenbank wiederherstellen

Kopieren Sie den Snapshot in das Konsens-Datenverzeichnis:

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

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

Ausführungs-Datenbank wiederherstellen

Extrahieren Sie das Archiv in das Ausführungs-Datenverzeichnis:

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

Ihren Node neu starten

docker compose up -d

Snapshot-Fehlerbehebung

Problem	Ursache / Lösung
`Access Denied`	Sie müssen `--request-payer requester` in jedem Befehl angeben. Der Bucket lehnt Anfragen ohne dies ab.
`403 Forbidden`	AWS-Anmeldedaten nicht konfiguriert. Führen Sie `aws sts get-caller-identity` aus, um eine gültige Sitzung zu überprüfen.
Leere Bucket-Auflistung	Ältere Backups werden automatisch bereinigt. Erscheint der Bucket leer, läuft möglicherweise gerade ein Backup-Zyklus — versuchen Sie es später erneut.
Falsche Dateiendung	Mainnet verwendet `.db`; Testnet verwendet `.mdb`. Stellen Sie sicher, dass Sie die richtige Datei für Ihr Netzwerk kopieren.

Setup & Konfiguration

Wartung

Konsens-Node

Non-Validator-Node-Einrichtung

Voraussetzungen

Verfügbare Netzwerke

Schnellstart

Architekturüberblick

Plasma Execution Client

Plasma Observer Client

Verzeichnisstruktur

Setup-Prozess erklärt

Konfiguration

NAT / Externe Adresse

Port-Konfiguration

Häufige Operationen

Ihren Node überwachen

Datenbank-Snapshots

Snapshot-Voraussetzungen

Snapshot-Buckets

Snapshot herunterladen

Aus Snapshot wiederherstellen

Snapshot-Fehlerbehebung

​Voraussetzungen

​Verfügbare Netzwerke

​Schnellstart

​Architekturüberblick

Plasma Execution Client

Plasma Observer Client

​Verzeichnisstruktur

​Setup-Prozess erklärt

​Konfiguration

​NAT / Externe Adresse

​Port-Konfiguration

​Häufige Operationen

​Ihren Node überwachen

​Datenbank-Snapshots

​Snapshot-Voraussetzungen

​Snapshot-Buckets

​Snapshot herunterladen

​Aus Snapshot wiederherstellen

​Snapshot-Fehlerbehebung

Voraussetzungen

Verfügbare Netzwerke

Schnellstart

Architekturüberblick

Verzeichnisstruktur

Setup-Prozess erklärt

Konfiguration

NAT / Externe Adresse

Port-Konfiguration

Häufige Operationen

Ihren Node überwachen

Datenbank-Snapshots

Snapshot-Voraussetzungen

Snapshot-Buckets

Snapshot herunterladen

Aus Snapshot wiederherstellen

Snapshot-Fehlerbehebung