# MFX Validator / Node Onboarding

**Дата создания:** 2025-11-23  
**Версия:** 1.0  
**Статус:** Production

---

## Введение

MFX Network — это EVM-совместимая блокчейн-сеть с Chain ID 2064, работающая в mainnet. Этот гайд предназначен для запуска собственной ноды или валидатора MFX Network, а не для использования кошелька или других клиентских приложений.

**Важно:** Этот гайд описывает процесс деплоя новой ноды/валидатора. Он не изменяет параметры сети, генезис или существующие прод-ноды.

---

## 1. Requirements

### Системные требования

Минимальные системные требования для внешнего валидатора / ноды:

| Параметр | Минимум | Рекомендуется |
|----------|---------|---------------|
| **OS** | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS или новее |
| **CPU** | 4 vCPU | 8 vCPU |
| **RAM** | 8 GB | 16 GB |
| **Disk** | NVMe SSD, 200 GB | NVMe SSD, 500 GB+ |
| **Network** | 100 Mbps, стабильный канал | 100+ Mbps, статический IP |

### Сетевые порты

| Порт | Протокол | Назначение | Публичный доступ |
|------|----------|------------|------------------|
| **7071** | UDP | P2P (если включен) | ✅ Да (для подключения пиров) |
| **8545** | TCP | RPC (локальный) | ❌ Нет (только локально) |
| **8546** | TCP | HTTP RPC (локальный) | ❌ Нет (только локально) |
| **22** | TCP | SSH | ✅ Да (с защитой) |

**Важно:** RPC порты (8545, 8546) **НЕ должны** быть доступны публично без дополнительной защиты (firewall, VPN, reverse proxy с аутентификацией). Публичный RPC без защиты может привести к злоупотреблениям и DDoS-атакам.

---

## 2. Quickstart (для опытных)

Если вы уже знакомы с деплоем блокчейн-нод, у вас есть два варианта:

#### Option A: one-liner install (рекомендуется)

Самая быстрая установка одной командой:

```bash
curl -s https://raw.githubusercontent.com/mfx-network/mfx-node-bootstrap/main/scripts/install.sh | sudo bash
```

Этот скрипт автоматически:
- установит необходимые пакеты
- клонирует или обновит репозиторий
- создаст `.env` из `.env.example` (если его нет)
- запустит `bootstrap.sh`
- выполнит self-check (если доступен)

После установки проверьте статус:
```bash
systemctl status mfx-node
```

#### Option B: manual install

Если предпочитаете делать всё вручную, выполните следующие команды:

```bash
# 1) Подключаемся к свежему серверу под root
ssh root@your-server

# 2) Получаем bootstrap-репозиторий
git clone https://github.com/mfx-network/mfx-node-bootstrap /opt/mfx/infra/mfx-node-bootstrap

cd /opt/mfx/infra/mfx-node-bootstrap

# 3) Копируем и редактируем .env
cp .env.example .env
nano .env

# 4) Запускаем bootstrap
sudo ./scripts/bootstrap.sh

# 5) Проверяем сервис
systemctl status mfx-node
```

**Важно:** Не вставляйте реальные приватные ключи в документацию или публичные репозитории. Используйте только плейсхолдеры вида `0x...`.

---

## 3. Подробный пошаговый гайд

### 3.1. Подготовка сервера

Обновите систему и установите необходимые пакеты:

```bash
# Обновление пакетов
apt-get update && apt-get upgrade -y

# Установка базовых утилит
apt-get install -y curl git ufw gettext-base

# Настройка firewall (опционально, но рекомендуется)
ufw allow 22/tcp
ufw allow 7071/udp  # P2P порт (если используется)
ufw enable
```

### 3.2. Получение репозитория mfx-node-bootstrap

Репозиторий находится по пути: `/opt/mfx/infra/mfx-node-bootstrap`

**Структура репозитория:**
- `scripts/bootstrap.sh` — основной скрипт деплоя
- `config/*.example` — шаблоны конфигурационных файлов
- `systemd/*.example` — шаблоны systemd unit файлов
- `.env.example` — пример конфигурации

Если репозиторий публичный, клонируйте его:
```bash
git clone https://github.com/mfx-network/mfx-node-bootstrap /opt/mfx/infra/mfx-node-bootstrap
```

Если репозиторий только локальный, получите его от команды MFX и скопируйте на сервер.

### 3.3. Настройка .env

Скопируйте пример конфигурации и отредактируйте:

```bash
cd /opt/mfx/infra/mfx-node-bootstrap
cp .env.example .env
nano .env
```

**Основные переменные (объяснения без конкретных значений):**

