Plasma Docs - Build on Plasma

Os nós não validadores fornecem acesso RPC à rede Plasma monitorando clientes de consenso e atendendo a solicitações de aplicações. Este guia cobre a implantação usando o repositório oficial non-validator-templates.

Pré-requisitos

Habilidades básicas de administração Linux

Docker e Docker Compose instalados

Um servidor que atenda aos requisitos de hardware

Redes Disponíveis

Rede	Chain ID	Versão de Consenso	Versão de Execução
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 as redes usam a imagem pública plasma-consensus-public — nenhuma autenticação do GHCR é necessária.

Início Rápido

Instale o Docker

Conecte-se ao seu servidor e garanta que o Docker e o Docker Compose estejam instalados.

Clone o repositório de templates

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

Inicie seu nó

Substitua {network} por mainnet, testnet ou devnet:

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

Verifique se os containers estão em execução

docker compose ps
docker compose logs -f plasma-consensus

Inicie o monitoramento (opcional)

docker compose -f monitoring.yml up -d

Visão Geral da Arquitetura

Seu nó não validador consiste em dois componentes principais:

Cliente de Execução Plasma

Baseado em Reth. Lida com execução de transações, gerenciamento de estado e fornece endpoints JSON-RPC para aplicações.

Cliente Observador da Plasma

Um cliente leve que monitora a rede de consenso da Plasma sem participar da produção ou validação de blocos.

A configuração do Docker Compose orquestra esses componentes junto com containers de inicialização que lidam com geração de JWT secret, geração de chaves e configuração de banco de dados automaticamente.

Estrutura de Diretórios

Cada diretório de rede segue o mesmo 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

Processo de Configuração Explicado

O arquivo Docker Compose define quatro serviços que são executados em sequência:

Inicialização do OpenSSL

Gera o JWT secret para comunicação segura via Engine API e cria chaves secp256k1 para a identidade de rede do seu nó. Estes são gerados apenas uma vez e persistem entre reinicializações.

Inicialização do Banco de Dados de Consenso

Inicializa o banco de dados de consenso com a configuração de gênesis para a rede escolhida e gera um peer ID para o seu nó.

Inicialização do Banco de Dados de Execução

Inicializa o banco de dados de execução do Reth com o estado de gênesis.

Implantação do Container

Assim que a inicialização for concluída, os clientes de execução e consenso são iniciados. O Cliente de Execução (Reth) inicia primeiro e expõe a API JSON-RPC e a Engine API. O Cliente Observador de Consenso inicia depois que o cliente de execução estiver saudável e se conecta à rede de consenso.

Configuração

Todos os números de versão e tags de imagem são definidos no arquivo .env de cada rede — esta é a fonte única de verdade para as versões de software. O cliente de consenso é configurado via non-validator.toml.

Referência de Configuração de Consenso (non-validator.toml)

Seção	Campos	Descrição
(top-level)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	Conexão com o motor de execução
`[persistence]`	`data_dir`	Caminho de armazenamento de dados de consenso
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	Rede P2P e descoberta de peers
`[api]`	`enabled`, `host`, `port`	Endpoint da 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 de bootstrap de consenso

NAT / Endereço Externo

Para nós atrás de NAT, configure um endereço externo para que os peers possam descobrir e se conectar ao seu nó:

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

Configuração de Portas

Porta	Serviço	Protocolo	Descrição
`8545`	RPC de Execução	HTTP	Endpoint da API JSON-RPC
`8551`	Auth de Execução	HTTP	Engine API (interna)
`30303`	P2P de Execução	TCP/UDP	Rede peer-to-peer
`34070`	P2P de Consenso	TCP	Rede de consenso
`35070`	API de Consenso	HTTP	Endpoint de saúde/API de consenso
`9001`	Métricas	HTTP	Métricas Prometheus

Requisitos de firewall: Garanta entrada/saída na porta 30303 (TCP/UDP) para P2P de execução, entrada na porta 34070 (TCP) para P2P de consenso e comunicação interna na porta 8551 para a Engine API. A interface JSON-RPC na porta 8545 é exposta por padrão — considere restringir o acesso em produção.

Operações Comuns

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

Monitorando seu Nó

Uma vez que seu nó esteja operacional, você pode monitorar sua saúde e status de sincronização. Para configuração abrangente de monitoramento e melhores práticas, consulte o guia de monitoramento.

