Plasma Docs - Build on Plasma

Los nodos no validadores brindan acceso RPC a la red Plasma monitoreando clientes de consenso y atendiendo solicitudes de aplicaciones. Esta guía cubre el despliegue usando el repositorio oficial non-validator-templates.

Requisitos previos

Habilidades básicas de administración de Linux

Docker y Docker Compose instalados

Un servidor que cumpla con los requisitos de hardware

Redes disponibles

Red	Chain ID	Versión de consenso	Versión de ejecución
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

Todas las redes usan la imagen pública plasma-consensus-public — no se requiere autenticación en GHCR.

Inicio rápido

Instala Docker

Conéctate a tu servidor y asegúrate de que Docker y Docker Compose estén instalados.

Clona el repositorio de templates

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

Inicia tu nodo

Reemplaza {network} con mainnet, testnet o devnet:

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

Verifica que los contenedores estén corriendo

docker compose ps
docker compose logs -f plasma-consensus

Inicia el monitoreo (opcional)

docker compose -f monitoring.yml up -d

Resumen de la arquitectura

Tu nodo no validador consta de dos componentes principales:

Cliente de ejecución de Plasma

Basado en Reth. Maneja la ejecución de transacciones, la gestión de estado y provee endpoints JSON-RPC para las aplicaciones.

Cliente observador de Plasma

Un cliente ligero que monitorea la red de consenso de Plasma sin participar en la producción de bloques ni en la validación.

La configuración de Docker Compose orquesta estos componentes junto con contenedores de inicialización que manejan automáticamente la generación de secretos JWT, la generación de claves y la configuración de la base de datos.

Estructura de directorios

Cada directorio de red sigue el mismo 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

Proceso de configuración explicado

El archivo Docker Compose define cuatro servicios que se ejecutan en secuencia:

Inicialización de OpenSSL

Genera el secreto JWT para la comunicación segura con la Engine API y crea claves secp256k1 para la identidad de red de tu nodo. Estas solo se generan una vez y persisten entre reinicios.

Inicialización de la base de datos de consenso

Inicializa la base de datos de consenso con la configuración de génesis para tu red elegida y genera un peer ID para tu nodo.

Inicialización de la base de datos de ejecución

Inicializa la base de datos de ejecución de Reth con el estado de génesis.

Despliegue de contenedores

Una vez completada la inicialización, los clientes de ejecución y consenso inician. El cliente de ejecución (Reth) inicia primero y expone la API JSON-RPC y la Engine API. El cliente observador de consenso inicia después de que el cliente de ejecución esté en buen estado y se conecta a la red de consenso.

Configuración

Todos los números de versión y tags de imágenes están definidos en el archivo .env de cada red — esta es la única fuente de verdad para las versiones de software. El cliente de consenso se configura a través de non-validator.toml.

Referencia de configuración de consenso (non-validator.toml)

Sección	Campos	Descripción
(nivel superior)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	Conexión con el motor de ejecución
`[persistence]`	`data_dir`	Ruta de almacenamiento de datos de consenso
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	Red P2P y descubrimiento de peers
`[api]`	`enabled`, `host`, `port`	Endpoint de la API de consenso
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	Comité de validadores
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	Peers bootstrap del consenso

NAT / Dirección externa

Para nodos detrás de NAT, configura una dirección externa para que los peers puedan descubrir y conectarse a tu nodo:

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

Configuración de puertos

Puerto	Servicio	Protocolo	Descripción
`8545`	RPC de ejecución	HTTP	Endpoint de la API JSON-RPC
`8551`	Auth de ejecución	HTTP	Engine API (interna)
`30303`	P2P de ejecución	TCP/UDP	Red peer-to-peer
`34070`	P2P de consenso	TCP	Red de consenso
`35070`	API de consenso	HTTP	Endpoint de salud/API del consenso
`9001`	Métricas	HTTP	Métricas de Prometheus

Requisitos de firewall: Asegúrate de tener tráfico entrante/saliente en el puerto 30303 (TCP/UDP) para el P2P de ejecución, entrante en el puerto 34070 (TCP) para el P2P de consenso, y comunicación interna en el puerto 8551 para la Engine API. La interfaz JSON-RPC en el puerto 8545 está expuesta por defecto — considera restringir el acceso en producción.

Operaciones comunes

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

Monitorea tu nodo