| Переменная | Описание | Пример |
|------------|----------|--------|
| `MFX_CHAIN_ID` | Chain ID сети MFX | `2064` |
| `MFX_NETWORK_ID` | Network ID (обычно совпадает с Chain ID) | `2064` |
| `MFX_CONSENSUS_MODE` | Режим консенсуса: `single_author` или `validator` | `validator` |
| `MFX_P2P_DISABLED` | Отключить P2P (true/false) | `false` |
| `MFX_P2P_PORT` | UDP порт для P2P | `7071` |
| `MFX_RPC_PORT` | TCP порт для RPC (только локальный) | `8545` |
| `MFX_HTTP_PORT` | HTTP RPC порт (только локальный) | `8546` |
| `MFX_AUTHOR_KEY_PATH` | Путь к приватному ключу автора (hex) | `/var/lib/mfx/node/keys/author.hex` |
| `MFX_TREASURY_ADDRESS` | Адрес казначейства (опционально) | `0x...` |
| `MFX_MINER_ADDRESS` | Адрес майнера (для обычного валидатора обычно свой адрес) | `0x...` |

**Важно:** 
- Не подставляйте продовые секреты в документацию
- Используйте только плейсхолдеры с пояснениями
- Для обычного валидатора/ноды обычно достаточно собственного адреса

### 3.4. Запуск bootstrap.sh

Скрипт `bootstrap.sh` выполняет следующие действия:

1. **Создает пользователя `mfx`** (если не существует)
2. **Создает директории данных:**
   - `/var/lib/mfx/node` — данные ноды
   - `/var/log/mfx/node` — логи
   - `/opt/mfx/blockchain/config` — конфигурационные файлы
3. **Генерирует приватный ключ** (если не существует)
4. **Копирует конфиги** из `config/*.example` с подстановкой переменных
5. **Настраивает systemd unit** для автоматического запуска
6. **Не изменяет существующую прод-ноду**

Запуск:

```bash
sudo ./scripts/bootstrap.sh
```

### 3.5. Проверка после запуска

**Проверка статуса сервиса:**

```bash
systemctl status mfx-node
```

**Просмотр логов:**

```bash
# Последние логи
journalctl -u mfx-node -n 100

# Логи в реальном времени
journalctl -u mfx-node -f
```

**Локальный RPC-пинг:**

```bash
curl -s http://127.0.0.1:8546 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

Ожидаемый ответ:
```json
{"jsonrpc":"2.0","id":1,"result":"0x..."}
```

---

## 4. Мониторинг и алерты (для валидатора)

### Центральный мониторинг

На основной инфраструктуре MFX Network работает Prometheus + Alertmanager, который мониторит прод-ноду. Центральный Alertmanager пока что не интегрирован с внешними валидаторами по умолчанию.

### Рекомендации для внешнего валидатора

**Минимум:**
- Установить `node_exporter` для системных метрик
- Настроить отдельный Prometheus (или интеграцию в существующий)
- Настроить базовые алерты

**Что мониторить:**

| Метрика | Описание | Критичность |
|---------|----------|-------------|
| **Высота блока** | Отставание от основной сети | Высокая |
| **CPU/RAM** | Нагрузка на сервер | Средняя |
| **Disk IOPS** | Производительность диска | Средняя |
| **Свободное место** | Доступное место на диске | Высокая |
| **Перезапуски сервиса** | Стабильность работы | Высокая |

**Пример настройки node_exporter:**

```bash
# Установка
wget https://github.com/prometheus/node_exporter/releases/download/v1.7.0/node_exporter-1.7.0.linux-amd64.tar.gz
tar xvfz node_exporter-1.7.0.linux-amd64.tar.gz
sudo mv node_exporter-1.7.0.linux-amd64/node_exporter /usr/local/bin/

# Создание systemd unit
sudo tee /etc/systemd/system/node_exporter.service > /dev/null <<EOF
[Unit]
Description=Node Exporter
After=network.target

[Service]
ExecStart=/usr/local/bin/node_exporter
Restart=always
User=nobody

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable node_exporter
sudo systemctl start node_exporter
```

**Интеграция с центральным Alertmanager:**

Интеграция внешних валидаторов с центральным Alertmanager возможна по договоренности с командой MFX. Свяжитесь с командой для настройки.

---

## 5. Обновления и обслуживание

### Безопасное обновление ноды

**Процесс обновления:**

1. **Остановить сервис:**
   ```bash
   sudo systemctl stop mfx-node
   ```

2. **Обновить бинарник:**
   ```bash
   # Если бинарник в репозитории
   cd /opt/mfx/blockchain
   git pull
   cargo build --release
   
   # Или скачать новый релиз
   # wget https://.../mfx-node-vX.X.X
   # chmod +x mfx-node-vX.X.X
   # mv mfx-node-vX.X.X /opt/mfx/blockchain/target/release/mfx-node
   ```

3. **Проверить версию:**
   ```bash
   /opt/mfx/blockchain/target/release/mfx-node --version
   ```

4. **Запустить сервис:**
   ```bash
   sudo systemctl start mfx-node
   ```

5. **Проверить логи:**
   ```bash
   journalctl -u mfx-node -f
   ```

### Graceful shutdown и перезапуск

**Graceful shutdown:**

```bash
# Остановка с ожиданием завершения текущих операций
sudo systemctl stop mfx-node