Verificações de Status
Status de Sincronização
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 Execução	`http://localhost:8545`
API de Consenso	`http://localhost:35070`
Métricas	`http://localhost:9001/metrics`

Seu nó começará a sincronizar imediatamente. A sincronização inicial pode levar vários minutos, dependendo das condições da rede e das especificações de hardware.

Snapshots de Banco de Dados

A Plasma publica snapshots diários de banco de dados para mainnet e testnet. Os snapshots permitem fazer o bootstrap de um novo nó em horas, em vez de sincronizar a partir do gênesis, o que pode levar significativamente mais tempo. Cada snapshot contém dois arquivos — o banco de dados da camada de consenso e o banco de dados da camada de execução — carregados em um bucket S3 requester-pays. Você precisa de uma conta AWS; as tarifas padrão de transferência de dados S3 se aplicam.

Pré-requisitos para Snapshot

Requisito	Detalhes
Conta AWS	Credenciais configuradas via `aws configure` ou variáveis de ambiente
AWS CLI	v2 recomendada (`aws --version`)
Espaço em disco	Mainnet: ~400 GB livres • Testnet: ~100 GB livres

A transferência de dados para fora de us-east-2 custa ~US$ 0,09/GB para os primeiros 10 TB/mês. A transferência de uma instância EC2 na mesma região é gratuita — executar seu nó em us-east-2 é a opção mais econômica.

Buckets de Snapshot

Propriedade	Mainnet	Testnet
Bucket	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
Região	`us-east-2` (Ohio)	`us-east-2` (Ohio)
Modelo de acesso	Requester-pays	Requester-pays
Cadência de backup	Diária	Diária às 02:00 UTC
Retenção	Contínua (backups mais antigos removidos automaticamente)	3 dias

Os backups são organizados em pastas com data (MM-DD-YY). Cada pasta contém dois arquivos:

Arquivo	Descrição
Banco de dados de consenso (`.db` na mainnet, `.mdb` na testnet)	Estado completo da camada de consenso
Banco de dados de execução (`.tar.gz`)	Arquivo tar do diretório `data/` de execução do Reth

Baixe um 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

Restaurar a Partir de Snapshot

Pare seu nó

cd {network}/docker-compose
docker compose down

Restaure o banco de dados de consenso

Copie o snapshot para o diretório de dados de 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/

Restaure o banco de dados de execução

Extraia o arquivo para o diretório de dados de execução:

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

Reinicie seu nó

docker compose up -d

Solução de Problemas de Snapshot

Problema	Causa / Correção
`Access Denied`	Você deve incluir `--request-payer requester` em cada comando. O bucket rejeita solicitações sem isso.
`403 Forbidden`	Credenciais AWS não configuradas. Execute `aws sts get-caller-identity` para verificar se você tem uma sessão válida.
Listagem de bucket vazia	Backups mais antigos são limpos automaticamente. Se o bucket parecer vazio, um ciclo de backup pode estar em andamento — verifique novamente mais tarde.
Extensão de arquivo incorreta	A mainnet usa `.db`; a testnet usa `.mdb`. Garanta que você copie o arquivo correto para sua rede.

​Pré-requisitos

​Redes Disponíveis

​Início Rápido

​Visão Geral da Arquitetura

Cliente de Execução Plasma

Cliente Observador da Plasma

​Estrutura de Diretórios

​Processo de Configuração Explicado

​Configuração

​NAT / Endereço Externo

​Configuração de Portas

​Operações Comuns

​Monitorando seu Nó

​Snapshots de Banco de Dados

​Pré-requisitos para Snapshot

​Buckets de Snapshot

​Baixe um Snapshot

​Restaurar a Partir de Snapshot

​Solução de Problemas de Snapshot

Pré-requisitos

Redes Disponíveis

Início Rápido

Visão Geral da Arquitetura

Estrutura de Diretórios

Processo de Configuração Explicado

Configuração

NAT / Endereço Externo

Configuração de Portas

Operações Comuns

Monitorando seu Nó

Snapshots de Banco de Dados

Pré-requisitos para Snapshot

Buckets de Snapshot

Baixe um Snapshot

Restaurar a Partir de Snapshot

Solução de Problemas de Snapshot