# Архитектура DChain

## Обзор

DChain — это L1-блокчейн для децентрализованного мессенджера. Архитектура разделена на четыре слоя:

```
┌─────────────────────────────────────────────────────────────┐
│  L3 Application  — messaging, usernames, auctions, escrow   │
│  (Smart contracts: username_registry, governance, auction,  │
│   escrow; deployed on-chain via DEPLOY_CONTRACT)            │
├─────────────────────────────────────────────────────────────┤
│  L2 Transport    — relay mailbox, E2E NaCl encryption       │
│  (relay/, mailbox, GossipSub envelopes, RELAY_PROOF tx)     │
├─────────────────────────────────────────────────────────────┤
│  L1 Chain        — PBFT consensus, WASM VM, BadgerDB        │
│  (blockchain/, consensus/, vm/, identity/)                  │
├─────────────────────────────────────────────────────────────┤
│  L0 Network      — libp2p, GossipSub, DHT, mDNS             │
│  (p2p/)                                                     │
└─────────────────────────────────────────────────────────────┘
```

---

## Консенсус (PBFT)

**Алгоритм:** Practical Byzantine Fault Tolerance, кворум 2/3.

**Фазы:**
```
Leader              Validator-2         Validator-3
  │── PRE-PREPARE ──▶│                       │
  │── PRE-PREPARE ────────────────────────▶  │
  │◀─ PREPARE ───────│                       │
  │◀─ PREPARE ────────────────────────────── │
  │── COMMIT ────────▶│                       │
  │── COMMIT ──────────────────────────────▶ │
  │◀─ COMMIT ────────│                       │
  │◀─ COMMIT ────────────────────────────── │
  AddBlock()
```

**Свойства:**
- Safety при ≤ f Byzantine нодах где N ≥ 3f+1
- Текущий testnet: N=2 валидатора, f=0 (узел node3 — relay-only observer)
- View-change при недоступном лидере: таймаут 10 секунд

**Блок-производство:**
- Fast ticker (500 ms) — при наличии транзакций в mempool
- Idle ticker (5 s) — пустые блоки для heartbeat и синхронизации

**Ключевые файлы:**
```
consensus/engine.go    — PBFT engine
consensus/msg.go       — ConsensusMsg типы (PRE-PREPARE, PREPARE, COMMIT, VIEW-CHANGE)
```

---

## Хранилище (BadgerDB)

Весь state хранится в BadgerDB (LSM-дерево, pure Go).

**Пространства ключей:**

| Префикс | Тип | Описание |
|---------|-----|---------|
| `block:<index_20d>` | JSON | Блоки по индексу |
| `height` | uint64 JSON | Текущая высота |
| `balance:<pubkey>` | uint64 JSON | Балансы токенов |
| `id:<pubkey>` | JSON | Identity (RegisterKey payload) |
| `validator:<pubkey>` | presence | Активный сет валидаторов |
| `relay:<pubkey>` | JSON | Зарегистрированные relay-ноды |
| `contract:<id>` | JSON | ContractRecord (метаданные + WASM) |
| `cstate:<id>:<key>` | raw bytes | Состояние контракта |
| `clog:<id>:<height_20d>:<seq_05d>` | JSON | Логи контракта |
| `rep:<pubkey>` | JSON | Репутация (blocks, relays, slashes) |
| `contact_in:<to>:<from>` | JSON | Входящие contact requests |
| `mail:<x25519>:<ts>:<id>` | JSON | Relay mailbox (TTL 7 дней) |

**Две отдельные БД:**
- `--db ./chaindata` — chain state (consensus state machine)
- `--mailbox-db ./mailboxdata` — relay mailbox (отдельная изоляция)

---

## P2P сеть (libp2p)

**Компоненты:**
- **Transport:** TCP `/ip4/0.0.0.0/tcp/4001`
- **Identity:** Ed25519 peer key (вывод из node identity)
- **Discovery:** mDNS (локалка) + Kademlia DHT (WAN)
- **Pub/Sub:** GossipSub с тремя топиками:

| Топик | Содержимое |
|-------|-----------|
| `dchain/tx/v1` | Транзакции (gossip) |
| `dchain/blocks/v1` | Готовые блоки (gossip от лидера) |
| `dchain/relay/v1` | Relay envelopes (зашифрованные сообщения) |

- **Direct streams:** PBFT consensus messages (pre-prepare/prepare/commit/view-change) идут напрямую между валидаторами через `/dchain/consensus/1.0.0` протокол
- **Sync:** block range sync по `/dchain/sync/1.0.0` при подключении нового пира

