Merge pull request #2 from ai5590/codex/analyze-block-addition-functionality-and-create-api-docs

Документация: добавление API `AddBlock` и раздела Blockchain в Dev_Docs
2026-03-30 00:38:39 +03:00 · 2026-03-30 00:38:39 +03:00 · 889ce0d921
commit 889ce0d921
parent 99cf000f24 1c9841b4a6
10 changed files with 372 additions and 8 deletions
--- a/Dev_Docs/00_INDEX.md
+++ b/Dev_Docs/00_INDEX.md
@ -4,34 +4,39 @@

 ## Список документов

-0. **API/00_Common_API_Format.md**  
+0. **API/00_Common_API_Format.md**
   Общий формат JSON-запросов и JSON-ответов по всему API: `op`, `requestId`, `status`, `ok`, `payload`, единые правила успеха и ошибок.

-0. **API/01_User_Registration_API.md**  
+0. **API/01_User_Registration_API.md**
   Временная глава API по регистрации пользователя: `AddUser` и временный `GetUser`, с пометкой о будущем переходе проверки identity напрямую через Solana.

-0. **API/02_Authentication_API.md**  
+0. **API/02_Authentication_API.md**
   Глава API по авторизации: `AuthChallenge`, `CreateAuthSession`, `SessionChallenge`, `SessionLogin`, подписи, `deviceKey`, `sessionKey`.

-0. **API/03_Session_Management_API.md**  
+0. **API/03_Session_Management_API.md**
   Глава API по управлению сессиями: `ListSessions` и `CloseActiveSession`.

+
+0. **API/04_Add_Block_to_Blockchain_API.md**
+   Глава API по записи блоков: формат `AddBlock`, коды ошибок, поддержанные типы/подтипы блоков и рекомендации по ресинхронизации.
+
+1. **01_Connection_and_Sessions.md**
 0. **API/05_Technical_Requests_API.md**  
   Технические запросы без авторизации: `Ping` для keep-alive и `GetServerInfo` для проверки доступности узла и чтения его публичной информации.

 1. **01_Connection_and_Sessions.md**  
   Процесс подключения к WebSocket, авторизация (двухшаговая), создание сессии, вход в существующую сессию, просмотр и закрытие сессий.

-2. **02_Blockchain_Structure_and_Block_Types.md**  
+2. **02_Blockchain_Structure_and_Block_Types.md**
   Архитектура блокчейна, форматы и типы блоков, что уже можно делать каждым типом блока.

-3. **03_Addable_Blocks_Channels_Messages_Connections.md**  
+3. **03_Addable_Blocks_Channels_Messages_Connections.md**
   Какие блоки добавляются через `AddBlock`, как делать каналы/подписки/контакты/друзей/лайки/ответы, что уже есть и чего не хватает в API.

-4. **04_Query_Design_for_Subscriptions_Counters_and_Sync.md**  
+4. **04_Query_Design_for_Subscriptions_Counters_and_Sync.md**
   Проектирование новых API-запросов: список подписок с общим/новым числом сообщений, список сообщений канала, граф ответов для сообщения, поток синхронизации online/offline.

-5. **05_Open_Questions_and_TODO.md**  
+5. **05_Open_Questions_and_TODO.md**
   Список открытых вопросов, рисков и приоритетов для доработки сервера.

 ## Почему так разбито
@ -41,3 +46,28 @@
 - **Потом прикладные функции (каналы/сообщения/связи)** — что реально можно сделать уже сейчас.
 - **Потом проектирование отсутствующих запросов** — чтобы закрыть разрыв между текущим сервером и нужной функциональностью клиента.
 - **В конце вопросы** — чтобы быстро согласовать спорные места.
