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
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.
Разделы
| Документ | Эндпоинты |
|---|---|
| chain.md | Блоки, транзакции, балансы, адреса, netstats, validators |
| contracts.md | Деплой, вызов, state, логи контрактов |
| 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) |
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.
Аутентификация
По умолчанию 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=<...>.
Примеры
# Базовый 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