dchain/docs/api/relay.md

Relay API

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

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

Это API для 1:1 чатов. Для публичных постов и ленты — см. feed.md.

Server-side guarantees (v1.0.x hardening):

• envelope.ID пересчитывается канонически (sha256(nonce||ct)[:16]) на mailbox.Store — защита от content-replay.
• envelope.SentAt переписывается серверным time.Now().Unix() — клиент не может back-date/future-date сообщения.
• /relay/broadcast и /relay/inbox/* обёрнуты в rate-limiter (withSubmitTxGuards / withReadLimit); одиночный атакующий не может через FIFO-eviction выбросить реальные сообщения получателя.
• DELETE /relay/inbox/{id} требует Ed25519-подпись владельца, связанную с x25519-ключом через identity-реестр.

Опубликовать envelope

POST /relay/broadcast — рекомендованный E2E-путь

Клиент запечатывает сообщение через NaCl box своим X25519-privkey на публичный ключ получателя → отправляет готовый envelope. Сервер проверяет размер, канонизирует id/timestamp, сохраняет в mailbox и гошепит пирам.

Request body:

{
  "envelope": {
    "id": "<hex>",
    "sender_pub": "<x25519_hex>",
    "recipient_pub": "<x25519_hex>",
    "sender_ed25519_pub": "<ed25519_hex>",
    "fee_ut": 0,
    "fee_sig": null,
    "nonce": "<base64 24B>",
    "ciphertext": "<base64 NaCl box>",
    "sent_at": 1710000000
  }
}

Response: {"id": "<canonical_id>", "status": "broadcast"}

Поле envelope.id сервер перезапишет на hex(sha256(nonce||ciphertext)[:16]); клиент может прислать любое непустое значение.

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

---

Отправить plaintext через релей (legacy / non-E2E)

POST /relay/send — ⚠ НЕ E2E

Нода запечатывает сообщение своим X25519-ключом. Получатель не сможет расшифровать без знания privkey релея, и отправитель не аутентифицируется. Оставлено для backward-compat; в продакшн-чатах используйте /relay/broadcast.

Request body:

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

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 конверта (legacy alias)

POST /relay/broadcast

См. выше. Это основной E2E-путь.

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=<x25519hex>

Удалить сообщение из inbox. Требует подписи Ed25519-ключа, чья identity связана с ?pub=<x25519> через on-chain identity-реестр — защита от grief-DELETE любым знающим ваш pubkey.

Request body:

{
  "ed25519_pub": "<hex>",
  "sig":         "<base64 Ed25519 signature>",
  "ts":          1710000000
}

Где sig = Ed25519.Sign(priv, "inbox-delete:<envID>:<x25519pub>:<ts>"). ts должен быть в пределах ±5 минут от серверного времени (anti-replay).

# подпись: printf 'inbox-delete:env-abc123:%s:%d' "$MY_X25519" "$TS" | sign
curl -X DELETE "http://localhost:8081/relay/inbox/env-abc123?pub=$MY_X25519" \
  -H "Content-Type: application/json" \
  -d "{\"ed25519_pub\":\"$MY_ED25519\",\"sig\":\"$SIG\",\"ts\":$TS}"

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

Errors: 403 если подпись/идентичность не совпадает; 503 если на ноде не настроен identity-resolver (DCHAIN_DISABLE_INBOX_DELETE).

---

Контакты

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 транзакцию.