# Проверка, что процесс завершился
ps aux | grep mfx-node
```

**Перезапуск:**

```bash
# Перезапуск без остановки (если поддерживается)
sudo systemctl restart mfx-node

# Или остановка + запуск
sudo systemctl stop mfx-node
sleep 5
sudo systemctl start mfx-node
```

---

## 6. FAQ / Troubleshooting

### Нода не стартует

**Симптомы:**
- `systemctl status mfx-node` показывает `failed`
- Сервис не запускается

**Решение:**
1. Проверьте логи: `journalctl -u mfx-node -n 50`
2. Проверьте права на каталог данных: `ls -la /var/lib/mfx/node`
3. Проверьте конфигурацию: `cat /opt/mfx/blockchain/config/mfx-node.toml`
4. Проверьте наличие бинарника: `ls -la /opt/mfx/blockchain/target/release/mfx-node`
5. Проверьте переменные окружения в systemd unit: `cat /etc/systemd/system/mfx-node.service`

### Нода не синхронизируется

**Симптомы:**
- Высота блока не растет
- Нода не подключается к пирам

**Решение:**
1. Проверьте порты:
   ```bash
   # P2P порт должен быть открыт
   ss -ulnp | grep 7071
   
   # Проверьте firewall
   ufw status
   ```

2. Проверьте список пиров в конфиге:
   ```bash
   grep -A 10 "\[p2p" /opt/mfx/blockchain/config/mfx-node.toml
   ```

3. Проверьте сетевые подключения:
   ```bash
   # Проверка доступности пиров
   ping <peer-ip>
   ```

4. Проверьте логи на ошибки подключения:
   ```bash
   journalctl -u mfx-node | grep -i "peer\|connection\|sync"
   ```

### Высота блока отстаёт от explorer

**Симптомы:**
- Локальная высота блока меньше, чем на explorer.mfx.network
- Нода не догоняет сеть

**Решение:**
1. Проверьте количество пиров:
   ```bash
   # В логах должно быть несколько подключений
   journalctl -u mfx-node | grep -i "peer"
   ```

2. Проверьте нагрузку на сервер:
   ```bash
   htop
   iostat -x 1
   ```

3. Проверьте сетевую задержку:
   ```bash
   ping explorer.mfx.network
   ```

4. Если отставание критическое, рассмотрите пересинхронизацию:
   ```bash
   # ОСТОРОЖНО: Это удалит локальные данные!
   sudo systemctl stop mfx-node
   sudo rm -rf /var/lib/mfx/node/*
   sudo systemctl start mfx-node
   ```

### Как проверить, что нода «живая»

**Проверка через RPC:**

```bash
# Получение текущей высоты блока
curl -s http://127.0.0.1:8546 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Проверка времени ответа
time curl -s http://127.0.0.1:8546 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

**Проверка логов:**

```bash
# Отсутствие ошибок в последних логах
journalctl -u mfx-node --since "5 minutes ago" | grep -i error

# Проверка активности (новые блоки)
journalctl -u mfx-node --since "1 minute ago" | grep -i "block\|height"
```

**Проверка системных метрик:**

```bash
# CPU и память
top -bn1 | grep mfx-node

# Диск
df -h /var/lib/mfx/node
```

---

## 7. Полезные ссылки

- **Explorer:** https://explorer.mfx.network
- **RPC Endpoint:** https://rpc.mfx.network/rpc-wallet
- **Chain Config:** https://explorer.mfx.network/mfx-chain.json
- **Документация инфраструктуры:** /opt/mfx/docs/MFX_INFRASTRUCTURE.md

---

## 8. Контакты и поддержка

При возникновении проблем:
1. Проверьте логи: `journalctl -u mfx-node -f`
2. Проверьте конфигурацию в `.env`
3. Убедитесь, что все зависимости установлены
4. Свяжитесь с командой MFX для получения помощи

---

**Последнее обновление:** 2025-11-23




## 9. Final checks

After you finish all steps above, please go through:



**MFX_VALIDATOR_CHECKLIST.md** on the server

(`/opt/mfx/docs/MFX_VALIDATOR_CHECKLIST.md`)



and run the self-check:



```bash

cd /opt/mfx/infra/mfx-node-bootstrap

./scripts/selfcheck.sh

```



If all checks are green, your node is ready.