ADAMANT Localnet и переопределения конфигурации: быстрая разработка, простое тестирование, лучшая автоматизация

Разработка для ADAMANT стала проще и быстрее для операторов нод, участников проекта и разработчиков приложений. Помимо публичной тестовой сети ADAMANT Testnet, разработчики теперь могут запускать облегчённую локальную сеть ADAMANT непосредственно на своём компьютере. Такая настройка Localnet предназначена для быстрых экспериментов, автоматизированных проверок, тестирования сценариев и рабочих процессов разработки, которым не требуется публичная сеть или тяжёлая инфраструктура. В то же время, ADAMANT Node теперь поддерживает гибкие переопределения конфигурации, позволяя операторам и скриптам автоматизации тестирования изменять настройки ноды при запуске без ручного редактирования config.json или test/config.json.

От Testnet к Localnet

Testnet остаётся важным, поскольку предоставляет разработчикам общую публичную среду, близкую к реальным сетевым условиям. Она полезна для тестирования интеграций, проверки поведения приложений, валидации совместимости нод, а также экспериментов с функциями до их выхода в Mainnet. Однако не каждая задача разработки требует публичной сети. Иногда разработчикам нужно что-то меньшее и быстрее — запустить несколько нод локально, протестировать изменения, связанные с консенсусом, проверить обнаружение пиров и синхронизацию, воспроизвести ошибку, запустить автоматизированные тесты сценариев или проверить поведение ноды перед открытием pull request. Именно для этого появился Localnet.

Что такое ADAMANT Localnet?

ADAMANT Localnet — это управляемая локальная многонодовая сеть ADAMANT, работающая на одном компьютере. Вместо подключения к публичным нодам Testnet, Localnet запускает несколько изолированных нод ADAMANT локально. Каждая нода имеет собственные порты, состояние выполнения, логи, конфигурацию, метаданные процесса и настройки базы данных.

Базовый рабочий процесс прост:

npm run start:localnet -- --nodes 3
npm run status:localnet
npm run stop:localnet

Когда требуется полная очистка, сохранённые локальные базы данных можно удалить с помощью npm run drop:localnet или npm run stop:localnet -- --dropOnStop.

Localnet намеренно облегчён. Он не требует публичного сервера, VPS или длительной синхронизации с сетью. Он работает локально, использует контролируемую тестовую конфигурацию и подходит для машин разработки. Это делает его полезным для участников, тестирующих изменения в ноде перед отправкой, мейнтейнеров, которым нужны быстрые проверки релизов, разработчиков приложений на основе API ADAMANT, а также скриптов автоматизации или сред, подобных CI.

Что создаёт Localnet под капотом

При запуске Localnet генерирует изолированные данные выполнения для каждой ноды, включая конфигурационные файлы для каждой ноды, состояние выполнения, PID-файлы, манифест, локальные данные цепочки и папки логов для каждой ноды. Логи разделены по нодам, например, в logs-localnet/node-1/, logs-localnet/node-2/ и так далее. Это важно, потому что при отладке проблем в многонодовой сети часто требуется сравнение поведения разных пиров — одного лог-файла недостаточно при анализе проблем с распространением данных, переподключениями, пропущенными блоками, split-brain ситуациями, поведением форджинга или консенсусом broadhash. Инструменты Localnet также создают машинно-читаемые метаданные, которые в дальнейшем могут использоваться инструментами тестирования сценариев.

Скрипт статуса предоставляет информацию по каждой ноде: статус API, количество делегатов, время последнего форджинга, nethash и текущий консенсус broadhash. Консенсус по broadhash особенно полезен для проверки того, действительно ли локальные ноды синхронизированы друг с другом после запуска. В локальном smoke-тесте была запущена 3-нодовая локальная сеть, выполнен опрос статуса, консенсус по broadhash достиг 100% на всех нодах, после чего локальная сеть была корректно остановлена и удалена.

Localnet нельзя остановить просто убийством процессов. Скрипт stop:localnet использует стандартный путь graceful shutdown ноды, что помогает избежать ненужных проблем с базой данных или состоянием выполнения и делает локальное тестирование ближе к реальному поведению в эксплуатации. По умолчанию локальные базы данных PostgreSQL сохраняются. Автоматическое создание баз данных зависит от наличия у локальной роли PostgreSQL разрешения CREATEDB; если его нет, разработчики могут использовать существующую настройку базы данных или документированные опции пропуска/создания.

Переопределения конфигурации: больше не нужно редактировать конфиги вручную

