# DHT Protocol Specification (Draft)

## 1. Общие положения

* DHT-протокол предназначен для обмена информацией о пирах между агентами.
* Используется **DID** (Decentralized Identifier) как уникальный идентификатор агента.
* Для проверки подлинности применяется криптоподпись (публичный/приватный ключ).
* Для защиты от спама/флуда используется **Proof-of-Work (PoW)**.
* Каждый агент может иметь несколько сетевых интерфейсов (адресов).
* У агента может быть только **одна устойчивая пара DID + pubkey**.

---

## 2. Интерфейсы

Формат интерфейса:

```json
{
  "addr": "tcp://1.2.3.4:4000",
  "nonce": 123456,
  "pow_hash": "abcd1234...",
  "difficulty": 22,
  "datetime": "2025-09-14T21:00:00Z",
  "type": "internet"
}
```

### Поддерживаемые протоколы

* `tcp://`
* `udp://`

### Поле `type` (опционально)

* `localhost` — адреса локальной машины.
* `lan:[маска_подсети]` — локальная сеть, пример: `lan:192.168.10.0`.
  (Один агент может иметь несколько сетевых интерфейсов и, соответственно, несколько LAN-сегментов.)
* `internet` — обычное TCP/UDP-подключение через глобальную сеть.
* `yggdrasil` — узел доступен через Yggdrasil overlay.
* `i2p` — узел доступен через I2P.

### Правила

* Если `port = 0` → интерфейс считается **отключённым**.
* Корректный интерфейс с более новой датой заменяет аналогичный старый (после проверки PoW).
* При обмене рекомендуется **не передавать локальные интерфейсы** в Интернет (исключение: Yggdrasil и I2P).

---

## 3. Proof-of-Work (PoW)

* Каждый интерфейс сопровождается PoW.
* Сложность PoW должна быть выбрана так, чтобы генерация занимала **несколько минут** (операция нечастая).
* Поля:

  * `nonce` — число, подобранное агентом.
  * `pow_hash` — хэш значения (`addr + nonce`).
  * `difficulty` — число ведущих нулей (или иное условие).

---

## 4. Сообщения

### 4.1 DISCOVERY

Используется для объявления себя в локальной сети.

```json
{
  "type": "DISCOVERY",
  "id": "did:example:123",
  "name": "Agent_X",
  "pubkey": "base58...",
  "addresses": [ { ... }, { ... } ]
}
```

### 4.2 PEER\_EXCHANGE\_REQUEST / RESPONSE

Запрос и обмен известными пирами.

```json
{
  "type": "PEER_EXCHANGE_REQUEST",
  "id": "did:example:123",
  "name": "Agent_X",
  "addresses": [ { ... } ]
}
```

Ответ:

```json
[
  {
    "id": "did:example:456",
    "name": "Agent_Y",
    "pubkey": "base58...",
    "addresses": [ { ... } ]
  }
]
```

---

## 5. Обработка ошибок и нестыковок

* **Разные pubkey для одного DID** → принимается **первый**, остальные игнорируются.
* **Адрес подписан чужим ключом** → запись отклоняется.
* **Адрес без PoW / с некорректным PoW** → запись отклоняется.
* **Несколько интерфейсов** → сохраняются все; новый с более свежей датой заменяет старый.

---

## 6. Безопасность

* Для всех сообщений требуется **подпись отправителя** (в будущем: обязательная проверка).
* Сообщения без подписи или с невалидным PoW могут игнорироваться.
* В перспективе можно добавить шифрование трафика (например, на уровне TCP/TLS или QUIC).