# REST + WebSocket API

DChain-нода обслуживает HTTP + WebSocket на `--stats-addr` (по умолчанию `:8080`).
JSON везде; ошибки в формате `{"error": "описание"}`, с 4xx для клиентских
проблем и 5xx для серверных.

Полная OpenAPI-спека живёт в бинаре (`/swagger/openapi.json`) и рендерится
Swagger UI на `/swagger`. Эти два эндпоинта можно выключить через
`DCHAIN_DISABLE_SWAGGER=true` — см. [deploy/single/README.md](../../deploy/single/README.md).

## Разделы

| Документ | Эндпоинты |
|---------|----------|
| [chain.md](chain.md) | Блоки, транзакции, балансы, адреса, netstats, validators |
| [contracts.md](contracts.md) | Деплой, вызов, state, логи контрактов |
| [relay.md](relay.md) | Relay-mailbox: отправка/приём encrypted envelopes |

## Discovery / metadata (always on)

| Endpoint | Возврат |
|----------|---------|
| `GET /api/netstats` | height, total_txs, supply, validator_count |
| `GET /api/network-info` | chain_id, genesis_hash, peers[], validators[], contracts |
| `GET /api/well-known-version` | node_version, build{}, protocol_version, features[], chain_id |
| `GET /api/well-known-contracts` | canonical contract_id → name mapping |
| `GET /api/update-check` | comparison with upstream Gitea release (см. [../update-system.md](../update-system.md)) |
| `GET /api/peers` | connected peer IDs + их версии (из gossip `dchain/version/v1`) |
| `GET /api/validators` | active validator set |
| `GET /metrics` | Prometheus exposition |

## Real-time (push)

- **`GET /api/ws`** — WebSocket, рекомендованный транспорт. Поддерживает
  `submit_tx`, `subscribe`, `unsubscribe`, `typing`, `ping`. Push-события:
  `block`, `tx`, `inbox`, `typing`, `submit_ack`.
- `GET /api/events` — SSE, legacy одностороннее streaming (для старых клиентов).

Protocol reference — `node/ws.go` + [../architecture.md](../architecture.md).

## Аутентификация

По умолчанию API **публичен**. Три режима access-control настраиваются через
env:

| Режим | `DCHAIN_API_TOKEN` | `DCHAIN_API_PRIVATE` | Эффект |
|-------|:------------------:|:--------------------:|--------|
| Public | не задан | — | Все могут читать и submit'ить tx |
| Token writes | задан | `false` | Читать — любой; `POST /api/tx` и WS `submit_tx` — только с `Authorization: Bearer <token>` |
| Fully private | задан | `true` | Все эндпоинты требуют token (включая `/api/netstats`) |

WebSocket: токен передаётся query-параметром `?token=<...>`.

## Примеры

```bash
# Базовый health
curl -s http://localhost:8080/api/netstats | jq .

# Версия ноды
curl -s http://localhost:8080/api/well-known-version | jq '{tag: .build.tag, features: .features}'

# Список пиров с их версиями
curl -s http://localhost:8080/api/peers | jq '.peers[].version'

# С токеном (private-режим)
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/netstats

# Submit tx (public-режим)
curl -s -X POST -H "Content-Type: application/json" \
  -d @tx.json http://localhost:8080/api/tx
```