chore: initial commit for v0.0.1
DChain single-node blockchain + React Native messenger client. Core: - PBFT consensus with multi-sig validator admission + equivocation slashing - BadgerDB + schema migration scaffold (CurrentSchemaVersion=0) - libp2p gossipsub (tx/v1, blocks/v1, relay/v1, version/v1) - Native Go contracts (username_registry) alongside WASM (wazero) - WebSocket gateway with topic-based fanout + Ed25519-nonce auth - Relay mailbox with NaCl envelope encryption (X25519 + Ed25519) - Prometheus /metrics, per-IP rate limit, body-size cap Deployment: - Single-node compose (deploy/single/) with Caddy TLS + optional Prometheus - 3-node dev compose (docker-compose.yml) with mocked internet topology - 3-validator prod compose (deploy/prod/) for federation - Auto-update from Gitea via /api/update-check + systemd timer - Build-time version injection (ldflags → node --version) - UI / Swagger toggle flags (DCHAIN_DISABLE_UI, DCHAIN_DISABLE_SWAGGER) Client (client-app/): - Expo / React Native / NativeWind - E2E NaCl encryption, typing indicator, contact requests - Auto-discovery of canonical contracts, chain_id aware, WS reconnect on node switch Documentation: - README.md, CHANGELOG.md, CONTEXT.md - deploy/single/README.md with 6 operator scenarios - deploy/UPDATE_STRATEGY.md with 4-layer forward-compat design - docs/contracts/*.md per contract
This commit is contained in:
vsecoder
246
docs/api/relay.md
Normal file
246
docs/api/relay.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# 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 транзакцию.
|
||||
Reference in New Issue
Block a user