dchain/docs/api/relay.md

Relay API

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

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

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

POST /relay/send

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

Request body:

{
  "recipient_pub": "<x25519_hex>",
  "msg_b64": "<base64_encoded_message>"
}

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

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:

{
  "id": "env-abc123",
  "recipient_pub": "...",
  "status": "sent"
}

---

Broadcast конверта

POST /relay/broadcast

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

Request body:

{
  "envelope": {
    "id": "...",
    "recipient_pub": "...",
    "sender_pub": "...",
    "payload_b64": "...",
    "timestamp": 1710000000,
    "fee_ut": 100
  }
}

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

Response:

{"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)

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

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

Response:

{
  "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.

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

Response:

{"pub": "...", "count": 3}

---

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

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

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

Response:

{"id": "env-abc123", "status": "deleted"}

---

Контакты

GET /relay/contacts?pub=<ed25519hex>

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

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

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

Response:

{
  "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:

# Отправить сообщение (автоматически ищет 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 транзакцию.