Запуск ноди

Вимоги

• Rust (stable) з ціллю wasm32-unknown-unknown
• Інструментарій C++ і clang (RocksDB збирається з вихідного коду)
• Node.js 18+ для gateway
• Кілька ГБ диска для збірки

Збірка

Нода вбудовує два системні контракти, тож збирайте їх першими:

cd neurochain
rustup target add wasm32-unknown-unknown

for c in nrc20 ncert; do
  (cd contracts/$c && RUSTFLAGS="-C link-arg=--allow-undefined" \
     cargo build --release --target wasm32-unknown-unknown)
done

cargo build -p neurochain-node --bin neurochain        # → target/debug/neurochain

Без кроку з контрактами збірка ноди падає з couldn't read …/nrc20.wasm. Прапорець --allow-undefined дозволяє host-імпортам контрактів лінкуватися з поточним Rust; нові контракти можуть натомість оголошувати #[link(wasm_import_module = "env")] (див. NeuroWASM).

Перша збірка триває кілька хвилин (RocksDB); наступні — секунди. Для всього, крім локального тестування, використовуйте --release.

Одна локальна нода

CHAIN_ENV=testnet \
NEUROCHAIN_DATA_DIR=./data \
NEUROCHAIN_MODELS_DIR=./models \
NEUROCHAIN_P2P_PORT=30333 \
NEUROCHAIN_RPC_PORT=9933 \
NEUROCHAIN_NODE_ADDR=localhost:30333 \
NEUROCHAIN_MIN_VALIDATORS=1 \
RUST_LOG=neurochain=info \
./target/debug/neurochain

• CHAIN_ENV=testnet вмикає кран і пом'якшує перевірку підписів для розробки. Для будь-чого справжнього не задавайте його (правила mainnet).
• Без NEUROCHAIN_GENESIS_VALIDATORS нода робить себе єдиним валідатором (neuro:node-1.node) і одразу починає виробляти блоки.
• NEUROCHAIN_MIN_VALIDATORS=1 прибирає попередження про те, що валідаторів менше 7.

Перевірте:

curl -s http://localhost:9933/health
# {"status":"ok","height":6,"validator_count":1,"bft_quorum":1,"bft_ready":false,…}

Потім запустіть gateway.

Мережа з кількох валідаторів

Кожен валідатор має стартувати з того самого генезису, у якому перелічено всіх валідаторів з їхніми публічними ключами консенсусу. Для локальної мережі репозиторій це автоматизує:

cd neurochain
scripts/net-test/net-test.sh keys 4    # створити 4 ключі валідаторів, записати спільний набір генезису
scripts/net-test/net-test.sh up 4      # запустити їх (спершу нода 1, решта підключаються до неї)
scripts/net-test/net-test.sh check     # висоти збігаються, блоки виробляються, спонсорований газ узгоджений
scripts/net-test/net-test.sh down

Скрипт використовує RPC-порти від 9941, P2P-порти від 30341 і дані в .net-test/, тож звичайної ноди з ./data не зачіпає.

Вручну:

1. Створіть ключ кожного валідатора. Запустіть кожну ноду один раз з власними NEUROCHAIN_DATA_DIR, NEUROCHAIN_NODE_ADDR і портами. Вона запише ключ у <data dir>/shard0/bft_key.bin і виведе в журнал:

   Consensus validator … — ML-DSA-65 pubkey (put in NEUROCHAIN_GENESIS_VALIDATORS): 6e80bab8…

   Зупиніть її і видаліть <data dir>/shard0/state_rdb та <data dir>/shard0/wal. bft_key.bin збережіть.
2. Запишіть набір генезису — однакове значення для кожної ноди:

   NEUROCHAIN_GENESIS_VALIDATORS='neuro:val1.node|host1:30333|1000000|0.9|<pubkey1>,neuro:val2.node|host2:30333|1000000|0.9|<pubkey2>,…'

   Поля: адреса валідатора, його P2P-адреса (має дорівнювати NEUROCHAIN_NODE_ADDR цієї ноди), стейк у NRO, початковий trust (лише для звітів), публічний ключ ML-DSA-65. Запис без публічного ключа не входить у консенсус.
3. Запустіть першу ноду, потім інші з NEUROCHAIN_BOOTSTRAP=host1:30333. Якщо валідаторів менше 7, задайте NEUROCHAIN_MIN_VALIDATORS рівним їхній кількості.

