546d2c503f
Excluded from release bundle:
- CONTEXT.md, CHANGELOG.md (agent/project working notes)
- client-app/ (React Native messenger — tracked separately)
- contracts/hello_go/ (unused standalone example)
Kept contracts/counter/ and contracts/name_registry/ as vm-test fixtures
(referenced by vm/vm_test.go; NOT production contracts).
Docs refactor:
- docs/README.md — new top-level index with cross-references
- docs/quickstart.md — rewrite around single-node as primary path
- docs/node/README.md — full rewrite, all CLI flags, schema table
- docs/api/README.md — add /api/well-known-version, /api/update-check
- docs/contracts/README.md — split native (Go) vs WASM (user-deployable)
- docs/update-system.md — new, full 5-layer update system design
- README.md — link into docs/, drop CHANGELOG/client-app references
Build-time version system (inherited from earlier commits this branch):
- node --version / client --version with ldflags-injected metadata
- /api/well-known-version with {build, protocol_version, features[]}
- Peer-version gossip on dchain/version/v1
- /api/update-check against Gitea release API
- deploy/single/update.sh with semver guard + 15-min systemd jitter
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
# 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
|
||
```
|