Plasma Docs - Build on Plasma

Les nœuds non validateurs fournissent un accès RPC au réseau Plasma en surveillant les clients de consensus et en servant les requêtes des applications. Ce guide couvre le déploiement à l’aide du dépôt officiel non-validator-templates.

Prérequis

Compétences de base en administration Linux

Docker et Docker Compose installés

Un serveur répondant aux exigences matérielles

Réseaux disponibles

Réseau	Chain ID	Version consensus	Version exécution
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

Tous les réseaux utilisent l’image publique plasma-consensus-public — aucune authentification GHCR n’est requise.

Démarrage rapide

Installer Docker

Connectez-vous à votre serveur et assurez-vous que Docker et Docker Compose sont installés.

Cloner le dépôt de templates

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

Démarrer votre nœud

Remplacez {network} par mainnet, testnet ou devnet :

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

Vérifier que les conteneurs fonctionnent

docker compose ps
docker compose logs -f plasma-consensus

Démarrer la surveillance (optionnel)

docker compose -f monitoring.yml up -d

Vue d’ensemble de l’architecture

Votre nœud non validateur est composé de deux composants principaux :

Client d'exécution Plasma

Basé sur Reth. Gère l’exécution des transactions, la gestion d’état et fournit des endpoints JSON-RPC aux applications.

Client observateur Plasma

Un client léger qui surveille le réseau de consensus Plasma sans participer à la production ou à la validation des blocs.

La configuration Docker Compose orchestre ces composants ainsi que des conteneurs d’initialisation qui gèrent automatiquement la génération du secret JWT, la génération des clés et la configuration de la base de données.

Structure du répertoire

Chaque répertoire de réseau suit la même structure :

