Plasma Docs - Build on Plasma

Не-валидирующие ноды обеспечивают RPC-доступ к сети Plasma, отслеживая клиенты консенсуса и обслуживая запросы приложений. В этом руководстве описано развёртывание с использованием официального репозитория non-validator-templates.

Предварительные требования

Базовые навыки администрирования Linux

Установлены Docker и Docker Compose

Сервер, отвечающий требованиям к оборудованию

Доступные сети

Сеть	Chain ID	Версия консенсуса	Версия исполнения
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

Все сети используют публичный образ plasma-consensus-public — аутентификация GHCR не требуется.

Быстрый старт

Установите Docker

Подключитесь к серверу и убедитесь, что Docker и Docker Compose установлены.

Клонируйте репозиторий шаблонов

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

Запустите ноду

Замените {network} на mainnet, testnet или devnet:

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

Убедитесь, что контейнеры запущены

docker compose ps
docker compose logs -f plasma-consensus

Запустите мониторинг (опционально)

docker compose -f monitoring.yml up -d

Обзор архитектуры

Ваша не-валидирующая нода состоит из двух основных компонентов:

Plasma Execution Client

На основе Reth. Обрабатывает исполнение транзакций, управление состоянием и предоставляет JSON-RPC точки для приложений.

Plasma Observer Client

Лёгкий клиент, который отслеживает сеть консенсуса Plasma без участия в производстве или валидации блоков.

Настройка Docker Compose оркестрирует эти компоненты вместе с инициализационными контейнерами, которые автоматически выполняют генерацию JWT-секрета, генерацию ключей и настройку базы данных.

Структура каталогов

Каждый каталог сети имеет одинаковую структуру:

