dchain/docs/api/relay.md

# Relay API

REST API для работы с шифрованными сообщениями через relay-сеть.

Сообщения шифруются E2E с использованием NaCl (X25519 + XSalsa20-Poly1305). Relay хранит зашифрованные конверты и доставляет их получателям.

## Отправить сообщение

### `POST /relay/send`

Зашифровать и отправить сообщение получателю.

**Request body:**
```json
{
  "recipient_pub": "<x25519_hex>",
  "msg_b64": "<base64_encoded_message>"
}
```

| Поле | Тип | Описание |
|------|-----|---------|
| `recipient_pub` | string | X25519 public key получателя (hex) |
| `msg_b64` | string | Сообщение в base64 |

```bash
MSG=$(echo -n "Hello, Bob!" | base64)
curl -X POST http://localhost:8081/relay/send \
  -H "Content-Type: application/json" \
  -d "{\"recipient_pub\":\"$BOB_X25519\",\"msg_b64\":\"$MSG\"}"
```

**Response:**
```json
{
  "id": "env-abc123",
  "recipient_pub": "...",
  "status": "sent"
}
```

---

## Broadcast конверта

### `POST /relay/broadcast`

Опубликовать pre-sealed конверт (для light-клиентов, которые шифруют на своей стороне).

**Request body:**
```json
{
  "envelope": {
    "id": "...",
    "recipient_pub": "...",
    "sender_pub": "...",
    "payload_b64": "...",
    "timestamp": 1710000000,
    "fee_ut": 100
  }
}
```

```bash
curl -X POST http://localhost:8081/relay/broadcast \
  -H "Content-Type: application/json" \
  -d '{"envelope": {...}}'
```

**Response:**
```json
{"id": "env-abc123", "status": "broadcast"}
```

---

## Inbox

### `GET /relay/inbox?pub=<x25519hex>&since=<ts>&limit=N`

Получить сообщения из inbox.

**Query параметры:**
| Параметр | Обязательный | Описание |
|---------|------------|---------|
| `pub` | Да | X25519 pubkey получателя (hex) |
| `since` | Нет | Unix timestamp — только сообщения новее |
| `limit` | Нет | Максимум (по умолчанию 50) |

```bash
# Получить все сообщения
curl "http://localhost:8081/relay/inbox?pub=$MY_X25519"

# Только новые (после timestamp)
curl "http://localhost:8081/relay/inbox?pub=$MY_X25519&since=1710000000&limit=20"
```

**Response:**
```json
{
  "pub": "...",
  "count": 2,
  "has_more": false,
  "items": [
    {
      "id": "env-abc123",
      "sender_pub": "...",
      "payload_b64": "...",
      "timestamp": 1710000000,
      "fee_ut": 100
    }
  ]
}
```

> `payload_b64` содержит зашифрованное сообщение. Расшифровка выполняется на стороне клиента с помощью X25519 private key.

---

### `GET /relay/inbox/count?pub=<hex>`

Количество сообщений в inbox.

```bash
curl "http://localhost:8081/relay/inbox/count?pub=$MY_X25519"
```

**Response:**
```json
{"pub": "...", "count": 3}
```

---

### `DELETE /relay/inbox/{envID}?pub=<hex>`

Удалить сообщение из inbox.

```bash
curl -X DELETE "http://localhost:8081/relay/inbox/env-abc123?pub=$MY_X25519"
```

**Response:**
```json
{"id": "env-abc123", "status": "deleted"}
```

---

## Контакты

### `GET /relay/contacts?pub=<ed25519hex>`

Входящие запросы на контакт.

> Используйте **ed25519** pubkey (не X25519).

```bash
curl "http://localhost:8081/relay/contacts?pub=$MY_ED25519"
```

**Response:**
```json
{
  "pub": "...",
  "count": 1,
  "contacts": [
    {
      "from_pub": "03abcd...",
      "from_nick": "alice",
      "intro": "Hi! Let's connect.",
      "fee_ut": 1000,
      "timestamp": 1710000000
    }
  ]
}
```

---

## CLI команды для relay

Прямой вызов relay API через CLI:

```bash
# Отправить сообщение (автоматически ищет X25519 ключ в registry)
client send-msg \
  --to $RECIPIENT_PUB \
  --msg "Hello!" \
  --key key.json \
  --node http://localhost:8081

# Отправить через @username
client send-msg \
  --to @alice \
  --msg "Hello Alice!" \
  --registry $REGISTRY_ID \
  --key key.json \
  --node http://localhost:8081

# Получить сообщения из inbox
client inbox \
  --key key.json \
  --node http://localhost:8081 \
  --limit 20

# Удалить прочитанные
client inbox \
  --key key.json \
  --node http://localhost:8081 \
  --delete

# Запросить контакт
client request-contact \
  --to $RECIPIENT_PUB \
  --fee 1000 \
  --intro "Hi, I want to connect" \
  --key key.json \
  --node http://localhost:8081
```

---

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

```
Отправитель                         Relay Node                    Получатель
    │                                    │                             │
    │── POST /relay/send ───────────────▶│                             │
    │   {recipient_pub, msg_b64}         │ Encrypt (NaCl box)          │
    │                                    │ Broadcast via gossipsub     │
    │                                    │◀── gossip ─────────────────▶│
    │                                    │                             │
    │                                    │ Store in mailbox            │
    │                                    │                             │
    │                                    │◀── GET /relay/inbox?pub=... ─│
    │                                    │                             │
    │                                    │─── {items:[{payload_b64}]} ▶│
    │                                    │                             │
    │                                    │ Submit RELAY_PROOF tx       │
    │                                    │ (claim fee from sender)     │
```

**Gossipsub топик:** `dchain/relay/v1`

**Fee:** Relay берёт fee (задаётся при регистрации `--relay-fee`). Sender должен иметь достаточный баланс. Fee списывается при доставке через RELAY_PROOF транзакцию.