dchain/docs/node/README.md

# Запуск ноды

## Быстрый старт (Docker)

```bash
git clone https://github.com/your/go-blockchain
cd go-blockchain
docker compose up -d
```

Запускает 3 ноды: `node1` (8081), `node2` (8082), `node3` (8083).

Деплой контрактов:
```bash
docker exec node1 /scripts/deploy_contracts.sh
```

Explorer: http://localhost:8081

---

## Запуск вручную

### Требования

- Go 1.21+
- BadgerDB (встроен)
- libp2p (встроен)

### Сборка

```bash
cd go-blockchain
go build ./cmd/node/
go build ./cmd/client/
```

### Genesis нода

```bash
# Первый запуск — создать genesis
./node \
  --key node1.json \
  --genesis \
  --validators "$(cat node1.json | jq -r .pub_key),$(cat node2.json | jq -r .pub_key),$(cat node3.json | jq -r .pub_key)" \
  --stats-addr :8081 \
  --listen /ip4/0.0.0.0/tcp/4001 \
  --db ./data/node1
```

### Peer нода

```bash
./node \
  --key node2.json \
  --peers /ip4/127.0.0.1/tcp/4001/p2p/<node1-peer-id> \
  --stats-addr :8082 \
  --listen /ip4/0.0.0.0/tcp/4002 \
  --db ./data/node2
```

---

## Флаги командной строки

| Флаг | По умолчанию | Описание |
|------|------------|---------|
| `--key` | `node.json` | Файл Ed25519 + X25519 идентичности |
| `--db` | `chaindata` | Директория BadgerDB |
| `--listen` | `/ip4/0.0.0.0/tcp/4001` | libp2p адрес |
| `--peers` | — | Bootstrap peer multiaddrs (через запятую) |
| `--validators` | — | Pubkeys валидаторов (через запятую, только для `--genesis`) |
| `--genesis` | false | Создать genesis блок при первом старте |
| `--stats-addr` | `:8080` | HTTP API/Explorer порт |
| `--wallet` | — | Payout кошелёк (hex pubkey) |
| `--wallet-pass` | — | Пароль к кошельку |
| `--heartbeat` | false | Отправлять heartbeat каждые 60 минут |
| `--register-relay` | false | Зарегистрироваться как relay-провайдер |
| `--relay-fee` | 0 | Fee за relay сообщение в µT |
| `--relay-key` | `relay.json` | X25519 ключ для relay шифрования |
| `--mailbox-db` | — | Директория для relay mailbox |
| `--governance-contract` | — | ID governance контракта для динамических параметров |

---

## Docker Compose

### docker-compose.yml структура

```yaml
services:
  node1:
    build: .
    ports:
      - "8081:8080"    # HTTP API
      - "4001:4001"    # libp2p
    volumes:
      - node1_data:/chaindata
      - ./keys:/keys:ro
    command: >
      node
        --key /keys/node1.json
        --genesis
        --validators "$VALIDATORS"
        --stats-addr :8080
        --listen /ip4/0.0.0.0/tcp/4001
        --governance-contract "$GOV_ID"
    environment:
      - VALIDATORS=03...,04...,05...

  node2:
    build: .
    ports:
      - "8082:8080"
    command: >
      node
        --key /keys/node2.json
        --peers /dns4/node1/tcp/4001/p2p/$NODE1_PEER_ID
        --stats-addr :8080
        --listen /ip4/0.0.0.0/tcp/4001
```

### Управление

```bash
# Запустить
docker compose up -d

# Логи
docker compose logs -f node1

# Остановить
docker compose down

# Сбросить данные
docker compose down -v
```

---

## Файл ключа

Каждая нода использует один файл с обоими ключами:

```json
{
  "pub_key": "03abcd...",       // Ed25519 pubkey (hex, 66 символов)
  "priv_key": "...",            // Ed25519 privkey (hex)
  "x25519_pub": "...",          // X25519 pubkey для E2E relay (hex, 64 символа)
  "x25519_priv": "..."          // X25519 privkey
}
```

Генерация:
```bash
client keygen --out node1.json
```

---

## Мониторинг

### HTTP healthcheck

```bash
curl http://localhost:8081/api/netstats
```

### Logs

```bash
# Docker
docker compose logs -f node1 | grep -E "block|error|warn"

# Прямой запуск
./node ... 2>&1 | tee node.log
```

### Метрики производительности

| Показатель | Норма |
|-----------|------|
| Время блока | ~3 с |
| Блоков в минуту | ~20 |
| PBFT фазы | prepare → commit → finalize |

---

## Структура данных BadgerDB

```
balance:<pubkey>              →  uint64 (µT)
identity:<pubkey>             →  JSON RegisterKeyPayload
stake:<pubkey>                →  uint64 (µT)
block:<index>                 →  JSON Block
tx:<txid>                     →  JSON TxRecord
txidx:<pubkey>:<block>:<seq>  →  txid (индекс по адресу)
contract:<id>                 →  JSON ContractRecord
cstate:<id>:<key>             →  []byte (state контракта)
clog:<id>:<seq>               →  JSON ContractLogEntry
relay:<pubkey>                →  JSON RegisteredRelayInfo
```

---

## Сброс и восстановление

```bash
# Полный сброс
docker compose down -v
docker compose up -d

# Только данные одной ноды
docker compose stop node1
docker volume rm go-blockchain_node1_data
docker compose up -d node1
```

После сброса нужно заново задеплоить контракты и залинковать governance.