---

## WASM Virtual Machine

**Runtime:** wazero v1.7.3, interpreter mode (детерминированный на всех платформах).

**Жизненный цикл контракта:**

```
DEPLOY_CONTRACT tx
  ├── validate: wazero.CompileModule() — если ошибка, tx отклоняется
  ├── contractID = hex(sha256(deployerPubKey || wasmBytes))[:16]
  ├── BadgerDB: contract:<id> → ContractRecord{WASMBytes, ABI, ...}
  └── state: cstate:<id>:* — изначально пусто

CALL_CONTRACT tx
  ├── ABI validation: метод существует, число аргументов совпадает
  ├── pre-charge: tx.Fee + gasLimit × gasPrice
  ├── vm.Call(contractID, wasmBytes, method, argsJSON, gasLimit, hostEnv)
  │     ├── compile (cached) + instrument (gas_tick в loop headers)
  │     ├── register "env" host module (14 функций)
  │     ├── [optional] wasi_snapshot_preview1 (для TinyGo контрактов)
  │     └── fn.Call(ctx) → gasUsed, error
  ├── refund: (gasLimit - gasUsed) × gasPrice → обратно sender
  └── logs: clog:<id>:<height>:<seq> → BadgerDB
```

**Gas модель:** каждый вызов функции (WASM или host) = 100 gas units.  
`gasCost (µT) = gasUsed × gasPrice` (gasPrice управляется governance или константа 1 µT).

**Типы контрактов:**
- **Binary WASM** — написаны на Go через кодогенераторы (`contracts/*/gen/main.go`)
- **TinyGo WASM** — написаны на Go, компилируются с `tinygo -target wasip1`

---

## Экономика

**Supply:** Фиксированный. Genesis-блок минтит **21 000 000 T** на ключ node1. Последующей эмиссии нет.

**Unit:** µT (микро-токен). 1 T = 1 000 000 µT.

**Доходы валидаторов:** только комиссии из транзакций блока (`TotalFees`). Без блок-реварда.

**Комиссии:**
| Операция | Минимальная fee |
|---------|----------------|
| Все транзакции | 1 000 µT (MinFee) |
| CONTACT_REQUEST | tx.Amount → recipient (anti-spam) |
| DEPLOY_CONTRACT | 10 000 µT |
| CALL_CONTRACT | MinFee + gasUsed × gasPrice |
| RELAY_PROOF | sender → relay node (произвольно) |

**Governance:** gas_price, relay_fee и другие параметры можно менять on-chain через governance-контракт без хардфорка.

---

## Relay (E2E мессенджер)

**Шифрование:** NaCl box (X25519 Diffie-Hellman + XSalsa20 + Poly1305).

**Ключи:** каждый Identity имеет два ключа:
- Ed25519 (подпись транзакций, chain identity)
- X25519 (вывод из Ed25519 seed, шифрование сообщений)

**Поток сообщения:**
```
Alice                      node1 (relay)              Bob
  │                             │                       │
  │── seal(msg, bob.X25519) ──▶ │                       │
  │   POST /relay/broadcast     │                       │
  │                             │── gossip envelope ──▶ │
  │                             │   store mailbox       │
  │                             │   (TTL 7 days)        │
  │                             │                       │
  │                             │◀── GET /relay/inbox ──│
  │                             │                       │── open(envelope)
  │                             │                       │   → plaintext
```

**Anti-spam:**
- Первый контакт — платный (CONTACT_REQUEST tx, fee идёт получателю)
- Envelope: max 64 KB, max 500 envelopes на получателя (FIFO)
- RELAY_PROOF: подписанное доказательство доставки, fee снимается со sender и кредитуется relay

---

## Динамические валидаторы

Сет валидаторов хранится on-chain в `validator:<pubkey>`. Любой текущий валидатор может добавить или убрать другого (ADD_VALIDATOR / REMOVE_VALIDATOR tx). После commit такого блока PBFT-движок перезагружает сет без рестарта ноды.

**Ключевые файлы:**
```
blockchain/chain.go          — state machine, applyTx, VMHostEnv
consensus/engine.go          — PBFT, UpdateValidators()
vm/vm.go                     — wazero runtime, NewVM()
vm/host.go                   — host module "env" (14 функций)
vm/gas.go                    — gas counter, Remaining()
relay/mailbox.go             — BadgerDB TTL mailbox
relay/crypto.go              — NaCl seal/open
p2p/host.go                  — libp2p host, GossipSub
node/api_routes.go           — HTTP API routing
```