+
+
+6. **Blockchain/00_Blockchain_Formats_and_Block_Types.md**
+   Индекс раздела по форматам блокчейна и блоков.
+
+7. **Blockchain/01_Common_Block_Format.md**
+   Общий бинарный формат блока (Frame v0), подпись и обязательные проверки на `AddBlock`.
+
+8. **Blockchain/02_Blockchain_Kinds_and_Lines.md**
+   Виды блокчейнов (`login-NNN`) и логические линии внутри цепочки.
+
+9. **Blockchain/10_TECH_Blocks.md**
+   Системные блоки: `HEADER_COMPAT`, `TECH_CREATE_CHANNEL`.
+
+10. **Blockchain/11_TEXT_Blocks.md**
+    Текстовые блоки: `POST`, `EDIT_POST`, `REPLY`, `EDIT_REPLY`.
+
+11. **Blockchain/12_REACTION_Blocks.md**
+    Реакции: `REACTION_LIKE`.
+
+12. **Blockchain/13_CONNECTION_Blocks.md**
+    Связи и подписки: `FRIEND/CONTACT/FOLLOW` и обратные операции.
+
+13. **Blockchain/14_USER_PARAM_Blocks.md**
+    Пользовательские параметры `key/value`.
--- a/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md
+++ b/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md
@ -0,0 +1,135 @@
+# API для разработчиков: 04 — Добавление блока в блокчейн (AddBlock)
+
+Документ описывает **текущий рабочий формат** сетевого вызова `AddBlock`, который используется для записи **любого** блока в блокчейн пользователя.
+
+> Важный принцип: на уровне JSON API сейчас есть **один универсальный метод** записи — `AddBlock`.
+> Конкретный смысл записи задаётся типом самого бинарного блока (`type/subType/version` в заголовке блока).
+
+## 1. Что делает `AddBlock`
+
+`AddBlock`:
+- принимает имя блокчейна и base64 бинарного блока;
+- проверяет непрерывность цепочки (`blockNumber`, `prevHash`);
+- проверяет формат и подпись Ed25519;
+- валидирует `body` по правилам типа блока;
+- сохраняет блок и обновляет состояние цепочки.
+
+## 2. JSON формат запроса
+
+`op = "AddBlock"`.
+
+```json
+{
+  "op": "AddBlock",
+  "requestId": "req-1001",
+  "payload": {
+    "blockchainName": "alice-001",
+    "blockNumber": 12,
+    "prevBlockHash": "ab12...ff", 
+    "blockBytesB64": "AAAB..."
+  }
+}
+```
+
+Поля `payload`:
+- `blockchainName` — обязательно, формат `login-NNN`.
+- `blockNumber` — обязательно (временное legacy-поле для совместимости; должно совпасть с номером внутри бинарного блока).
+- `prevBlockHash` — legacy-поле, сейчас сервер использует `prevHash` из бинарного блока и состояние цепочки.
+- `blockBytesB64` — обязательно: **полный бинарный блок** (`preimage + sigMarker + signature`) в Base64.
+
+## 3. Успешный ответ
+
+```json
+{
+  "op": "AddBlock",
+  "requestId": "req-1001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "reasonCode": null,
+    "serverLastGlobalNumber": 12,
+    "serverLastGlobalHash": "9f0e...a1"
+  }
+}
+```
+
+## 4. Ошибка (единый формат)
+
+При ошибках сервер отдаёт `Net_Exception_Response` со стандартными полями и дополнительно с состоянием сервера для ресинка:
+
+```json
+{
+  "op": "AddBlock",
+  "requestId": "req-1001",
+  "status": 400,
+  "ok": false,
+  "error": "bad_prev_hash",
+  "message": "Некорректный prevHash (цепочка не совпадает)",
+  "payload": {
+    "serverLastGlobalNumber": 11,
+    "serverLastGlobalHash": "c3d4...98"
+  }
+}
+```
+
+### Основные `reasonCode`
+
+- `empty_blockchain_name`, `bad_blockchain_name`
+- `blockchain_state_not_found`
+- `bad_block_base64`, `bad_block_format`, `bad_block_body`
+- `bad_block_number`, `req_global_mismatch`, `bad_prev_hash`
+- `bad_signature`, `signature_verify_failed`
+- `prev_line_block_not_found`, `bad_prev_line_hash`
+- `limit_exceeded`
+- `internal_error`
+
+## 5. Какие блоки реально можно добавлять через `AddBlock`
+
+Через `AddBlock` можно писать все поддержанные форматы:
+
+1. **TECH (type=0)**
+   - `HEADER_COMPAT (subType=0)`
+   - `TECH_CREATE_CHANNEL (subType=1)`
+
+2. **TEXT (type=1)**
+   - `TEXT_POST (10)`
+   - `TEXT_EDIT_POST (11)`
+   - `TEXT_REPLY (20)`
+   - `TEXT_EDIT_REPLY (21)`
+
+3. **REACTION (type=2)**
+   - `REACTION_LIKE (1)`
+
+4. **CONNECTION (type=3)**
+   - `CONNECTION_FRIEND (10)`
+   - `CONNECTION_UNFRIEND (11)`
+   - `CONNECTION_CONTACT (20)`
+   - `CONNECTION_UNCONTACT (21)`
+   - `CONNECTION_FOLLOW (30)`
+   - `CONNECTION_UNFOLLOW (31)`
+
+5. **USER_PARAM (type=4)**
+   - `USER_PARAM_TEXT_TEXT (1)`
+
+## 6. Хватает ли функций сейчас
+
+Коротко: **для записи событий в блокчейн — хватает**, для полноценного клиентского чтения — **пока не хватает**.
+
+Что есть:
+- единый надёжный write-путь `AddBlock`;
+- есть `GetFriendsLists` и API по `UserParam`;
+- есть унифицированные коды ошибок и поля для ресинхронизации.
+
+Что пока ограничивает продукт:
+- нет полноценного read API для каналов/постов/тредов;
+- нет API списка подписок с серверными счётчиками непрочитанного;
+- нет ленты событий (новые ответы/лайки/подписки) как отдельного RPC.
+
+## 7. Рекомендации по клиенту при записи блоков
+
+1. Перед отправкой держать локальный `lastNumber/lastHash`.
+2. При `bad_prev_hash` или `bad_block_number`:
+   - взять `serverLastGlobalNumber/serverLastGlobalHash` из ошибки,
+   - пересобрать следующий блок на актуальной вершине.
+3. Для edit-блоков всегда ссылаться на **оригинальный** блок, а не на предыдущий edit.
+4. Для связей/подписок использовать target на **root** (HEADER или CREATE_CHANNEL), а не на произвольный пост.
--- a/Dev_Docs/Blockchain/00_Blockchain_Formats_and_Block_Types.md
+++ b/Dev_Docs/Blockchain/00_Blockchain_Formats_and_Block_Types.md
@ -0,0 +1,25 @@
+# Форматы блокчейнов и блоков (индекс раздела)
+
+Этот раздел разбит на несколько файлов, чтобы формат добавляемых блоков было проще читать и сопровождать.
+
+## Структура раздела
+
+- `01_Common_Block_Format.md` — общий бинарный формат блока (Frame v0), правила подписи и проверки.
+- `02_Blockchain_Kinds_and_Lines.md` — виды блокчейнов и логические линии внутри цепочки.
+- `10_TECH_Blocks.md` — системные блоки (`type=0`).
+- `11_TEXT_Blocks.md` — текстовые блоки (`type=1`).
+- `12_REACTION_Blocks.md` — реакции (`type=2`).
+- `13_CONNECTION_Blocks.md` — связи/подписки (`type=3`).
+- `14_USER_PARAM_Blocks.md` — пользовательские параметры (`type=4`).
+
+## Быстрая карта типов
+
+- `type=0` — TECH: HEADER, CREATE_CHANNEL.
+- `type=1` — TEXT: POST/EDIT_POST/REPLY/EDIT_REPLY.
+- `type=2` — REACTION: LIKE.
+- `type=3` — CONNECTION: FRIEND/CONTACT/FOLLOW и обратные операции.
+- `type=4` — USER_PARAM: key/value-параметры пользователя.
+
+## Примечание
+
+Если нужно добавить новый тип или подтип блока, сначала обновляйте профильный файл этого раздела, затем API-документацию в `Dev_Docs/API`.
--- a/Dev_Docs/Blockchain/01_Common_Block_Format.md
+++ b/Dev_Docs/Blockchain/01_Common_Block_Format.md
@ -0,0 +1,49 @@
+# Общий формат добавляемого блока (Frame v0)
+
+Этот файл описывает **единый бинарный формат** блока, который клиент отправляет через `AddBlock` в поле `blockBytesB64`.
+
+## 1. Полная структура блока
+
+Блок состоит из двух частей:
+
+1. **PREIMAGE** (подписывается)
+2. **TAIL** (маркер подписи + подпись)
+
+### PREIMAGE
+
+- `frameCode (uint16)`
+- `prevHash32 (32 bytes)`
+- `blockSize (int32)` — размер PREIMAGE
+- `blockNumber (int32)`
+- `timestamp (int64)`
+- `type (uint16)`
+- `subType (uint16)`
+- `version (uint16)`
+- `bodyBytes (N)`
+
+### TAIL
+
+- `sigMarker (uint16)`
+- `signature64 (64 bytes, Ed25519)`
+
+## 2. Что проверяет сервер при AddBlock
+
+- `frameCode` должен быть `0x0000`.
+- `sigMarker` должен быть `0x0100`.
+- `blockNumber` должен идти строго по порядку (`last + 1`).
+- `prevHash32` должен совпасть с вершиной цепочки на сервере.
+- `body` должен пройти `check()` для конкретного типа.
+- подпись должна валидироваться публичным ключом блокчейна.
+
+## 3. Ограничения
+
+- максимальный полный размер блока: до 4 MiB;
+- timestamp не должен сильно уходить в будущее;
+- `bodyBytes` парсится по `type/subType/version` из заголовка блока.
+
+## 4. Почему это важно
+
+Одинаковый общий формат позволяет:
+- передавать разные виды записей через один RPC `AddBlock`;
+- валидировать блоки единообразно;
+- расширять типы `body`, не ломая каркас блока.
--- a/Dev_Docs/Blockchain/02_Blockchain_Kinds_and_Lines.md
+++ b/Dev_Docs/Blockchain/02_Blockchain_Kinds_and_Lines.md
@ -0,0 +1,33 @@
+# Виды блокчейнов и логических линий
+
+## 1. Именованный блокчейн
+
+Базовый идентификатор цепочки пользователя:
+
+- `blockchainName = <login>-<NNN>`
+- пример: `alice-001`
+
+Обычно это одна основная цепочка пользователя.
+
+## 2. Логические линии внутри одной цепочки
+
+Физически цепочка одна, но внутри есть независимые логические последовательности (линии), которые ведутся через поля:
+
+- `lineCode`
+- `prevLineNumber`
+- `prevLineHash32`
+- `thisLineNumber`
+
+Линии используются для:
+- TECH-событий;
+- каналов с текстовыми постами;
+- связей и подписок;
+- пользовательских параметров.
+
+## 3. Root-идея для каналов и подписок
+
+Для ссылок вида follow/friend/contact принято ссылаться на корневые блоки:
+- `HEADER` для базовой сущности пользователя/канала `0`;
+- `CREATE_CHANNEL` для пользовательских каналов.
+
+Так ссылки остаются стабильными, даже когда в канале появляются новые сообщения.
--- a/Dev_Docs/Blockchain/10_TECH_Blocks.md
+++ b/Dev_Docs/Blockchain/10_TECH_Blocks.md
@ -0,0 +1,18 @@
+# TECH блоки (`type=0`, `version=1`)
+
+TECH-тип покрывает системные записи цепочки.
+
+## Подтипы
+
+1. `subType=0` — `HEADER_COMPAT`
+   - стартовый блок цепочки;
+   - payload: tag `SHiNE` + login владельца.
+
+2. `subType=1` — `TECH_CREATE_CHANNEL`
+   - создание нового канала;
+   - хранит line-поля + `channelName`.
+
+## Назначение
+
+- инициализация блокчейна;
+- управление набором каналов пользователя.
--- a/Dev_Docs/Blockchain/11_TEXT_Blocks.md
+++ b/Dev_Docs/Blockchain/11_TEXT_Blocks.md
@ -0,0 +1,25 @@
+# TEXT блоки (`type=1`, `version=1`)
+
+TEXT-тип хранит сообщения и редактирования.
+
+## Подтипы
+
+1. `subType=10` — `TEXT_POST`
+   - пост в линии канала;
+   - содержит line-поля + текст.
+
+2. `subType=11` — `TEXT_EDIT_POST`
+   - редактирование поста;
+   - line-поля + target на оригинальный POST + новый текст.
+
+3. `subType=20` — `TEXT_REPLY`
+   - ответ на сообщение;
+   - target (`toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`) + текст.
+
+4. `subType=21` — `TEXT_EDIT_REPLY`
+   - редактирование ответа;
+   - target на исходный REPLY + новый текст.
+
+## Правило для edit
+
+`EDIT_POST` и `EDIT_REPLY` должны ссылаться на **оригинальный** блок, а не на предыдущий edit.
--- a/Dev_Docs/Blockchain/12_REACTION_Blocks.md
+++ b/Dev_Docs/Blockchain/12_REACTION_Blocks.md
@ -0,0 +1,11 @@
+# REACTION блоки (`type=2`, `version=1`)
+
+## Подтипы
+
+1. `subType=1` — `REACTION_LIKE`
+   - лайк на целевой блок;
+   - хранит target: `toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`.
+
+## Назначение
+
+- реакция на текстовые сообщения (и потенциально другие target-блоки, если это разрешено бизнес-логикой).
--- a/Dev_Docs/Blockchain/13_CONNECTION_Blocks.md
+++ b/Dev_Docs/Blockchain/13_CONNECTION_Blocks.md
@ -0,0 +1,24 @@
+# CONNECTION блоки (`type=3`, `version=1`)
+
+CONNECTION-тип описывает социальные связи и подписки.
+
+## Подтипы
+
+1. `subType=10` — `CONNECTION_FRIEND`
+2. `subType=11` — `CONNECTION_UNFRIEND`
+3. `subType=20` — `CONNECTION_CONTACT`
+4. `subType=21` — `CONNECTION_UNCONTACT`
+5. `subType=30` — `CONNECTION_FOLLOW`
+6. `subType=31` — `CONNECTION_UNFOLLOW`
+
+## Общий формат payload
+
+- line-поля (`lineCode`, `prevLineNumber`, `prevLineHash32`, `thisLineNumber`)
+- target (`toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`)
+
+## Правила target
+
+- FRIEND/CONTACT обычно указывают на `HEADER` цели (`block 0`).
+- FOLLOW указывает на root канала:
+  - `HEADER` для канала `0`;
+  - `CREATE_CHANNEL` для пользовательского канала.
--- a/Dev_Docs/Blockchain/14_USER_PARAM_Blocks.md
+++ b/Dev_Docs/Blockchain/14_USER_PARAM_Blocks.md
@ -0,0 +1,14 @@
+# USER_PARAM блоки (`type=4`, `version=1`)
+
+## Подтипы
+
+1. `subType=1` — `USER_PARAM_TEXT_TEXT`
+   - хранит line-поля + `paramKey` + `paramValue`.
+
+## Назначение
+
+- сохранение пользовательского состояния (настройки клиента, синк-метки, курсоры чтения и т.д.).
+
+## Практика
+
+Для сложных структур удобно хранить JSON-строку в `paramValue` с версией схемы.