{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

Processus d’installation expliqué

Le fichier Docker Compose définit quatre services qui s’exécutent en séquence :

Initialisation OpenSSL

Génère le secret JWT pour une communication sécurisée de l’Engine API et crée des clés secp256k1 pour l’identité réseau de votre nœud. Celles-ci ne sont générées qu’une seule fois et persistent à travers les redémarrages.

Initialisation de la base de données du consensus

Initialise la base de données du consensus avec la configuration du genesis pour le réseau choisi et génère un peer ID pour votre nœud.

Initialisation de la base de données d'exécution

Initialise la base de données d’exécution Reth avec l’état du genesis.

Déploiement des conteneurs

Une fois l’initialisation terminée, les clients d’exécution et de consensus démarrent. Le client d’exécution (Reth) démarre en premier et expose l’API JSON-RPC et l’Engine API. Le client observateur de consensus démarre après que le client d’exécution est en bonne santé et se connecte au réseau de consensus.

Configuration

Tous les numéros de version et tags d’image sont définis dans le fichier .env de chaque réseau — c’est la source unique de vérité pour les versions logicielles. Le client de consensus est configuré via non-validator.toml.

Référence de configuration du consensus (non-validator.toml)

Section	Champs	Description
(top-level)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	Connexion au moteur d’exécution
`[persistence]`	`data_dir`	Chemin de stockage des données de consensus
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	Réseau P2P et découverte des pairs
`[api]`	`enabled`, `host`, `port`	Endpoint de l’API consensus
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	Comité des validateurs
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	Pairs bootstrap du consensus

NAT / Adresse externe

Pour les nœuds derrière un NAT, configurez une adresse externe afin que les pairs puissent découvrir et se connecter à votre nœud :

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

Configuration des ports

Port	Service	Protocole	Description
`8545`	Exécution RPC	HTTP	Endpoint API JSON-RPC
`8551`	Exécution Auth	HTTP	Engine API (interne)
`30303`	Exécution P2P	TCP/UDP	Réseau peer-to-peer
`34070`	Consensus P2P	TCP	Réseau de consensus
`35070`	Consensus API	HTTP	Endpoint santé/API du consensus
`9001`	Metrics	HTTP	Métriques Prometheus

Exigences du pare-feu : Assurez-vous d’avoir un trafic entrant/sortant sur le port 30303 (TCP/UDP) pour le P2P d’exécution, entrant sur le port 34070 (TCP) pour le P2P de consensus, et la communication interne sur le port 8551 pour l’Engine API. L’interface JSON-RPC sur le port 8545 est exposée par défaut — envisagez de restreindre l’accès en production.

Opérations courantes

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

Surveillance de votre nœud

Une fois que votre nœud est opérationnel, vous pouvez surveiller sa santé et son statut de synchronisation. Pour une configuration de surveillance complète et les bonnes pratiques, consultez le guide de surveillance.

Vérifications de statut
Statut de synchronisation
Endpoints

# 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

Endpoint	URL
Exécution RPC	`http://localhost:8545`
Consensus API	`http://localhost:35070`
Metrics	`http://localhost:9001/metrics`

Votre nœud commencera à se synchroniser immédiatement. La synchronisation initiale peut prendre plusieurs minutes selon les conditions du réseau et les spécifications de votre matériel.

Snapshots de base de données

Plasma publie des snapshots quotidiens de la base de données pour le mainnet et le testnet. Les snapshots vous permettent d’amorcer un nouveau nœud en heures plutôt qu’en synchronisant depuis le genesis, ce qui peut prendre beaucoup plus de temps. Chaque snapshot contient deux fichiers — la base de données de la couche de consensus et la base de données de la couche d’exécution — téléchargés vers un bucket S3 requester-pays. Vous avez besoin d’un compte AWS ; les tarifs standard de transfert de données S3 s’appliquent.

Prérequis pour les snapshots

Exigence	Détails
Compte AWS	Identifiants configurés via `aws configure` ou variables d’environnement
AWS CLI	v2 recommandé (`aws --version`)
Espace disque	Mainnet : ~400 Go libres • Testnet : ~100 Go libres

Le transfert de données depuis us-east-2 coûte environ 0,09 $/Go pour les 10 premiers To/mois. Le transfert depuis une instance EC2 dans la même région est gratuit — exécuter votre nœud dans us-east-2 est l’option la plus économique.

Buckets de snapshots

Propriété	Mainnet	Testnet
Bucket	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
Région	`us-east-2` (Ohio)	`us-east-2` (Ohio)
Modèle d’accès	Requester-pays	Requester-pays
Cadence de sauvegarde	Quotidienne	Quotidienne à 02:00 UTC
Rétention	Glissante (anciennes sauvegardes supprimées automatiquement)	3 jours

Les sauvegardes sont organisées en dossiers datés (MM-DD-YY). Chaque dossier contient deux fichiers :

Fichier	Description
Base de données consensus (`.db` sur mainnet, `.mdb` sur testnet)	État complet de la couche de consensus
Base de données d’exécution (`.tar.gz`)	Archive tar du répertoire `data/` de l’exécution Reth

Télécharger un snapshot

# 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

Restaurer depuis un snapshot

Arrêter votre nœud

cd {network}/docker-compose
docker compose down

Restaurer la base de données du consensus

Copiez le snapshot dans le répertoire de données du consensus :

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

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

Restaurer la base de données d'exécution

Extrayez l’archive dans le répertoire de données d’exécution :

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

Redémarrer votre nœud

docker compose up -d

Dépannage des snapshots

Problème	Cause / Solution
`Access Denied`	Vous devez inclure `--request-payer requester` sur chaque commande. Le bucket rejette les requêtes sans cette option.
`403 Forbidden`	Identifiants AWS non configurés. Exécutez `aws sts get-caller-identity` pour vérifier que vous avez une session valide.
Liste de bucket vide	Les anciennes sauvegardes sont automatiquement nettoyées. Si le bucket apparaît vide, un cycle de sauvegarde peut être en cours — réessayez plus tard.
Mauvaise extension de fichier	Le mainnet utilise `.db` ; le testnet utilise `.mdb`. Assurez-vous de copier le bon fichier pour votre réseau.

​Prérequis

​Réseaux disponibles

​Démarrage rapide

​Vue d’ensemble de l’architecture

Client d'exécution Plasma

Client observateur Plasma

​Structure du répertoire

​Processus d’installation expliqué

​Configuration

​NAT / Adresse externe

​Configuration des ports

​Opérations courantes

​Surveillance de votre nœud

​Snapshots de base de données

​Prérequis pour les snapshots

​Buckets de snapshots

​Télécharger un snapshot

​Restaurer depuis un snapshot

​Dépannage des snapshots

Prérequis

Réseaux disponibles

Démarrage rapide

Vue d’ensemble de l’architecture

Structure du répertoire

Processus d’installation expliqué

Configuration

NAT / Adresse externe

Configuration des ports

Opérations courantes

Surveillance de votre nœud

Snapshots de base de données

Prérequis pour les snapshots

Buckets de snapshots

Télécharger un snapshot

Restaurer depuis un snapshot

Dépannage des snapshots