Skip to content

API.md

Latest commit

 

History

History
99 lines (78 loc) · 5.33 KB

API.md

File metadata and controls

99 lines (78 loc) · 5.33 KB
Raw

API dagdb

Расположение: docs/api/ · Спецификация: openapi.json (OpenAPI 3.0.3), отдаётся GET /openapi.json; минимальный Swagger UI — GET /docs.

Спецификация публичного API — openapi.json (OpenAPI 3.0.3), доступна в рантайме по GET /openapi.json; минимальный Swagger UI — GET /docs.

Публичные эндпоинты не требуют токена. Внутренние (/add, /remove_heavy_nodes, /load-genesis, /raft/*, /mng/*) требуют заголовок x-internal-token и в спецификации не документируются.

Публичные эндпоинты

Метод Путь Назначение
POST / Принять подписанную транзакцию
GET /pool?limit=&offset= Узлы-кандидаты к очистке (по числу родителей)
GET /full?limit=&offset= Граф с глубинами (по возрастанию глубины)
GET /metrics Метрики Prometheus
GET /health Liveness
GET /ready Readiness (лидер выбран, Redis достижим)
GET /openapi.json OpenAPI-спецификация
GET /docs Swagger UI

limit — по умолчанию 100, максимум 1000; offset — по умолчанию 0. Тело запроса ограничено MAX_REQUEST_BYTES (по умолчанию 1 МиБ, ответ 413). Публичный POST / ограничен по частоте (429 при превышении).

Схема транзакции

{
  "tx": {
    "prnts": ["<hash>", "<hash>"],   // 2..100 уникальных непустых хэшей
    "addr":  "<ed25519 pubkey base58>",
    "seq":   0,
    "var":   { "ca": "<addr>", "to": "<addr>", "val": 100, "msg": "optional" }
  },
  "sign": "<ed25519 signature, hex, 64 bytes>",
  "func": "transferToken"
}

func

func входит в подписываемый и хэшируемый контент. Известные значения: transferToken. Подмена func меняет канонический хэш и ломает подпись.

var для transferToken

Поле Тип Правило
ca string непустой адрес-источник
to string непустой адрес-получатель
val integer ≥ 0 сумма
msg string? не длиннее 2500 символов

Канонический хэш и подпись

  1. Берётся JSON-представление tx и в него добавляется func.
  2. Выполняется каноническая сериализация: ключи всех объектов рекурсивно сортируются, порядок элементов массивов сохраняется.
  3. hash = blake3(canonical_json).
  4. sign — ed25519-подпись байтов хэша ключом addr.

Правила валидации одинаковы на всех репликах и не зависят от сети/времени:

  • prnts: 2..100 элементов, непустые, уникальные; на границе API.
  • Генезис-узлы (пустой список родителей) допустимы только во внутренней команде.
  • func должен быть известен.
  • структура var обязана соответствовать func.
  • подпись обязана проверяться против адреса.
  • узел с таким хэшем не должен существовать (в DAG или реестре added).
  • все родители должны существовать в живом DAG; родитель, оставшийся только в реестре added (удалённый), отклоняется (V15).
  • seq адреса обязан строго возрастать (анти-replay; пустой addr генезиса освобождён) (V18). Монотонность проверяется в рамках одного адреса: порядок применения в логе не обязан совпадать с порядком отправки, поэтому клиент обязан сериализовать seq одного аккаунта (следующий seq слать только после ответа на предыдущий). Для конкурентной отправки используйте разные адреса (аккаунты) — их seq независимы.

Примеры

Подпись и отправка (фрагмент на Rust):

let hash = ordered_sum(&tx, "transferToken")?;      // blake3 канонического контента
let sign = hex::encode(signing_key.sign(hash.as_bytes()).to_bytes());
let body = json!({ "tx": tx, "sign": sign, "func": "transferToken" });
reqwest::Client::new().post("http://127.0.0.1:21001/").json(&body).send().await?;

Чтение графа:

curl 'http://127.0.0.1:21001/full?limit=50&offset=0'
curl 'http://127.0.0.1:21001/pool?limit=50'