Una vez que tu nodo esté operativo, puedes monitorear su salud y estado de sincronización. Para la configuración completa de monitoreo y buenas prácticas, consulta la guía de monitoreo.

Verificaciones de estado
Estado de sincronización
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
RPC de ejecución	`http://localhost:8545`
API de consenso	`http://localhost:35070`
Métricas	`http://localhost:9001/metrics`

Tu nodo comenzará a sincronizar inmediatamente. La sincronización inicial puede tomar varios minutos dependiendo de las condiciones de la red y las especificaciones de tu hardware.

Instantáneas de la base de datos

Plasma publica instantáneas diarias de la base de datos para mainnet y testnet. Las instantáneas te permiten bootstrap un nuevo nodo en horas en lugar de sincronizar desde el génesis, lo cual puede tomar significativamente más tiempo. Cada instantánea contiene dos archivos — la base de datos de la capa de consenso y la base de datos de la capa de ejecución — subidos a un bucket S3 requester-pays. Necesitas una cuenta de AWS; se aplican las tarifas estándar de transferencia de datos de S3.

Requisitos previos para las instantáneas

Requisito	Detalles
Cuenta de AWS	Credenciales configuradas vía `aws configure` o variables de entorno
AWS CLI	Se recomienda v2 (`aws --version`)
Espacio en disco	Mainnet: ~400 GB libres • Testnet: ~100 GB libres

La transferencia de datos saliente desde us-east-2 cuesta ~$0,09/GB para los primeros 10 TB/mes. La transferencia desde una instancia EC2 en la misma región es gratuita — ejecutar tu nodo en us-east-2 es la opción más rentable.

Buckets de instantáneas

Propiedad	Mainnet	Testnet
Bucket	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
Región	`us-east-2` (Ohio)	`us-east-2` (Ohio)
Modelo de acceso	Requester-pays	Requester-pays
Cadencia de respaldo	Diaria	Diaria a las 02:00 UTC
Retención	Rolling (los respaldos antiguos se eliminan automáticamente)	3 días

Los respaldos se organizan en carpetas con sello de fecha (MM-DD-YY). Cada carpeta contiene dos archivos:

Archivo	Descripción
Base de datos de consenso (`.db` en mainnet, `.mdb` en testnet)	Estado completo de la capa de consenso
Base de datos de ejecución (`.tar.gz`)	Archivo tar del directorio `data/` de ejecución de Reth

Descargar una instantánea

# 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

Restaurar desde una instantánea

Detén tu nodo

cd {network}/docker-compose
docker compose down

Restaura la base de datos de consenso

Copia la instantánea al directorio de datos del consenso:

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

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

Restaura la base de datos de ejecución

Extrae el archivo al directorio de datos de ejecución:

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

Reinicia tu nodo

docker compose up -d

Solución de problemas de instantáneas

Problema	Causa / Solución
`Access Denied`	Debes incluir `--request-payer requester` en cada comando. El bucket rechaza solicitudes sin él.
`403 Forbidden`	Credenciales de AWS no configuradas. Ejecuta `aws sts get-caller-identity` para verificar que tienes una sesión válida.
Listado de bucket vacío	Los respaldos antiguos se limpian automáticamente. Si el bucket parece vacío, puede que un ciclo de respaldo esté en progreso — vuelve a verificar más tarde.
Extensión de archivo incorrecta	Mainnet usa `.db`; testnet usa `.mdb`. Asegúrate de copiar el archivo correcto para tu red.

​Requisitos previos

​Redes disponibles

​Inicio rápido

​Resumen de la arquitectura

Cliente de ejecución de Plasma

Cliente observador de Plasma

​Estructura de directorios

​Proceso de configuración explicado

​Configuración

​NAT / Dirección externa

​Configuración de puertos

​Operaciones comunes

​Monitorea tu nodo

​Instantáneas de la base de datos

​Requisitos previos para las instantáneas

​Buckets de instantáneas

​Descargar una instantánea

​Restaurar desde una instantánea

​Solución de problemas de instantáneas

Requisitos previos

Redes disponibles

Inicio rápido

Resumen de la arquitectura

Estructura de directorios

Proceso de configuración explicado

Configuración

NAT / Dirección externa

Configuración de puertos

Operaciones comunes

Monitorea tu nodo

Instantáneas de la base de datos

Requisitos previos para las instantáneas

Buckets de instantáneas

Descargar una instantánea

Restaurar desde una instantánea

Solución de problemas de instantáneas