Ранее ADAMANT Node поддерживал выбор конфигурационного файла с помощью --config и имел несколько жёстко заданных переопределений через CLI, таких как --port, --address, --peers, --log и --snapshot. Это работало для простых случаев, но плохо масштабировалось. Операторам и скриптам автоматизации часто нужно изменять вложенные значения конфигурации — порты, настройки Redis, настройки базы данных, списки пиров, параметры логирования, настройки API, конфигурацию форджинга, высоты активации или параметры, специфичные для тестов. Ручное редактирование скопированных конфигурационных файлов подвержено ошибкам, добавление отдельного флага CLI для каждого ключа конфигурации не масштабируется, а замена всего файла конфигурации слишком громоздка для небольших изменений, зависящих от окружения.

Теперь разработчики могут передавать отдельные значения конфигурации непосредственно при запуске, используя ключи в формате dot-path, соответствующие структуре объекта конфигурации:

node app.js \
  --config test/config.json \
  --genesis test/genesisBlock.json \
  --config-set consensusActivationHeights.fairSystem=4359465 \
  --config-set redis='{ "url": "redis://127.0.0.1:6379/1", "password": null }'

Это позволяет скриптам переопределять отдельное скалярное значение или целый объект. Значения разбираются как совместимые с JSON, где это возможно, поэтому числа, булевы значения, null, массивы и объекты могут быть корректно представлены, а не обрабатываются как обычные строки.

Переопределения конфигурации также поддерживают файлы. Файл переопределений в стиле env может содержать записи вида:

consensusActivationHeights.fairSystem=4359465
redis='{ "url": "redis://127.0.0.1:6379/1", "password": null }'

Реализация также поддерживает частичные файлы переопределений в формате JSON. Это полезно для локальных окружений, автоматизации тестирования, рабочих процессов, подобных CI, и мейнтейнеров, которым нужен воспроизводимый набор изменений без модификации отслеживаемых конфигурационных файлов. Localnet использует этот механизм по умолчанию через test/config.localnet.json, сохраняя базовую конфигурацию стабильной, а различия, специфичные для Localnet, применяются через тот же проверенный механизм переопределений.

Проверка и безопасность

Окончательная конфигурация по-прежнему проверяется по схеме конфигурации ADAMANT после разрешения значений по умолчанию, файлов переопределений, прямых переопределений и устаревших CLI-сокращений. Ошибочные пути, неверные типы значений, некорректный JSON и небезопасные ключи должны приводить к сбою до запуска, а не к непредсказуемому поведению во время выполнения. Чувствительные значения скрываются в логах переопределений конфигурации, включая пароли, парфразы, секреты и токены. Устаревшие сокращения при запуске направляются через тот же проверенный конвейер переопределений и сохраняют наивысший приоритет, поэтому существующие рабочие процессы продолжают работать, а новые получают более универсальный и согласованный механизм конфигурации.

Некоторые значения конфигурации чувствительны к консенсусу. Переопределение ключей, таких как consensusActivationHeights.*, может быть полезно для локальных или тестовых сценариев, но использование несовместимых с сетью высот активации с неправильной цепочкой может привести к расхождению ноды с сетью. Переопределения конфигурации предназначены для явного и прозрачного использования. Они полезны для Localnet, Testnet, автоматизации и контролируемых эксплуатационных сценариев, но должны использоваться с осторожностью на продакшн-нодах Mainnet. Эта функция изменяет только механизм разрешения конфигурации при запуске — она не влияет напрямую на логику блоков, сериализацию транзакций, логику вознаграждений, комиссионные, порядок делегатов, проверку подписей или правила консенсуса.

Localnet и Testnet работают вместе

Localnet не заменяет Testnet; они решают разные задачи. Localnet лучше всего подходит для быстрой, приватной, воспроизводимой разработки на одной машине, где разработчикам нужен полный контроль, быстрый запуск и изолированные эксперименты. Testnet лучше подходит для публичного, совместного тестирования на уровне сети, где разработчикам требуется постоянная среда, публичные пиры, тестовые монеты ADM, доступ к обозревателю и проверка приложений в общей сети. Вместе они дают участникам ADAMANT более надёжный конвейер разработки: тестируйте локально с Localnet, проверяйте на публичном Testnet, затем готовьте более безопасные релизы для Mainnet.

Управление жизненным циклом Localnet намеренно отделено от выполнения тестов сценариев. Скрипты Localnet отвечают за запуск, остановку, проверку и очистку локальной сети. Затем сценарии могут направляться на уже доступный Localnet или Testnet и формировать отчёты. Такое разделение делает ответственность ясной и упрощает создание будущих инструментов.