{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

Процесс настройки

Файл Docker Compose определяет четыре сервиса, которые запускаются последовательно:

Инициализация OpenSSL

Генерирует JWT-секрет для безопасной коммуникации Engine API и создаёт secp256k1-ключи для сетевой идентичности ноды. Они генерируются только один раз и сохраняются между перезапусками.

Инициализация базы данных консенсуса

Инициализирует базу данных консенсуса с конфигурацией genesis для выбранной сети и генерирует peer ID для вашей ноды.

Инициализация базы данных исполнения

Инициализирует базу данных исполнения Reth с состоянием genesis.

Развёртывание контейнеров

После завершения инициализации запускаются клиенты исполнения и консенсуса. Клиент исполнения (Reth) запускается первым и предоставляет JSON-RPC API и Engine API. Клиент-наблюдатель консенсуса запускается после того, как клиент исполнения становится здоровым, и подключается к сети консенсуса.

Конфигурация

Все номера версий и теги образов определены в файле .env каждой сети — это единый источник истины для версий программного обеспечения. Клиент консенсуса настраивается через non-validator.toml.

Справочник конфигурации консенсуса (non-validator.toml)

Раздел	Поля	Описание
(верхний уровень)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	Подключение к движку исполнения
`[persistence]`	`data_dir`	Путь хранения данных консенсуса
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	P2P-сети и обнаружение пиров
`[api]`	`enabled`, `host`, `port`	Точка API консенсуса
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	Комитет валидаторов
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	Bootstrap-пиры консенсуса

NAT / Внешний адрес

Для нод за NAT настройте внешний адрес, чтобы пиры могли обнаруживать вашу ноду и подключаться к ней:

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

Конфигурация портов

Порт	Сервис	Протокол	Описание
`8545`	Execution RPC	HTTP	JSON-RPC API endpoint
`8551`	Execution Auth	HTTP	Engine API (внутренний)
`30303`	Execution P2P	TCP/UDP	P2P-сети
`34070`	Consensus P2P	TCP	Сети консенсуса
`35070`	Consensus API	HTTP	Точка здоровья/API консенсуса
`9001`	Metrics	HTTP	Prometheus-метрики

Требования к фаерволу: обеспечьте входящий/исходящий трафик на порту 30303 (TCP/UDP) для P2P-исполнения, входящий на порту 34070 (TCP) для P2P-консенсуса и внутреннюю коммуникацию на порту 8551 для Engine API. JSON-RPC интерфейс на порту 8545 открыт по умолчанию — рассмотрите возможность ограничения доступа в production.

Распространённые операции

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

Мониторинг ноды

После того как нода заработает, можно отслеживать её здоровье и статус синхронизации. Для полной настройки мониторинга и лучших практик см. руководство по мониторингу.

Проверка статуса
Статус синхронизации
Точки

# 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

Точка	URL
Execution RPC	`http://localhost:8545`
Consensus API	`http://localhost:35070`
Metrics	`http://localhost:9001/metrics`

Ваша нода начнёт синхронизироваться сразу. Начальная синхронизация может занять несколько минут в зависимости от условий сети и характеристик оборудования.

Снапшоты базы данных

Plasma публикует ежедневные снапшоты базы данных для mainnet и testnet. Снапшоты позволяют поднять новую ноду за часы вместо синхронизации с genesis, которая может занять значительно больше времени. Каждый снапшот содержит два файла — базу данных уровня консенсуса и базу данных уровня исполнения — загруженные в S3-бакет с оплатой со стороны запросчика. Вам нужен AWS-аккаунт; применяются стандартные тарифы передачи данных S3.

Предварительные требования для снапшотов

Требование	Детали
AWS-аккаунт	Учётные данные настроены через `aws configure` или переменные окружения
AWS CLI	Рекомендуется v2 (`aws --version`)
Дисковое пространство	Mainnet: ~400 ГБ свободно • Testnet: ~100 ГБ свободно

Передача данных из us-east-2 стоит ~$0,09/ГБ для первых 10 ТБ/месяц. Передача с EC2-инстанса в том же регионе бесплатна — запуск ноды в us-east-2 — самый экономичный вариант.

Бакеты со снапшотами

Свойство	Mainnet	Testnet
Бакет	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
Регион	`us-east-2` (Огайо)	`us-east-2` (Огайо)
Модель доступа	Requester-pays	Requester-pays
Частота резервного копирования	Ежедневно	Ежедневно в 02:00 UTC
Срок хранения	Скользящий (старые резервные копии удаляются автоматически)	3 дня

Резервные копии организованы по папкам с датой (MM-DD-YY). Каждая папка содержит два файла:

Файл	Описание
База данных консенсуса (`.db` в mainnet, `.mdb` в testnet)	Полное состояние уровня консенсуса
База данных исполнения (`.tar.gz`)	Tar-архив каталога `data/` Reth-исполнения

Скачивание снапшота

# 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

Восстановление из снапшота

Остановите ноду

cd {network}/docker-compose
docker compose down

Восстановите базу данных консенсуса

Скопируйте снапшот в каталог данных консенсуса:

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

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

Восстановите базу данных исполнения

Извлеките архив в каталог данных исполнения:

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

Перезапустите ноду

docker compose up -d

Устранение неполадок со снапшотами

Проблема	Причина / Исправление
`Access Denied`	Нужно включать `--request-payer requester` в каждую команду. Бакет отклоняет запросы без него.
`403 Forbidden`	AWS-учётные данные не настроены. Запустите `aws sts get-caller-identity`, чтобы убедиться, что у вас есть валидная сессия.
Пустой листинг бакета	Старые резервные копии автоматически очищаются. Если бакет кажется пустым, возможно, цикл резервного копирования в процессе — проверьте позже.
Неправильное расширение файла	Mainnet использует `.db`; testnet использует `.mdb`. Убедитесь, что вы копируете правильный файл для вашей сети.

​Предварительные требования

​Доступные сети

​Быстрый старт

​Обзор архитектуры

Plasma Execution Client

Plasma Observer Client

​Структура каталогов

​Процесс настройки

​Конфигурация

​NAT / Внешний адрес

​Конфигурация портов

​Распространённые операции

​Мониторинг ноды

​Снапшоты базы данных

​Предварительные требования для снапшотов

​Бакеты со снапшотами

​Скачивание снапшота

​Восстановление из снапшота

​Устранение неполадок со снапшотами

Предварительные требования

Доступные сети

Быстрый старт

Обзор архитектуры

Структура каталогов

Процесс настройки

Конфигурация

NAT / Внешний адрес

Конфигурация портов

Распространённые операции

Мониторинг ноды

Снапшоты базы данных

Предварительные требования для снапшотов

Бакеты со снапшотами

Скачивание снапшота

Восстановление из снапшота

Устранение неполадок со снапшотами