Повідомлення консенсусу йдуть тим самим P2P-портом; окремого порту консенсусу немає. Нода розпізнає, який вона валідатор, зіставляючи NEUROCHAIN_NODE_ADDR з P2P-адресою в наборі генезису.

Набір генезису ніколи не змінюється

Валідатори, що приєднуються пізніше, реєструють .node і стейкають (див. Стейкінг); вони не змінюють NEUROCHAIN_GENESIS_VALIDATORS. Нода, запущена з іншим набором генезису чи балансом, відхиляє блоки інших і пише в журнал STATE DIVERGENCE.

Docker Compose

З кореня репозиторію:

cp .env.example .env        # відредагуйте за потреби
docker compose up -d        # нода, gateway, вебзастосунок
docker compose --profile monitoring up -d   # плюс Prometheus і Grafana

Образи збирають контракти й ноду поетапно. Дані ноди — в томі node1-data; файли AI-моделей монтуються лише для читання з neurochain/models.

Папка даних

Шлях	Вміст
<data dir>/shard<N>/bft_key.bin	Ключ консенсусу й підпису ноди — зробіть резервну копію, нікому не передавайте
<data dir>/shard<N>/state_rdb/	Стан мережі шарда N у RocksDB
<data dir>/shard<N>/wal/	Журнал попереднього запису консенсусу, відтворюється після перезапуску

Старт зі знімка стану

Нова нода може не відтворювати історію, а завантажити підписаний знімок стану з працюючої ноди:

NEUROCHAIN_CHECKPOINT_URL=http://trusted-node:9933 ./target/debug/neurochain

З порожньою папкою даних нода отримує /api/v1/state/snapshot, застосовує його й наздоганяє з цієї висоти. Знімок розкриває всі баланси й стейки; захистіть ендпоінт через NEUROCHAIN_SNAPSHOT_TOKEN (клієнти тоді надсилають Authorization: Bearer <token>).

Доступність і TLS

• За правилами mainnet RPC слухає localhost, з CHAIN_ENV=testnet — 0.0.0.0; щоб обрати, задайте NEUROCHAIN_RPC_HOST.
• Задайте NEUROCHAIN_TLS_CERT і NEUROCHAIN_TLS_KEY (шляхи до PEM), щоб обслуговувати RPC через HTTPS.
• Перед користувачами ставте gateway, а не ноду.
• NEUROCHAIN_INTERNAL_TOKEN захищає внутрішні ендпоінти (запис у журнал оракула, експорт даних для AI) заголовком X-Internal-Token.

Моніторинг

GET /metrics віддає метрики Prometheus:

Метрика	Значення
nc_block_height, nc_bft_round	Просування мережі
nc_bft_validators_active, nc_bft_quorum_size	Набір валідаторів
nc_peer_count, nc_mempool_size, nc_tx_total	Мережа й навантаження
nc_total_staked, nc_base_fee, nc_fees_burned	Економіка (суми в uNRO)
nc_deploy_rejected_total{rule_id}	Розгортання, відхилені VMGuardian, за правилами
nc_model_active_count, nc_model_voting_count, nc_model_version{…}, nc_model_confirms_needed, nc_model_voting_deadline_remaining_blocks	Реєстр AI-моделей
nc_sentinel_flagged_total{category}, nc_sentinel_held_total, nc_sentinel_released_total{how}	Sentinel

У monitoring/ лежать конфігурація збору Prometheus і готова панель Grafana зі сповіщеннями про великий мемпул, менше 2 пірів і сплеск відхилених розгортань.

Резервне копіювання й відновлення

./scripts/backup.sh [data_dir] [backup_dir]     # копія на льоту; нода продовжує працювати
./scripts/restore.sh <backup_dir> [data_dir]    # спершу зупиніть ноду

Резервні копії містять bft_key.bin — зберігайте їх так само надійно, як сам ключ.

Корисні рядки журналу

Рядок	Значення
consensus decided, committing height=…	Блок фіналізовано
Below minimum: n/7 active validators	Валідаторів менше, ніж NEUROCHAIN_MIN_VALIDATORS
STATE DIVERGENCE	Стан цієї ноди відрізняється від стану пропонувальника; вона не голосує, доки це не вирішено
genesis validator(s) missing ML-DSA pubkey	Запис у наборі генезису не має публічного ключа і виключений

Усі змінні: Змінні середовища.