> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plasma.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração de Nó Não Validador

> Guia completo para configurar e executar nós não validadores com Docker Compose.

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](https://github.com/PlasmaLaboratories/non-validator-templates).

## Pré-requisitos

<Check>Habilidades básicas de administração Linux</Check>
<Check>Docker e Docker Compose instalados</Check>
<Check>Um servidor que atenda aos [requisitos de hardware](./hardware-requirements)</Check>

## 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

<Steps>
  <Step title="Instale o Docker">
    Conecte-se ao seu servidor e garanta que o **Docker** e o **Docker Compose** estejam instalados.
  </Step>

  <Step title="Clone o repositório de templates">
    ```bash theme={null}
    git clone https://github.com/PlasmaLaboratories/non-validator-templates.git
    cd non-validator-templates
    ```
  </Step>

  <Step title="Inicie seu nó">
    Substitua `{network}` por `mainnet`, `testnet` ou `devnet`:

    ```bash theme={null}
    cd {network}/docker-compose
    docker compose up -d
    ```
  </Step>

  <Step title="Verifique se os containers estão em execução">
    ```bash theme={null}
    docker compose ps
    docker compose logs -f plasma-consensus
    ```
  </Step>

  <Step title="Inicie o monitoramento (opcional)">
    ```bash theme={null}
    docker compose -f monitoring.yml up -d
    ```
  </Step>
</Steps>

## Visão Geral da Arquitetura

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

<CardGroup cols={2}>
  <Card title="Cliente de Execução Plasma" icon="microchip">
    Baseado em [Reth](https://github.com/paradigmxyz/reth). Lida com execução de transações, gerenciamento de estado e fornece endpoints JSON-RPC para aplicações.
  </Card>

  <Card title="Cliente Observador da Plasma" icon="satellite-dish">
    Um cliente leve que monitora a rede de consenso da Plasma sem participar da produção ou validação de blocos.
  </Card>
</CardGroup>

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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ó.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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`.

<Accordion title="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                |
</Accordion>

### 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ó:

<CodeGroup>
  ```toml non-validator.toml theme={null}
  [network]
  external_address = "node.example.com:34070"
  ```

  ```bash CLI theme={null}
  --p2p.external-address node.example.com:34070
  ```
</CodeGroup>

### 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               |

<Warning>
  **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.
</Warning>

## Operações Comuns

```bash theme={null}
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](../maintenance/monitoring).

<Tabs>
  <Tab title="Verificações de Status">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Status de Sincronização">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Endpoints">
    | Endpoint        | URL                             |
    | --------------- | ------------------------------- |
    | RPC de Execução | `http://localhost:8545`         |
    | API de Consenso | `http://localhost:35070`        |
    | Métricas        | `http://localhost:9001/metrics` |
  </Tab>
</Tabs>

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           |

<Info>
  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.
</Info>

### 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

```bash theme={null}
# 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

<Steps>
  <Step title="Pare seu nó">
    ```bash theme={null}
    cd {network}/docker-compose
    docker compose down
    ```
  </Step>

  <Step title="Restaure o banco de dados de consenso">
    Copie o snapshot para o diretório de dados de consenso:

    ```bash theme={null}
    # Mainnet (.db)
    cp backups/consensus-backup-*.db /path/to/plasma-data-dir/

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

  <Step title="Restaure o banco de dados de execução">
    Extraia o arquivo para o diretório de dados de execução:

    ```bash theme={null}
    tar -xzf backups/execution-backup-*.tar.gz -C /path/to/execution-data-dir/
    ```
  </Step>

  <Step title="Reinicie seu nó">
    ```bash theme={null}
    docker compose up -d
    ```
  </Step>
</Steps>

### 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.                                                       |