Compare commits
No commits in common. "main" and "master" have entirely different histories.
69
.gitignore
vendored
69
.gitignore
vendored
@ -1,11 +1,4 @@
|
|||||||
## папки с данными создавайемыми при работе сервера
|
|
||||||
data/
|
|
||||||
logs/
|
|
||||||
logs
|
|
||||||
.understand-anything/
|
|
||||||
|
|
||||||
.gradle
|
.gradle
|
||||||
.gradle-home/
|
|
||||||
build/
|
build/
|
||||||
!gradle/wrapper/gradle-wrapper.jar
|
!gradle/wrapper/gradle-wrapper.jar
|
||||||
!**/src/main/**/build/
|
!**/src/main/**/build/
|
||||||
@ -48,65 +41,3 @@ bin/
|
|||||||
|
|
||||||
### Mac OS ###
|
### Mac OS ###
|
||||||
.DS_Store
|
.DS_Store
|
||||||
|
|
||||||
# временный debug token
|
|
||||||
.debug-token
|
|
||||||
|
|
||||||
# Локальные артефакты и секреты Solana-модуля
|
|
||||||
shine-solana/.git/
|
|
||||||
shine-solana/.git-local-backup/
|
|
||||||
shine-solana/.idea/
|
|
||||||
shine-solana/shine/.idea/
|
|
||||||
shine-solana/shine/.gradle/
|
|
||||||
shine-solana/shine/.anchor/
|
|
||||||
shine-solana/shine/.yarn/
|
|
||||||
shine-solana/shine/.vendor/
|
|
||||||
shine-solana/shine/node_modules/
|
|
||||||
shine-solana/shine/target/
|
|
||||||
shine-solana/shine/test-ledger/
|
|
||||||
shine-solana/shine/old_vers/
|
|
||||||
shine-solana/shine/program-keypair.json
|
|
||||||
shine-solana/shine/keys/
|
|
||||||
shine-solana/shine/validator.log
|
|
||||||
shine-solana/shine/doc/КОШЕЛЬКИ_DEVNET_ТЕСТ.md
|
|
||||||
shine-solana/shine/scripts/del/
|
|
||||||
shine-solana/shine/scripts/**/keypairs/
|
|
||||||
shine-solana/shine/scripts/**/runs/
|
|
||||||
shine-solana/shine/scripts/**/*.env
|
|
||||||
shine-solana/shine/scripts/**/TEMP_*.md
|
|
||||||
|
|
||||||
# Локальные артефакты и внешние материалы ESP32-подпроекта
|
|
||||||
ESP32/esp32-config-tool/
|
|
||||||
ESP32/**/.git/
|
|
||||||
ESP32/**/.idea/
|
|
||||||
ESP32-wallet/.idea/
|
|
||||||
ESP32/**/.arduino-build/
|
|
||||||
ESP32/**/official-demo/
|
|
||||||
!ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/
|
|
||||||
ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/**
|
|
||||||
!ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/
|
|
||||||
ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/**
|
|
||||||
!ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/
|
|
||||||
ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/**
|
|
||||||
!ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/libraries/
|
|
||||||
ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/libraries/**
|
|
||||||
!ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/libraries/lv_conf.h
|
|
||||||
ESP32/**/original-firmware/*.bin
|
|
||||||
ESP32/**/original-firmware/*.bin.sha256
|
|
||||||
ESP32/**/*.elf
|
|
||||||
ESP32/**/*.map
|
|
||||||
ESP32/**/*.merged.bin
|
|
||||||
ESP32/**/*.uf2
|
|
||||||
ESP32/**/*.o
|
|
||||||
ESP32/**/*.d
|
|
||||||
ESP32/**/*.a
|
|
||||||
|
|
||||||
# Полные серверные бэкапы (тяжёлые архивы, не коммитим)
|
|
||||||
server-backup/archive/**
|
|
||||||
!server-backup/archive/.gitkeep
|
|
||||||
|
|
||||||
# Локальная дев-обвязка Claude (дев-сервер shine-UI, сессии, планы) — не коммитим
|
|
||||||
.claude/
|
|
||||||
# Рабочие бэкапы/превью-ассеты UI — не для репозитория
|
|
||||||
*.bak.png
|
|
||||||
shine-UI/assets/navbar_preview.png
|
|
||||||
|
|||||||
1
.idea/.name
generated
1
.idea/.name
generated
@ -1 +0,0 @@
|
|||||||
shine-server-server
|
|
||||||
2
.idea/gradle.xml
generated
2
.idea/gradle.xml
generated
@ -13,8 +13,6 @@
|
|||||||
<option value="$PROJECT_DIR$/shine-server-config" />
|
<option value="$PROJECT_DIR$/shine-server-config" />
|
||||||
<option value="$PROJECT_DIR$/shine-server-crypto" />
|
<option value="$PROJECT_DIR$/shine-server-crypto" />
|
||||||
<option value="$PROJECT_DIR$/shine-server-db" />
|
<option value="$PROJECT_DIR$/shine-server-db" />
|
||||||
<option value="$PROJECT_DIR$/shine-server-geo" />
|
|
||||||
<option value="$PROJECT_DIR$/shine-server-log" />
|
|
||||||
<option value="$PROJECT_DIR$/shine-server-net-protocol" />
|
<option value="$PROJECT_DIR$/shine-server-net-protocol" />
|
||||||
<option value="$PROJECT_DIR$/shine-server-net-server" />
|
<option value="$PROJECT_DIR$/shine-server-net-server" />
|
||||||
</set>
|
</set>
|
||||||
|
|||||||
2
.idea/vcs.xml
generated
2
.idea/vcs.xml
generated
@ -1,6 +1,6 @@
|
|||||||
<?xml version="1.0" encoding="UTF-8"?>
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
<project version="4">
|
<project version="4">
|
||||||
<component name="VcsDirectoryMappings">
|
<component name="VcsDirectoryMappings">
|
||||||
<mapping directory="" vcs="Git" />
|
<mapping directory="$PROJECT_DIR$" vcs="Git" />
|
||||||
</component>
|
</component>
|
||||||
</project>
|
</project>
|
||||||
156
AGENTS.md
156
AGENTS.md
@ -1,156 +0,0 @@
|
|||||||
# AGENTS
|
|
||||||
|
|
||||||
## Язык проекта
|
|
||||||
- По умолчанию использовать русский язык во всех пользовательских текстах и технических пояснениях.
|
|
||||||
- Пояснения к коммитам, PR и merge-запросам писать на русском языке.
|
|
||||||
- Комментарии в коде, встроенные справки, документацию и инструкции писать по возможности на русском языке.
|
|
||||||
|
|
||||||
## Примечание
|
|
||||||
- Если внешний инструмент/интеграция требует английский формат, допускается английский, но рядом желательно дать краткое пояснение на русском.
|
|
||||||
|
|
||||||
## Структура проекта (кратко)
|
|
||||||
- Серверный код SHiNE находится в папке `SHiNE-server/`.
|
|
||||||
- Код клиентского UI SHiNE находится в папке `shine-UI/`.
|
|
||||||
- Веб-панель администратора сервера (управление Solana PDA сервера) находится в `shine-UI/`:
|
|
||||||
- точка входа `shine-UI/server-ui.html`;
|
|
||||||
- остальные файлы серверного UI — в `shine-UI/server-ui/`.
|
|
||||||
- Локальный Telegram-бот агента-кодера находится в папке `SHiNE-agent-bot-coder/` и не является кодом основного серверного приложения.
|
|
||||||
- Solana/Anchor-модуль находится в папке `shine-solana/shine/` и ведётся отдельно от основного server/UI деплоя.
|
|
||||||
|
|
||||||
## Сервис агента-кодера
|
|
||||||
- В проекте есть локальный Telegram-бот-сервис агента-кодера в папке `SHiNE-agent-bot-coder/`.
|
|
||||||
- Сервис принимает сообщения из Telegram, ведёт историю диалога, ставит задачи в очередь и вызывает Codex CLI для обработки запросов по проекту.
|
|
||||||
- Автоматически читаемые инструкции для Codex внутри сервиса держать в `SHiNE-agent-bot-coder/AGENTS.md`.
|
|
||||||
- Подробные служебные правила Telegram-обработчика, его очередь, история, systemd-запуск и особенности ответов описывать в `SHiNE-agent-bot-coder/AGENT.md`.
|
|
||||||
- Если в сообщениях пользователя встречается «агент MD» или похожая формулировка про файл инструкций Codex, считать, что имеется в виду автоматически читаемый `AGENTS.md`.
|
|
||||||
|
|
||||||
## ESP32 UI homeserver
|
|
||||||
- Для UI-скетча устройства `ESP32-S3-Touch-AMOLED-2.16` документ-спецификация и Arduino-скетч должны всегда оставаться синхронными.
|
|
||||||
- Актуальный документ по экранной логике, состояниям, кнопкам, полям, статусам и ограничениям UI считать источником истины для скетча.
|
|
||||||
- При изменении документа обязательно в том же наборе изменений приводить в соответствие скетч.
|
|
||||||
- При изменении скетча обязательно в том же наборе изменений обновлять документ, если поменялись экраны, тексты, переходы, статусы, кнопки, поля или поведение.
|
|
||||||
- Для нового ESP32 UI-прототипа homeserver использовать русский язык как основной и отдельно следить, чтобы текст реально отображался на устройстве, а не только логически присутствовал в коде.
|
|
||||||
|
|
||||||
## Solana-модуль
|
|
||||||
- В проекте есть отдельный Solana/Anchor-модуль в папке `shine-solana/shine/`.
|
|
||||||
- Модуль логически связан с SHiNE, но не должен автоматически подключаться к сборке или деплою основного сервера без отдельного решения.
|
|
||||||
- В Solana-модуле действуют локальные инструкции `shine-solana/shine/AGENTS.md`; при изменениях внутри модуля сначала читать их.
|
|
||||||
- В git добавлять исходники, lock-файлы, настройки проекта и документацию Solana-модуля, но не добавлять локальные ключи, `.git`, `.idea`, `.gradle`, `target`, `node_modules`, `test-ledger`, логи, временные run-отчёты и `.env`-конфиги.
|
|
||||||
- Для Solana deploy/push использовать правила из локального `shine-solana/shine/AGENTS.md`; не смешивать deploy Solana-модуля с `deployServer`/`deployUI` основного проекта.
|
|
||||||
- Для регистрации пользователей в Solana (программа `shine_users`) единая актуальная инструкция по деплою/инициализации, адресам программ, и куда их прописывать в UI/сервере находится в:
|
|
||||||
- `Dev_Docs/Инициализация_Solana_регистрации/README.md`
|
|
||||||
- Этот файл считать основной справкой (single source of truth) по деплою и первичной инициализации Solana-регистрации в текущем проекте.
|
|
||||||
- Актуальная архитектурная справка по устройству Solana-программ, PDA-счетам, ролям DAO и движению средств находится в:
|
|
||||||
- `Dev_Docs/Solana_Architecture/README.md`
|
|
||||||
- Документ формата пользовательской PDA-записи `shine_users` находится в:
|
|
||||||
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
|
|
||||||
|
|
||||||
## Документация блокчейна
|
|
||||||
- Актуальная документация по форматам блокчейна находится в `Dev_Docs/Blockchain/README.md`.
|
|
||||||
- Это точка входа (оглавление), рядом расположены детальные файлы по форматам, типам каналов и командным сообщениям.
|
|
||||||
- При любом изменении кода, связанного с блокчейном (формат блока, типы каналов, правила чтения/записи, команды), обязательно обновлять соответствующие документы в `Dev_Docs/Blockchain/`.
|
|
||||||
- Дополнительно обязательно вести `Dev_Docs/Blockchain/CHANGELOG.md`: дописывать изменения построчно с указанием даты/времени и хэша коммита, после которого внесено изменение.
|
|
||||||
- Перед любым изменением формата блокчейна обязательно заранее предупреждать пользователя, что формат будет изменён.
|
|
||||||
- Изменять формат блокчейна можно только после явного подтверждения пользователя (без подтверждения формат не менять).
|
|
||||||
- Добавление любых данных в блокчейн выполнять только через операцию `AddBlock`.
|
|
||||||
- Перед каждым `AddBlock` обязательно проверять/актуализировать текущее состояние вершины блокчейна (`last global number/hash`) и использовать его при формировании блока.
|
|
||||||
|
|
||||||
## Документация личных сообщений (DM)
|
|
||||||
- Актуальная документация по логике личных сообщений находится в `Dev_Docs/Personal_Messages/README.md`.
|
|
||||||
- При любом изменении кода, связанного с личными сообщениями (формат подписанного DM-блока, типы DM-сообщений, правила доставки/ACK/read-receipt, роутинг по сессиям, UI-логика чатов), обязательно обновлять `Dev_Docs/Personal_Messages/README.md`.
|
|
||||||
- Логика личных сообщений в коде должна всегда соответствовать `Dev_Docs/Personal_Messages/README.md`.
|
|
||||||
- Документ по личным сообщениям обязан поддерживаться в актуальном состоянии.
|
|
||||||
|
|
||||||
## Документация API сервера
|
|
||||||
- Актуальная документация по публичному JSON/WebSocket API сервера находится в `Dev_Docs/API/`.
|
|
||||||
- При любом изменении серверного API/эндпоинтов/операций `op` обязательно обновлять соответствующие документы в `Dev_Docs/API/`.
|
|
||||||
- Перед изменением самого серверного API обязательно явно предупредить пользователя, какие операции, поля запросов/ответов или коды ошибок будут изменены, и запросить отдельное подтверждение.
|
|
||||||
- Без явного подтверждения пользователя формат серверного API не менять; допускается только приведение документации в соответствие уже существующему коду.
|
|
||||||
- Если добавляется новая операция `op`, нужно обновить общий список операций в `Dev_Docs/API/09_Operations_Index.md` или создать его, если файла ещё нет.
|
|
||||||
|
|
||||||
## Известная проблема (временная пометка)
|
|
||||||
- Мнения по связям пользователя (`known_person`, `shine_confirmed`, `shine_seen`) в UI могут отображаться нестабильно.
|
|
||||||
- Требуется отдельная доработка и финальная проверка end-to-end: запись мнения в блокчейн → обновление `connections_state` → ответ `GetUserConnectionsGraph` → отображение в UI.
|
|
||||||
- До фикса считать эту часть функционала незавершённой и обязательно перепроверять вручную после каждого деплоя.
|
|
||||||
|
|
||||||
## Версионирование
|
|
||||||
- Единый файл версий проекта: `VERSION.properties` (в корне репозитория).
|
|
||||||
- Перед каждым новым коммитом обязательно увеличивать версии в `VERSION.properties`:
|
|
||||||
- `client.version` — версия клиентского UI.
|
|
||||||
- `server.version` — версия серверной части.
|
|
||||||
- Базовое правило инкремента: `+1` по последнему числовому сегменту (patch), если не оговорено иное.
|
|
||||||
- Обычные коммиты делать стандартным `git commit`; переменная `$GITEA_TOKEN` для коммитов не нужна и не используется.
|
|
||||||
|
|
||||||
## Deploy
|
|
||||||
- Все документы и заметки по деплою хранить в папке `Dev_Docs/deploy/`.
|
|
||||||
- Production-хост SHiNE: `player@shineup.me` (`185.229.109.118`).
|
|
||||||
- Основной test-хост SHiNE: `player@193.8.215.70` (`test2.shineup.me`).
|
|
||||||
- Резервный test-хост SHiNE: `player@93.170.12.154` (`test.shineup.me`).
|
|
||||||
- Базовый путь на сервере для SHiNE: `/home/player` (проекты SHiNE размещать в `/home/player/SHiNE/...`).
|
|
||||||
- По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
|
|
||||||
- Для операций `git push` при необходимости использовать токен из переменной окружения `$GITEA_TOKEN`.
|
|
||||||
- Любые изменения и любой деплой на production `shineup.me` выполнять только после отдельного явного подтверждения пользователя.
|
|
||||||
- Если пользователь пишет просто `задеплой` без уточнения production/test, по умолчанию деплоить на `test2.shineup.me`.
|
|
||||||
- Default server deploy: `./gradlew deployServer` или `./gradlew deployServerTest2`.
|
|
||||||
- Default UI deploy: `./gradlew deployUI` или `./gradlew deployUITest2`.
|
|
||||||
- Production server deploy: `./gradlew deployServerProduction`.
|
|
||||||
- Production UI deploy: `./gradlew deployUIProduction`.
|
|
||||||
- Резервный test deploy на `test.shineup.me`: `./gradlew deployServerTest` и `./gradlew deployUITest`, но пока их не использовать без отдельной причины.
|
|
||||||
- Для локального запуска использовать `./gradlew startLocal` (или `startLocalWithBuild`).
|
|
||||||
- Сначала предлагать локальную проверку, а деплой на сервер выполнять по запросу пользователя.
|
|
||||||
- Для временной бесплатной загрузки аватаров в Arweave секретный JWK нельзя хранить в git и нельзя прописывать в репозиторный `application.properties`.
|
|
||||||
- Для продовой настройки тестового Arweave-кошелька JWK-файл нужно хранить только на сервере, например: `/home/player/SHiNE/secrets/test-free-avatar-wallet.json`.
|
|
||||||
- Для этой временной фичи на проде должны быть заданы параметры `test.freeAvatar.walletJwkPath` и `test.freeAvatar.walletAddress` через серверный override-конфиг/секреты на хосте.
|
|
||||||
- После изменения продовых значений `test.freeAvatar.*` нужно заново выполнить серверный деплой или перезапуск сервера, чтобы настройки были перечитаны приложением.
|
|
||||||
- При таких изменениях в git допускается коммитить только документацию и код чтения настроек, но не сам JWK, не содержимое секрета и не реальные приватные ключи.
|
|
||||||
|
|
||||||
## Логи звонков (установка соединения)
|
|
||||||
- Специальный поток диагностики установки звонков идёт через `CallDeliveryReport` (клиент → сервер).
|
|
||||||
- На проде специальный файл для звонков:
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/call-delivery-events.log`
|
|
||||||
- Общий серверный лог (и ротации) на проде:
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/app.log`
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/app.YYYY-MM-DD.log`
|
|
||||||
- Для анализа причин недозвона в первую очередь фильтровать записи по ключам:
|
|
||||||
- `CallDeliveryReport`
|
|
||||||
- `call_connected`
|
|
||||||
- `outgoing_failed`
|
|
||||||
- `incoming_failed`
|
|
||||||
- `call_busy`
|
|
||||||
- `call_declined`
|
|
||||||
- `unknown_error`
|
|
||||||
- В этих записях искать поля `reason`, `failureStage`, `pcConnectionState`, `pcIceConnectionState`, `routeLabel`, `configuredTurnHosts*`, `reachableTurnHosts*`.
|
|
||||||
|
|
||||||
## Недопроверенные фичи (обязательно)
|
|
||||||
- Папка для учёта недопроверенных фич: `Dev_Docs/Pending_Features/`.
|
|
||||||
- По каждой новой доработке, которая требует ручной проверки, добавлять отдельный markdown-файл в `Dev_Docs/Pending_Features/`.
|
|
||||||
- Рекомендуемый формат имени файла: `YYYY-MM-DD_HHMM_<short-feature-name>.md`.
|
|
||||||
- Имена новых файлов и краткие описания фич по возможности писать на русском языке.
|
|
||||||
- Внутри файла обязательно указывать:
|
|
||||||
- краткое описание фичи;
|
|
||||||
- что именно проверять;
|
|
||||||
- ожидаемый результат;
|
|
||||||
- статус (например: `pending`, `in_progress`, `done`).
|
|
||||||
- После подтверждения, что фича проверена и работает корректно, соответствующий файл удалять.
|
|
||||||
- В `Dev_Docs/Pending_Features/README.md` вести краткий регламент и поддерживать актуальность.
|
|
||||||
|
|
||||||
## Будущие фичи
|
|
||||||
- Папка для задач, сознательно отложенных на будущее: `Dev_Docs/Future_Features/`.
|
|
||||||
- Точка входа по планам: `Dev_Docs/Future_Features/README.md`.
|
|
||||||
- Внутри планы разделены по горизонтам: `near/`, `medium/`, `far/`.
|
|
||||||
- Если пользователь спрашивает, какие есть планы или что можно продолжить, сначала читать `Dev_Docs/Future_Features/README.md`, затем при необходимости конкретные файлы из горизонтов.
|
|
||||||
- Файлы из этой папки не считать активными задачами и не начинать реализацию без явной просьбы пользователя.
|
|
||||||
- Если часть кода временно отключена или закомментирована, в файле будущей фичи подробно описывать:
|
|
||||||
- какие файлы и участки отключены;
|
|
||||||
- что осталось в коде как заготовка;
|
|
||||||
- какие документы нужно обновить при возврате;
|
|
||||||
- с какого сценария продолжать разработку.
|
|
||||||
|
|
||||||
## Коммуникация по новым задачам (обязательно)
|
|
||||||
- При получении нового задания сначала кратко пересказать задачу своими словами.
|
|
||||||
- До начала реализации задать недостающие уточняющие вопросы (если они есть).
|
|
||||||
- Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
|
|
||||||
- Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя).
|
|
||||||
- После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации.
|
|
||||||
- Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения.
|
|
||||||
- Без подтверждения пользователя реализацию не начинать.
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# Runbook для агента: тест сетевого соединения
|
|
||||||
|
|
||||||
## Быстрый цикл
|
|
||||||
1. Убедись, что сервер запущен.
|
|
||||||
2. Скажи пользователю: «Запусти двух клиентов и напиши “продолжай”».
|
|
||||||
3. По команде «продолжай»:
|
|
||||||
- вызови `GET /debug/ws/clients`,
|
|
||||||
- выбери 2 активные сессии (предпочтительно разных логинов),
|
|
||||||
- вызови `POST /debug/ws/connect`,
|
|
||||||
- получи `runId`.
|
|
||||||
4. Читай `GET /debug/ws/logs?limit=200&runId=<runId>` и сообщай прогресс.
|
|
||||||
5. Если неуспех — покажи ошибки, предложи перезапуск 2 клиентов и повтори.
|
|
||||||
|
|
||||||
## Формат взаимодействия с пользователем
|
|
||||||
- Старт: «Сервер готов. Запусти двух клиентов и скажи “продолжай”.»
|
|
||||||
- После старта run: «Тест запущен, runId=..., проверяю логи.»
|
|
||||||
- Успех: «Соединение установлено, вижу connected.»
|
|
||||||
- Неуспех: «Соединение не поднялось, причины: ... Предлагаю перезапустить клиентов и повторить.»
|
|
||||||
11
CLAUDE.md
11
CLAUDE.md
@ -1,11 +0,0 @@
|
|||||||
@AGENTS.md
|
|
||||||
@AGENT_DEBUG_RUNBOOK.md
|
|
||||||
|
|
||||||
## Обязательно читать при работе с UI
|
|
||||||
@shine-UI/AGENTS.md
|
|
||||||
|
|
||||||
## Справка по подпроектам
|
|
||||||
- При работе внутри `SHiNE-agent-bot-coder/` — читать `SHiNE-agent-bot-coder/AGENTS.md` и `SHiNE-agent-bot-coder/AGENT.md`.
|
|
||||||
- При работе внутри `shine-solana/shine/` — читать `shine-solana/shine/AGENTS.md`.
|
|
||||||
- При работе внутри `shine-UI/server-ui/` — читать `shine-UI/AGENTS.md`.
|
|
||||||
- При работе внутри `SHiNE-server/` — читать `SHiNE-server/AGENTS.md`.
|
|
||||||
@ -1,255 +0,0 @@
|
|||||||
# DAO_запуск
|
|
||||||
|
|
||||||
Рабочий документ по тому, что ещё нужно сделать для первого запуска DAO-сценария SHiNE.
|
|
||||||
|
|
||||||
Логика документа:
|
|
||||||
|
|
||||||
- `этап1` — то, без чего нельзя считать сценарий первого запуска собранным даже в тестовом виде;
|
|
||||||
- `этап2` — то, что полезно и, вероятно, потребуется дальше, но это можно делать после старта `этап1` или параллельно без блокировки первого результата.
|
|
||||||
|
|
||||||
Базовая среда первого прохода:
|
|
||||||
|
|
||||||
- сеть `Solana devnet`;
|
|
||||||
- модель синхронизации: `server-to-server`;
|
|
||||||
- `Solana + Arweave` используются как якорь и архив;
|
|
||||||
- DAO понимается как стандартный governance/smart-contract контур, который управляет отдельными программами SHiNE, приносящими деньги.
|
|
||||||
|
|
||||||
## Краткий вывод
|
|
||||||
|
|
||||||
Для первого запуска DAO в тестовом виде текущего списка в целом хватает, но только если понимать запуск как:
|
|
||||||
|
|
||||||
- можно развернуть и проверить базовый DAO-контур;
|
|
||||||
- можно зарегистрировать пользователей и ключевые сущности;
|
|
||||||
- можно провести тестовую покупку билета через smart contract;
|
|
||||||
- можно завести тестовый денежный поток в программы, управляемые DAO;
|
|
||||||
- можно проверить опорную межсерверную синхронизацию и фиксацию состояния в архивный слой.
|
|
||||||
|
|
||||||
Если же под "запуском" понимать уже полностью устойчивую production-схему с ротацией ключей, восстановлением любого сервера из архива, железными устройствами подписи и полным циклом администрирования, то текущий список нужно будет ещё расширять.
|
|
||||||
|
|
||||||
## Этап1
|
|
||||||
|
|
||||||
Цель этапа: собрать минимально жизнеспособный DAO-сценарий в `devnet`, который можно пройти руками от регистрации до базовой экономики и проверки архитектуры.
|
|
||||||
|
|
||||||
### 1. Переписать и стабилизировать регистрацию пользователей без Anchor
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- довести `shine_users` в чистом Rust/Solana SDK до рабочего и проверенного состояния;
|
|
||||||
- убедиться, что `shine_login_guard` и связанный сценарий регистрации совместимы с новым ABI;
|
|
||||||
- проверить создание и чтение `user_pda`;
|
|
||||||
- проверить update пользовательской записи и связанные экономические параметры;
|
|
||||||
- синхронизировать сервер, UI и lazy-import с новым форматом и seed'ами.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- без стабильной пользовательской регистрации дальше нельзя строить ни DAO-сценарий, ни привязку устройств, ни платёжные сценарии.
|
|
||||||
|
|
||||||
### 2. Проверить полный сценарий регистрации и базовой Solana-интеграции
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- руками прогнать регистрацию нового пользователя;
|
|
||||||
- руками прогнать создание и update server PDA там, где это требуется текущему сценарию;
|
|
||||||
- убедиться, что сервер читает новые PDA без anchor-зависимостей и без старых discriminator'ов;
|
|
||||||
- зафиксировать, какие именно части сценария уже подтверждены руками, а какие ещё нет.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- сейчас в проекте уже есть признаки перехода на pure Rust, но без ручной проверки это нельзя считать завершённым.
|
|
||||||
|
|
||||||
### 3. Создать стандартный DAO smart contract / governance-контур
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- определить и реализовать стандартный DAO-контур, который будет управлять программами SHiNE;
|
|
||||||
- зафиксировать, какие права сразу передаются DAO, а какие временно остаются на отдельных ключах;
|
|
||||||
- подготовить тестовую DAO-структуру в `devnet`.
|
|
||||||
|
|
||||||
Минимум для первого запуска:
|
|
||||||
|
|
||||||
- DAO существует как управляемая сущность;
|
|
||||||
- DAO может владеть или контролировать ключевые права управления денежными программами;
|
|
||||||
- есть понятный путь, как DAO влияет на доходные программы SHiNE.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- без этого "DAO-запуск" будет только запуском отдельных Solana-программ, но не запуском управляемой DAO-системы.
|
|
||||||
|
|
||||||
### 4. Доработать смарт-контракт выплат с третьей очередью
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- добавить в `shine_payments` третью очередь, о которой уже принято решение;
|
|
||||||
- проверить совместимость с текущей моделью тикетов, выплат и DAO-управления;
|
|
||||||
- убедиться, что логика очередей соответствует ожидаемой экономике проекта.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- по текущей постановке это нужно именно для сценария регистрации DAO и дальнейшей экономики.
|
|
||||||
|
|
||||||
### 5. Сделать UI для покупки билетов и просмотра очереди
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- добавить UI-сценарий покупки билетов через smart contract;
|
|
||||||
- показать пользователю, сколько перед ним человек в очереди;
|
|
||||||
- убедиться, что UI отражает актуальное состояние контрактной логики, а не локальные предположения.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- покупка билетов у тебя обозначена как часть DAO-сценария, а не как побочная функция;
|
|
||||||
- без UI можно тестировать контракт вручную, но нельзя считать сценарий запуска достаточно собранным для нормальной проверки.
|
|
||||||
|
|
||||||
### 6. Реализовать базовую синхронизацию серверов
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- сделать обмен состоянием между серверами по модели `server-to-server`;
|
|
||||||
- определить минимальный набор данных, который обязан синхронизироваться;
|
|
||||||
- предусмотреть фиксацию синхронизированного состояния в `Arweave`, а `Solana` использовать как якорь и ссылочный слой;
|
|
||||||
- описать, какой сервер считается источником истины в спорных случаях или как решается конфликт.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- без межсерверной синхронизации трудно обосновать архитектуру сети как воспроизводимую и переносимую;
|
|
||||||
- это напрямую связано с идеей, что любой сможет поднять свой сервер.
|
|
||||||
|
|
||||||
### 7. Подготовить базовый сценарий архивирования и восстановления
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- описать и частично реализовать схему: серверы синхронизируются между собой, архив состояния уходит в `Arweave`, ссылка/якорь фиксируется через `Solana`;
|
|
||||||
- определить минимальный сценарий восстановления блоков или состояния из архивного слоя;
|
|
||||||
- подтвердить, что новый сервер может получить достаточно данных для старта.
|
|
||||||
|
|
||||||
Почему это в `этап1`:
|
|
||||||
|
|
||||||
- это один из ключевых признаков независимой и воспроизводимой DAO-инфраструктуры.
|
|
||||||
|
|
||||||
## Этап2
|
|
||||||
|
|
||||||
Цель этапа: усилить безопасность, автономность и удобство системы после того, как минимальный DAO-сценарий уже запустился и проверен в `devnet`.
|
|
||||||
|
|
||||||
### 1. Смена ключей цифровой подписи
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- продумать и реализовать смену `root key`, `client key`, `blockchain key`;
|
|
||||||
- описать ограничения, кто и в каком сценарии может менять каждый тип ключа;
|
|
||||||
- продумать, как не потерять доступ и как обновлять доверие к новым ключам.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- для production это очень важно;
|
|
||||||
- для первого тестового запуска можно временно использовать фиксированный набор ключей.
|
|
||||||
|
|
||||||
### 2. Полная повторная перепроверка всех сценариев
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- повторно прогнать регистрацию, DAO, выплаты, билеты, синхронизацию и архивирование после стабилизации `этап1`;
|
|
||||||
- оформить итоговый чек-лист ручной проверки;
|
|
||||||
- отдельно проверить пограничные сценарии и восстановление после ошибок.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- это обязательный шаг перед переходом от "собрали" к "доверяем".
|
|
||||||
|
|
||||||
### 3. Устройство на ESP32 как homeserver с ключами
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- дописать прошивку, чтобы устройство могло выступать homeserver с ключами;
|
|
||||||
- дать ему возможность регистрироваться и подключаться к серверу;
|
|
||||||
- определить, какие операции устройство подписывает и где хранит ключевой материал.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- это очень сильное развитие архитектуры, но оно не должно блокировать первый DAO-запуск.
|
|
||||||
|
|
||||||
### 4. Логин и подпись через коробочки / устройства
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- реализовать сценарий входа через устройство или хотя бы сценарий подписи сообщений и ключей через устройство;
|
|
||||||
- определить, как это встраивается в регистрацию DAO и подтверждение действий;
|
|
||||||
- проверить, можно ли через это безопасно регистрировать DAO или подписывать критичные команды.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- это следующий уровень безопасности и UX, но не минимальный блокер первого старта.
|
|
||||||
|
|
||||||
### 5. Создание тестового DAO с использованием устройств подписи
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- после готовности устройств собрать тестовый DAO-сценарий уже с аппаратным участием;
|
|
||||||
- проверить, где устройство достаточно, а где всё ещё нужен обычный кошелёк или управляющий ключ.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- это проверка усиленной модели, а не базового старта.
|
|
||||||
|
|
||||||
### 6. Расписание синхронизации серверов
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- определить периодичность и правила фоновой синхронизации;
|
|
||||||
- продумать ручной и автоматический режим;
|
|
||||||
- решить, как часто публиковать архивные снимки и якоря.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- сначала важнее добиться самой работающей синхронизации, а потом уже делать её регулярной и автономной.
|
|
||||||
|
|
||||||
### 7. Полное восстановление блоков из Solana/Arweave
|
|
||||||
|
|
||||||
Что сделать:
|
|
||||||
|
|
||||||
- довести процедуру восстановления до сценария "любой может поднять свой сервер";
|
|
||||||
- определить минимальный bootstrap-набор;
|
|
||||||
- проверить восстановление на чистом окружении.
|
|
||||||
|
|
||||||
Почему это в `этап2`:
|
|
||||||
|
|
||||||
- для концепции сети это критично, но как полноценная задача обычно идёт после появления базового архива и первичной синхронизации.
|
|
||||||
|
|
||||||
## Что блокирует первый запуск сильнее всего
|
|
||||||
|
|
||||||
Если расставить приоритет внутри `этап1`, то самый жёсткий порядок сейчас выглядит так:
|
|
||||||
|
|
||||||
1. pure Rust регистрация пользователей и ручная проверка сценария;
|
|
||||||
2. DAO/gov-контур и его права управления;
|
|
||||||
3. доработка выплат с третьей очередью;
|
|
||||||
4. покупка билетов через smart contract и UI-проверка очереди;
|
|
||||||
5. межсерверная синхронизация;
|
|
||||||
6. архивирование в `Arweave` с якорем в `Solana`;
|
|
||||||
7. минимальное восстановление состояния новым сервером.
|
|
||||||
|
|
||||||
## Что уже частично похоже на готовое
|
|
||||||
|
|
||||||
По текущим документам и следам в проекте уже видно, что:
|
|
||||||
|
|
||||||
- переход `shine_users` и `shine_login_guard` на pure Rust уже начат и в значительной степени сделан;
|
|
||||||
- архитектура DAO, `shine_users` и `shine_payments` уже описана;
|
|
||||||
- часть Solana-структуры и PDA-форматов уже формализована;
|
|
||||||
- тема ESP32 уже отдельно присутствует в проекте как направление.
|
|
||||||
|
|
||||||
Это хорошо, потому что документ получается не "с нуля", а как сборка того, что уже назрело в коде и планах.
|
|
||||||
|
|
||||||
## Вопросы, которые всё ещё стоит уточнить
|
|
||||||
|
|
||||||
1. Какой именно стандарт DAO планируется использовать в первом проходе: готовый governance-стек Solana или собственная минимальная обвязка вокруг управляющих кошельков?
|
|
||||||
2. Третья очередь в `shine_payments` уже точно определена по смыслу, или пока есть только решение "она нужна", но без финальной экономики?
|
|
||||||
3. Что именно считается единицей синхронизации между серверами: блоки SHiNE, агрегированные снапшоты, PDA-состояния, или смесь этих вариантов?
|
|
||||||
4. Нужен ли для `этап1` уже полноценный автоматический recovery нового сервера, или достаточно доказать это в полу-ручном сценарии?
|
|
||||||
5. Покупка билетов должна в первом проходе работать только через web/UI, или также нужен отдельный сценарий из серверного UI или скриптов?
|
|
||||||
|
|
||||||
## Рекомендуемый следующий практический шаг
|
|
||||||
|
|
||||||
Если идти без распыления, то следующим рабочим фокусом стоит считать:
|
|
||||||
|
|
||||||
1. закрыть ручную проверку pure Rust регистрации;
|
|
||||||
2. после этого формализовать минимальный DAO-контур;
|
|
||||||
3. затем переходить к третьей очереди выплат и к UI покупки билетов;
|
|
||||||
4. после этого делать синхронизацию, архив и восстановление.
|
|
||||||
@ -1,92 +0,0 @@
|
|||||||
# DEBUG: тестирование сетевого соединения между двумя клиентами
|
|
||||||
|
|
||||||
Документ описывает временный debug-контур для проверки WebRTC соединения между двумя активными WS-сессиями.
|
|
||||||
|
|
||||||
## 1) Подготовка
|
|
||||||
|
|
||||||
|
|
||||||
0. Убедись, что в `application.properties` включен параметр:
|
|
||||||
`debug.tempApi.enabled=true`
|
|
||||||
1. Создай файл `.debug-token` в корне проекта на основе `debug-token.example`.
|
|
||||||
2. В `.debug-token` должна быть одна строка: секретный токен.
|
|
||||||
3. Перезапусти сервер.
|
|
||||||
|
|
||||||
## 2) API debug
|
|
||||||
|
|
||||||
Базовый заголовок для всех запросов:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
-H "Authorization: Bearer <YOUR_DEBUG_TOKEN>"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.1 Получить список живых клиентов
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -s \
|
|
||||||
-H "Authorization: Bearer <YOUR_DEBUG_TOKEN>" \
|
|
||||||
http://localhost:7070/debug/ws/clients | jq
|
|
||||||
```
|
|
||||||
|
|
||||||
Ответ содержит `sessionId`, `login`, `ip`, `userAgent`, и клиентскую информацию.
|
|
||||||
|
|
||||||
### 2.2 Запустить debug-соединение между двумя сессиями
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -s -X POST \
|
|
||||||
-H "Authorization: Bearer <YOUR_DEBUG_TOKEN>" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{
|
|
||||||
"initiatorSessionId": "SESSION_ID_A",
|
|
||||||
"responderSessionId": "SESSION_ID_B",
|
|
||||||
"clearDebugLog": false
|
|
||||||
}' \
|
|
||||||
http://localhost:7070/debug/ws/connect | jq
|
|
||||||
```
|
|
||||||
|
|
||||||
В ответе придёт `runId`. Его используй для фильтра логов.
|
|
||||||
|
|
||||||
### 2.3 Читать последние N debug-логов
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -s \
|
|
||||||
-H "Authorization: Bearer <YOUR_DEBUG_TOKEN>" \
|
|
||||||
"http://localhost:7070/debug/ws/logs?limit=200&runId=<RUN_ID>" | jq
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3) Операционный сценарий “Codex + пользователь”
|
|
||||||
|
|
||||||
1. Codex поднимает сервер и сообщает пользователю ссылку на UI.
|
|
||||||
2. Codex пишет пользователю: **«Запусти двух клиентов и скажи “продолжай”»**.
|
|
||||||
3. Пользователь запускает два клиента (лучше под разными логинами).
|
|
||||||
4. Пользователь пишет: **«продолжай»**.
|
|
||||||
5. Codex:
|
|
||||||
- вызывает `/debug/ws/clients`,
|
|
||||||
- выбирает 2 сессии,
|
|
||||||
- вызывает `/debug/ws/connect`,
|
|
||||||
- получает `runId`,
|
|
||||||
- читает `/debug/ws/logs?runId=...` и сообщает прогресс.
|
|
||||||
6. Если соединение не удалось:
|
|
||||||
- Codex сообщает ошибки по логам,
|
|
||||||
- при необходимости просит перезапустить 2 клиента,
|
|
||||||
- повторяет запуск debug-run.
|
|
||||||
|
|
||||||
## 4) Какие сообщения считать успехом
|
|
||||||
|
|
||||||
- `peer_connection_connected`
|
|
||||||
- `debug_connection_success`
|
|
||||||
- `signal_sent_200/210/220` без ошибок
|
|
||||||
|
|
||||||
## 5) Что говорить пользователю в ходе прогона (через «колонку»/чат)
|
|
||||||
|
|
||||||
Рекомендуемые фразы:
|
|
||||||
|
|
||||||
- «Сервер запущен. Запусти двух клиентов и напиши “продолжай”.»
|
|
||||||
- «Вижу 2 активные сессии, запускаю тест соединения.»
|
|
||||||
- «Тест запущен, runId=... Сейчас проверяю логи.»
|
|
||||||
- «Соединение установлено / не установлено. Ниже причины и следующий шаг.»
|
|
||||||
|
|
||||||
## 6) Ограничения
|
|
||||||
|
|
||||||
- Механизм временный, не для production-эксплуатации.
|
|
||||||
- Доступ к debug API имеет любой, кто знает токен.
|
|
||||||
- Рекомендуется тестить между разными логинами.
|
|
||||||
@ -1,62 +0,0 @@
|
|||||||
0. ПЕРЕДЕЛАТЬ ВСЁ НА НОВЫЙ ФОРМАТ!!
|
|
||||||
|
|
||||||
ВЫНЕСТИ ЭТИ ТРИ ВЕЩИ В ОБЩИЙ ПАРСЕР
|
|
||||||
* [2] type - тип соощения
|
|
||||||
* [2] Sиbtype - субтип сообщения
|
|
||||||
* [2] version - версия формата соощения
|
|
||||||
|
|
||||||
А ОСТАЛЬНОЕ В РЕАЛИЗАЦИЮ
|
|
||||||
|
|
||||||
|
|
||||||
ПЕРЕДЕЛАЕМ БД
|
|
||||||
|
|
||||||
1. СДЕЛАЕМ ЛИНИЮ ТОЛЬКО ДЛЯ ТЕХ ТИПОВ КОМУ НАДО (ЛАЙКАМ И ОТВЕТАМ НЕ НАДО)
|
|
||||||
(НОМЕР СООБЩЕНИЯ В ЛИНИИ ХРАНИТЬ В БЛОКАХ ВРОДЕ И НЕ НАДО ТЕМ БОЛЕЕ ЕГО ПОТОМ ПЕРЕПРОВЕРЯТЬ ВСЁ РАВНО)
|
|
||||||
А МОЖЕТ И НАДО ТК КАК ПО ОДНОМУ БЛОКУ ( ИЛИ ЧАСТИ БЛОКОВ ПОНЯТЬ КАКАЯ ЭТО ЧАСТЬ ПЕРЕПИСКИ - ВЕДЬ ГЛОБАЛ НОМЕР ВООБЩЕ НЕ ПОКАЗАТЕЛЬ)
|
|
||||||
|
|
||||||
В БД ПОМЕЧАТЬ ЧТО БЛОК ИЗ ЭТОЙ ЛИНИИ (ДЛЯ БЫСТРОГО ПОИСКА)
|
|
||||||
|
|
||||||
А УНИКАЛЬНЫЙ НОМЕР ЛИНИИ ЭТО ПО СУТИ НОМЕР СООБЩЕНИЯ СОЗДАВШЕГО ЛИНИЮ КАНАЛ (НУ И ФОРМАТ СООБЩЕНИЯ НАЧАЛА ЛИНИИ - КАНАЛА)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
3. СООТВЕТСТВЕННО удалить НАПИСАТЬ/ПЕРОВЕРИТЬ НОРМАЛЬНЫЙ SubscriptionsDAO - ТК СТАРЫЙ РАБОТАЛ НО НА ДРУГОМ ФОРМАТЕ И ТИПО КРИВО
|
|
||||||
|
|
||||||
и дальше:
|
|
||||||
ЗДЕЛАТЬ ТРИ ЗАПРОСА:
|
|
||||||
СПИСОК КАНАЛОВ НА КОГО ПОДПИСАН И ПО СКОЛЬКО СООБЩЕНИЙ И ПОСЛДНИЙ ТЕКСТ
|
|
||||||
ДОДЕЛАТЬ И СВЯЗ ПОДПИСАН УЖЕ НЕ ТОЛЬКО НА ЧЕЛА НО И НА КАНАЛ. (И ПОЛУЧАЕТСЯ ЕСТЬ ОБЩИЙ КАНАЛЛ ПОСТОВ (НО НЕКОТОРЫЕ ПОСТЫ В НИКУДА-
|
|
||||||
А НЕКОТОРЫЕ ПОСТЫ ОБЪЯВЛЕНИЕ КАНАЛА
|
|
||||||
|
|
||||||
СПИСОК СООБЩЕНИЙ В КАНАЛЕ
|
|
||||||
|
|
||||||
ОПСИСАНИЕ ОДНОГО СОООБЩЕНИЯ (С ИСТОРИЕЙ ДО НАЧАЛА ВЕТКИ И СО ВСЕМИ ОТВЕТАМИ НА НЕГО)
|
|
||||||
|
|
||||||
(НУ И В БУДУЩЕМ четвёртый ИСТОРИЮ сообщения ПО ЕДИТУ)
|
|
||||||
|
|
||||||
|
|
||||||
И ПОМЯТКА
|
|
||||||
ВСЕГДА СЧИТАЕМ ПО ПОСЛЕДНЕМУ БЛОКЧЕЙНУ ДОСТУПНОМУ ПОЛЬЗОВАТЕЛЮ
|
|
||||||
ХОТЯ ССЫЛКА ПО НОМЕРУ БЛОКЧЕЙНА КУДА ДОБАВИЛИ
|
|
||||||
|
|
||||||
ЛАЙКИ И ОТВЕТЫ ПИШЕМ НА НОМЕР СООБЩЕНИЯ ЕДИТА
|
|
||||||
(СЧИТАЕМ ТРИГЕРОМ И НА ОРИГИНАЛЬНЫЙ СУМАРНОЕ И ОТДЕЛЬНО НА НЕГО, И НА КАЖДЫЙ ЕДИТ ОТДЕЛЬНО)
|
|
||||||
|
|
||||||
ОТВЕТЫ ПОКАЗЫВАЕМ ВСЕ ВРАЗ
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -1,10 +0,0 @@
|
|||||||
Сделать возможность убрать свой лайк. (пока не надо а сложность что надо больше проверок) - хотя можно и без проверки, просто за двойной лайк или за снятие двойное лайка. Будет двойное проникновение :)) тому кто изменил код клиента и убрал проверку на клиенте - и блокчейн заблокируется и всё.
|
|
||||||
поэтому просто на каждую реакцию добавиться убрать эту ракцию .
|
|
||||||
- это просто
|
|
||||||
|
|
||||||
сделатьпотом что бы в солану_юзерс хранилось имя текущего блокчейна пользователя. Что бы потом можно было грузить именно актуальный ТО ЕСТЬ потом можно будет менять блокченый!
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
сделать сессион пасворд тоже ключём подписи устройства!!
|
|
||||||
@ -1,22 +0,0 @@
|
|||||||
Перечень библиотек и их краткое описание
|
|
||||||
|
|
||||||
shine-server-log
|
|
||||||
Статический “сиренный” метод для максимально заметного критического лога администратору
|
|
||||||
|
|
||||||
shine-server-config
|
|
||||||
Минимальный конфиг-лоадер, который один раз читает application.properties и даёт доступ к параметрам.
|
|
||||||
|
|
||||||
shine-server-geo
|
|
||||||
Утилиты, которые вытаскивают IP/язык/UA из Jetty WebSocket и (опционально) резолвят гео по IP с кэшем в БД.
|
|
||||||
|
|
||||||
shine-server-crypto
|
|
||||||
Базовые крипто-утилиты для SHA-256 и Ed25519 (BouncyCastle) + проверка подписи/хэша для .bch сущностей и маленький self-test.
|
|
||||||
|
|
||||||
shine-server-bd
|
|
||||||
Библиотека реалезующая всю работу с БД:
|
|
||||||
|
|
||||||
shine-server-blockchain
|
|
||||||
Библиотека, которая задаёт единый бинарный формат блоков (RAW+signature+hash), парсит/валидирует “тело” блока по type/version, и проверяет целостность/подпись цепочки через SHA-256 + Ed25519 с привязкой к login и предыдущим хэшам.
|
|
||||||
|
|
||||||
shine-server-protocol
|
|
||||||
Библиотека JSON-протокол поверх WebSocket для взаимодействия с клиентами.
|
|
||||||
@ -1,17 +0,0 @@
|
|||||||
shine-server-bd — это библиотека реалезующая всю работу с БД:
|
|
||||||
|
|
||||||
хранит пользователей/сессии/параметры/кэш IP→гео и данные блокчейна (состояние + блоки), предоставляя единый SqliteDbController для соединений, набор DAO под каждую таблицу (Singleton, методы с Connection для транзакций и без Connection — сами открывают/закрывают), и простые entity-модели как контейнеры данных для маппинга ResultSet↔Java.
|
|
||||||
|
|
||||||
Логика структуры классов (в двух словах):
|
|
||||||
|
|
||||||
shine.db.SqliteDbController — один вход в БД: читает db.path, при отсутствии файла создаёт БД, выдаёт новые Connection и настраивает PRAGMA.
|
|
||||||
shine.db.DatabaseInitializer — разовая сборка схемы (таблицы + индексы).
|
|
||||||
|
|
||||||
|
|
||||||
shine.db.entities.* — POJO-модели строк таблиц (без логики, только поля/геттеры/сеттеры + иногда удобные методы вроде getClientKeyByte()).
|
|
||||||
shine.db.dao.* — DAO по таблицам: ActiveSessionsDAO, SolanaUsersDAO, UserParamsDAO, IpGeoCacheDAO, BlockchainStateDAO, BlocksDAO; плюс “сервисные” DAO:
|
|
||||||
|
|
||||||
UserCreateDAO — атомарная регистрация пользователя в транзакции (BEGIN IMMEDIATE + rollback/commit).
|
|
||||||
// Временное решение позволяющее регистрировать новых пользователей
|
|
||||||
// атомарно и добавляет запись и в solana_users и в BlockchainState
|
|
||||||
|
|
||||||
@ -1,85 +0,0 @@
|
|||||||
shine-server-blockchain — это библиотека, которая задаёт формат блока, правила парсинга/валидации тела, крипто-проверку (hash+Ed25519) и безопасную работу с файлами блокчейна (data/<name>.bch через временный .tmp_bch).
|
|
||||||
|
|
||||||
Как устроена структура и логика работы
|
|
||||||
|
|
||||||
1) “Блок” как центральный объект (ядро)
|
|
||||||
BchBlockEntry — единая модель блока “как лежит на диске/в сети”:
|
|
||||||
читает/собирает байты в формате RAW + signature64 + hash32
|
|
||||||
сразу парсит body через BodyRecordParser
|
|
||||||
сразу проверяет что lineIndex совпадает с тем, что ожидает конкретный тип body (expectedLineIndex())
|
|
||||||
То есть: всё, что считается “блоком”, обязано быть самодостаточно валидным уже на этапе создания объекта.
|
|
||||||
|
|
||||||
2) “Body” как плагины по типам (расширяемая часть) ! <-- Новые типы записей добавлть сюда !
|
|
||||||
BodyRecord — интерфейс контракта для всех тел:
|
|
||||||
type/version — идентификаторы формата
|
|
||||||
expectedLineIndex() — жёсткое правило “в какой линии может жить”
|
|
||||||
check() — логическая валидация содержимого
|
|
||||||
toBytes() — сериализация обратно в бинарь
|
|
||||||
|
|
||||||
BodyRecordParser — диспетчер: читает первые 4 байта (type+ver) и выбирает нужный класс:
|
|
||||||
HeaderBody (lineIndex=0)
|
|
||||||
TextBody (lineIndex=1)
|
|
||||||
ReactionBody (lineIndex=2)
|
|
||||||
|
|
||||||
Добавление нового типа = добавить новый класс XxxBody + кейс в BodyRecordParser.
|
|
||||||
|
|
||||||
3) Криптография как отдельный слой проверки
|
|
||||||
BchCryptoVerifier отвечает за “как получить хэш и как проверить подпись”:
|
|
||||||
строит preimage = "SHiNE" + login + prevGlobalHash32 + prevLineHash32 + rawBytes
|
|
||||||
считает sha256(preimage) и сравнивает с hash32 внутри блока
|
|
||||||
проверяет Ed25519 подпись над hash32
|
|
||||||
Важно: BchBlockEntry не проверяет подпись — он проверяет структуру блока и правильность body/lineIndex, а криптопроверка вынесена отдельно.
|
|
||||||
|
|
||||||
4) Утилиты вокруг имени и файлов
|
|
||||||
|
|
||||||
BlockchainNameUtil — извлекает login из blockchainName (отрезает 3 символа суффикса).
|
|
||||||
FileStoreUtil — безопасное файловое хранилище:
|
|
||||||
|
|
||||||
|
|
||||||
5) Объяснение структуры работы
|
|
||||||
|
|
||||||
Типичный сценарий: пришёл блок → проверить → принять
|
|
||||||
Шаг 0. Контекст (что у нас уже есть снаружи)
|
|
||||||
|
|
||||||
Снаружи библиотеки (в сервере) у тебя уже известны:
|
|
||||||
userLogin — владелец блокчейна
|
|
||||||
publicKey32 — публичный ключ пользователя
|
|
||||||
prevGlobalHash32 — хэш предыдущего блока по глобальной цепи
|
|
||||||
prevLineHash32 — хэш предыдущего блока по текущей линии
|
|
||||||
|
|
||||||
Библиотека не хранит это сама, она ожидает, что сервер это передаст.
|
|
||||||
|
|
||||||
Шаг 1. Парсинг блока (структура + логика)
|
|
||||||
BchBlockEntry block = new BchBlockEntry(fullBytes);
|
|
||||||
|
|
||||||
|
|
||||||
Что происходит здесь автоматически:
|
|
||||||
проверяется длина блока
|
|
||||||
проверяется recordSize
|
|
||||||
парсится RAW-заголовок
|
|
||||||
парсится body через BodyRecordParser
|
|
||||||
проверяется, что lineIndex соответствует типу body
|
|
||||||
(HEADER → line 0, TEXT → line 1, REACTION → line 2 и т.д.)
|
|
||||||
❗ На этом шаге никакой криптографии ещё нет — только структура и логика формата.
|
|
||||||
|
|
||||||
Если тут не упало исключение → блок структурно корректен.
|
|
||||||
|
|
||||||
Шаг 2. Подготовка данных для криптопроверки (они получаются просто из частей байтов полного блокас подписью)
|
|
||||||
byte[] rawBytes = block.getRawBytes();
|
|
||||||
byte[] signature64 = block.getSignature64();
|
|
||||||
byte[] hash32FromTail = block.getHash32();
|
|
||||||
|
|
||||||
Важно:
|
|
||||||
rawBytes — это ровно те байты, которые участвовали в хэшировании
|
|
||||||
hash32FromTail — это то, что автор блока положил внутрь блока
|
|
||||||
|
|
||||||
Шаг 3. Криптографическая проверка (ключевой вызов)
|
|
||||||
boolean ok = BchCryptoVerifier.verifyAll(
|
|
||||||
userLogin,
|
|
||||||
prevGlobalHash32,
|
|
||||||
prevLineHash32,
|
|
||||||
rawBytes,
|
|
||||||
signature64,
|
|
||||||
publicKey32,
|
|
||||||
hash32FromTail
|
|
||||||
);
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
Общая структура блока
|
|
||||||
|
|
||||||
Блок — это бинарная запись фиксированного формата:
|
|
||||||
|
|
||||||
[ RAW ][ signature64 ][ hash32 ]
|
|
||||||
|
|
||||||
RAW — данные блока (участвуют в хэшировании и подписи)
|
|
||||||
signature64 — Ed25519-подпись над hash32
|
|
||||||
hash32 — SHA-256 от preimage (привязан к цепочке и владельцу)
|
|
||||||
|
|
||||||
RAW-часть (BigEndian)
|
|
||||||
recordSize int32 — размер RAW (без signature+hash)
|
|
||||||
recordNumber int32 — глобальный номер блока
|
|
||||||
timestamp int64 — unix time (seconds)
|
|
||||||
lineIndex int16 — индекс линии
|
|
||||||
lineNumber int32 — номер блока внутри линии
|
|
||||||
bodyBytes bytes — тело блока (type+version+payload)
|
|
||||||
|
|
||||||
Общая структура блокчейна
|
|
||||||
|
|
||||||
Блокчейн — это:
|
|
||||||
линейная цепочка блоков (по recordNumber)
|
|
||||||
внутри неё — параллельные логические линии (lineIndex)
|
|
||||||
каждая линия имеет собственную нумерацию (lineNumber) и prevLineHash
|
|
||||||
вся цепочка связана ещё и prevGlobalHash
|
|
||||||
|
|
||||||
👉 Таким образом, каждый блок:
|
|
||||||
связан с предыдущим глобальным блоком
|
|
||||||
и с предыдущим блоком своей линии
|
|
||||||
|
|
||||||
Это даёт:
|
|
||||||
строгий порядок всей истории
|
|
||||||
и независимую валидацию логических потоков
|
|
||||||
|
|
||||||
Криптографический смысл блока
|
|
||||||
|
|
||||||
Хэш блока считается от:
|
|
||||||
"SHiNE" +
|
|
||||||
login +
|
|
||||||
prevGlobalHash32 +
|
|
||||||
prevLineHash32 +
|
|
||||||
RAW
|
|
||||||
|
|
||||||
Это означает:
|
|
||||||
блок жёстко привязан к владельцу (login)
|
|
||||||
блок невозможно перенести в другую цепочку
|
|
||||||
подмена предыдущего блока ломает всю цепь
|
|
||||||
Подпись Ed25519 делается над этим хэшем.
|
|
||||||
@ -1,36 +0,0 @@
|
|||||||
Формат и смысл существующих Body
|
|
||||||
|
|
||||||
1) HeaderBody (type=0, ver=1)
|
|
||||||
|
|
||||||
Линия: lineIndex = 0
|
|
||||||
Смысл:
|
|
||||||
Генезис-блок блокчейна, объявляет формат и владельца.
|
|
||||||
|
|
||||||
Содержит:
|
|
||||||
сигнатуру формата "SHiNE"
|
|
||||||
login владельца блокчейна
|
|
||||||
👉 Всегда первый блок, всегда в линии 0.
|
|
||||||
|
|
||||||
2) TextBody (type=1, ver=1)
|
|
||||||
|
|
||||||
Линия: lineIndex = 1
|
|
||||||
Смысл:
|
|
||||||
Основной контент — текстовые записи (посты, сообщения, дневник).
|
|
||||||
|
|
||||||
Содержит:
|
|
||||||
UTF-8 текст произвольной длины
|
|
||||||
👉 Это “основная история” блокчейна пользователя.
|
|
||||||
|
|
||||||
3) ReactionBody (type=2, ver=1)
|
|
||||||
|
|
||||||
Линия: lineIndex = 2
|
|
||||||
Смысл:
|
|
||||||
Связь с другим блокчейном или блоком (реакция, ответ, лайк, ссылка).
|
|
||||||
|
|
||||||
Содержит:
|
|
||||||
код реакции
|
|
||||||
имя целевого блокчейна
|
|
||||||
globalNumber целевого блока
|
|
||||||
hash32 целевого блока
|
|
||||||
👉 Это механизм межблокчейн-связей без изменения чужих цепочек.
|
|
||||||
|
|
||||||
@ -1,7 +0,0 @@
|
|||||||
shine-server-config
|
|
||||||
|
|
||||||
Минимальная библиотека конфигурации, предоставляющая потокобезопасный singleton-доступ к параметрам из application.properties.
|
|
||||||
|
|
||||||
Настройки:
|
|
||||||
server.port=7070 — порт запуска сервера
|
|
||||||
db.path=data/shine.sqlite — путь к SQLite базе данных
|
|
||||||
@ -1,8 +0,0 @@
|
|||||||
shine-server-crypto
|
|
||||||
|
|
||||||
О чём: базовые крипто-утилиты для SHA-256 и Ed25519 (BouncyCastle) + проверка подписи/хэша для .bch сущностей и маленький self-test.
|
|
||||||
Внешние методы, которые вызываются:
|
|
||||||
BchCryptoVerifier.verifyAll(), BchCryptoVerifier.buildPreimage(), Ed25519Util.generatePrivateKey(), Ed25519Util.generatePrivateKeyFromString(), Ed25519Util.derivePublicKey(), Ed25519Util.sign(), Ed25519Util.verify(), Ed25519Util.keyToBase64(), Ed25519Util.keyFromBase64(),
|
|
||||||
HashSHA256Util.sha256()
|
|
||||||
|
|
||||||
HashSHA256Util.loginToLoginId(), HashSHA256Util.loginIdFromLogin(),
|
|
||||||
@ -1,19 +0,0 @@
|
|||||||
shine-server-geo
|
|
||||||
|
|
||||||
Назначение: утилиты для получения “кто подключился” (IP/UA/язык) и геолокации по IP (с опциональным кэшем в БД).
|
|
||||||
|
|
||||||
Классы:
|
|
||||||
|
|
||||||
ClientInfoService — собирает строку UA/ch-ua/platform/mobile/remoteIP, вытаскивает реальный IP (приоритет: X-Forwarded-For → X-Real-IP → remoteAddress), парсит первый Accept-Language.
|
|
||||||
GeoLookupService — геолокация по IP через внешний API (ip-api.com), умеет вариант без кэша и с кэшем в таблице ip_geo_cache через IpGeoCacheDAO (пишет даже unknown), плюс метод получения внешнего IP через api.ipify.org.
|
|
||||||
GeoLookupTestMain — консольный тест: берёт IP из аргумента или определяет внешний, вызывает геолокацию и печатает результат + время.
|
|
||||||
|
|
||||||
|
|
||||||
Внешние (публично используемые) методы:
|
|
||||||
|
|
||||||
ClientInfoService.buildClientInfoString(Session) — формирует строку с User-Agent, client-hints и реальным IP клиента
|
|
||||||
ClientInfoService.extractClientIp(Session) — извлекает реальный IP (X-Forwarded-For / X-Real-IP / remoteAddress)
|
|
||||||
ClientInfoService.extractPreferredLanguageTag(Session) — возвращает основной язык клиента из Accept-Language
|
|
||||||
GeoLookupService.resolveCountryCityOrIp(String ip) — геолокация по IP без кэша (Country, City или unknown)
|
|
||||||
GeoLookupService.resolveCountryCityOrIpWithCache(String ip) — геолокация по IP с кэшированием в БД
|
|
||||||
GeoLookupService.fetchPublicIpOrDefault(String fallbackIp) — получение внешнего IP текущей машины
|
|
||||||
@ -1,10 +0,0 @@
|
|||||||
shine-log (BlockchainAdminNotifier)
|
|
||||||
|
|
||||||
Суть (1 предложение): единая точка для “красного” оповещения админа о критических проблемах консистентности, сейчас — через максимально заметный log.error, позже — через Telegram/email/webhook и т.п.
|
|
||||||
|
|
||||||
Структура (очень кратко):
|
|
||||||
|
|
||||||
BlockchainAdminNotifier (final utility)
|
|
||||||
|
|
||||||
BlockchainAdminNotifier.critical(String message)
|
|
||||||
BlockchainAdminNotifier.critical(String message, Throwable t)
|
|
||||||
@ -1,52 +0,0 @@
|
|||||||
shine-server-protocol
|
|
||||||
Библиотека JSON-протокол поверх WebSocket для взаимодействия с клиентами.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Всё общение — JSON поверх WebSocket
|
|
||||||
Формат всегда один:
|
|
||||||
|
|
||||||
request: op + requestId + payload
|
|
||||||
response: op + requestId + status + payload
|
|
||||||
|
|
||||||
|
|
||||||
Net_Event / Net_Request / Net_Response
|
|
||||||
Базовые классы протокола.
|
|
||||||
requestId связывает запрос и ответ, status = результат.
|
|
||||||
|
|
||||||
Хэндлер = логика операции
|
|
||||||
Каждый op обрабатывается своим JsonMessageHandler.
|
|
||||||
|
|
||||||
Entities (Request / Response)
|
|
||||||
DTO-классы для Jackson:
|
|
||||||
|
|
||||||
Net_Xxx_Request — что приходит от клиента
|
|
||||||
|
|
||||||
Net_Xxx_Response — что уходит клиенту
|
|
||||||
|
|
||||||
JsonHandlerRegistry
|
|
||||||
Связывает:
|
|
||||||
|
|
||||||
op → RequestClass
|
|
||||||
op → Handler
|
|
||||||
|
|
||||||
|
|
||||||
JsonInboundProcessor
|
|
||||||
Единая точка входа:
|
|
||||||
парсит JSON → маппит payload → вызывает handler → собирает ответ JSON.
|
|
||||||
|
|
||||||
Папки по темам
|
|
||||||
|
|
||||||
auth/ — авторизация и сессии
|
|
||||||
(AuthChallenge → CreateAuthSession → Refresh / List / Close)
|
|
||||||
|
|
||||||
blockchain/ — AddBlock
|
|
||||||
|
|
||||||
tempToTest/ — AddUser (временный, потом уйдёт в блокчейн-логику)
|
|
||||||
|
|
||||||
ConnectionContext
|
|
||||||
Состояние одного WebSocket-подключения (login, session, authStatus).
|
|
||||||
|
|
||||||
ActiveConnectionsRegistry
|
|
||||||
Глобальный реестр активных авторизованных соединений
|
|
||||||
(нужно для закрытия других сессий).
|
|
||||||
@ -1,209 +0,0 @@
|
|||||||
SHiNE — структура БД (актуальная версия)
|
|
||||||
|
|
||||||
Перечень таблиц и назначение
|
|
||||||
|
|
||||||
solana_users
|
|
||||||
Справочник пользователей: логин + ключ устройства + (опционально) Solana-ключ.
|
|
||||||
Базовая таблица, используется как FK почти везде.
|
|
||||||
|
|
||||||
active_sessions
|
|
||||||
Активные сессии авторизации/работы клиента: секреты, тайминги, WebPush-данные, IP и информация о клиенте.
|
|
||||||
|
|
||||||
users_params
|
|
||||||
Хранилище актуальных параметров пользователя.
|
|
||||||
Для каждой пары (login, param) хранится только самая новая версия по time_ms.
|
|
||||||
|
|
||||||
ip_geo_cache
|
|
||||||
Кеш геолокации по IP для снижения нагрузки на внешние сервисы.
|
|
||||||
|
|
||||||
blockchain_state
|
|
||||||
Агрегированное состояние блокчейна по blockchain_name:
|
|
||||||
лимиты, текущий размер, последний глобальный блок и состояние линий 0..7.
|
|
||||||
|
|
||||||
blocks
|
|
||||||
Журнал всех блоков и сообщений.
|
|
||||||
Содержит историю событий: тексты, реакции, ответы, связи.
|
|
||||||
PRIMARY KEY намеренно отсутствует.
|
|
||||||
|
|
||||||
connections_state ⭐
|
|
||||||
Актуальное состояние связей между пользователями
|
|
||||||
(друг / контакт / подписка).
|
|
||||||
Обновляется автоматически на основе событий из blocks.
|
|
||||||
|
|
||||||
message_stats ⭐
|
|
||||||
Агрегированные счётчики лайков и ответов на конкретные сообщения.
|
|
||||||
Поддерживается триггерами из blocks.
|
|
||||||
|
|
||||||
Таблицы подробно
|
|
||||||
|
|
||||||
solana_users
|
|
||||||
login — TEXT PK — уникальный логин пользователя
|
|
||||||
client_key — TEXT NOT NULL — публичный ключ устройства (Base64(32) / HEX(64))
|
|
||||||
solana_key — TEXT NULL — публичный ключ Solana-аккаунта
|
|
||||||
|
|
||||||
active_sessions
|
|
||||||
session_id — TEXT PK — идентификатор сессии
|
|
||||||
login — TEXT NOT NULL, FK → solana_users(login)
|
|
||||||
session_pwd — TEXT NOT NULL — секрет сессии
|
|
||||||
storage_pwd — TEXT NOT NULL — секрет storage
|
|
||||||
session_created_at_ms — INTEGER NOT NULL
|
|
||||||
last_authirificated_at_ms — INTEGER NOT NULL
|
|
||||||
push_endpoint — TEXT NULL
|
|
||||||
push_p256dh_key — TEXT NULL
|
|
||||||
push_auth_key — TEXT NULL
|
|
||||||
client_ip — TEXT NULL
|
|
||||||
client_info_from_client — TEXT NULL
|
|
||||||
client_info_from_request — TEXT NULL
|
|
||||||
user_language — TEXT NULL
|
|
||||||
|
|
||||||
users_params
|
|
||||||
login — TEXT NOT NULL, FK → solana_users(login)
|
|
||||||
param — TEXT NOT NULL
|
|
||||||
time_ms — INTEGER NOT NULL
|
|
||||||
value — TEXT NOT NULL
|
|
||||||
client_key — TEXT NULL
|
|
||||||
signature — TEXT NULL
|
|
||||||
|
|
||||||
Ограничение:
|
|
||||||
UNIQUE(login, param)
|
|
||||||
|
|
||||||
Логика:
|
|
||||||
обновление принимается только если excluded.time_ms > users_params.time_ms
|
|
||||||
|
|
||||||
ip_geo_cache
|
|
||||||
ip — TEXT PK
|
|
||||||
geo — TEXT NULL
|
|
||||||
updated_at_ms — INTEGER NOT NULL
|
|
||||||
|
|
||||||
blockchain_state
|
|
||||||
blockchain_name — TEXT PK
|
|
||||||
login — TEXT NOT NULL, FK → solana_users(login)
|
|
||||||
blockchain_key — TEXT NOT NULL
|
|
||||||
size_limit — INTEGER NOT NULL
|
|
||||||
file_size_bytes — INTEGER NOT NULL
|
|
||||||
last_global_number — INTEGER NOT NULL (-1 = genesis)
|
|
||||||
last_global_hash — TEXT NOT NULL
|
|
||||||
updated_at_ms — INTEGER NOT NULL
|
|
||||||
|
|
||||||
Линии 0..7:
|
|
||||||
для каждой линии:
|
|
||||||
lineX_last_number
|
|
||||||
lineX_last_hash
|
|
||||||
|
|
||||||
blocks
|
|
||||||
login — TEXT NOT NULL
|
|
||||||
bch_name — TEXT NOT NULL
|
|
||||||
block_global_number — INTEGER NOT NULL
|
|
||||||
block_global_pre_hash — TEXT NOT NULL
|
|
||||||
block_line_index — INTEGER NOT NULL
|
|
||||||
block_line_number — INTEGER NOT NULL
|
|
||||||
block_line_pre_hash — TEXT NOT NULL
|
|
||||||
msg_type — INTEGER NOT NULL
|
|
||||||
msg_sub_type — INTEGER NOT NULL
|
|
||||||
block_bytes — BLOB NULL
|
|
||||||
|
|
||||||
Ссылка на другой блок (nullable):
|
|
||||||
to_login
|
|
||||||
to_bch_name
|
|
||||||
to_block_global_number
|
|
||||||
to_block_hash
|
|
||||||
|
|
||||||
connections_state ⭐
|
|
||||||
Текущее агрегированное состояние связей.
|
|
||||||
|
|
||||||
login — TEXT NOT NULL
|
|
||||||
rel_type — INTEGER NOT NULL
|
|
||||||
10 = FRIEND
|
|
||||||
20 = CONTACT
|
|
||||||
30 = FOLLOW
|
|
||||||
to_login — TEXT NOT NULL
|
|
||||||
to_bch_name — TEXT NOT NULL
|
|
||||||
to_block_global_number — INTEGER NULL
|
|
||||||
to_block_hash — TEXT NULL
|
|
||||||
|
|
||||||
Ограничение:
|
|
||||||
UNIQUE(login, rel_type, to_login)
|
|
||||||
|
|
||||||
message_stats ⭐
|
|
||||||
Счётчики активности по целевому сообщению.
|
|
||||||
|
|
||||||
to_login — TEXT NOT NULL
|
|
||||||
to_bch_name — TEXT NOT NULL
|
|
||||||
to_block_global_number — INTEGER NOT NULL
|
|
||||||
to_block_hash — TEXT NOT NULL
|
|
||||||
likes_count — INTEGER NOT NULL DEFAULT 0
|
|
||||||
replies_count — INTEGER NOT NULL DEFAULT 0
|
|
||||||
|
|
||||||
UNIQUE:
|
|
||||||
(to_login, to_bch_name, to_block_global_number, to_block_hash)
|
|
||||||
|
|
||||||
Триггеры БД (полная логика)
|
|
||||||
|
|
||||||
3.1 Связи пользователей
|
|
||||||
trg_blocks_connection_state_ai
|
|
||||||
AFTER INSERT ON blocks
|
|
||||||
|
|
||||||
Условие:
|
|
||||||
msg_type = 3 (connection)
|
|
||||||
|
|
||||||
Добавление / обновление связи
|
|
||||||
msg_sub_type IN (10,20,30)
|
|
||||||
выполняется UPSERT в connections_state
|
|
||||||
|
|
||||||
Удаление связи
|
|
||||||
msg_sub_type IN (11,21,31)
|
|
||||||
удаляется соответствующая связь:
|
|
||||||
11 → 10
|
|
||||||
21 → 20
|
|
||||||
31 → 30
|
|
||||||
|
|
||||||
Итог:
|
|
||||||
blocks — журнал событий
|
|
||||||
connections_state — всегда актуальное состояние
|
|
||||||
|
|
||||||
3.2 Подсчёт лайков ⭐
|
|
||||||
trg_blocks_message_stats_like_ai
|
|
||||||
AFTER INSERT ON blocks
|
|
||||||
|
|
||||||
Условие:
|
|
||||||
msg_type = 2 (reaction)
|
|
||||||
msg_sub_type = 1 (like)
|
|
||||||
|
|
||||||
Действие:
|
|
||||||
определяется цель по to_bch_name, to_block_global_number, to_block_hash
|
|
||||||
to_login вычисляется как
|
|
||||||
substr(to_bch_name, 1, length(to_bch_name) - 3)
|
|
||||||
выполняется UPSERT в message_stats
|
|
||||||
likes_count += 1
|
|
||||||
|
|
||||||
3.3 Подсчёт ответов ⭐
|
|
||||||
trg_blocks_message_stats_reply_ai
|
|
||||||
AFTER INSERT ON blocks
|
|
||||||
|
|
||||||
Условие:
|
|
||||||
msg_type = 1 (text)
|
|
||||||
msg_sub_type = 2 (reply)
|
|
||||||
|
|
||||||
Действие:
|
|
||||||
цель определяется аналогично лайкам
|
|
||||||
выполняется UPSERT в message_stats
|
|
||||||
replies_count += 1
|
|
||||||
|
|
||||||
Индексы (смысл)
|
|
||||||
|
|
||||||
idx_solana_users_login — поиск пользователя
|
|
||||||
idx_active_sessions_login — сессии пользователя
|
|
||||||
idx_users_params_login — параметры пользователя
|
|
||||||
idx_ip_geo_cache_updated_at — чистка кеша
|
|
||||||
idx_blockchain_state_login — блокчейны пользователя
|
|
||||||
idx_blockchain_state_updated_at — обслуживание
|
|
||||||
idx_blocks_chain_global — чтение цепочки
|
|
||||||
idx_blocks_to_target — реакции / ответы
|
|
||||||
idx_message_stats_target — быстрый доступ к счётчикам
|
|
||||||
|
|
||||||
Итоговая модель мышления
|
|
||||||
|
|
||||||
blocks — неизменяемый журнал событий
|
|
||||||
connections_state — проекция связей
|
|
||||||
message_stats — проекция активности
|
|
||||||
всё вычисляется детерминированно через триггеры
|
|
||||||
@ -1,75 +0,0 @@
|
|||||||
# Протокол звонков (MVP)
|
|
||||||
|
|
||||||
Версия: browser-to-browser, runtime-only signaling.
|
|
||||||
|
|
||||||
## Цели
|
|
||||||
- Технические сообщения звонка не сохраняются в БД direct_messages.
|
|
||||||
- Первый INVITE рассылается всем активным сессиям получателя и дублируется web push.
|
|
||||||
- Последующие сигналы идут только в конкретную sessionId и не дублируются в push.
|
|
||||||
|
|
||||||
## Операции API
|
|
||||||
|
|
||||||
### 1) CallInviteBroadcast
|
|
||||||
Отправляет общий вызов пользователю.
|
|
||||||
|
|
||||||
Запрос payload:
|
|
||||||
- `toLogin: string`
|
|
||||||
- `callId: string`
|
|
||||||
- `type: 100` (INVITE)
|
|
||||||
|
|
||||||
Поведение сервера:
|
|
||||||
- Рассылает `IncomingCallInvite` во все активные WS-сессии `toLogin`.
|
|
||||||
- В payload события передаёт:
|
|
||||||
- `fromLogin`
|
|
||||||
- `fromSessionId` (session инициатора)
|
|
||||||
- `toLogin`
|
|
||||||
- `callId`
|
|
||||||
- `type=100`
|
|
||||||
- `timeMs`
|
|
||||||
- Отправляет web push уведомление о входящем вызове.
|
|
||||||
|
|
||||||
Ответ payload:
|
|
||||||
- `callId`
|
|
||||||
- `deliveredWsSessions`
|
|
||||||
- `deliveredFcmSessions`
|
|
||||||
|
|
||||||
### 2) CallSignalToSession
|
|
||||||
Отправляет технический сигнал в конкретную сессию.
|
|
||||||
|
|
||||||
Запрос payload:
|
|
||||||
- `toLogin: string`
|
|
||||||
- `targetSessionId: string`
|
|
||||||
- `callId: string`
|
|
||||||
- `type: int`
|
|
||||||
- `data: string` (для SDP/ICE/служебных строк)
|
|
||||||
|
|
||||||
Поведение сервера:
|
|
||||||
- Ищет только `targetSessionId`.
|
|
||||||
- Проверяет, что сессия принадлежит `toLogin`.
|
|
||||||
- Отправляет `IncomingCallSignal` только в эту сессию.
|
|
||||||
- В БД ничего не сохраняет.
|
|
||||||
- Push не отправляет.
|
|
||||||
|
|
||||||
Ответ payload:
|
|
||||||
- `delivered: boolean`
|
|
||||||
|
|
||||||
## Коды type
|
|
||||||
- `100` INVITE
|
|
||||||
- `110` RINGING
|
|
||||||
- `120` ACCEPT
|
|
||||||
- `130` DECLINE_BUSY
|
|
||||||
- `140` TIMEOUT
|
|
||||||
- `150` HANGUP
|
|
||||||
- `200` OFFER
|
|
||||||
- `210` ANSWER
|
|
||||||
- `220` ICE
|
|
||||||
|
|
||||||
## Правила UI/логики
|
|
||||||
- Если уже есть активный звонок и пришел новый INVITE -> автоответ `DECLINE_BUSY` без UI.
|
|
||||||
- После ACCEPT `callId` остаётся во всех OFFER/ANSWER/ICE сообщениях до конца звонка.
|
|
||||||
- При параллельных звонках A<->B допускается детерминированное правило, кто создаёт OFFER.
|
|
||||||
|
|
||||||
## Тайминги MVP
|
|
||||||
- Ожидание подтверждения/реакции после INVITE: до 5с (у инициатора).
|
|
||||||
- Ожидание принятия у входящего звонка: 20с.
|
|
||||||
- Общий лимит ожидания до соединения: 22с.
|
|
||||||
@ -1,9 +0,0 @@
|
|||||||
|
|
||||||
|
|
||||||
Дальше делать:
|
|
||||||
Описание форматов.
|
|
||||||
Запросы клиент-сервер.
|
|
||||||
Промт на клиента.
|
|
||||||
|
|
||||||
---
|
|
||||||
Потом в сервак дописать синхронизацию серверов.
|
|
||||||
@ -1,53 +0,0 @@
|
|||||||
# SHiNE Deployment Servers Inventory
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
This folder contains all deployment-related notes and server records for SHiNE.
|
|
||||||
|
|
||||||
## Legacy Production Server
|
|
||||||
- Name: `VPS-02` (legacy)
|
|
||||||
- Access: `root@194.87.0.247`
|
|
||||||
- Current role: old production server
|
|
||||||
- Confirmed services:
|
|
||||||
- `coturn` is installed and active (`systemd: active/running`)
|
|
||||||
- `caddy` is installed (reported by project context; verify version on host if needed)
|
|
||||||
- TURN configuration observed on host:
|
|
||||||
- `listening-port=3478`
|
|
||||||
- `external-ip=194.87.0.247`
|
|
||||||
- `relay-ip=194.87.0.247`
|
|
||||||
- auth mode: `use-auth-secret` + `static-auth-secret`
|
|
||||||
- SHiNE deployment note:
|
|
||||||
- This host is used as current/legacy runtime for SHiNE.
|
|
||||||
- Gradle-based deployment is used in this project (see repository deploy tasks and scripts).
|
|
||||||
|
|
||||||
## Target Production Server (Migration)
|
|
||||||
- Name: `VPS-05` (new)
|
|
||||||
- Access: `root@45.136.124.227`
|
|
||||||
- Planned role: new primary production server for gradual migration
|
|
||||||
- Baseline setup done:
|
|
||||||
- `ripgrep` installed
|
|
||||||
- user `player` created
|
|
||||||
- user `player` added to `sudo` group
|
|
||||||
- deployment directory created: `/home/player/SHiNE`
|
|
||||||
- Rule:
|
|
||||||
- All SHiNE-related runtime files and deployments on VPS-05 should be placed under `/home/player/SHiNE`.
|
|
||||||
|
|
||||||
## Additional TURN Node
|
|
||||||
- Name: `promo-node-93`
|
|
||||||
- Access: `ubuntu@93.170.12.154` (and `player` user for SHiNE operations)
|
|
||||||
- Role: additional TURN node for SHiNE calls
|
|
||||||
- TURN setup:
|
|
||||||
- `coturn` installed and active
|
|
||||||
- `listening-port=3478`
|
|
||||||
- `tls-listening-port=5349`
|
|
||||||
- `use-auth-secret` + shared `static-auth-secret`
|
|
||||||
- relay UDP port range: `49152-50152`
|
|
||||||
- Runtime files:
|
|
||||||
- `/etc/turnserver.conf`
|
|
||||||
- `/home/player/SHiNE/coturn/turnserver.conf`
|
|
||||||
- Cleanup done:
|
|
||||||
- Disabled old reverse SSH tunnel (`reverse-ssh.service`) that exposed `0.0.0.0:1200 -> localhost:22` to `194.87.0.247`.
|
|
||||||
|
|
||||||
## Next Migration Steps (recommended)
|
|
||||||
1. Install and configure runtime dependencies (JDK, Caddy, DB, TURN if required).
|
|
||||||
2. Mirror SHiNE deployment process from VPS-02 using existing Gradle deployment flow.
|
|
||||||
3. Move traffic gradually and validate logs/metrics before final cutover.
|
|
||||||
@ -1,140 +0,0 @@
|
|||||||
# API для разработчиков: Общий формат запросов и ответов
|
|
||||||
|
|
||||||
Этот файл описывает не конкретные операции, а общий wire-контракт всего API сервера.
|
|
||||||
|
|
||||||
Здесь зафиксировано:
|
|
||||||
|
|
||||||
- как выглядит любой запрос;
|
|
||||||
- как выглядит любой успешный ответ;
|
|
||||||
- как выглядит любой ответ с ошибкой;
|
|
||||||
- какие поля являются обязательными для всех операций;
|
|
||||||
- как клиент должен интерпретировать `status`, `ok` и `payload`.
|
|
||||||
|
|
||||||
Логика простая: сначала клиент и сервер договариваются о едином формате конверта, и только потом в остальных документах уже описываются конкретные методы и их поля.
|
|
||||||
|
|
||||||
## 1. Общий формат запроса
|
|
||||||
|
|
||||||
Все запросы по WebSocket используют один и тот же JSON-конверт:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "OperationName",
|
|
||||||
"requestId": "req-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Поля
|
|
||||||
|
|
||||||
- `op` — имя операции.
|
|
||||||
- `requestId` — клиентский идентификатор запроса.
|
|
||||||
- `payload` — объект параметров операции.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Общий формат успешного ответа
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "OperationName",
|
|
||||||
"requestId": "req-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Общий формат ответа с ошибкой
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "OperationName",
|
|
||||||
"requestId": "req-001",
|
|
||||||
"status": 400,
|
|
||||||
"ok": false,
|
|
||||||
"error": "BAD_REQUEST",
|
|
||||||
"message": "Human readable description",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Обязательные правила
|
|
||||||
|
|
||||||
- Сервер возвращает `op` в каждом ответе.
|
|
||||||
- Сервер возвращает `requestId` в каждом ответе без изменений.
|
|
||||||
- Сервер возвращает `status` в каждом ответе.
|
|
||||||
- Сервер возвращает `ok` в каждом ответе.
|
|
||||||
- Сервер всегда возвращает `payload` как объект.
|
|
||||||
- Даже при отсутствии данных сервер возвращает `payload: {}`.
|
|
||||||
- `ok` находится на верхнем уровне ответа, а не внутри `payload`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Правило интерпретации
|
|
||||||
|
|
||||||
Источник истины — `status`.
|
|
||||||
|
|
||||||
- если `status` в диапазоне `200..299`, то ответ успешный и `ok` должен быть `true`;
|
|
||||||
- если `status` вне диапазона `200..299`, то ответ ошибочный и `ok` должен быть `false`.
|
|
||||||
|
|
||||||
Запрещённые состояния:
|
|
||||||
|
|
||||||
- `status = 200` и `ok = false`;
|
|
||||||
- `status = 400` и `ok = true`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Общие правила формата
|
|
||||||
|
|
||||||
- Все строки подписи и challenge собираются в UTF-8.
|
|
||||||
- Временные метки передаются как Unix time в миллисекундах.
|
|
||||||
- Бинарные поля передаются строками Base64.
|
|
||||||
- При ошибке `error` — это машинный код причины.
|
|
||||||
- При ошибке `message` — человекочитаемое описание причины.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Общие коды ошибок
|
|
||||||
|
|
||||||
Ниже перечислены коды ошибок, которые не привязаны к одной конкретной операции и могут встречаться в разных местах API.
|
|
||||||
|
|
||||||
- `400 / EMPTY_JSON` — клиент отправил пустое или полностью отсутствующее JSON-сообщение.
|
|
||||||
- `400 / NO_OP` — в корневом объекте не передано поле `op`.
|
|
||||||
- `400 / UNKNOWN_OP` — сервер не знает такую операцию.
|
|
||||||
- `400 / NO_PAYLOAD` — в корневом объекте отсутствует `payload`.
|
|
||||||
- `400 / BAD_PAYLOAD` — `payload` передан, но это не JSON-объект.
|
|
||||||
- `400 / BAD_REQUEST_FORMAT` — JSON-конверт формально валиден, но поля операции не удалось распарсить в ожидаемый формат.
|
|
||||||
- `500 / INTERNAL_HANDLER_ERROR` — в handler конкретной операции случилась непредвиденная серверная ошибка.
|
|
||||||
- `500 / INTERNAL_ERROR` — произошла внутренняя ошибка на уровне общего JSON-процессора или другого серверного слоя.
|
|
||||||
|
|
||||||
Общее правило для dev/test этапа:
|
|
||||||
|
|
||||||
- `message` в таких ошибках должен быть коротким, но полезным;
|
|
||||||
- по возможности сервер добавляет тип исключения и краткую деталь причины;
|
|
||||||
- это сделано для упрощения интеграционных тестов и отладки;
|
|
||||||
- позже для production этот уровень детализации может быть уменьшен.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Источник истины по списку операций
|
|
||||||
|
|
||||||
Фактический список публичных WebSocket-операций берётся из:
|
|
||||||
|
|
||||||
- `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
|
|
||||||
|
|
||||||
Если операция зарегистрирована в `HANDLERS` и `REQUEST_TYPES`, она считается доступной через JSON/WebSocket API. Общий актуальный индекс таких операций поддерживается в `Dev_Docs/API/09_Operations_Index.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Короткое резюме
|
|
||||||
|
|
||||||
- Запросы всегда идут как `op + requestId + payload`.
|
|
||||||
- Ответы всегда идут как `op + requestId + status + ok + payload`.
|
|
||||||
- Ошибки всегда возвращают `ok: false`, `error`, `message`, `payload: {}`.
|
|
||||||
@ -1,200 +0,0 @@
|
|||||||
# API для разработчиков: Регистрация пользователя
|
|
||||||
|
|
||||||
Этот файл описывает раздел API, связанный с проверкой наличия пользователя на сервере и dev/test операциями.
|
|
||||||
|
|
||||||
Сейчас здесь три метода:
|
|
||||||
|
|
||||||
- `AddUser` — операция отключена (регистрация только через Solana);
|
|
||||||
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
|
|
||||||
- `SearchUsers` — dev/test поиск логинов по префиксу.
|
|
||||||
|
|
||||||
Регистрация выполняется через Solana (`shine_users`). Сервер при входе может лениво импортировать пользователя из Solana PDA в локальную БД, если записи ещё нет.
|
|
||||||
|
|
||||||
## Статус документа
|
|
||||||
|
|
||||||
Это временная глава API.
|
|
||||||
|
|
||||||
Текущая регистрация пользователя и текущая проверка, существует пользователь или нет, пока реализованы как серверные dev/test операции. В будущем и регистрация, и проверка identity должны идти напрямую через Solana.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Операция `AddUser`
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Операция отключена. Используется только как явный ответ клиентам старых версий.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AddUser",
|
|
||||||
"requestId": "reg-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "anya",
|
|
||||||
"blockchainName": "anya-001",
|
|
||||||
"solanaKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"blockchainKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"clientKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"bchLimit": 1000000
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Пример ответа
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AddUser",
|
|
||||||
"requestId": "reg-001",
|
|
||||||
"status": 410,
|
|
||||||
"ok": false,
|
|
||||||
"error": "ADD_USER_DISABLED",
|
|
||||||
"message": "Серверная регистрация AddUser отключена. Используйте регистрацию через Solana.",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `AddUser`
|
|
||||||
|
|
||||||
- `410 / ADD_USER_DISABLED` — серверная регистрация отключена, используйте Solana-first flow.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Операция `GetUser`
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Временная серверная проверка, существует пользователь или нет.
|
|
||||||
|
|
||||||
Важно:
|
|
||||||
|
|
||||||
- это server-side existence-check;
|
|
||||||
- если пользователя нет в локальной БД, он может быть импортирован при авторизации из Solana PDA.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUser",
|
|
||||||
"requestId": "user-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "anya"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ: пользователь существует
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUser",
|
|
||||||
"requestId": "user-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"exists": true,
|
|
||||||
"login": "Anya",
|
|
||||||
"blockchainName": "anya-001",
|
|
||||||
"solanaKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"blockchainKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"clientKey": "BASE64_32_PUBLIC_KEY",
|
|
||||||
"serverLastGlobalNumber": 128,
|
|
||||||
"serverLastGlobalHash": "4f...ab",
|
|
||||||
"serverBlockchainSizeBytes": 45212,
|
|
||||||
"serverBlockchainSizeLimitBytes": 100000
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Дополнительные серверные поля в `GetUser`:
|
|
||||||
|
|
||||||
- `serverLastGlobalNumber` — номер последнего блока в пользовательском блокчейне на сервере;
|
|
||||||
- `serverLastGlobalHash` — hash последнего блока (hex-строка 64 символа);
|
|
||||||
- `serverBlockchainSizeBytes` — текущий размер пользовательского блокчейна на сервере в байтах;
|
|
||||||
- `serverBlockchainSizeLimitBytes` — текущий лимит размера блокчейна на сервере в байтах;
|
|
||||||
|
|
||||||
### Успешный ответ: пользователя нет
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUser",
|
|
||||||
"requestId": "user-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"exists": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Пример ошибки
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUser",
|
|
||||||
"requestId": "user-001",
|
|
||||||
"status": 400,
|
|
||||||
"ok": false,
|
|
||||||
"error": "BAD_FIELDS",
|
|
||||||
"message": "Некорректные поля: login",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `GetUser`
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — не передан или пуст `login`.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД при поиске пользователя.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Операция `SearchUsers`
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Поиск пользователей по префиксу логина. Операция зарегистрирована в серверном API и используется как вспомогательная dev/test операция.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SearchUsers",
|
|
||||||
"requestId": "search-001",
|
|
||||||
"payload": {
|
|
||||||
"prefix": "an"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SearchUsers",
|
|
||||||
"requestId": "search-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"logins": ["anya", "andrey"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `SearchUsers`
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — некорректный или пустой `prefix`.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД при поиске.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Короткое резюме
|
|
||||||
|
|
||||||
- `AddUser` — отключен (`410 / ADD_USER_DISABLED`).
|
|
||||||
- `GetUser` — проверка существования пользователя на сервере.
|
|
||||||
- `SearchUsers` — временный поиск пользователей по префиксу.
|
|
||||||
- Регистрация выполняется только через Solana.
|
|
||||||
@ -1,341 +0,0 @@
|
|||||||
# API для разработчиков: Авторизация
|
|
||||||
|
|
||||||
Этот файл описывает именно этапы авторизации клиента, то есть как создать новую сессию и как войти в уже существующую.
|
|
||||||
|
|
||||||
Здесь четыре базовых метода обычной авторизации:
|
|
||||||
|
|
||||||
- `AuthChallenge`
|
|
||||||
- `CreateAuthSession`
|
|
||||||
- `SessionChallenge`
|
|
||||||
- `SessionLogin`
|
|
||||||
|
|
||||||
Логика раздела такая:
|
|
||||||
|
|
||||||
- сначала клиент либо начинает создание новой сессии через `clientKey`;
|
|
||||||
- либо начинает вход в уже созданную сессию через `sessionKey`;
|
|
||||||
- сервер на первом шаге выдаёт challenge/nonce;
|
|
||||||
- на втором шаге клиент присылает подписанный ответ;
|
|
||||||
- сервер сверяет актуальные публичные ключи и только потом проверяет подпись.
|
|
||||||
|
|
||||||
Новые поля этого раздела:
|
|
||||||
|
|
||||||
- `sessionType` — числовой код типа сессии;
|
|
||||||
- `clientPlatform` — свободная строка платформы клиента.
|
|
||||||
|
|
||||||
Текущие поддерживаемые коды `sessionType`:
|
|
||||||
|
|
||||||
- `1` — обычный клиент;
|
|
||||||
- `50` — кошелёк;
|
|
||||||
- `100` — homeserver.
|
|
||||||
|
|
||||||
Правило проверки `sessionType`:
|
|
||||||
|
|
||||||
1. если в `Solana PDA` нет записи для `sessionKey`, сервер принимает `sessionType`, присланный клиентом;
|
|
||||||
2. если запись в `PDA` есть, `sessionType` в запросе должен совпадать с `session_type` из `PDA`;
|
|
||||||
3. при несовпадении сервер возвращает `460 / SESSION_TYPE_MISMATCH`.
|
|
||||||
|
|
||||||
Ниже в документе сначала описан сценарий, а потом зафиксированы точные форматы запросов и ответов.
|
|
||||||
|
|
||||||
Отдельно появился новый серверный сценарий pairing через доверенный homeserver/ESP. Он не заменяет обычный вход и описан в:
|
|
||||||
|
|
||||||
- `Dev_Docs/Протоколы/ESP_Pairing_и_режимы_подключения.md`
|
|
||||||
|
|
||||||
Кратко:
|
|
||||||
|
|
||||||
- `AuthChallenge/CreateAuthSession` и `SessionChallenge/SessionLogin` остаются каноническими потоками обычной авторизации;
|
|
||||||
- pairing через ESP идёт отдельными `op` и только подготавливает безопасное добавление новой сессии;
|
|
||||||
- решение об одобрении pairing принимает любая уже авторизованная доверенная сессия пользователя.
|
|
||||||
|
|
||||||
## 1. Поток авторизации
|
|
||||||
|
|
||||||
Поддерживаются два сценария:
|
|
||||||
|
|
||||||
1. Создание новой сессии:
|
|
||||||
`AuthChallenge` -> `CreateAuthSession`
|
|
||||||
2. Вход в существующую сессию:
|
|
||||||
`SessionChallenge` -> `SessionLogin`
|
|
||||||
|
|
||||||
`clientKey` используется для создания новой сессии.
|
|
||||||
|
|
||||||
`sessionKey` используется для входа в уже созданную сессию.
|
|
||||||
|
|
||||||
`sessionKey` передаётся и хранится целиком одной строкой, например:
|
|
||||||
|
|
||||||
```text
|
|
||||||
ed25519/BASE64_PUBLIC_KEY
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. `AuthChallenge`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AuthChallenge",
|
|
||||||
"requestId": "auth-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AuthChallenge",
|
|
||||||
"requestId": "auth-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"authNonce": "8f2f0f71-0b1c-4ab2-8f5d-0bc5d6f6aa11"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `AuthChallenge`
|
|
||||||
|
|
||||||
- `400 / EMPTY_LOGIN` — пустой `login`.
|
|
||||||
- `400 / ALREADY_AUTHED` — по текущему соединению уже выполнена авторизация.
|
|
||||||
- `422 / UNKNOWN_USER` — пользователь с таким `login` не найден.
|
|
||||||
- `501 / SOLANA_IMPORT_FAILED` — сервер не смог проверить/импортировать пользователя из Solana при lazy-import.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера, если появится вне штатного сценария.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. `CreateAuthSession`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CreateAuthSession",
|
|
||||||
"requestId": "create-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"sessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
|
||||||
"storagePwd": "BASE64_OR_APP_SPECIFIC_SECRET",
|
|
||||||
"timeMs": 1774600000123,
|
|
||||||
"authNonce": "nonce",
|
|
||||||
"clientKey": "BASE64_DEVICE_PUBLIC_KEY",
|
|
||||||
"signatureB64": "BASE64_SIGNATURE",
|
|
||||||
"sessionType": 1,
|
|
||||||
"clientPlatform": "Web",
|
|
||||||
"clientInfo": "Android 15; Pixel 9"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Строка для подписи
|
|
||||||
|
|
||||||
```text
|
|
||||||
AUTH_CREATE_SESSION:{login}:{sessionKey}:{storagePwd}:{timeMs}:{authNonce}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Дополнительная проверка ключа
|
|
||||||
|
|
||||||
Перед проверкой подписи сервер должен:
|
|
||||||
|
|
||||||
1. взять актуальный `solana_users.client_key`;
|
|
||||||
2. сравнить его с `payload.clientKey`;
|
|
||||||
3. только потом проверять подпись.
|
|
||||||
|
|
||||||
Если `clientKey` не совпадает, сервер возвращает ошибку `DEVICE_KEY_NOT_ACTUAL`.
|
|
||||||
|
|
||||||
На будущее:
|
|
||||||
|
|
||||||
- для ротации `client_key` желательно добавить перепроверку через Solana.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CreateAuthSession",
|
|
||||||
"requestId": "create-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"sessionId": "sess_7c5e5c4b"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `CreateAuthSession`
|
|
||||||
|
|
||||||
- `400 / NO_STEP1_CONTEXT` — для данного соединения не был корректно выполнен `AuthChallenge`.
|
|
||||||
- `400 / EMPTY_LOGIN` — пустой `login`.
|
|
||||||
- `400 / LOGIN_MISMATCH` — `login` не совпадает с тем, для кого был выдан `authNonce`.
|
|
||||||
- `501 / DB_ERROR_USER_LOOKUP` — ошибка БД при повторном чтении пользователя.
|
|
||||||
- `422 / USER_NOT_FOUND` — пользователь не найден.
|
|
||||||
- `501 / NO_LOGIN` — у пользователя на сервере не заполнен `login`.
|
|
||||||
- `400 / EMPTY_STORAGE_PWD` — пустой `storagePwd`.
|
|
||||||
- `400 / EMPTY_SESSION_KEY` — пустой `sessionKey`.
|
|
||||||
- `422 / UNSUPPORTED_KEY_ALGORITHM` — префикс алгоритма в `sessionKey` или `clientKey` не поддерживается текущим сервером.
|
|
||||||
- `400 / BAD_BASE64` — неверный Base64 в `sessionKey`, `clientKey` или `signatureB64`.
|
|
||||||
- `400 / EMPTY_SIGNATURE` — пустая подпись.
|
|
||||||
- `400 / TIME_SKEW` — время клиента отличается от серверного больше допустимого окна.
|
|
||||||
- `400 / NO_DEVICE_KEY` — у пользователя в БД отсутствует `clientKey`.
|
|
||||||
- `400 / EMPTY_AUTH_NONCE` — пустой `authNonce`.
|
|
||||||
- `400 / AUTH_NONCE_MISMATCH` — `authNonce` не соответствует значению из `AuthChallenge`.
|
|
||||||
- `400 / EMPTY_DEVICE_KEY` — в запросе не передан `clientKey`.
|
|
||||||
- `422 / DEVICE_KEY_NOT_ACTUAL` — `clientKey` не совпадает с актуальной версией на сервере.
|
|
||||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
|
||||||
- `460 / SESSION_TYPE_MISMATCH` — `sessionType` не совпадает с типом сессии, уже опубликованным для этого `sessionKey` в Solana PDA.
|
|
||||||
- `501 / SESSION_TYPE_PDA_CHECK_FAILED` — сервер не смог проверить `sessionType` по Solana PDA.
|
|
||||||
- `501 / DB_ERROR_SESSION_CREATE` — ошибка БД при создании записи активной сессии.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. `SessionChallenge`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SessionChallenge",
|
|
||||||
"requestId": "sch-001",
|
|
||||||
"payload": {
|
|
||||||
"sessionId": "sess_7c5e5c4b"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SessionChallenge",
|
|
||||||
"requestId": "sch-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"nonce": "0e5bb0f4-c7d8-4efb-b44d-bf31a6126c66"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `SessionChallenge`
|
|
||||||
|
|
||||||
- `400 / EMPTY_SESSION_ID` — пустой `sessionId`.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД при чтении сессии.
|
|
||||||
- `422 / SESSION_NOT_FOUND` — сессия не найдена.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. `SessionLogin`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SessionLogin",
|
|
||||||
"requestId": "slogin-001",
|
|
||||||
"payload": {
|
|
||||||
"sessionId": "sess_7c5e5c4b",
|
|
||||||
"sessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
|
||||||
"timeMs": 1774600010456,
|
|
||||||
"signatureB64": "BASE64_SIGNATURE",
|
|
||||||
"sessionType": 1,
|
|
||||||
"clientPlatform": "Web",
|
|
||||||
"clientInfo": "Android 15; Pixel 9"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Строка для подписи
|
|
||||||
|
|
||||||
```text
|
|
||||||
SESSION_LOGIN:{sessionId}:{timeMs}:{nonce}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Дополнительная проверка ключа
|
|
||||||
|
|
||||||
Перед проверкой подписи сервер должен:
|
|
||||||
|
|
||||||
1. взять `active_sessions.session_key`;
|
|
||||||
2. сравнить его с `payload.sessionKey`;
|
|
||||||
3. только потом проверять подпись.
|
|
||||||
|
|
||||||
Если ключ не совпадает, сервер возвращает ошибку `SESSION_KEY_NOT_ACTUAL`.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SessionLogin",
|
|
||||||
"requestId": "slogin-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"storagePwd": "BASE64_OR_APP_SPECIFIC_SECRET"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `SessionLogin`
|
|
||||||
|
|
||||||
- `400 / EMPTY_SESSION_ID` — пустой `sessionId`.
|
|
||||||
- `400 / NO_CHALLENGE` — перед `SessionLogin` не был успешно выполнен `SessionChallenge` либо nonce уже истёк.
|
|
||||||
- `400 / SESSION_ID_MISMATCH` — nonce был выдан для другого `sessionId`.
|
|
||||||
- `400 / TIME_SKEW` — время клиента отличается от серверного больше допустимого окна.
|
|
||||||
- `400 / EMPTY_SIGNATURE` — пустая подпись.
|
|
||||||
- `400 / EMPTY_SESSION_KEY` — пустой `sessionKey`.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД при чтении сессии.
|
|
||||||
- `422 / SESSION_NOT_FOUND` — сессия не найдена.
|
|
||||||
- `501 / NO_SESSION_KEY` — у сессии отсутствует `session_key`.
|
|
||||||
- `422 / SESSION_KEY_NOT_ACTUAL` — переданный `sessionKey` не совпадает с актуальной версией на сервере.
|
|
||||||
- `422 / UNSUPPORTED_KEY_ALGORITHM` — префикс алгоритма в `sessionKey` не поддерживается текущим сервером.
|
|
||||||
- `400 / BAD_BASE64` — неверный Base64 в `sessionKey` или `signatureB64`.
|
|
||||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
|
||||||
- `460 / SESSION_TYPE_MISMATCH` — `sessionType` не совпадает с типом сессии, уже опубликованным для этого `sessionKey` в Solana PDA.
|
|
||||||
- `501 / SESSION_TYPE_PDA_CHECK_FAILED` — сервер не смог проверить `sessionType` по Solana PDA.
|
|
||||||
- `501 / DB_ERROR_USER_LOOKUP` — ошибка БД при чтении пользователя для этой сессии.
|
|
||||||
- `422 / USER_NOT_FOUND_FOR_SESSION` — пользователь, которому принадлежит сессия, не найден.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Pairing через homeserver/ESP
|
|
||||||
|
|
||||||
Новые `op`, относящиеся к этому сценарию:
|
|
||||||
|
|
||||||
- `GetTrustedDeviceLoginSettings`
|
|
||||||
- `UpsertTrustedDeviceLoginSettings`
|
|
||||||
- `StartTrustedDeviceLogin`
|
|
||||||
- `ListTrustedDeviceLoginRequests`
|
|
||||||
- `ApproveTrustedDeviceLogin`
|
|
||||||
- `RejectTrustedDeviceLogin`
|
|
||||||
- `CancelTrustedDeviceLogin`
|
|
||||||
- `GetTrustedDeviceLoginStatus`
|
|
||||||
|
|
||||||
В этом потоке:
|
|
||||||
|
|
||||||
- новое устройство не владеет `clientKey` и не проходит обычный `CreateAuthSession`;
|
|
||||||
- пароль проверяется сервером только как фильтр;
|
|
||||||
- решение об одобрении принимает уже авторизованная доверенная сессия пользователя;
|
|
||||||
- сервер не расшифровывает `encryptedPayload` и не становится источником приватных ключей.
|
|
||||||
|
|
||||||
Точные форматы этих операций см. в `03_Session_Management_API.md` и в протокольном документе:
|
|
||||||
|
|
||||||
- `Dev_Docs/Протоколы/ESP_Pairing_и_режимы_подключения.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Пример ошибки
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SessionLogin",
|
|
||||||
"requestId": "slogin-001",
|
|
||||||
"status": 403,
|
|
||||||
"ok": false,
|
|
||||||
"error": "SESSION_KEY_NOT_ACTUAL",
|
|
||||||
"message": "session_key не соответствует актуальной версии",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@ -1,485 +0,0 @@
|
|||||||
# API для разработчиков: Управление сессиями
|
|
||||||
|
|
||||||
Этот файл описывает методы, которые используются уже после успешной авторизации пользователя в сессию.
|
|
||||||
|
|
||||||
Здесь два метода:
|
|
||||||
|
|
||||||
- `ListSessions` — получить список активных сессий пользователя;
|
|
||||||
- `CloseActiveSession` — закрыть одну из активных сессий.
|
|
||||||
|
|
||||||
Дополнительно в этом же слое управления сессиями появился сценарий pairing через доверенную уже авторизованную сессию пользователя:
|
|
||||||
|
|
||||||
- `GetTrustedDeviceLoginSettings`
|
|
||||||
- `UpsertTrustedDeviceLoginSettings`
|
|
||||||
- `ListTrustedDeviceLoginRequests`
|
|
||||||
- `ApproveTrustedDeviceLogin`
|
|
||||||
- `RejectTrustedDeviceLogin`
|
|
||||||
- `CancelTrustedDeviceLogin`
|
|
||||||
|
|
||||||
Анонимное новое устройство работает с двумя связанными операциями:
|
|
||||||
|
|
||||||
- `StartTrustedDeviceLogin`
|
|
||||||
- `GetTrustedDeviceLoginStatus`
|
|
||||||
|
|
||||||
Логика раздела такая:
|
|
||||||
|
|
||||||
- сначала пользователь проходит `SessionLogin`;
|
|
||||||
- после этого сервер считает соединение авторизованным;
|
|
||||||
- уже в этом состоянии клиент может читать список сессий и управлять ими.
|
|
||||||
|
|
||||||
То есть это не этап создания или входа в сессию, а этап последующего контроля уже существующих активных сессий.
|
|
||||||
|
|
||||||
## 1. `ListSessions`
|
|
||||||
|
|
||||||
Доступно только после успешного `SessionLogin`.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListSessions",
|
|
||||||
"requestId": "list-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListSessions",
|
|
||||||
"requestId": "list-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"sessions": [
|
|
||||||
{
|
|
||||||
"sessionId": "sess_7c5e5c4b",
|
|
||||||
"sessionType": 1,
|
|
||||||
"clientPlatform": "Web",
|
|
||||||
"onlineOnThisServer": true,
|
|
||||||
"clientInfoFromClient": "Android 15; Pixel 9",
|
|
||||||
"clientInfoFromRequest": "UA=Java-http-client/17.0.18; remote=127.0.0.1",
|
|
||||||
"geo": "RU/Moscow",
|
|
||||||
"lastAuthenticatedAtMs": 1774600010500
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `ListSessions`
|
|
||||||
|
|
||||||
- `422 / NOT_AUTHENTICATED` — запрос доступен только после успешного `SessionLogin`.
|
|
||||||
- `501 / DB_ERROR_LIST_SESSIONS` — ошибка БД при чтении списка активных сессий.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
### Поля одной сессии в `ListSessions`
|
|
||||||
|
|
||||||
- `sessionId` — идентификатор активной сессии;
|
|
||||||
- `sessionType` — числовой код типа сессии:
|
|
||||||
- `1` — клиент;
|
|
||||||
- `50` — кошелёк;
|
|
||||||
- `100` — homeserver;
|
|
||||||
- `clientPlatform` — строка платформы, как её прислал клиент;
|
|
||||||
- `onlineOnThisServer` — `true`, если эта сессия сейчас держит живое WebSocket-подключение именно к данному серверу;
|
|
||||||
- `clientInfoFromClient` — краткая строка клиента;
|
|
||||||
- `clientInfoFromRequest` — строка, собранная сервером из запроса;
|
|
||||||
- `geo` — страна/город или fallback-строка;
|
|
||||||
- `lastAuthenticatedAtMs` — время последней успешной авторизации этой сессии.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. `CloseActiveSession`
|
|
||||||
|
|
||||||
Доступно только после успешного `SessionLogin`.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CloseActiveSession",
|
|
||||||
"requestId": "close-001",
|
|
||||||
"payload": {
|
|
||||||
"sessionId": "sess_7c5e5c4b"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CloseActiveSession",
|
|
||||||
"requestId": "close-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `CloseActiveSession`
|
|
||||||
|
|
||||||
- `422 / NOT_AUTHENTICATED` — запрос доступен только после успешного `SessionLogin`.
|
|
||||||
- `400 / NO_SESSION_TO_CLOSE` — сервер не смог определить, какую сессию нужно закрыть.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД при поиске сессии или её удалении.
|
|
||||||
- `422 / SESSION_NOT_FOUND` — целевая сессия не найдена.
|
|
||||||
- `422 / SESSION_OF_ANOTHER_USER` — нельзя закрывать сессию другого пользователя.
|
|
||||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Пример ошибки
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CloseActiveSession",
|
|
||||||
"requestId": "close-001",
|
|
||||||
"status": 403,
|
|
||||||
"ok": false,
|
|
||||||
"error": "NOT_AUTHENTICATED",
|
|
||||||
"message": "Операция доступна только для авторизованных пользователей",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## 4. Формат `sessionId`
|
|
||||||
|
|
||||||
Текущее серверное значение `sessionId` генерируется как:
|
|
||||||
|
|
||||||
- случайные **32 байта** (`SecureRandom`),
|
|
||||||
- кодирование в **стандартный Base64 RFC 4648** (алфавит `A-Z a-z 0-9 + /`),
|
|
||||||
- **без padding** `=`.
|
|
||||||
|
|
||||||
Практически это строка длиной около **43 символов** (для 32 байт без `=`).
|
|
||||||
|
|
||||||
Пример реального формата:
|
|
||||||
|
|
||||||
```
|
|
||||||
K9v3nQ4u8jYk0a2p7cD4mLx1zR0sT5wV6bN8eH3fQ1M
|
|
||||||
```
|
|
||||||
|
|
||||||
Важно: это **не человеко-читаемое имя**, а непрозрачный идентификатор.
|
|
||||||
Нужно передавать его как есть, без нормализации регистра и без URL-экранирования внутри JSON.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. TrustedDeviceLogin через доверенную сессию
|
|
||||||
|
|
||||||
Этот блок относится к сценарию добавления новой сессии через доверенное устройство пользователя.
|
|
||||||
|
|
||||||
### 5.1. `GetTrustedDeviceLoginSettings`
|
|
||||||
|
|
||||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetTrustedDeviceLoginSettings",
|
|
||||||
"requestId": "trusted-login-get-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetTrustedDeviceLoginSettings",
|
|
||||||
"requestId": "trusted-login-get-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"enabled": true,
|
|
||||||
"hasPassword": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если отдельной записи настроек на сервере ещё нет, сервер считает состояние по умолчанию таким:
|
|
||||||
|
|
||||||
- `enabled = true`
|
|
||||||
- `hasPassword = false`
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION` — операция вызвана без уже авторизованной доверенной сессии пользователя.
|
|
||||||
|
|
||||||
### 5.2. `UpsertTrustedDeviceLoginSettings`
|
|
||||||
|
|
||||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertTrustedDeviceLoginSettings",
|
|
||||||
"requestId": "esp-set-001",
|
|
||||||
"payload": {
|
|
||||||
"enabled": true,
|
|
||||||
"passwordHash": "sha256$0123abcd..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если вход через доверенное устройство должен работать **без доп. пароля**, клиент включает его с пустым `passwordHash`.
|
|
||||||
|
|
||||||
Если `enabled = false`, сервер автоматически удаляет пароль и запрещает вход через другое устройство.
|
|
||||||
|
|
||||||
Формат непустого `passwordHash`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
sha256$<hex( SHA-256("shine-pairing|" + lower(login.trim()) + "|" + password) )>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertTrustedDeviceLoginSettings",
|
|
||||||
"requestId": "esp-set-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"enabled": true,
|
|
||||||
"hasPassword": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION` — операция вызвана без уже авторизованной доверенной сессии пользователя.
|
|
||||||
|
|
||||||
### 5.3. `StartTrustedDeviceLogin`
|
|
||||||
|
|
||||||
Эта операция доступна без уже существующей пользовательской сессии.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "StartTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-start-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"passwordHash": "sha256$0123abcd...",
|
|
||||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
|
||||||
"requesterSessionType": 1,
|
|
||||||
"requesterClientPlatform": "Android",
|
|
||||||
"payloadType": 1
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если на доверённом устройстве вход включён **без доп. пароля**, новое устройство может отправить пустой `passwordHash`.
|
|
||||||
|
|
||||||
Поле `trustedSessionOnline` показывает, что у пользователя сейчас есть хотя бы одна онлайн доверенная сессия, способная принять pairing-заявку.
|
|
||||||
Поле `shortCode` теперь содержит `10` цифр. В UI его рекомендуется показывать как `5` пар, например: `49 20 70 91 23`.
|
|
||||||
|
|
||||||
TTL заявки фиксирован на сервере и сейчас всегда равен `300` секундам.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "StartTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-start-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"state": "created",
|
|
||||||
"shortCode": "4920709123",
|
|
||||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
|
||||||
"expiresAtMs": 1781441990538,
|
|
||||||
"trustedSessionOnline": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / EMPTY_LOGIN`
|
|
||||||
- `400 / EMPTY_REQUESTER_SESSION_KEY`
|
|
||||||
- `400 / BAD_REQUESTER_SESSION_KEY`
|
|
||||||
- `400 / BAD_SESSION_TYPE`
|
|
||||||
- `400 / BAD_PAYLOAD_TYPE`
|
|
||||||
- `422 / PAIRING_NOT_AVAILABLE`
|
|
||||||
- `422 / PAIRING_PASSWORD_INVALID` — pairing-пароль не подходит. Та же ошибка возвращается и если новое устройство ввело пароль, а у пользователя режим pairing включён без пароля.
|
|
||||||
- `422 / PAIRING_NO_TRUSTED_SESSION_ONLINE` — сейчас нет ни одной онлайн доверённой сессии пользователя, поэтому код не создаётся.
|
|
||||||
- `429 / PAIRING_RATE_LIMITED`
|
|
||||||
|
|
||||||
### 5.4. `ListTrustedDeviceLoginRequests`
|
|
||||||
|
|
||||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
|
||||||
Возвращает только реально активные pending-заявки со `state = created`. Уже `approved` и `rejected` заявки в этот список больше не попадают.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListTrustedDeviceLoginRequests",
|
|
||||||
"requestId": "esp-list-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"requests": [
|
|
||||||
{
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"state": "created",
|
|
||||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
|
||||||
"requesterSessionType": 1,
|
|
||||||
"requesterClientPlatform": "Android",
|
|
||||||
"payloadType": 1,
|
|
||||||
"shortCode": "4920709123",
|
|
||||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
|
||||||
"createdAtMs": 1781441810538,
|
|
||||||
"expiresAtMs": 1781441990538,
|
|
||||||
"deliveredToHomeserver": true
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION`
|
|
||||||
|
|
||||||
### 5.5. `ApproveTrustedDeviceLogin`
|
|
||||||
|
|
||||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ApproveTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-approve-001",
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"encryptedPayload": "BASE64_OR_OTHER_OPAQUE_PAYLOAD"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ApproveTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-approve-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"state": "approved"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / EMPTY_PAIRING_ID`
|
|
||||||
- `400 / EMPTY_ENCRYPTED_PAYLOAD`
|
|
||||||
- `404 / PAIRING_NOT_FOUND`
|
|
||||||
- `422 / PAIRING_OF_ANOTHER_USER`
|
|
||||||
- `422 / PAIRING_NOT_PENDING`
|
|
||||||
- `422 / PAIRING_EXPIRED`
|
|
||||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION`
|
|
||||||
|
|
||||||
### 5.6. `RejectTrustedDeviceLogin`
|
|
||||||
|
|
||||||
Доступно для любой уже авторизованной доверенной сессии пользователя. Похоже на approve, но переводит заявку в `state=rejected`.
|
|
||||||
|
|
||||||
### 5.7. `GetTrustedDeviceLoginStatus`
|
|
||||||
|
|
||||||
Операция для нового устройства.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetTrustedDeviceLoginStatus",
|
|
||||||
"requestId": "esp-status-001",
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ после approve
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetTrustedDeviceLoginStatus",
|
|
||||||
"requestId": "esp-status-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"state": "approved",
|
|
||||||
"shortCode": "4920709123",
|
|
||||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
|
||||||
"payloadType": 1,
|
|
||||||
"encryptedPayload": "AQIDBA==",
|
|
||||||
"expiresAtMs": 1781441990538
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Возможные `state`
|
|
||||||
|
|
||||||
- `created`
|
|
||||||
- `approved`
|
|
||||||
- `rejected`
|
|
||||||
- `canceled`
|
|
||||||
- `expired`
|
|
||||||
|
|
||||||
### 5.8. `CancelTrustedDeviceLogin`
|
|
||||||
|
|
||||||
Операция для нового устройства, которое уже создало pairing-заявку и хочет принудительно снять ожидание до истечения TTL.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CancelTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-cancel-001",
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CancelTrustedDeviceLogin",
|
|
||||||
"requestId": "esp-cancel-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"pairingId": "base64url",
|
|
||||||
"state": "canceled"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / EMPTY_PAIRING_ID`
|
|
||||||
- `400 / EMPTY_REQUESTER_SESSION_KEY`
|
|
||||||
- `400 / BAD_REQUESTER_SESSION_KEY`
|
|
||||||
- `404 / PAIRING_NOT_FOUND`
|
|
||||||
- `422 / PAIRING_OF_ANOTHER_REQUESTER`
|
|
||||||
- `422 / PAIRING_NOT_PENDING`
|
|
||||||
@ -1,176 +0,0 @@
|
|||||||
# 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`
|
|
||||||
- `repost_disabled` — репосты временно отключены до будущей реализации
|
|
||||||
- `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)`
|
|
||||||
- `TEXT_REPOST (30)` — формат зарезервирован, но новые блоки временно отклоняются с `repost_disabled`
|
|
||||||
|
|
||||||
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)`
|
|
||||||
- `CONNECTION_SPOUSE (40)`
|
|
||||||
- `CONNECTION_UNSPOUSE (41)`
|
|
||||||
- `CONNECTION_PARENT (50)`
|
|
||||||
- `CONNECTION_UNPARENT (51)`
|
|
||||||
- `CONNECTION_CHILD (52)`
|
|
||||||
- `CONNECTION_UNCHILD (53)`
|
|
||||||
- `CONNECTION_SIBLING (54)`
|
|
||||||
- `CONNECTION_UNSIBLING (55)`
|
|
||||||
- `CONNECTION_KNOWN_PERSON (60)`
|
|
||||||
- `CONNECTION_UNKNOWN_PERSON (61)`
|
|
||||||
- `CONNECTION_SHINE_CONFIRMED (70)`
|
|
||||||
- `CONNECTION_SHINE_UNCONFIRMED (71)`
|
|
||||||
- `CONNECTION_SHINE_SEEN (74)`
|
|
||||||
- `CONNECTION_SHINE_UNSEEN (75)`
|
|
||||||
|
|
||||||
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), а не на произвольный пост.
|
|
||||||
|
|
||||||
|
|
||||||
## 8. USER_PARAM для «личных данных»
|
|
||||||
|
|
||||||
Да, на текущем API это можно добавить **без изменения серверного кода**:
|
|
||||||
|
|
||||||
- в `UserParam` поле `param` сейчас не ограничено фиксированным справочником;
|
|
||||||
- сервер хранит пары `param -> value` как строки (при наличии корректной подписи и `time_ms`);
|
|
||||||
- чтение уже есть через `GetUserParam` и `ListUserParams`.
|
|
||||||
|
|
||||||
Рекомендуемый стартовый набор ключей для профиля (MVP):
|
|
||||||
|
|
||||||
- `name`
|
|
||||||
- `last_name`
|
|
||||||
- `address_physical`
|
|
||||||
- `address_web`
|
|
||||||
- `phone`
|
|
||||||
|
|
||||||
Практическая рекомендация: заранее зафиксировать единый словарь ключей в клиенте/документации, чтобы избежать дублей вида `lastname` vs `last_name`, `site` vs `address_web` и т.д.
|
|
||||||
|
|
||||||
Ограничения, которые важно учесть:
|
|
||||||
|
|
||||||
- сейчас нет серверной ACL-политики чтения параметров (в MVP их может читать любой клиент, который знает `login`);
|
|
||||||
- нет валидации формата значений для конкретных ключей (телефон, URL и т.д. проверяются только на стороне клиента);
|
|
||||||
- нет отдельного индекса/поиска по этим полям — только точечное чтение и listing по `login`.
|
|
||||||
@ -1,333 +0,0 @@
|
|||||||
# API для разработчиков: Технические запросы
|
|
||||||
|
|
||||||
Этот файл описывает технические WebSocket-запросы, которые нужны для служебной работы клиента с сервером. Часть операций доступна без авторизации, часть требует успешной авторизованной сессии.
|
|
||||||
|
|
||||||
Сейчас здесь шесть методов:
|
|
||||||
|
|
||||||
- `Ping` — keep-alive запрос для поддержания живого WebSocket-соединения;
|
|
||||||
- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети;
|
|
||||||
- `GetCallIceConfig` — выдача STUN/TURN конфигурации для звонков;
|
|
||||||
- `ClientErrorLog` — отправка клиентской ошибки в серверный лог;
|
|
||||||
- `ClientDebugLog` — отправка клиентского debug-события в серверный буфер;
|
|
||||||
- `CallDeliveryReport` — диагностический отчёт клиента о доставке/установке звонка.
|
|
||||||
|
|
||||||
Логика раздела такая:
|
|
||||||
|
|
||||||
- `Ping` нужен для регулярной проверки, что соединение всё ещё живо;
|
|
||||||
- `GetServerInfo` нужен до авторизации и до работы с данными, чтобы клиент понял, что сервер доступен, и показал пользователю краткую карточку этого узла.
|
|
||||||
|
|
||||||
Ниже сначала описаны назначение методов, затем точные форматы запросов и ответов.
|
|
||||||
|
|
||||||
## 1. `Ping`
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Служебный keep-alive запрос.
|
|
||||||
|
|
||||||
Клиент может отправлять его периодически, чтобы:
|
|
||||||
|
|
||||||
- поддерживать активное WebSocket-соединение;
|
|
||||||
- понимать, что сервер отвечает;
|
|
||||||
- при необходимости получать текущее серверное время.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "Ping",
|
|
||||||
"requestId": "ping-001",
|
|
||||||
"payload": {
|
|
||||||
"ts": 1774700000123
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Поле `ts` в запросе необязательно для логики сервера. Сервер его не валидирует и не использует для принятия решения.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "Ping",
|
|
||||||
"requestId": "ping-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"ts": 1774700000456
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `Ping`
|
|
||||||
|
|
||||||
- У `Ping` нет специальных прикладных ошибок.
|
|
||||||
- Если произойдёт непредвиденная проблема, сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. `GetServerInfo`
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Запрос публичной информации о сервере.
|
|
||||||
|
|
||||||
Он нужен клиенту для выбора сервера в децентрализованной сети. По этому запросу клиент может:
|
|
||||||
|
|
||||||
- проверить, что сервер вообще доступен;
|
|
||||||
- показать URL и версию сервера;
|
|
||||||
- показать физический регион или адрес размещения;
|
|
||||||
- показать описание сервера;
|
|
||||||
- показать поле `origin` как комментарий о природе этого узла;
|
|
||||||
- показать дополнительную текстовую информацию.
|
|
||||||
|
|
||||||
Этот запрос доступен без авторизации.
|
|
||||||
|
|
||||||
### Источник данных
|
|
||||||
|
|
||||||
- `version` берётся из Gradle build и подставляется в `application.properties`;
|
|
||||||
- остальные поля читаются из настроек сервера;
|
|
||||||
- если значение в конфиге не задано, сервер возвращает пустую строку.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetServerInfo",
|
|
||||||
"requestId": "srv-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetServerInfo",
|
|
||||||
"requestId": "srv-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"url": "wss://node.example.org/ws",
|
|
||||||
"version": "1.0",
|
|
||||||
"physicalRegion": "Грузия, Тбилиси",
|
|
||||||
"description": "Public community SHiNE node",
|
|
||||||
"origin": "Community-operated node",
|
|
||||||
"extraInfo": "IPv4 + IPv6; test federation enabled"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Поля ответа
|
|
||||||
|
|
||||||
- `url` — публичный URL сервера.
|
|
||||||
- `version` — версия сервера из Gradle build.
|
|
||||||
- `physicalRegion` — физический регион или адрес размещения сервера.
|
|
||||||
- `description` — человекочитаемое описание сервера.
|
|
||||||
- `origin` — комментарий о том, какой это сервер.
|
|
||||||
- `extraInfo` — любая дополнительная информация о сервере.
|
|
||||||
|
|
||||||
### Специфические коды ошибок `GetServerInfo`
|
|
||||||
|
|
||||||
- У `GetServerInfo` нет специальных прикладных ошибок при штатной работе.
|
|
||||||
- Если произойдёт непредвиденная проблема, сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. `GetCallIceConfig`
|
|
||||||
|
|
||||||
Доступно только после успешной авторизации.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetCallIceConfig",
|
|
||||||
"requestId": "ice-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetCallIceConfig",
|
|
||||||
"requestId": "ice-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"stunUrls": ["stun:stun.example.org:3478"],
|
|
||||||
"turnUrls": ["turn:turn.example.org:3478?transport=udp"],
|
|
||||||
"turnUsername": "user",
|
|
||||||
"turnPassword": "password",
|
|
||||||
"turnServers": [
|
|
||||||
{
|
|
||||||
"id": "primary",
|
|
||||||
"urls": ["turn:turn.example.org:3478?transport=udp"],
|
|
||||||
"username": "user",
|
|
||||||
"password": "password"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"turnEnabled": true,
|
|
||||||
"generatedAtMs": 1774700000123,
|
|
||||||
"expiresAtMs": 1774700300123,
|
|
||||||
"ttlSec": 300
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `GetCallIceConfig`
|
|
||||||
|
|
||||||
- `422 / NOT_AUTHENTICATED` — требуется авторизация.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. `ClientErrorLog`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ClientErrorLog",
|
|
||||||
"requestId": "err-001",
|
|
||||||
"payload": {
|
|
||||||
"kind": "global_error",
|
|
||||||
"message": "TypeError: failed",
|
|
||||||
"stack": "...",
|
|
||||||
"sourceUrl": "https://shineup.me/app.js",
|
|
||||||
"lineNumber": 10,
|
|
||||||
"columnNumber": 20,
|
|
||||||
"route": "#/channel-view/own-0",
|
|
||||||
"href": "https://shineup.me/#/channel-view/own-0",
|
|
||||||
"userAgent": "...",
|
|
||||||
"clientTs": 1774700000123,
|
|
||||||
"requestOp": "GetChannelMessages",
|
|
||||||
"requestIdRef": "GetChannelMessages-123",
|
|
||||||
"contextJson": "{\"screen\":\"channels\"}"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ClientErrorLog",
|
|
||||||
"requestId": "err-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"serverTs": 1774700000456,
|
|
||||||
"accepted": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `ClientErrorLog`
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — обязательные поля ошибки не заполнены.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. `ClientDebugLog`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ClientDebugLog",
|
|
||||||
"requestId": "dbg-001",
|
|
||||||
"payload": {
|
|
||||||
"runId": "ui-run-1",
|
|
||||||
"level": "info",
|
|
||||||
"message": "opened channels tab",
|
|
||||||
"details": "{\"route\":\"#/channels\"}"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ClientDebugLog",
|
|
||||||
"requestId": "dbg-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"accepted": true,
|
|
||||||
"serverTs": 1774700000456
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `ClientDebugLog`
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — поле `message` не заполнено.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. `CallDeliveryReport`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CallDeliveryReport",
|
|
||||||
"requestId": "call-report-001",
|
|
||||||
"payload": {
|
|
||||||
"type": "outgoing_failed",
|
|
||||||
"value": "{\"reason\":\"ice_failed\",\"callId\":\"call-1\"}"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "CallDeliveryReport",
|
|
||||||
"requestId": "call-report-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"serverTs": 1774700000456,
|
|
||||||
"accepted": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Специфические коды ошибок `CallDeliveryReport`
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — поле `type` не заполнено.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Короткое резюме
|
|
||||||
|
|
||||||
- `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
|
|
||||||
- `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
|
|
||||||
- `GetCallIceConfig` нужен для WebRTC-звонков и требует авторизации.
|
|
||||||
- `ClientErrorLog`, `ClientDebugLog`, `CallDeliveryReport` используются для диагностики клиента и звонков.
|
|
||||||
|
|
||||||
|
|
||||||
## 8. Прямое техническое сообщение в конкретную сессию
|
|
||||||
|
|
||||||
На текущий момент в публичном JSON API этого документа **нет отдельного RPC** для отправки произвольного технического сообщения в конкретную сессию пользователя (по `sessionId`).
|
|
||||||
|
|
||||||
Что уже есть в системе:
|
|
||||||
|
|
||||||
- сервер хранит `sessionId` активной сессии;
|
|
||||||
- есть `ListSessions`, чтобы клиент получил список sessionId своего пользователя;
|
|
||||||
- у сервера есть внутренний реестр активных WS-подключений по `sessionId`.
|
|
||||||
|
|
||||||
Чего не хватает для полноценной фичи «direct tech message by sessionId»:
|
|
||||||
|
|
||||||
1. отдельная API-операция (например, `SendSessionTechMessage`);
|
|
||||||
2. правило авторизации (кто имеет право писать в чужую/свою сессию);
|
|
||||||
3. унифицированный формат payload и события доставки;
|
|
||||||
4. коды ошибок (`SESSION_OFFLINE`, `SESSION_NOT_FOUND`, `FORBIDDEN` и т.п.).
|
|
||||||
|
|
||||||
Итог: как инфраструктурная база это почти готово, но нужен отдельный RPC-слой и политика доступа.
|
|
||||||
@ -1,341 +0,0 @@
|
|||||||
# 06. Channels Read API
|
|
||||||
|
|
||||||
## Человеко-читаемое объяснение
|
|
||||||
Эти функции — это **чтение данных каналов** для UI:
|
|
||||||
|
|
||||||
1. `ListSubscriptionsFeed` — отдает данные для экрана списка каналов:
|
|
||||||
- ваши каналы (личный + созданные вами),
|
|
||||||
- каналы пользователей, на кого вы подписаны,
|
|
||||||
- отдельные каналы, на которые вы подписаны напрямую.
|
|
||||||
|
|
||||||
2. `GetChannelMessages` — отдает полную ленту одного канала (пока без курсоров, загружается сразу целиком),
|
|
||||||
включая версии сообщений, лайки и ответы.
|
|
||||||
|
|
||||||
3. `GetMessageThread` — отдает дерево обсуждения вокруг конкретного сообщения:
|
|
||||||
предки, фокус-сообщение, потомки.
|
|
||||||
|
|
||||||
4. `GetChannelsCounters` — отдает счетчики разделов каналов для пользователя.
|
|
||||||
|
|
||||||
5. `ListGroupChats200` — отдает список групповых чатов типа `200`.
|
|
||||||
|
|
||||||
6. `GetGroupDialog` — отдает сообщения конкретного группового чата типа `200`.
|
|
||||||
|
|
||||||
> На первом этапе мы **не используем курсоры** (`nextCursor`) и загружаем полные списки.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1) ListSubscriptionsFeed
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListSubscriptionsFeed",
|
|
||||||
"requestId": "req-1",
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"limit": 200
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListSubscriptionsFeed",
|
|
||||||
"requestId": "req-1",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"ownedChannels": [
|
|
||||||
{
|
|
||||||
"channel": {
|
|
||||||
"ownerLogin": "Alice",
|
|
||||||
"ownerBlockchainName": "alice-001",
|
|
||||||
"channelName": "0",
|
|
||||||
"personal": true,
|
|
||||||
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
|
|
||||||
},
|
|
||||||
"messagesCount": 120,
|
|
||||||
"lastMessage": {
|
|
||||||
"messageRef": { "blockNumber": 921, "blockHash": "..." },
|
|
||||||
"text": "последняя версия текста",
|
|
||||||
"createdAtMs": 1760000000000,
|
|
||||||
"authorLogin": "Alice",
|
|
||||||
"authorBlockchainName": "alice-001"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"followedUsersChannels": [
|
|
||||||
{
|
|
||||||
"channel": {
|
|
||||||
"ownerLogin": "Bob",
|
|
||||||
"ownerBlockchainName": "bob-001",
|
|
||||||
"channelName": "0",
|
|
||||||
"personal": true,
|
|
||||||
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
|
|
||||||
},
|
|
||||||
"messagesCount": 540,
|
|
||||||
"lastMessage": {
|
|
||||||
"messageRef": { "blockNumber": 922, "blockHash": "..." },
|
|
||||||
"text": "последняя версия текста",
|
|
||||||
"createdAtMs": 1760000100000,
|
|
||||||
"authorLogin": "Bob",
|
|
||||||
"authorBlockchainName": "bob-001"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"followedChannels": [
|
|
||||||
{
|
|
||||||
"channel": {
|
|
||||||
"ownerLogin": "Carl",
|
|
||||||
"ownerBlockchainName": "carl-001",
|
|
||||||
"channelName": "market",
|
|
||||||
"personal": false,
|
|
||||||
"channelRoot": { "blockNumber": 456, "blockHash": "..." }
|
|
||||||
},
|
|
||||||
"messagesCount": 90,
|
|
||||||
"lastMessage": {
|
|
||||||
"messageRef": { "blockNumber": 1002, "blockHash": "..." },
|
|
||||||
"text": "актуальный текст",
|
|
||||||
"createdAtMs": 1760001000000,
|
|
||||||
"authorLogin": "Carl",
|
|
||||||
"authorBlockchainName": "carl-001"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2) GetChannelMessages
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelMessages",
|
|
||||||
"requestId": "req-2",
|
|
||||||
"payload": {
|
|
||||||
"channel": {
|
|
||||||
"ownerBlockchainName": "bob-001",
|
|
||||||
"channelRootBlockNumber": 123,
|
|
||||||
"channelRootBlockHash": "..."
|
|
||||||
},
|
|
||||||
"limit": 200,
|
|
||||||
"sort": "asc"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelMessages",
|
|
||||||
"requestId": "req-2",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"channel": {
|
|
||||||
"ownerLogin": "Bob",
|
|
||||||
"ownerBlockchainName": "bob-001",
|
|
||||||
"channelName": "news",
|
|
||||||
"channelRoot": { "blockNumber": 123, "blockHash": "..." }
|
|
||||||
},
|
|
||||||
"messages": [
|
|
||||||
{
|
|
||||||
"messageRef": { "blockNumber": 140, "blockHash": "..." },
|
|
||||||
"authorLogin": "Bob",
|
|
||||||
"authorBlockchainName": "bob-001",
|
|
||||||
"createdAtMs": 1760000000000,
|
|
||||||
"text": "текущая версия",
|
|
||||||
"likesCount": 12,
|
|
||||||
"repliesCount": 3,
|
|
||||||
"versionsTotal": 4,
|
|
||||||
"versions": [
|
|
||||||
{ "versionIndex": 1, "blockNumber": 140, "blockHash": "...", "text": "v1", "createdAtMs": 1760000000000 },
|
|
||||||
{ "versionIndex": 2, "blockNumber": 155, "blockHash": "...", "text": "v2", "createdAtMs": 1760001000000 },
|
|
||||||
{ "versionIndex": 3, "blockNumber": 170, "blockHash": "...", "text": "v3", "createdAtMs": 1760002000000 },
|
|
||||||
{ "versionIndex": 4, "blockNumber": 199, "blockHash": "...", "text": "v4", "createdAtMs": 1760003000000 }
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3) GetMessageThread
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetMessageThread",
|
|
||||||
"requestId": "req-3",
|
|
||||||
"payload": {
|
|
||||||
"message": {
|
|
||||||
"blockchainName": "bob-001",
|
|
||||||
"blockNumber": 333,
|
|
||||||
"blockHash": "..."
|
|
||||||
},
|
|
||||||
"depthUp": 20,
|
|
||||||
"depthDown": 2,
|
|
||||||
"limitChildrenPerNode": 50
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetMessageThread",
|
|
||||||
"requestId": "req-3",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"ancestors": [MessageNode],
|
|
||||||
"focus": MessageNode,
|
|
||||||
"descendants": [MessageNodeTree]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### MessageNode (дополнение)
|
|
||||||
- `MessageNode` расширяет формат сообщения из `GetChannelMessages` и дополнительно содержит:
|
|
||||||
- `channelInfo` — мета-информация о канале (если применимо);
|
|
||||||
- `rawBlockB64` — сырой `block_bytes` текущего блока в Base64.
|
|
||||||
- Поле `rawBlockB64` присутствует у узлов во всех частях ответа `GetMessageThread`: `focus`, `ancestors[]`, `descendants[]`.
|
|
||||||
- В `GetChannelMessages` поле `rawBlockB64` **не добавляется** (лента канала без сырого блока, чтобы не раздувать ответ).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4) GetChannelsCounters
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelsCounters",
|
|
||||||
"requestId": "req-4",
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelsCounters",
|
|
||||||
"requestId": "req-4",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"feedCount": 12,
|
|
||||||
"dialogs100Count": 3,
|
|
||||||
"groupChats200Count": 4,
|
|
||||||
"myChannelsCount": 2
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5) ListGroupChats200
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListGroupChats200",
|
|
||||||
"requestId": "req-5",
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListGroupChats200",
|
|
||||||
"requestId": "req-5",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"chats": [
|
|
||||||
{
|
|
||||||
"ownerLogin": "Alice",
|
|
||||||
"ownerBlockchainName": "alice-001",
|
|
||||||
"channelRootBlockNumber": 123,
|
|
||||||
"channelRootBlockHash": "...",
|
|
||||||
"channelName": "team",
|
|
||||||
"chatTitle": "Team chat",
|
|
||||||
"membersCount": 3,
|
|
||||||
"updatedAtMs": 1760000000000
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6) GetGroupDialog
|
|
||||||
|
|
||||||
### Request
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetGroupDialog",
|
|
||||||
"requestId": "req-6",
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"group": {
|
|
||||||
"ownerBlockchainName": "alice-001",
|
|
||||||
"channelRootBlockNumber": 123
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Response (success)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetGroupDialog",
|
|
||||||
"requestId": "req-6",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"group": {
|
|
||||||
"ownerLogin": "Alice",
|
|
||||||
"ownerBlockchainName": "alice-001",
|
|
||||||
"channelRootBlockNumber": 123,
|
|
||||||
"channelName": "team",
|
|
||||||
"chatTitle": "Team chat"
|
|
||||||
},
|
|
||||||
"messages": [
|
|
||||||
{
|
|
||||||
"authorLogin": "Bob",
|
|
||||||
"authorBlockchainName": "bob-001",
|
|
||||||
"blockNumber": 140,
|
|
||||||
"blockHash": "...",
|
|
||||||
"createdAtMs": 1760000000000,
|
|
||||||
"text": "Привет"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Reason codes
|
|
||||||
- `bad_fields`
|
|
||||||
- `user_not_found`
|
|
||||||
- `channel_not_found`
|
|
||||||
- `message_not_found`
|
|
||||||
- `limit_too_large`
|
|
||||||
- `channel_name_already_exists`
|
|
||||||
- `internal_error`
|
|
||||||
@ -1,145 +0,0 @@
|
|||||||
# 07. Channels Feature Runbook (человеческое описание + диагностика)
|
|
||||||
|
|
||||||
## 1) Что уже сделано простыми словами
|
|
||||||
|
|
||||||
Сейчас реализован полный минимальный контур для каналов:
|
|
||||||
|
|
||||||
1. **Серверные read API**:
|
|
||||||
- `ListSubscriptionsFeed` — экран списка каналов.
|
|
||||||
- `GetChannelMessages` — сообщения конкретного канала.
|
|
||||||
- `GetMessageThread` — дерево обсуждения для сообщения.
|
|
||||||
|
|
||||||
2. **UI вкладки Каналы**:
|
|
||||||
- при открытии пытается загрузить реальный feed с сервера;
|
|
||||||
- если сервер недоступен — fallback на мок-данные;
|
|
||||||
- группы каналов выводятся в нужном порядке;
|
|
||||||
- есть кнопка «Добавить канал», модалки подписки, переход в канал.
|
|
||||||
|
|
||||||
3. **Проверка уникальности имени канала на сервере**
|
|
||||||
- в `AddBlock` при `CreateChannelBody` добавлена проверка;
|
|
||||||
- при дубле возвращается `409 channel_name_already_exists`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2) Что тестировать в первую очередь (быстрый чеклист)
|
|
||||||
|
|
||||||
### Базовый smoke
|
|
||||||
1. Авторизоваться в UI.
|
|
||||||
2. Открыть вкладку «Каналы».
|
|
||||||
3. Убедиться, что данные загрузились с сервера (или виден fallback-баннер).
|
|
||||||
4. Нажать любой канал — должен открыться экран канала с сообщениями.
|
|
||||||
|
|
||||||
### API smoke
|
|
||||||
1. Вызвать `ListSubscriptionsFeed`.
|
|
||||||
2. Для канала `ownedChannels[0]` вызвать `GetChannelMessages`.
|
|
||||||
3. Для первого `messages[0]` вызвать `GetMessageThread`.
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
1. `ListSubscriptionsFeed` с пустым login -> `bad_fields`.
|
|
||||||
2. `GetChannelMessages` с битым channel payload -> `bad_fields`.
|
|
||||||
3. `GetMessageThread` с несуществующим block -> `message_not_found`.
|
|
||||||
4. `AddBlock(CreateChannel)` с уже существующим именем -> `channel_name_already_exists`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3) Готовые JSON-запросы для ручной диагностики
|
|
||||||
|
|
||||||
## 3.1 ListSubscriptionsFeed
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListSubscriptionsFeed",
|
|
||||||
"requestId": "debug-feed-1",
|
|
||||||
"payload": {
|
|
||||||
"login": "TestUser1",
|
|
||||||
"limit": 200
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3.2 GetChannelMessages
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelMessages",
|
|
||||||
"requestId": "debug-ch-1",
|
|
||||||
"payload": {
|
|
||||||
"channel": {
|
|
||||||
"ownerBlockchainName": "TestUser1-001",
|
|
||||||
"channelRootBlockNumber": 0,
|
|
||||||
"channelRootBlockHash": ""
|
|
||||||
},
|
|
||||||
"limit": 200,
|
|
||||||
"sort": "asc"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3.3 GetMessageThread
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetMessageThread",
|
|
||||||
"requestId": "debug-thread-1",
|
|
||||||
"payload": {
|
|
||||||
"message": {
|
|
||||||
"blockchainName": "TestUser1-001",
|
|
||||||
"blockNumber": 123,
|
|
||||||
"blockHash": "<hash-from-GetChannelMessages>"
|
|
||||||
},
|
|
||||||
"depthUp": 20,
|
|
||||||
"depthDown": 2,
|
|
||||||
"limitChildrenPerNode": 50
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4) Что смотреть в ответах
|
|
||||||
|
|
||||||
### ListSubscriptionsFeed
|
|
||||||
- `payload.login` — канонический login.
|
|
||||||
- `ownedChannels / followedUsersChannels / followedChannels` — массивы.
|
|
||||||
- у каждой записи есть:
|
|
||||||
- `channel.channelRoot.blockNumber`,
|
|
||||||
- `messagesCount`,
|
|
||||||
- `lastMessage` (может быть null, если сообщений нет).
|
|
||||||
|
|
||||||
### GetChannelMessages
|
|
||||||
- `payload.channel` заполнен;
|
|
||||||
- `payload.messages[]` содержит:
|
|
||||||
- `likesCount`, `repliesCount`,
|
|
||||||
- `versionsTotal`, `versions[]`,
|
|
||||||
- `text` должен быть текущей (последней) версией.
|
|
||||||
|
|
||||||
### GetMessageThread
|
|
||||||
- `payload.ancestors[]`, `payload.focus`, `payload.descendants[]`.
|
|
||||||
- у узлов должны быть версии и счетчики.
|
|
||||||
- у каждого узла дополнительно может приходить `rawBlockB64` (Base64 сырого `block_bytes`).
|
|
||||||
|
|
||||||
### Важно по совместимости
|
|
||||||
- `rawBlockB64` добавлен только в `GetMessageThread`.
|
|
||||||
- `GetChannelMessages` не содержит `rawBlockB64` (без изменений формата ленты).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5) Частые проблемы и как быстро локализовать
|
|
||||||
|
|
||||||
1. **`status != 200`, code=bad_fields**
|
|
||||||
- проверить вложенность payload и обязательные поля.
|
|
||||||
|
|
||||||
2. **`message_not_found` в GetMessageThread**
|
|
||||||
- обычно передали blockNumber/hash не из `messageRef`.
|
|
||||||
|
|
||||||
3. **Пустой список сообщений в GetChannelMessages**
|
|
||||||
- проверить `ownerBlockchainName` и `channelRootBlockNumber`.
|
|
||||||
|
|
||||||
4. **`channel_name_already_exists` при AddBlock**
|
|
||||||
- это ожидаемо: в этой цепочке уже есть канал с таким именем.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6) Для будущей доработки
|
|
||||||
|
|
||||||
1. Добавить курсоры (пагинацию) для больших каналов.
|
|
||||||
2. Перевести «Подписаться»/«Добавить канал» в UI с демо-заглушек на реальные write RPC.
|
|
||||||
3. Добавить batch-агрегации для thread/versions (оптимизация).
|
|
||||||
4. Добавить полноценные интеграционные тесты на негативные кейсы и нагрузку.
|
|
||||||
@ -1,162 +0,0 @@
|
|||||||
# MCP: чтение и дозапись персонального публичного чата (type=100)
|
|
||||||
|
|
||||||
Документ для реализации MCP-инструмента, который:
|
|
||||||
- читает переписку между двумя логинами (`from`, `to`);
|
|
||||||
- добавляет новое сообщение от отправителя через серверный `AddBlock`.
|
|
||||||
|
|
||||||
Важно: речь про **персональные публичные** каналы (`channelTypeCode=100`), а не приватные DM.
|
|
||||||
|
|
||||||
## 1. Базовые предпосылки
|
|
||||||
|
|
||||||
1. У каждого пользователя свой блокчейн (`<login>-001`).
|
|
||||||
2. Персональный публичный чат хранится как канал типа `100`:
|
|
||||||
- у `A` канал с `channelName = B`;
|
|
||||||
- у `B` зеркальный канал с `channelName = A`.
|
|
||||||
3. Сообщения канала — `TEXT_POST` и `TEXT_REPOST` в линии `line_code = rootBlockNumber` канала.
|
|
||||||
4. Запись блока возможна только при валидной подписи blockchain-ключом владельца цепочки.
|
|
||||||
|
|
||||||
## 2. Что должен уметь MCP-инструмент
|
|
||||||
|
|
||||||
Минимальный набор операций:
|
|
||||||
|
|
||||||
1. `read_personal_public_dialog(fromLogin, toLogin, limitPerSide=200)`
|
|
||||||
2. `append_personal_public_message(fromLogin, toLogin, text)`
|
|
||||||
|
|
||||||
## 3. Алгоритм чтения переписки
|
|
||||||
|
|
||||||
### 3.1 Найти оба канала (прямой и зеркальный)
|
|
||||||
|
|
||||||
Для `fromLogin = A`, `toLogin = B`:
|
|
||||||
|
|
||||||
1. Запросить `ListSubscriptionsFeed` для `A` и найти owned-канал:
|
|
||||||
- `ownerLogin == A`
|
|
||||||
- `channelName == B`
|
|
||||||
- `channelTypeCode == 100`
|
|
||||||
2. Запросить `ListSubscriptionsFeed` для `B` и найти owned-канал:
|
|
||||||
- `ownerLogin == B`
|
|
||||||
- `channelName == A`
|
|
||||||
- `channelTypeCode == 100`
|
|
||||||
|
|
||||||
Если какой-то из каналов не найден — вернуть частичный результат + флаг отсутствия зеркала.
|
|
||||||
|
|
||||||
### 3.2 Вычитать сообщения из каналов
|
|
||||||
|
|
||||||
Для каждого найденного канала вызвать `GetChannelMessages`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetChannelMessages",
|
|
||||||
"payload": {
|
|
||||||
"login": "<текущий-login-сессии>",
|
|
||||||
"channel": {
|
|
||||||
"ownerBlockchainName": "...",
|
|
||||||
"channelRootBlockNumber": 123,
|
|
||||||
"channelRootBlockHash": "..."
|
|
||||||
},
|
|
||||||
"limit": 200,
|
|
||||||
"sort": "asc"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.3 Склеить в единый диалог
|
|
||||||
|
|
||||||
1. Объединить массивы сообщений из `A->B` и `B->A`.
|
|
||||||
2. Отсортировать по `createdAtMs`, при равенстве — по `messageRef.blockNumber`.
|
|
||||||
3. Вернуть структуру:
|
|
||||||
- `messages[]`
|
|
||||||
- `directChannelFound` / `reverseChannelFound`
|
|
||||||
- метаданные обоих каналов.
|
|
||||||
|
|
||||||
## 4. Алгоритм дозаписи сообщения
|
|
||||||
|
|
||||||
Цель: добавить сообщение **от имени `fromLogin`** в его канал `fromLogin -> toLogin`.
|
|
||||||
|
|
||||||
### 4.1 Найти канал отправителя
|
|
||||||
|
|
||||||
Через `ListSubscriptionsFeed(fromLogin)` найти owned-канал:
|
|
||||||
- `channelName == toLogin`
|
|
||||||
- `channelTypeCode == 100`
|
|
||||||
|
|
||||||
Если канал не найден — вернуть ошибку `channel_not_found`.
|
|
||||||
|
|
||||||
### 4.2 Отправить `AddBlock` с `TEXT_POST`
|
|
||||||
|
|
||||||
Использовать клиентский/серверный helper формирования `TEXT_POST` body:
|
|
||||||
- `lineCode = channelRootBlockNumber`;
|
|
||||||
- `prevLineNumber/prevLineHash` берутся из последнего сообщения линии;
|
|
||||||
- подпись — blockchain private key пользователя `fromLogin`.
|
|
||||||
|
|
||||||
Если у вас в MCP нет приватного ключа пользователя, дозапись невозможна.
|
|
||||||
|
|
||||||
## 5. Контракт MCP (рекомендуемый)
|
|
||||||
|
|
||||||
## `read_personal_public_dialog`
|
|
||||||
|
|
||||||
Вход:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"fromLogin": "alice",
|
|
||||||
"toLogin": "bob",
|
|
||||||
"limitPerSide": 200
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Выход:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"directChannelFound": true,
|
|
||||||
"reverseChannelFound": true,
|
|
||||||
"messages": [
|
|
||||||
{
|
|
||||||
"authorLogin": "alice",
|
|
||||||
"text": "Привет",
|
|
||||||
"createdAtMs": 1760000000000,
|
|
||||||
"channelSide": "alice->bob",
|
|
||||||
"messageRef": { "blockNumber": 11, "blockHash": "..." }
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## `append_personal_public_message`
|
|
||||||
|
|
||||||
Вход:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"fromLogin": "alice",
|
|
||||||
"toLogin": "bob",
|
|
||||||
"text": "Тест"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Выход:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"serverLastGlobalNumber": 321,
|
|
||||||
"serverLastGlobalHash": "..."
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 6. Ограничения и безопасность
|
|
||||||
|
|
||||||
1. Персональный канал типа `100` сейчас публичный по модели чтения (не E2E DM).
|
|
||||||
2. Нельзя дозаписать блок в чужой блокчейн без приватного ключа владельца (проверка подписи сервером).
|
|
||||||
3. Для прод-инструмента нужно:
|
|
||||||
- строгая авторизация MCP-вызовов;
|
|
||||||
- аудит, кто и от чьего имени запрашивал чтение/запись;
|
|
||||||
- лимиты/квоты на запись.
|
|
||||||
|
|
||||||
## 7. Мини-чеклист для реализации MCP
|
|
||||||
|
|
||||||
1. Реализовать helper поиска канала `findOwnedPersonalChannel(ownerLogin, peerLogin)`.
|
|
||||||
2. Реализовать чтение двух сторон и merge/sort.
|
|
||||||
3. Реализовать отправку `TEXT_POST` в найденный канал отправителя.
|
|
||||||
4. Добавить понятные ошибки:
|
|
||||||
- `user_not_found`
|
|
||||||
- `channel_not_found`
|
|
||||||
- `reverse_channel_not_found`
|
|
||||||
- `signature_required`
|
|
||||||
- `add_block_failed`
|
|
||||||
@ -1,69 +0,0 @@
|
|||||||
# API для разработчиков: индекс операций
|
|
||||||
|
|
||||||
Этот файл фиксирует полный список публичных JSON/WebSocket операций, зарегистрированных в коде сервера.
|
|
||||||
|
|
||||||
Источник истины на момент актуализации:
|
|
||||||
|
|
||||||
- `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
|
|
||||||
|
|
||||||
Если операция есть в `HANDLERS` и `REQUEST_TYPES`, клиент может отправлять её как `op` в общем JSON-конверте из `00_Common_API_Format.md`.
|
|
||||||
|
|
||||||
## Актуальные операции
|
|
||||||
|
|
||||||
| Операция | Раздел документации | Кратко |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `AddUser` | `01_User_Registration_API.md` | отключено (`410 / ADD_USER_DISABLED`) |
|
|
||||||
| `GetUser` | `01_User_Registration_API.md` | чтение/проверка пользователя + server-состояние его блокчейна |
|
|
||||||
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов по префиксу |
|
|
||||||
| `TestGetFreeAvatarQuota` | `14_Test_Free_Avatar_Upload_API.md` | временный тестовый просмотр остатка бесплатных загрузок аватара |
|
|
||||||
| `TestUploadFreeAvatar` | `14_Test_Free_Avatar_Upload_API.md` | временная тестовая бесплатная загрузка маленького аватара в Arweave |
|
|
||||||
| `AuthChallenge` | `02_Authentication_API.md` | challenge для создания новой сессии |
|
|
||||||
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
|
|
||||||
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
|
|
||||||
| `SessionLogin` | `02_Authentication_API.md` | вход в существующую сессию |
|
|
||||||
| `GetTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | чтение текущего режима входа через доверенное устройство |
|
|
||||||
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
|
|
||||||
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
|
|
||||||
| `ListTrustedDeviceLoginRequests` | `03_Session_Management_API.md` | список активных pairing-заявок для доверенной сессии |
|
|
||||||
| `ApproveTrustedDeviceLogin` | `03_Session_Management_API.md` | подтверждение pairing-заявки доверенной сессией |
|
|
||||||
| `RejectTrustedDeviceLogin` | `03_Session_Management_API.md` | отклонение pairing-заявки доверенной сессией |
|
|
||||||
| `CancelTrustedDeviceLogin` | `03_Session_Management_API.md` | отмена pairing-заявки со стороны нового ожидающего устройства |
|
|
||||||
| `GetTrustedDeviceLoginStatus` | `03_Session_Management_API.md` | чтение статуса и результата pairing-заявки |
|
|
||||||
| `ListSessions` | `03_Session_Management_API.md` | список активных сессий |
|
|
||||||
| `CloseActiveSession` | `03_Session_Management_API.md` | закрытие активной сессии |
|
|
||||||
| `AddBlock` | `04_Add_Block_to_Blockchain_API.md` | добавление блока в блокчейн |
|
|
||||||
| `Ping` | `05_Technical_Requests_API.md` | keep-alive |
|
|
||||||
| `GetServerInfo` | `05_Technical_Requests_API.md` | публичная информация о сервере |
|
|
||||||
| `GetCallIceConfig` | `05_Technical_Requests_API.md` | STUN/TURN конфигурация звонков |
|
|
||||||
| `ClientErrorLog` | `05_Technical_Requests_API.md` | логирование клиентской ошибки |
|
|
||||||
| `ClientDebugLog` | `05_Technical_Requests_API.md` | клиентский debug-лог |
|
|
||||||
| `CallDeliveryReport` | `05_Technical_Requests_API.md` | диагностика доставки/установки звонков |
|
|
||||||
| `ListSubscriptionsFeed` | `06_Channels_Read_API.md` | лента каналов/подписок |
|
|
||||||
| `GetChannelMessages` | `06_Channels_Read_API.md` | сообщения канала |
|
|
||||||
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
|
|
||||||
| `GetChannelsCounters` | `06_Channels_Read_API.md` | счетчики разделов каналов |
|
|
||||||
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
|
|
||||||
| `GetGroupDialog` | `06_Channels_Read_API.md` | сообщения группового чата типа `200` |
|
|
||||||
| `UpsertUserParam` | `10_User_Params_API.md` | запись параметра пользователя |
|
|
||||||
| `GetUserParam` | `10_User_Params_API.md` | чтение одного параметра пользователя |
|
|
||||||
| `ListUserParams` | `10_User_Params_API.md` | список параметров пользователя |
|
|
||||||
| `GetFriendsLists` | `11_Connections_API.md` | входящие/исходящие друзья |
|
|
||||||
| `ListContacts` | `11_Connections_API.md` | контакты текущего пользователя |
|
|
||||||
| `GetUserConnectionsGraph` | `11_Connections_API.md` | граф связей пользователя |
|
|
||||||
| `AddCloseFriend` | `11_Connections_API.md` | добавить близкого друга |
|
|
||||||
| `UpsertPushToken` | `12_Direct_Messages_Push_Calls_API.md` | регистрация WebPush-токена |
|
|
||||||
| `SendTestWebPush` | `12_Direct_Messages_Push_Calls_API.md` | тестовая push-доставка |
|
|
||||||
| `SendDirectMessage` | `12_Direct_Messages_Push_Calls_API.md` | отправка подписанного DM-пакета |
|
|
||||||
| `SendMessagePair` | `12_Direct_Messages_Push_Calls_API.md` | отправка пары входящий/исходящий DM |
|
|
||||||
| `ReceiveOutcomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | алиас `SendMessagePair` |
|
|
||||||
| `ReceiveIncomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | прием входящего DM-блока |
|
|
||||||
| `AckSessionDelivery` | `12_Direct_Messages_Push_Calls_API.md` | подтверждение доставки в сессию |
|
|
||||||
| `CallInviteBroadcast` | `12_Direct_Messages_Push_Calls_API.md` | broadcast приглашения к звонку |
|
|
||||||
| `CallSignalToSession` | `12_Direct_Messages_Push_Calls_API.md` | сигнал звонка в конкретную сессию |
|
|
||||||
|
|
||||||
## Важные замечания
|
|
||||||
|
|
||||||
- `ReceiveOutcomingMessage` сейчас зарегистрирован как алиас того же handler/request-класса, что и `SendMessagePair`.
|
|
||||||
- Отдельных HTTP endpoints для DM-файлов сейчас нет.
|
|
||||||
- Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
|
|
||||||
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
|
|
||||||
@ -1,129 +0,0 @@
|
|||||||
# API для разработчиков: параметры пользователя
|
|
||||||
|
|
||||||
Документ описывает операции для записи и чтения пользовательских параметров.
|
|
||||||
|
|
||||||
Текущие операции:
|
|
||||||
|
|
||||||
- `UpsertUserParam`
|
|
||||||
- `GetUserParam`
|
|
||||||
- `ListUserParams`
|
|
||||||
|
|
||||||
## 1. `UpsertUserParam`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertUserParam",
|
|
||||||
"requestId": "param-upsert-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"param": "display_name",
|
|
||||||
"time_ms": 1774700000123,
|
|
||||||
"value": "Alice",
|
|
||||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
|
||||||
"signature": "BASE64_SIGNATURE"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertUserParam",
|
|
||||||
"requestId": "param-upsert-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Типовые ошибки
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — некорректные обязательные поля.
|
|
||||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
|
||||||
- `501 / DB_ERROR` — ошибка БД.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. `GetUserParam`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUserParam",
|
|
||||||
"requestId": "param-get-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"param": "display_name"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUserParam",
|
|
||||||
"requestId": "param-get-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"param": "display_name",
|
|
||||||
"time_ms": 1774700000123,
|
|
||||||
"value": "Alice",
|
|
||||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
|
||||||
"signature": "BASE64_SIGNATURE"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если параметр не найден, сервер возвращает `404` с пустым `payload`; отдельный прикладной код ошибки текущий handler не задаёт.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. `ListUserParams`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListUserParams",
|
|
||||||
"requestId": "param-list-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListUserParams",
|
|
||||||
"requestId": "param-list-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"params": [
|
|
||||||
{
|
|
||||||
"login": "alice",
|
|
||||||
"param": "display_name",
|
|
||||||
"time_ms": 1774700000123,
|
|
||||||
"value": "Alice",
|
|
||||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
|
||||||
"signature": "BASE64_SIGNATURE"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Примечание
|
|
||||||
|
|
||||||
Имена JSON-полей `time_ms` и `client_key` сейчас соответствуют Java-модели ответа/запроса и должны передаваться именно в таком виде.
|
|
||||||
@ -1,174 +0,0 @@
|
|||||||
# API для разработчиков: связи пользователей
|
|
||||||
|
|
||||||
Документ описывает операции чтения и записи пользовательских связей.
|
|
||||||
|
|
||||||
Текущие операции:
|
|
||||||
|
|
||||||
- `GetFriendsLists`
|
|
||||||
- `ListContacts`
|
|
||||||
- `GetUserConnectionsGraph`
|
|
||||||
- `AddCloseFriend`
|
|
||||||
|
|
||||||
## 1. `GetFriendsLists`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetFriendsLists",
|
|
||||||
"requestId": "friends-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetFriendsLists",
|
|
||||||
"requestId": "friends-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"out_friends": ["Bob"],
|
|
||||||
"in_friends": ["Kate"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. `ListContacts`
|
|
||||||
|
|
||||||
`ListContacts` использует текущую авторизованную сессию. В payload нет дополнительных полей.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListContacts",
|
|
||||||
"requestId": "contacts-001",
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ListContacts",
|
|
||||||
"requestId": "contacts-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"contacts": ["Bob", "Kate"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. `GetUserConnectionsGraph`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUserConnectionsGraph",
|
|
||||||
"requestId": "graph-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "GetUserConnectionsGraph",
|
|
||||||
"requestId": "graph-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"outFriends": ["Bob"],
|
|
||||||
"inFriends": ["Kate"],
|
|
||||||
"outContacts": [],
|
|
||||||
"inContacts": [],
|
|
||||||
"outFollows": [],
|
|
||||||
"inFollows": [],
|
|
||||||
"outSpouses": [],
|
|
||||||
"inSpouses": [],
|
|
||||||
"outParents": [],
|
|
||||||
"inParents": [],
|
|
||||||
"outChildren": [],
|
|
||||||
"inChildren": [],
|
|
||||||
"outSiblings": [],
|
|
||||||
"inSiblings": [],
|
|
||||||
"outKnownPersons": [],
|
|
||||||
"inKnownPersons": [],
|
|
||||||
"outShineConfirmed": [],
|
|
||||||
"inShineConfirmed": [],
|
|
||||||
"outShineSeen": [],
|
|
||||||
"inShineSeen": [],
|
|
||||||
"parents": [],
|
|
||||||
"children": [],
|
|
||||||
"siblings": [],
|
|
||||||
"spouses": [],
|
|
||||||
"allUsers": [
|
|
||||||
{
|
|
||||||
"login": "Bob",
|
|
||||||
"official": false,
|
|
||||||
"shine": true,
|
|
||||||
"officialLabel": "",
|
|
||||||
"shineLabel": "shine",
|
|
||||||
"avatar": { "ar": "..." }
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Примечание
|
|
||||||
|
|
||||||
Поля `known_person`, `shine_confirmed`, `shine_seen` в UI считаются недопроверенной зоной проекта; при изменениях этой логики нужна ручная end-to-end проверка.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. `AddCloseFriend`
|
|
||||||
|
|
||||||
`AddCloseFriend` использует текущую авторизованную сессию как источник `login`.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AddCloseFriend",
|
|
||||||
"requestId": "close-friend-001",
|
|
||||||
"payload": {
|
|
||||||
"toLogin": "bob"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AddCloseFriend",
|
|
||||||
"requestId": "close-friend-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"login": "Alice",
|
|
||||||
"toLogin": "Bob",
|
|
||||||
"relation": "close_friend"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@ -1,190 +0,0 @@
|
|||||||
# API для разработчиков: DM, push и сигналы звонков
|
|
||||||
|
|
||||||
Документ описывает публичные операции, связанные с личными сообщениями, WebPush и сигналами звонков.
|
|
||||||
|
|
||||||
Подробная логика DM и бинарного формата:
|
|
||||||
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md`
|
|
||||||
|
|
||||||
## 1. `UpsertPushToken`
|
|
||||||
|
|
||||||
Требует авторизации.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertPushToken",
|
|
||||||
"requestId": "push-upsert-001",
|
|
||||||
"payload": {
|
|
||||||
"sessionId": "SESSION_ID",
|
|
||||||
"endpoint": "https://push.example/...",
|
|
||||||
"p256dhKey": "BASE64",
|
|
||||||
"authKey": "BASE64",
|
|
||||||
"platform": "web",
|
|
||||||
"userAgent": "Mozilla/5.0 ..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "UpsertPushToken",
|
|
||||||
"requestId": "push-upsert-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"tokenId": "token-1",
|
|
||||||
"updatedAtMs": 1774700000123
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 2. `SendTestWebPush`
|
|
||||||
|
|
||||||
Требует авторизации.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SendTestWebPush",
|
|
||||||
"requestId": "push-test-001",
|
|
||||||
"payload": {
|
|
||||||
"login": "alice",
|
|
||||||
"sessionId": "SESSION_ID",
|
|
||||||
"title": "Test",
|
|
||||||
"text": "Push body"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3. `SendMessagePair` и `ReceiveOutcomingMessage`
|
|
||||||
|
|
||||||
`ReceiveOutcomingMessage` — алиас `SendMessagePair`.
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Передаёт пару signed DM-блоков:
|
|
||||||
|
|
||||||
- `incomingBlobB64` — блок `type=1` или `type=3`
|
|
||||||
- `outgoingBlobB64` — блок `type=2` или `type=4`
|
|
||||||
|
|
||||||
Для контентных сообщений `type=1/2` внутри base64 лежит бинарный формат `SHiNE_DM`.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SendMessagePair",
|
|
||||||
"requestId": "dm-pair-001",
|
|
||||||
"payload": {
|
|
||||||
"incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK",
|
|
||||||
"outgoingBlobB64": "BASE64_OUTGOING_SIGNED_BLOCK"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "SendMessagePair",
|
|
||||||
"requestId": "dm-pair-001",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"baseKey": "from|to|time|nonce",
|
|
||||||
"incomingKey": "from|to|time|nonce|1",
|
|
||||||
"outgoingKey": "from|to|time|nonce|2",
|
|
||||||
"deliveredWsSessions": 1,
|
|
||||||
"deliveredWebPushSessions": 0
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / BAD_FIELDS` — пустой `incomingBlobB64` или `outgoingBlobB64`
|
|
||||||
- `400 / BAD_BLOCK_FORMAT` — base64 или бинарный контейнер повреждён
|
|
||||||
- `400 / BAD_CONTENT_FORMAT` — для контентного сообщения пришёл не `SHiNE_DM`
|
|
||||||
- `400 / ATTACHMENTS_DISABLED` — в `SHiNE_DM` пришёл `attachmentsCount != 0`
|
|
||||||
- `404 / USER_NOT_FOUND` — один из логинов не найден
|
|
||||||
- `460 / BAD_SIGNATURE` — подпись блока не прошла проверку
|
|
||||||
|
|
||||||
## 4. `ReceiveIncomingMessage`
|
|
||||||
|
|
||||||
Принимает только один входящий signed DM-блок.
|
|
||||||
|
|
||||||
### Назначение
|
|
||||||
|
|
||||||
Используется там, где нужно принять только incoming-вариант сообщения.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "ReceiveIncomingMessage",
|
|
||||||
"requestId": "dm-in-001",
|
|
||||||
"payload": {
|
|
||||||
"incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 5. `AckSessionDelivery`
|
|
||||||
|
|
||||||
Требует авторизации. Подтверждает доставку в текущую сессию.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "AckSessionDelivery",
|
|
||||||
"requestId": "ack-001",
|
|
||||||
"payload": {
|
|
||||||
"messageKey": "from|to|time|nonce|1"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 6. Событие `SignedMessageArrived`
|
|
||||||
|
|
||||||
Сервер присылает его по WebSocket в активные сессии адресата.
|
|
||||||
|
|
||||||
### Payload события
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"messageKey": "from|to|time|nonce|1",
|
|
||||||
"baseKey": "from|to|time|nonce",
|
|
||||||
"fromLogin": "alice",
|
|
||||||
"toLogin": "bob",
|
|
||||||
"targetLogin": "bob",
|
|
||||||
"messageType": 1,
|
|
||||||
"timeMs": 1774700000123,
|
|
||||||
"nonce": 123456789,
|
|
||||||
"blobB64": "BASE64_SIGNED_BLOCK",
|
|
||||||
"backlog": false
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если это новая ревизия того же письма, `messageKey` остаётся тем же, а `revisionTimeMs` меняется внутри бинарного блока.
|
|
||||||
|
|
||||||
## 7. `CallInviteBroadcast`
|
|
||||||
|
|
||||||
Требует авторизации. Шлёт приглашение к звонку в активные сессии `toLogin`.
|
|
||||||
|
|
||||||
## 8. `CallSignalToSession`
|
|
||||||
|
|
||||||
Требует авторизации. Шлёт сигнал звонка в конкретную сессию.
|
|
||||||
|
|
||||||
## 9. Замечания
|
|
||||||
|
|
||||||
- read-receipt `type=3/4` пока остаются в legacy-формате `SHiNE_dm2`
|
|
||||||
- контентные DM `type=1/2` используют `SHiNE_DM`
|
|
||||||
- сервер хранит только последнюю версию контентного сообщения по `messageKey`
|
|
||||||
- удаление сообщения реализуется новой ревизией с пустым телом и `attachmentsCount = 0`
|
|
||||||
- HTTP endpoints для DM-файлов сейчас отсутствуют
|
|
||||||
@ -1,190 +0,0 @@
|
|||||||
# API для разработчиков: HTTP debug endpoints
|
|
||||||
|
|
||||||
Этот файл описывает отдельный HTTP debug API сервера. Он не использует WebSocket-конверт `op/requestId/payload` и включается только настройкой:
|
|
||||||
|
|
||||||
- `debug.tempApi.enabled=true`
|
|
||||||
|
|
||||||
Источник истины:
|
|
||||||
|
|
||||||
- `src/main/java/server/debug/DebugApiConfigurator.java`
|
|
||||||
- `src/main/java/server/debug/*Servlet.java`
|
|
||||||
|
|
||||||
Если `.debug-token` отсутствует или пуст, endpoints возвращают `503 / DEBUG_DISABLED`.
|
|
||||||
|
|
||||||
## Авторизация
|
|
||||||
|
|
||||||
Для большинства debug endpoints используется Bearer token из `.debug-token`:
|
|
||||||
|
|
||||||
```http
|
|
||||||
Authorization: Bearer <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
Для `POST /debug/ws/ui-reload-all` поддерживается заголовок:
|
|
||||||
|
|
||||||
```http
|
|
||||||
X-Debug-Token: <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
При неверном токене сервер возвращает `401 / UNAUTHORIZED`.
|
|
||||||
|
|
||||||
## Формат успешного HTTP-ответа
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Формат HTTP-ошибки
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": false,
|
|
||||||
"code": "BAD_JSON",
|
|
||||||
"message": "Тело запроса должно быть JSON"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 1. `GET /debug/ws/clients`
|
|
||||||
|
|
||||||
Возвращает список активных WebSocket-клиентов.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"count": 1,
|
|
||||||
"clients": [
|
|
||||||
{
|
|
||||||
"sessionId": "SESSION_ID",
|
|
||||||
"login": "alice",
|
|
||||||
"authStatus": 2,
|
|
||||||
"wsOpen": true,
|
|
||||||
"remoteAddress": "127.0.0.1",
|
|
||||||
"ip": "127.0.0.1",
|
|
||||||
"userAgent": "Mozilla/5.0 ...",
|
|
||||||
"clientInfoFromClient": "...",
|
|
||||||
"clientInfoFromRequest": "...",
|
|
||||||
"userLanguage": "ru",
|
|
||||||
"sessionCreatedAtMs": 1774700000123
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 2. `POST /debug/ws/connect`
|
|
||||||
|
|
||||||
Запускает debug-сценарий соединения двух активных WS-сессий и отправляет им события:
|
|
||||||
|
|
||||||
- `DebugConnectPrepareResponder`
|
|
||||||
- `DebugConnectStartInitiator`
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"initiatorSessionId": "SESSION_ID_1",
|
|
||||||
"responderSessionId": "SESSION_ID_2",
|
|
||||||
"clearDebugLog": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"runId": "dbg-...",
|
|
||||||
"callId": "debug-call-...",
|
|
||||||
"accepted": true,
|
|
||||||
"initiatorSessionId": "SESSION_ID_1",
|
|
||||||
"responderSessionId": "SESSION_ID_2",
|
|
||||||
"initiatorLogin": "alice",
|
|
||||||
"responderLogin": "bob",
|
|
||||||
"mode": "cross-login"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / BAD_JSON` — тело запроса не JSON.
|
|
||||||
- `400 / BAD_FIELDS` — не заполнены sessionId или переданы одинаковые sessionId.
|
|
||||||
- `404 / INITIATOR_NOT_FOUND` — сессия инициатора не найдена или неактивна.
|
|
||||||
- `404 / RESPONDER_NOT_FOUND` — сессия получателя не найдена или неактивна.
|
|
||||||
|
|
||||||
## 3. `GET /debug/ws/logs`
|
|
||||||
|
|
||||||
Возвращает tail debug-логов из `DebugRunLogBuffer`.
|
|
||||||
|
|
||||||
### Query-параметры
|
|
||||||
|
|
||||||
- `limit` — количество записей.
|
|
||||||
- `runId` — фильтр по runId.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"count": 1,
|
|
||||||
"limit": 100,
|
|
||||||
"runIdFilter": "ui-run-1",
|
|
||||||
"logs": [
|
|
||||||
{
|
|
||||||
"ts": 1774700000123,
|
|
||||||
"level": "info",
|
|
||||||
"runId": "ui-run-1",
|
|
||||||
"source": "debug-connect",
|
|
||||||
"sessionId": "SESSION_ID",
|
|
||||||
"login": "alice",
|
|
||||||
"message": "opened channels tab",
|
|
||||||
"details": "{}"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 4. `POST /debug/ws/ui-reload-all`
|
|
||||||
|
|
||||||
Рассылает активным UI-сессиям debug-событие на reload.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"reason": "manual_debug_api",
|
|
||||||
"reloadAfterMs": 700
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Если `reason` не передан или пустой, сервер использует `manual_debug_api`. `reloadAfterMs` ограничивается диапазоном `100..15000`.
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"accepted": true,
|
|
||||||
"reason": "manual_debug_api",
|
|
||||||
"reloadAfterMs": 700,
|
|
||||||
"issuedAtMs": 1774700000123,
|
|
||||||
"totalConnections": 2,
|
|
||||||
"sentCount": 2,
|
|
||||||
"skippedCount": 0
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `400 / BAD_JSON` — тело запроса не JSON.
|
|
||||||
@ -1,176 +0,0 @@
|
|||||||
# Временное Test API для бесплатной загрузки аватаров в Arweave
|
|
||||||
|
|
||||||
> Статус: **временное тестовое решение**.
|
|
||||||
> Все операции из этого файла начинаются с `Test...`, чтобы это было видно сразу и в коде, и в UI.
|
|
||||||
|
|
||||||
## Назначение
|
|
||||||
|
|
||||||
Этот временный API даёт пользователю ограниченную бесплатную загрузку маленьких аватаров в Arweave:
|
|
||||||
|
|
||||||
- загрузка идёт через **серверный Arweave-кошелёк**;
|
|
||||||
- лимит на пользователя: по умолчанию `3` загрузки за всё время;
|
|
||||||
- лимит хранится в SQLite-таблице `test_free_avatar_uploads`;
|
|
||||||
- если лимит исчерпан, сервер возвращает понятную ошибку;
|
|
||||||
- загружать можно только маленький итоговый файл аватара, по умолчанию до `128 KB`.
|
|
||||||
|
|
||||||
## Настройки сервера
|
|
||||||
|
|
||||||
В `application.properties`:
|
|
||||||
|
|
||||||
```properties
|
|
||||||
test.freeAvatar.enabled=true
|
|
||||||
test.freeAvatar.gateway=https://arweave.net
|
|
||||||
test.freeAvatar.limitPerUser=3
|
|
||||||
test.freeAvatar.maxBytes=131072
|
|
||||||
test.freeAvatar.walletAddress=
|
|
||||||
test.freeAvatar.walletJwkPath=
|
|
||||||
```
|
|
||||||
|
|
||||||
Пояснения:
|
|
||||||
|
|
||||||
- `test.freeAvatar.enabled` - включить или выключить временный API;
|
|
||||||
- `test.freeAvatar.gateway` - Arweave gateway для `price/tx/wallet`;
|
|
||||||
- `test.freeAvatar.limitPerUser` - пожизненный бесплатный лимит на пользователя;
|
|
||||||
- `test.freeAvatar.maxBytes` - максимальный размер итогового файла;
|
|
||||||
- `test.freeAvatar.walletAddress` - публичный адрес серверного Arweave-кошелька;
|
|
||||||
- `test.freeAvatar.walletJwkPath` - путь к приватному JWK-файлу серверного кошелька.
|
|
||||||
|
|
||||||
Важно:
|
|
||||||
|
|
||||||
- приватный JWK хранится вне кода;
|
|
||||||
- если `walletAddress` указан и не совпадает с адресом, вычисленным из JWK, сервер вернёт ошибку настройки.
|
|
||||||
|
|
||||||
## `TestGetFreeAvatarQuota`
|
|
||||||
|
|
||||||
Возвращает остаток бесплатных загрузок для текущего авторизованного пользователя.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "TestGetFreeAvatarQuota",
|
|
||||||
"requestId": "req-test-avatar-quota-1",
|
|
||||||
"payload": {}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "TestGetFreeAvatarQuota",
|
|
||||||
"requestId": "req-test-avatar-quota-1",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"enabled": true,
|
|
||||||
"limit": 3,
|
|
||||||
"usedCount": 1,
|
|
||||||
"remainingCount": 2,
|
|
||||||
"maxBytes": 131072
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Поля ответа
|
|
||||||
|
|
||||||
- `enabled` - временный API сейчас включён на сервере или нет;
|
|
||||||
- `limit` - полный лимит бесплатных загрузок;
|
|
||||||
- `usedCount` - сколько уже израсходовано;
|
|
||||||
- `remainingCount` - сколько ещё осталось;
|
|
||||||
- `maxBytes` - максимальный размер итогового файла.
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `422 NOT_AUTHENTICATED` - требуется авторизация.
|
|
||||||
|
|
||||||
## `TestUploadFreeAvatar`
|
|
||||||
|
|
||||||
Временная бесплатная загрузка маленькой аватарки в Arweave через серверный кошелёк.
|
|
||||||
|
|
||||||
### Правила
|
|
||||||
|
|
||||||
- операция требует авторизованную сессию;
|
|
||||||
- сервер использует текущий login из сессии;
|
|
||||||
- сервер принимает только:
|
|
||||||
- `image/jpeg`
|
|
||||||
- `image/png`
|
|
||||||
- `image/webp`
|
|
||||||
- размер итогового файла должен быть не больше `maxBytes` из квоты;
|
|
||||||
- если пользователь уже сделал `limit` бесплатных загрузок, операция запрещена.
|
|
||||||
|
|
||||||
### Запрос
|
|
||||||
|
|
||||||
`fileBytesBase64` - это обычный Base64 байт итогового подготовленного файла.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "TestUploadFreeAvatar",
|
|
||||||
"requestId": "req-test-avatar-upload-1",
|
|
||||||
"payload": {
|
|
||||||
"contentType": "image/webp",
|
|
||||||
"fileBytesBase64": "UklGRiQAAABXRUJQVlA4WAoAAAAQAAAA...",
|
|
||||||
"sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Успешный ответ
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"op": "TestUploadFreeAvatar",
|
|
||||||
"requestId": "req-test-avatar-upload-1",
|
|
||||||
"status": 200,
|
|
||||||
"ok": true,
|
|
||||||
"payload": {
|
|
||||||
"txId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
|
|
||||||
"sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
|
||||||
"usedCount": 2,
|
|
||||||
"remainingCount": 1,
|
|
||||||
"limit": 3,
|
|
||||||
"gateway": "https://arweave.net"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Поля ответа
|
|
||||||
|
|
||||||
- `txId` - Arweave Transaction ID загруженного файла;
|
|
||||||
- `sha256Hex` - SHA-256 загруженного файла;
|
|
||||||
- `usedCount` - сколько бесплатных загрузок уже израсходовано после этой операции;
|
|
||||||
- `remainingCount` - сколько бесплатных загрузок осталось;
|
|
||||||
- `limit` - общий лимит;
|
|
||||||
- `gateway` - gateway, через который сервер отправлял транзакцию.
|
|
||||||
|
|
||||||
### Ошибки
|
|
||||||
|
|
||||||
- `422 NOT_AUTHENTICATED` - требуется авторизация;
|
|
||||||
- `400 BAD_FIELDS` - не переданы `contentType` или `fileBytesBase64`;
|
|
||||||
- `400 BAD_BASE64` - `fileBytesBase64` не декодируется;
|
|
||||||
- `400 BAD_AVATAR_FILE` - файл не проходит ограничения сервера;
|
|
||||||
- `400 FREE_AVATAR_LIMIT_EXHAUSTED` - бесплатный лимит аватарок исчерпан;
|
|
||||||
- `501 FREE_AVATAR_TEMP_DISABLED` - временная функция выключена или сервер не настроен;
|
|
||||||
- `500 INTERNAL_ERROR` - внутренняя ошибка сервера.
|
|
||||||
|
|
||||||
## Как это используется в UI
|
|
||||||
|
|
||||||
На экране редактирования профиля в мастере смены аватара есть временный сценарий:
|
|
||||||
|
|
||||||
- `Залить аватар бесплатно`
|
|
||||||
|
|
||||||
UI:
|
|
||||||
|
|
||||||
1. вызывает `TestGetFreeAvatarQuota`;
|
|
||||||
2. показывает остаток лимита;
|
|
||||||
3. локально подготавливает уменьшенный файл аватара;
|
|
||||||
4. проверяет, что итоговый файл не превышает `maxBytes`;
|
|
||||||
5. вызывает `TestUploadFreeAvatar`;
|
|
||||||
6. после получения `txId` обычным путём записывает `avatar.ar` в профиль через `AddBlock`.
|
|
||||||
|
|
||||||
## Почему решение временное
|
|
||||||
|
|
||||||
- используется общий серверный Arweave-кошелёк;
|
|
||||||
- лимит хранится отдельной технической таблицей;
|
|
||||||
- операции имеют префикс `Test...`;
|
|
||||||
- сценарий нужен как переходный бесплатный путь для маленьких аватаров.
|
|
||||||
@ -1,25 +0,0 @@
|
|||||||
# Форматы блокчейнов и блоков (индекс раздела)
|
|
||||||
|
|
||||||
Этот раздел разбит на несколько файлов, чтобы формат добавляемых блоков было проще читать и сопровождать.
|
|
||||||
|
|
||||||
## Структура раздела
|
|
||||||
|
|
||||||
- `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/REPOST.
|
|
||||||
- `type=2` — REACTION: LIKE/UNLIKE.
|
|
||||||
- `type=3` — CONNECTION: FRIEND/CONTACT/FOLLOW/SPOUSE/PARENT/CHILD/SIBLING и обратные операции.
|
|
||||||
- `type=4` — USER_PARAM: key/value-параметры пользователя.
|
|
||||||
|
|
||||||
## Примечание
|
|
||||||
|
|
||||||
Если нужно добавить новый тип или подтип блока, сначала обновляйте профильный файл этого раздела, затем API-документацию в `Dev_Docs/API`.
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
# Типы каналов и CreateChannel
|
|
||||||
|
|
||||||
## 1. Формат `CreateChannelBody` (`msg_type=0`, `subType=1`, `version=1`)
|
|
||||||
Payload включает:
|
|
||||||
|
|
||||||
1. line-поля канала (`lineCode`, `prevLineNumber`, `prevLineHash32`, `thisLineNumber`);
|
|
||||||
2. `channelName`;
|
|
||||||
3. `channelDescription`;
|
|
||||||
4. `channelType` (`uint16`, 2 байта);
|
|
||||||
5. `channelTypeVersion` (`uint16`, 2 байта).
|
|
||||||
|
|
||||||
## 2. Типы каналов
|
|
||||||
- `0` — `stories` (root-канал пользователя).
|
|
||||||
- `1` — публичный канал.
|
|
||||||
- `100` — персональный канал.
|
|
||||||
- `200` — групповой/чатовый канал.
|
|
||||||
|
|
||||||
Версия типа (`channelTypeVersion`) сейчас используется со значением `1`.
|
|
||||||
|
|
||||||
Важно для MVP:
|
|
||||||
- `100` и `200` в формате поддерживаются, но в текущем UI не используются.
|
|
||||||
- В MVP рабочий UI-флоу — каналы `0` и `1`.
|
|
||||||
|
|
||||||
## 3. Имя root-канала
|
|
||||||
- Root-канал (`line_code = 0`) в API/чтении отображается как `stories`.
|
|
||||||
- Публикации в `stories` разрешены владельцу собственного блокчейна.
|
|
||||||
|
|
||||||
## 4. Уникальность имени канала
|
|
||||||
Проверка уникальности выполняется на сервере по ключу:
|
|
||||||
|
|
||||||
`owner_bch_name + channel_type_code + slug(channel_name)`
|
|
||||||
|
|
||||||
Это означает:
|
|
||||||
- одно и то же имя допустимо у одного владельца для разных типов (`1`, `100`, `200`);
|
|
||||||
- в рамках одного типа и одного владельца имя уникально.
|
|
||||||
|
|
||||||
## 5. Персональные каналы (`type=100`)
|
|
||||||
- Сервер не проверяет бизнес-валидность собеседника по имени канала.
|
|
||||||
- Проверка существования login для персонального канала выполняется на UI при создании.
|
|
||||||
- При чтении сервер пытается собрать парный поток `A->B` + `B->A` (если обратный канал существует).
|
|
||||||
@ -1,49 +0,0 @@
|
|||||||
# Общий формат добавляемого блока (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`, не ломая каркас блока.
|
|
||||||
@ -1,47 +0,0 @@
|
|||||||
# Виды блокчейнов и логических линий
|
|
||||||
|
|
||||||
## 1. Именованный блокчейн
|
|
||||||
|
|
||||||
Базовый идентификатор цепочки пользователя:
|
|
||||||
|
|
||||||
- `blockchainName = <login>-<NNN>`
|
|
||||||
- пример: `alice-001`
|
|
||||||
|
|
||||||
Обычно это одна основная цепочка пользователя.
|
|
||||||
|
|
||||||
## 2. Логические линии внутри одной цепочки
|
|
||||||
|
|
||||||
Физически цепочка одна, но внутри есть независимые логические последовательности (линии), которые ведутся через поля:
|
|
||||||
|
|
||||||
- `lineCode`
|
|
||||||
- `prevLineNumber`
|
|
||||||
- `prevLineHash32`
|
|
||||||
- `thisLineNumber`
|
|
||||||
|
|
||||||
Линии используются для:
|
|
||||||
- TECH-событий;
|
|
||||||
- каналов с текстовыми постами;
|
|
||||||
- связей и подписок;
|
|
||||||
- пользовательских параметров.
|
|
||||||
|
|
||||||
## 3. Правила line-полей (фактическая серверная валидация)
|
|
||||||
|
|
||||||
Line-поля: `lineCode`, `prevLineNumber`, `prevLineHash32`, `thisLineNumber`.
|
|
||||||
|
|
||||||
- Line-поля разрешены только для `msg_type`: `0`, `1`, `3`, `4`.
|
|
||||||
- Если передано хотя бы одно line-поле, должны быть переданы все 4.
|
|
||||||
- `prevLineNumber/prevLineHash32` должны указывать на существующий блок этой же цепочки.
|
|
||||||
- Для первого шага после root (`prevLineNumber == lineCode`):
|
|
||||||
- `TEXT (msg_type=1)`: `thisLineNumber = 0`;
|
|
||||||
- `TECH/CONNECTION/USER_PARAM (0/3/4)`: `thisLineNumber = 1`.
|
|
||||||
- Для обычного шага:
|
|
||||||
- `TEXT`: `thisLineNumber` допускает `same` или `+1` от предыдущего блока линии;
|
|
||||||
- `TECH/CONNECTION/USER_PARAM`: строго `+1`.
|
|
||||||
|
|
||||||
## 4. Root-идея для каналов и подписок
|
|
||||||
|
|
||||||
Для ссылок вида follow/friend/contact принято ссылаться на корневые блоки:
|
|
||||||
- `HEADER` для базовой сущности пользователя/канала `0`;
|
|
||||||
- `CREATE_CHANNEL` для пользовательских каналов.
|
|
||||||
|
|
||||||
Так ссылки остаются стабильными, даже когда в канале появляются новые сообщения.
|
|
||||||
@ -1,33 +0,0 @@
|
|||||||
# Командные сообщения каналов
|
|
||||||
|
|
||||||
## 1. Общий префикс
|
|
||||||
Командные сообщения распознаются по префиксу:
|
|
||||||
|
|
||||||
`/.`
|
|
||||||
|
|
||||||
Пример:
|
|
||||||
- `/.desc Новый комментарий канала`
|
|
||||||
|
|
||||||
## 2. Поддерживаемые команды
|
|
||||||
|
|
||||||
### Для всех типов каналов (`0`, `1`, `100`, `200`)
|
|
||||||
- `/.desc <text>` — смена описания канала.
|
|
||||||
|
|
||||||
Примечание:
|
|
||||||
- Описание канала в чтении определяется последней командой `/.desc` в линии канала.
|
|
||||||
- Если `/.desc` не было, используется описание из `CreateChannel`.
|
|
||||||
|
|
||||||
### Дополнительно для `type=200`
|
|
||||||
- `/.add <login> <channelName>`
|
|
||||||
- `/.remove <login> <channelName>`
|
|
||||||
|
|
||||||
Формат аргументов фиксирован: через пробел.
|
|
||||||
|
|
||||||
## 3. Текущая модель применения
|
|
||||||
- Команды передаются как обычные `TEXT_POST` сообщения.
|
|
||||||
- Сервер уже применяет `/.desc` при вычислении актуального описания канала.
|
|
||||||
- Команды `/.add` и `/.remove` зарезервированы под расширенную модель участников `type=200` на уровне UI/агрегации.
|
|
||||||
|
|
||||||
## 4. Статус для MVP
|
|
||||||
- В текущем UI каналы `type=100` и `type=200` не используются.
|
|
||||||
- Соответственно, `/.add` и `/.remove` считаются запланированными и пока не участвуют в рабочем UI-сценарии.
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# TECH блоки (`type=0`, `version=1`)
|
|
||||||
|
|
||||||
TECH-тип покрывает системные записи цепочки.
|
|
||||||
|
|
||||||
## Подтипы
|
|
||||||
|
|
||||||
1. `subType=0` — `HEADER_COMPAT`
|
|
||||||
- стартовый блок цепочки;
|
|
||||||
- payload: tag `SHiNE` + login владельца.
|
|
||||||
|
|
||||||
2. `subType=1` — `TECH_CREATE_CHANNEL`
|
|
||||||
- создание нового канала;
|
|
||||||
- хранит line-поля + `channelName` + `channelDescription` + `channelType` + `channelTypeVersion`.
|
|
||||||
|
|
||||||
## Назначение
|
|
||||||
|
|
||||||
- инициализация блокчейна;
|
|
||||||
- управление набором каналов пользователя.
|
|
||||||
@ -1,38 +0,0 @@
|
|||||||
# 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 + новый текст.
|
|
||||||
- допускается пустой `text` для логического удаления сообщения (без физического удаления блока).
|
|
||||||
|
|
||||||
5. `subType=30` — `TEXT_REPOST`
|
|
||||||
- репост сообщения в линию канала;
|
|
||||||
- содержит line-поля + target на оригинальное сообщение + текст комментария;
|
|
||||||
- на текущем этапе продуктовой логики репост не редактируется (версии не накапливаются);
|
|
||||||
- временно отключён для записи через `AddBlock` до будущей реализации репостов.
|
|
||||||
|
|
||||||
## Правило для edit
|
|
||||||
|
|
||||||
`EDIT_POST` и `EDIT_REPLY` должны ссылаться на **оригинальный** блок, а не на предыдущий edit.
|
|
||||||
|
|
||||||
## Пустой text в edit
|
|
||||||
|
|
||||||
- Для `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` допустим `textLen=0`.
|
|
||||||
- Такой edit трактуется как логическое удаление содержимого сообщения.
|
|
||||||
- Для удаления используется именно edit-блок; отдельного `DELETE`-подтипа нет.
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
# REACTION блоки (`type=2`, `version=1`)
|
|
||||||
|
|
||||||
## Подтипы
|
|
||||||
|
|
||||||
1. `subType=1` — `REACTION_LIKE`
|
|
||||||
- лайк на целевой блок;
|
|
||||||
- хранит target: `toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`.
|
|
||||||
2. `subType=2` — `REACTION_UNLIKE`
|
|
||||||
- снятие лайка с целевого блока;
|
|
||||||
- хранит target: `toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`.
|
|
||||||
|
|
||||||
## Назначение
|
|
||||||
|
|
||||||
- реакция на текстовые сообщения (и потенциально другие target-блоки, если это разрешено бизнес-логикой).
|
|
||||||
@ -1,29 +0,0 @@
|
|||||||
# CONNECTION блоки (`type=3`, `version=1`)
|
|
||||||
|
|
||||||
CONNECTION-тип описывает социальные связи и подписки.
|
|
||||||
|
|
||||||
## Подтипы
|
|
||||||
|
|
||||||
• `10/11` — `close_friend / unclose_friend` (близкий друг)
|
|
||||||
• `20/21` — `contact / uncontact` (контакт)
|
|
||||||
• `30/31` — `follow / unfollow` (подписан)
|
|
||||||
• `40/41` — `spouse / unspouse` (супруг/супруга)
|
|
||||||
• `50/51` — `parent / unparent` (родитель)
|
|
||||||
• `52/53` — `child / unchild` (ребёнок)
|
|
||||||
• `54/55` — `sibling / unsibling` (брат/сестра)
|
|
||||||
• `60/61` — `known_person / unknown_person` (знаю этого человека)
|
|
||||||
• `70/71` — `shine_confirmed / shine_unconfirmed` (точно уверен, что сияющий)
|
|
||||||
• `74/75` — `shine_seen / shine_unseen` (мало знаком, но видел сияющим)
|
|
||||||
|
|
||||||
## Общий формат payload
|
|
||||||
|
|
||||||
- line-поля (`lineCode`, `prevLineNumber`, `prevLineHash32`, `thisLineNumber`)
|
|
||||||
- target (`toBlockchainName`, `toBlockGlobalNumber`, `toBlockHash32`)
|
|
||||||
|
|
||||||
## Правила target
|
|
||||||
|
|
||||||
- FRIEND/CONTACT обычно указывают на `HEADER` цели (`block 0`).
|
|
||||||
- FOLLOW указывает на root канала:
|
|
||||||
- `HEADER` для канала `0`;
|
|
||||||
- `CREATE_CHANNEL` для пользовательского канала.
|
|
||||||
- Для остальных типов связи (`SPOUSE/PARENT/CHILD/SIBLING`) используется тот же target-формат.
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
# USER_PARAM блоки (`type=4`, `version=1`)
|
|
||||||
|
|
||||||
## Подтипы
|
|
||||||
|
|
||||||
1. `subType=1` — `USER_PARAM_TEXT_TEXT`
|
|
||||||
- хранит line-поля + `paramKey` + `paramValue`.
|
|
||||||
|
|
||||||
## Назначение
|
|
||||||
|
|
||||||
- сохранение пользовательского состояния (настройки клиента, синк-метки, курсоры чтения и т.д.).
|
|
||||||
|
|
||||||
## Практика
|
|
||||||
|
|
||||||
Для сложных структур удобно хранить JSON-строку в `paramValue` с версией схемы.
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
# История изменений документации блокчейна
|
|
||||||
|
|
||||||
## 2026-05-24 11:40:00 +0300
|
|
||||||
- Базовый коммит-ориентир: `abdce05`.
|
|
||||||
- `TEXT_REPOST (subType=30)` оставлен как зарезервированный формат, но новые блоки репоста временно отключены на уровне `AddBlock`.
|
|
||||||
- В `11_TEXT_Blocks.md` зафиксировано, что запись `TEXT_REPOST` временно не используется до будущей реализации.
|
|
||||||
- В `Dev_Docs/API/04_Add_Block_to_Blockchain_API.md` добавлен код отказа `repost_disabled`.
|
|
||||||
|
|
||||||
## 2026-05-21 19:05:00 +0300
|
|
||||||
- Базовый коммит-ориентир: `5344c42`.
|
|
||||||
- Добавлен новый TEXT-подтип `TEXT_REPOST (subType=30)`:
|
|
||||||
- обновлён перечень типов в `11_TEXT_Blocks.md`;
|
|
||||||
- обновлена быстрая карта типов в `00_Blockchain_Formats_and_Block_Types.md`.
|
|
||||||
- Уточнено API-описание поддержанных подтипов в `Dev_Docs/API/04_Add_Block_to_Blockchain_API.md`.
|
|
||||||
- В документе `Dev_Docs/API/08_MCP_Чтение_и_дозапись_персонального_публичного_чата.md` зафиксировано, что чтение канала учитывает `TEXT_POST` и `TEXT_REPOST`.
|
|
||||||
|
|
||||||
## 2026-05-20 11:34:17 +0300
|
|
||||||
- Базовый коммит-ориентир: `a53444b`.
|
|
||||||
- В `13_CONNECTION_Blocks.md` добавлены новые CONNECTION подтипы:
|
|
||||||
- `60/61` — `known_person / unknown_person` (знаю этого человека);
|
|
||||||
- `70/71` — `shine_confirmed / shine_unconfirmed` (точно уверен, что сияющий);
|
|
||||||
- `74/75` — `shine_seen / shine_unseen` (мало знаком, но видел сияющим).
|
|
||||||
- Обновлён список CONNECTION-подтипов в `Dev_Docs/API/04_Add_Block_to_Blockchain_API.md`.
|
|
||||||
|
|
||||||
## 2026-05-19 20:30:21 +0300
|
|
||||||
- Базовый коммит-ориентир: `7986184`.
|
|
||||||
- Уточнён документ `11_TEXT_Blocks.md`: для `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` зафиксировано, что `textLen=0` допустим и трактуется как логическое удаление сообщения.
|
|
||||||
- Явно закреплено, что отдельного `DELETE`-подтипа нет, удаление выполняется edit-блоком.
|
|
||||||
|
|
||||||
## 2026-05-19 00:22:46 +0300
|
|
||||||
- Базовый коммит-ориентир: `c27da63a3e65`.
|
|
||||||
- Актуализирован `README.md` как точка входа для MVP-документации по протоколу.
|
|
||||||
- В документации явно зафиксировано, что `channelType=100` и `channelType=200` присутствуют в формате, но пока не используются в UI.
|
|
||||||
- Актуализирован перечень REACTION-подтипов: добавлен `REACTION_UNLIKE (subType=2)`.
|
|
||||||
- Актуализирован перечень CONNECTION-подтипов: добавлены `SPOUSE/PARENT/CHILD/SIBLING` и обратные операции.
|
|
||||||
- В документ `02_Blockchain_Kinds_and_Lines.md` добавлены фактические серверные правила валидации line-полей.
|
|
||||||
- Обновлён корневой `AGENTS.md`: формат блокчейна менять только после явного подтверждения пользователя и с предварительным предупреждением.
|
|
||||||
|
|
||||||
## 2026-05-13 00:02:32 +0300
|
|
||||||
- Базовый коммит-ориентир: `f63f40f1eb2f`.
|
|
||||||
- Добавлен текущий формат `CreateChannelBody` с полями `channelType (2 байта)` и `channelTypeVersion (2 байта)`.
|
|
||||||
- Зафиксированы типы каналов: `0=stories`, `1=public`, `100=personal`, `200=group`.
|
|
||||||
- Серверная уникальность имени канала изменена на `owner + type + name(slug)`.
|
|
||||||
- Root-канал `0` переименован в `stories` на уровне API-чтения.
|
|
||||||
- Для персонального канала (`type=100`) включена сборка парного потока при чтении (`A->B` + `B->A`, если существует).
|
|
||||||
- Добавлена поддержка командного префикса `/.` и команды `/.desc` для актуализации описания канала при чтении.
|
|
||||||
- Зафиксированы команды `/.add` и `/.remove` для каналов `type=200` (зарезервировано под расширение участниками).
|
|
||||||
- В `AGENTS.md` добавлено обязательное правило актуализации документации в `Dev_Docs/Blockchain/`.
|
|
||||||
@ -1,33 +0,0 @@
|
|||||||
# Документация блокчейна SHiNE (MVP)
|
|
||||||
|
|
||||||
Этот каталог описывает только текущий рабочий формат протокола для MVP.
|
|
||||||
|
|
||||||
## Основные документы
|
|
||||||
1. [01_Common_Block_Format.md](./01_Common_Block_Format.md)
|
|
||||||
Единый бинарный формат блока (Frame v0), подпись, базовые проверки.
|
|
||||||
2. [02_Blockchain_Kinds_and_Lines.md](./02_Blockchain_Kinds_and_Lines.md)
|
|
||||||
Виды цепочек и правила line-полей.
|
|
||||||
3. [10_TECH_Blocks.md](./10_TECH_Blocks.md)
|
|
||||||
Системные блоки (`msg_type=0`).
|
|
||||||
4. [11_TEXT_Blocks.md](./11_TEXT_Blocks.md)
|
|
||||||
Текстовые блоки (`msg_type=1`).
|
|
||||||
5. [12_REACTION_Blocks.md](./12_REACTION_Blocks.md)
|
|
||||||
Реакции (`msg_type=2`).
|
|
||||||
6. [13_CONNECTION_Blocks.md](./13_CONNECTION_Blocks.md)
|
|
||||||
Социальные связи (`msg_type=3`).
|
|
||||||
7. [14_USER_PARAM_Blocks.md](./14_USER_PARAM_Blocks.md)
|
|
||||||
Параметры пользователя (`msg_type=4`).
|
|
||||||
8. [01_Channel_Types_and_CreateChannel.md](./01_Channel_Types_and_CreateChannel.md)
|
|
||||||
Типы каналов и формат `CreateChannelBody`.
|
|
||||||
9. [02_Channel_Commands.md](./02_Channel_Commands.md)
|
|
||||||
Команды в текстовых сообщениях каналов.
|
|
||||||
10. [CHANGELOG.md](./CHANGELOG.md)
|
|
||||||
Журнал изменений документации.
|
|
||||||
|
|
||||||
## Важные ограничения MVP
|
|
||||||
- Каналы `type=100` и `type=200` присутствуют в формате, но сейчас не используются в UI.
|
|
||||||
- Поддерживаемый рабочий сценарий UI на текущем этапе: `stories (type=0)` и `public (type=1)`.
|
|
||||||
|
|
||||||
## Обязательное сопровождение
|
|
||||||
- При любом изменении формата/правил блокчейна в коде документы этого каталога обновляются в том же наборе изменений.
|
|
||||||
- Каждое обновление документов фиксируется в `CHANGELOG.md` с датой/временем и хэшем коммита-основания.
|
|
||||||
@ -1,100 +0,0 @@
|
|||||||
# Синхронизация блоков и DM между серверами SHiNE
|
|
||||||
|
|
||||||
Документ описывает архитектуру и протокол синхронизации данных между партнёрскими серверами SHiNE.
|
|
||||||
|
|
||||||
## 1. Зачем нужна синхронизация
|
|
||||||
|
|
||||||
Пользователи SHiNE могут быть «приписаны» к разным серверам.
|
|
||||||
Когда пользователь A (на сервере X) пишет пользователю B (на сервере Y):
|
|
||||||
|
|
||||||
1. Сервер X принимает сообщение;
|
|
||||||
2. Сервер X должен переслать DM-блок серверу Y;
|
|
||||||
3. Сервер Y сохраняет блок и доставляет в активные сессии пользователя B.
|
|
||||||
|
|
||||||
Аналогично, блоки пользовательского блокчейна (записи `AddBlock`) должны синхронизироваться,
|
|
||||||
чтобы любой партнёрский сервер мог отдать полную историю пользователя.
|
|
||||||
|
|
||||||
## 2. Список серверов синхронизации (`sync_servers`)
|
|
||||||
|
|
||||||
Каждый сервер регистрирует в своей Solana PDA список `sync_servers` —
|
|
||||||
логины SHiNE-аккаунтов партнёрских серверов, с которыми он синхронизируется.
|
|
||||||
|
|
||||||
- Список хранится в блоке `ServerProfileBlock` внутри `user_pda` сервера.
|
|
||||||
- Адрес каждого партнёрского сервера читается из его PDA на Solana.
|
|
||||||
- Синхронизация двусторонняя: оба сервера должны иметь друг друга в `sync_servers`.
|
|
||||||
|
|
||||||
## 3. Что синхронизируется
|
|
||||||
|
|
||||||
### 3.1 Личные сообщения (DM)
|
|
||||||
|
|
||||||
- Все DM-блоки форматов типов `1/2` (текст) и `3/4` (read-receipt).
|
|
||||||
- Сервер-отправитель: при получении пары блоков от клиента перенаправляет их серверу получателя.
|
|
||||||
- Сервер-получатель: сохраняет блоки в `signed_messages_v2`, доставляет в активные сессии.
|
|
||||||
- Дедупликация по уникальному `message_key = from|to|timeMs|nonce|type`.
|
|
||||||
|
|
||||||
### 3.2 Блоки пользовательского блокчейна
|
|
||||||
|
|
||||||
- Все блоки `AddBlock` пользователей, зарегистрированных на сервере или синхронизирующихся через него.
|
|
||||||
- Синхронизируются в обе стороны между всеми партнёрами из `sync_servers`.
|
|
||||||
- Порядок блоков сохраняется (по глобальному номеру блока и хэшу).
|
|
||||||
- Дедупликация по глобальному номеру блока и хэшу.
|
|
||||||
|
|
||||||
## 4. Протокол синхронизации (целевой, не реализован)
|
|
||||||
|
|
||||||
### 4.1 Межсерверное соединение
|
|
||||||
|
|
||||||
- Серверы устанавливают постоянное WebSocket-соединение друг с другом.
|
|
||||||
- Адрес партнёра определяется по `server_address` из его Solana PDA.
|
|
||||||
- Аутентификация: подпись Ed25519 корневым ключом сервера (`root_key` из PDA).
|
|
||||||
- При разрыве — переподключение с экспоненциальным backoff.
|
|
||||||
|
|
||||||
### 4.2 Доставка новых данных (push)
|
|
||||||
|
|
||||||
- При получении нового блока или DM сервер немедленно пушит его всем подключённым партнёрам.
|
|
||||||
- Партнёр подтверждает приём (ACK). Без ACK — повтор с backoff.
|
|
||||||
|
|
||||||
### 4.3 Начальная синхронизация (backfill)
|
|
||||||
|
|
||||||
- При первом подключении к партнёру серверы обмениваются «курсорами» состояния:
|
|
||||||
последний глобальный номер блока, последний известный DM-ключ.
|
|
||||||
- Сервер с более полной историей досылает недостающее партнёру.
|
|
||||||
|
|
||||||
### 4.4 Разрешение конфликтов
|
|
||||||
|
|
||||||
- Блоки пользовательского блокчейна: порядок определяется глобальным номером блока.
|
|
||||||
Конфликтующие ветки (fork) разрешаются по правилам `AddBlock` (см. `Dev_Docs/Blockchain/README.md`).
|
|
||||||
- DM: конфликтов нет, `message_key` уникален.
|
|
||||||
|
|
||||||
## 5. Маршрутизация DM между серверами
|
|
||||||
|
|
||||||
При отправке DM от пользователя A к пользователю B:
|
|
||||||
|
|
||||||
1. Клиент A отправляет пару блоков на свой сервер X.
|
|
||||||
2. Сервер X определяет, на каком сервере зарегистрирован пользователь B.
|
|
||||||
- Сначала проверяет локально (если B зарегистрирован на X).
|
|
||||||
- Иначе читает PDA пользователя B из Solana и смотрит `access_servers`.
|
|
||||||
- Выбирает первый доступный сервер из `access_servers` и перенаправляет туда DM.
|
|
||||||
3. Сервер Y (из `access_servers` B) сохраняет и доставляет блоки.
|
|
||||||
|
|
||||||
Кэш адресов серверов: обновляется раз в сессию (при ошибке соединения).
|
|
||||||
|
|
||||||
## 6. Безопасность
|
|
||||||
|
|
||||||
- Все блоки подписаны ключами пользователя на клиенте — сервер не может подделать содержимое.
|
|
||||||
- Серверы не расшифровывают DM-контент (шифрование — задача следующего этапа).
|
|
||||||
- При синхронизации каждый блок проходит валидацию подписи на принимающем сервере.
|
|
||||||
|
|
||||||
## 7. Статус реализации
|
|
||||||
|
|
||||||
| Компонент | Статус |
|
|
||||||
|-----------|--------|
|
|
||||||
| Регистрация серверной PDA в Solana | ✅ Реализовано |
|
|
||||||
| Чтение `sync_servers` из PDA | Нужна реализация |
|
|
||||||
| Межсерверный WebSocket-канал | Нужна реализация |
|
|
||||||
| Push новых DM партнёрам | Нужна реализация |
|
|
||||||
| Push блоков блокчейна партнёрам | Нужна реализация |
|
|
||||||
| Backfill при первом подключении | Нужна реализация |
|
|
||||||
| Маршрутизация DM через access_servers | Нужна реализация (заглушка) |
|
|
||||||
|
|
||||||
Текущая версия сервера работает без межсерверной синхронизации.
|
|
||||||
Синхронизация — задача следующего этапа разработки.
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
# Будущие фичи
|
|
||||||
|
|
||||||
Эта папка хранит задачи, которые сознательно отложены и сейчас не должны попадать в активную разработку или ручную проверку без отдельной команды пользователя.
|
|
||||||
|
|
||||||
## Горизонты планирования
|
|
||||||
|
|
||||||
- `near/` - ближайшие планы: задачи, к которым можно вернуться сегодня или завтра.
|
|
||||||
- `medium/` - среднесрочные планы: задачи на ближайшие недели или 1-2 месяца.
|
|
||||||
- `far/` - дальнее будущее: идеи без понятного срока возврата.
|
|
||||||
|
|
||||||
Если пользователь спрашивает, какие есть планы, агент должен смотреть эти три папки и кратко перечислять задачи по горизонтам.
|
|
||||||
|
|
||||||
## Как использовать
|
|
||||||
|
|
||||||
1. Каждая будущая фича описывается отдельным markdown-файлом в одном из горизонтов.
|
|
||||||
2. В файле нужно фиксировать:
|
|
||||||
- зачем нужна фича;
|
|
||||||
- к какому сроку или горизонту она относится;
|
|
||||||
- что нужно сделать;
|
|
||||||
- какие вопросы нужно уточнить перед реализацией;
|
|
||||||
- что уже было сделано в коде, если фича частично реализована;
|
|
||||||
- что временно отключено или закомментировано, если применимо;
|
|
||||||
- какие документы нужно обновить при возврате к задаче;
|
|
||||||
- с какого места продолжать разработку.
|
|
||||||
3. Агент не должен начинать реализацию файлов из этой папки без явной просьбы пользователя.
|
|
||||||
|
|
||||||
## Текущие планы
|
|
||||||
|
|
||||||
### Ближайшие
|
|
||||||
|
|
||||||
- `near/2026-05-25_1106_telegram_agent_players.md` - разрешённые пользователи Telegram для агента, отдельные папки игроков, персональные истории и публикация краткого вопроса/ответа в общий канал.
|
|
||||||
- `near/2026-05-25_1106_wallet_topup_solana_arweave.md` - пополнение Solana и Arweave через внешний сервис покупки с подсказкой и копированием адреса.
|
|
||||||
|
|
||||||
### Среднесрочные
|
|
||||||
|
|
||||||
- `medium/2026-05-24_1140_репосты_в_каналах_и_тредах.md` - репосты в каналах и тредах.
|
|
||||||
- `medium/2026-05-25_1106_shine_balance_wallet.md` - кошелёк и пополнение баланса сияния через блокчейн.
|
|
||||||
- `medium/2026-05-26_0029_esp32s3_file_storage.md` - ESP32S3 как личное файловое хранилище SHiNE для файлов переписок и вложений.
|
|
||||||
- `medium/2026-06-03_подключение_других_устройств_через_qr.md` - довести подключение других устройств через QR: сейчас заготовка есть, но сценарий работает нестабильно и его нужно будет отдельно доделать.
|
|
||||||
- `medium/2026-06-02_сессионные_homeserver_в_pda.md` - несколько homeserver-ов пользователя как типизированные сессии в PDA с версией записи.
|
|
||||||
|
|
||||||
### DAO-запуск
|
|
||||||
|
|
||||||
- `dao_запуск/2026-06-05_esp32_hardware_wallet_device_session.md` - ESP32 как аппаратный кошелёк: постоянная device-сессия на сервере, подтверждение операций на экране, делегированные сессии для браузера/телефона.
|
|
||||||
|
|
||||||
### Дальнее будущее
|
|
||||||
|
|
||||||
- `far/2026-06-20_1639_homeserver_technical_commands_and_file_transfer.md` - технические команды для homeserver через SHiNE/WebRTC DataChannel и обмен файлами по чанкам с адресацией по `SHA-256`.
|
|
||||||
@ -1,64 +0,0 @@
|
|||||||
# ESP32 как аппаратный кошелёк (device-сессия)
|
|
||||||
|
|
||||||
## Суть фичи
|
|
||||||
|
|
||||||
ESP32 становится аппаратным HSM (hardware security module): хранит ключи, постоянно подключён к SHiNE-серверу как device-сессия, подтверждает операции нажатием на экране. Другие устройства (браузер, телефон) взаимодействуют с ESP32 через сервер — без прямого соединения.
|
|
||||||
|
|
||||||
## Два ключевых сценария
|
|
||||||
|
|
||||||
### Сценарий 1 — Создание делегированной сессии
|
|
||||||
1. Браузер/телефон → сервер: «хочу делегированную сессию от имени пользователя X»
|
|
||||||
2. Сервер → ESP32 (device-сессия): «запрос на одобрение»
|
|
||||||
3. Пользователь нажимает «Да» на сенсорном экране ESP32
|
|
||||||
4. ESP32 → сервер: одобрено → сервер создаёт делегированную сессию для браузера
|
|
||||||
|
|
||||||
### Сценарий 2 — Подпись транзакции / блока
|
|
||||||
1. Браузер (через делегированную сессию) → сервер → ESP32: «подпиши вот это»
|
|
||||||
2. ESP32 показывает запрос на экране, пользователь подтверждает
|
|
||||||
3. ESP32 подписывает нужным ключом → ответ через сервер → браузер
|
|
||||||
|
|
||||||
## Что нужно сделать
|
|
||||||
|
|
||||||
### ESP32 (основная работа)
|
|
||||||
- [ ] Инициализация WiFi (SSID/пароль в NVS)
|
|
||||||
- [ ] WebSocket-клиент (`WebSocketsClient`) — постоянное соединение с сервером
|
|
||||||
- [ ] Авторизация на сервере: `AuthChallenge` → `CreateAuthSession` через `clientKey` (уже есть в NVS), сохранить `sessionId` в NVS
|
|
||||||
- [ ] Обработчик входящих WebSocket-событий: JSON-парсинг, диспетчер по типу
|
|
||||||
- [ ] Новые UI-экраны: «Разрешить сессию?» и «Подписать?» с кнопками Да/Нет
|
|
||||||
- [ ] Расширенное хранилище ключей в NVS (произвольные именованные ключи сверх базовых трёх)
|
|
||||||
- [ ] Переподключение при разрыве (reconnect loop)
|
|
||||||
|
|
||||||
### Сервер (минимальные изменения)
|
|
||||||
- [ ] Добавить поле `sessionType` (`USER` / `DEVICE`) в таблицу `active_sessions`
|
|
||||||
- [ ] Новая операция `DeviceApprovalRequest` — браузер запрашивает одобрение у device-сессии
|
|
||||||
- [ ] Новая операция `DeviceApprovalResponse` — ESP32 отвечает (одобрено/отклонено)
|
|
||||||
- [ ] Новые операции `SignRequest` / `SignResponse` — запрос подписи и ответ
|
|
||||||
- [ ] Роутинг: при получении запроса найти device-сессию через `ActiveConnectionsRegistry.getByLogin(login)` + фильтр по `sessionType=DEVICE`, переслать туда
|
|
||||||
|
|
||||||
### Клиент (отдельный этап)
|
|
||||||
- [ ] Браузерное расширение или UI: создание делегированной сессии, отправка `SignRequest`
|
|
||||||
|
|
||||||
## Что уже готово (переиспользуем)
|
|
||||||
|
|
||||||
- **Роутинг сообщений** — `SendDirectMessage` с `TARGET_ONE_SESSION` и `CallSignalToSession` уже умеют точечно доставлять в конкретный `sessionId`. Механизм готов, нужно добавить только новые op-коды поверх него.
|
|
||||||
- **Ed25519 на ESP32** — библиотека `<Ed25519.h>` уже используется в скетче. Подписи работают.
|
|
||||||
- **NVS** — уже хранит логин, мастер-секрет, 3 пары ключей. Расширяется легко.
|
|
||||||
- **`ActiveConnectionsRegistry`** — поиск по `login` и `sessionId` уже есть на сервере.
|
|
||||||
- **Аутентификация** — схема `AuthChallenge` → `CreateAuthSession` через Ed25519 уже полностью реализована.
|
|
||||||
|
|
||||||
## Оценка сложности
|
|
||||||
|
|
||||||
| Компонент | Сложность |
|
|
||||||
|---|---|
|
|
||||||
| ESP32: WiFi + WebSocket-клиент + авторизация | Средняя |
|
|
||||||
| ESP32: обработчик входящих + UI подтверждений | Средняя |
|
|
||||||
| Сервер: флаг sessionType + 4 новых op-а + роутинг | Низкая–средняя |
|
|
||||||
| Браузерное расширение | Высокая (отдельный этап) |
|
|
||||||
|
|
||||||
**Итого фазы ESP32 + сервер: ~1–1.5 недели.**
|
|
||||||
|
|
||||||
## С чего начинать
|
|
||||||
|
|
||||||
1. Серверная часть проще и быстрее — начать с добавления `sessionType` и `DeviceApprovalRequest/Response`.
|
|
||||||
2. Затем ESP32: WiFi → WebSocket → авторизация → обработчик входящих → UI.
|
|
||||||
3. Браузерное расширение — отдельная итерация после того как ESP32 + сервер работают.
|
|
||||||
@ -1,114 +0,0 @@
|
|||||||
# Homeserver: технические команды и передача файлов через SHiNE/WebRTC
|
|
||||||
|
|
||||||
## Зачем нужна фича
|
|
||||||
|
|
||||||
Идея на дальнее будущее: дать возможность обращаться к homeserver не только как к участнику сети SHiNE, но и как к удалённой технической точке управления.
|
|
||||||
|
|
||||||
Цели:
|
|
||||||
- отправлять на homeserver технические команды в текстовом виде;
|
|
||||||
- получать текстовый ответ на команду;
|
|
||||||
- при наличии WebRTC DataChannel передавать части файлов в обе стороны;
|
|
||||||
- хранить полученные файлы на SD-карте homeserver;
|
|
||||||
- использовать единый механизм доставки как через сервер SHiNE, так и напрямую через DataChannel.
|
|
||||||
|
|
||||||
## Горизонт
|
|
||||||
|
|
||||||
`far` - идея без ближайшего срока реализации. Сейчас приоритет ниже, чем запуск и стабилизация основного проекта.
|
|
||||||
|
|
||||||
## Что именно имеется в виду
|
|
||||||
|
|
||||||
### 1. Единая модель технической команды
|
|
||||||
|
|
||||||
Техническая команда должна иметь единый смысл независимо от транспорта доставки:
|
|
||||||
- через любой доступный сервер SHiNE;
|
|
||||||
- через уже установленный WebRTC DataChannel.
|
|
||||||
|
|
||||||
Если конкретный транспорт недоступен, ответ по нему может не прийти. Это считается нормальным поведением протокола.
|
|
||||||
|
|
||||||
### 2. Команда как короткоживущий подписанный сигнал
|
|
||||||
|
|
||||||
У команды должны быть:
|
|
||||||
- `commandId`;
|
|
||||||
- временная метка;
|
|
||||||
- TTL около 10 секунд;
|
|
||||||
- криптографическая подпись.
|
|
||||||
|
|
||||||
Смысл такой:
|
|
||||||
- если команда быстро дошла, homeserver подтверждает принятие;
|
|
||||||
- если не дошла вовремя, команда считается протухшей;
|
|
||||||
- отправитель может безопасно послать повтор;
|
|
||||||
- при повторе homeserver отвечает либо `команда принята`, либо `уже выполнено ранее`.
|
|
||||||
|
|
||||||
Это даёт дедупликацию и безопасный resend без повторного выполнения действия.
|
|
||||||
|
|
||||||
### 3. Текстовые технические команды
|
|
||||||
|
|
||||||
Базовый сценарий похож на короткий удалённый shell-протокол, но на уровне строго ограниченных команд:
|
|
||||||
- отправил строку-команду;
|
|
||||||
- получил строку-ответ.
|
|
||||||
|
|
||||||
Команды не обязаны исполнять произвольный shell. Предпочтительная модель - белый список операций с контролируемым форматом аргументов и ответа.
|
|
||||||
|
|
||||||
### 4. Передача файлов только при наличии DataChannel
|
|
||||||
|
|
||||||
Если между устройствами есть WebRTC DataChannel, через него можно передавать технические сообщения для файлового обмена.
|
|
||||||
|
|
||||||
Предварительная модель:
|
|
||||||
- имя файла = `SHA-256` содержимого;
|
|
||||||
- можно запросить диапазон байт `from..to`;
|
|
||||||
- можно отправить диапазон байт `from..to`;
|
|
||||||
- homeserver хранит полученные данные на SD-карте;
|
|
||||||
- если DataChannel нет, на запрос файловой передачи возвращается ответ в духе `не могу передать, нет data channel`.
|
|
||||||
|
|
||||||
Фактически файл-обмен должен быть частным случаем общего протокола технических команд.
|
|
||||||
|
|
||||||
### 5. Установка data-соединения по явной команде
|
|
||||||
|
|
||||||
Нужна техническая команда уровня:
|
|
||||||
- `установить data-соединение`.
|
|
||||||
|
|
||||||
Ответ:
|
|
||||||
- либо `да`, после чего запускается обычная процедура `offer/answer/ICE`;
|
|
||||||
- либо `нет` и причина отказа.
|
|
||||||
|
|
||||||
### 6. Доставка на пользовательские сессии
|
|
||||||
|
|
||||||
Логика должна быть совместима с общей моделью SHiNE, где технические сигналы можно отправлять на конкретные активные сессии пользователя.
|
|
||||||
|
|
||||||
Идея:
|
|
||||||
- на любую активную сессию пользователя можно посылать техническую команду;
|
|
||||||
- контакт пользователя может инициировать такую техническую коммуникацию так же, как он уже инициирует звонок или другой служебный сигнал.
|
|
||||||
|
|
||||||
## Что нужно будет сделать при возврате к задаче
|
|
||||||
|
|
||||||
- Спроектировать отдельный формат технических команд и ack-ответов.
|
|
||||||
- Решить, будет ли это новый тип служебных сообщений в существующем протоколе блокчейн/сигналинга или отдельная ветка поверх уже имеющихся transport-операций.
|
|
||||||
- Отдельно продумать авторизацию: кто именно из контактов и какие команды имеет право слать.
|
|
||||||
- Ограничить набор допустимых команд, чтобы не превратить механизм в небезопасный удалённый shell.
|
|
||||||
- Спроектировать протокол чанков файлов: размер чанка, нумерация, повторная отправка, контроль целостности, дозагрузка, завершение файла.
|
|
||||||
- Продумать хранение на SD-карте: временные файлы, сборка чанков, проверка итогового `SHA-256`, очистка мусора.
|
|
||||||
- Продумать поведение при отсутствии DataChannel, таймаутах и дублирующихся командах.
|
|
||||||
- Проверить, как это лучше встраивать в текущие клиентские сессии, звонки и homeserver-логику.
|
|
||||||
|
|
||||||
## Вопросы для будущего уточнения
|
|
||||||
|
|
||||||
- Это должен быть строго служебный протокол или пользователь сможет вызывать его и вручную из UI.
|
|
||||||
- Нужен ли доступ только к заранее разрешённым каталогам/файлам.
|
|
||||||
- Нужна ли двусторонняя синхронизация файлов или достаточно ручных команд `запросить кусок` / `отправить кусок`.
|
|
||||||
- Нужно ли разрешать передачу файлов через сервер SHiNE как fallback, или файл-обмен должен идти только через DataChannel.
|
|
||||||
- Какой максимальный размер файлов и допустимый объём хранения на SD-карте.
|
|
||||||
|
|
||||||
## Что уже сделано
|
|
||||||
|
|
||||||
Пока только зафиксирована идея и базовая концепция. Реализация не начиналась.
|
|
||||||
|
|
||||||
## Какие документы нужно будет обновить при реализации
|
|
||||||
|
|
||||||
- `Dev_Docs/Blockchain/README.md` и связанные файлы, если изменятся типы служебных сообщений или форматы блокчейн-команд.
|
|
||||||
- `Dev_Docs/API/` если изменится публичный серверный API или появятся новые операции.
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md` если часть маршрутизации или подтверждений будет встроена в существующую логику доставки/сессий.
|
|
||||||
- Документацию по homeserver/ESP32, если появится пользовательская или сервисная файловая логика на устройстве.
|
|
||||||
|
|
||||||
## С какого места продолжать позже
|
|
||||||
|
|
||||||
Возвращаться к задаче только после стабилизации запуска проекта и базовых текущих функций. Начинать с проектирования протокола команд и матрицы прав доступа, а уже потом переходить к DataChannel-файлообмену.
|
|
||||||
@ -1,7 +0,0 @@
|
|||||||
# Дальнее будущее
|
|
||||||
|
|
||||||
Сюда переносить задачи, у которых нет понятного срока возврата и которые не нужно учитывать в ближайшем или среднесрочном планировании.
|
|
||||||
|
|
||||||
## Идеи
|
|
||||||
|
|
||||||
- `2026-06-20_1639_homeserver_technical_commands_and_file_transfer.md` - технические команды для homeserver через сервер SHiNE или WebRTC DataChannel, а также файловый обмен чанками с хранением на SD-карте.
|
|
||||||
@ -1,99 +0,0 @@
|
|||||||
# Репосты в каналах и тредах
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`future`
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`medium`
|
|
||||||
|
|
||||||
- Ориентир:
|
|
||||||
1-2 месяца
|
|
||||||
|
|
||||||
- Решение от 2026-05-24:
|
|
||||||
Репосты временно убраны из активной разработки. Фича уже была частично реализована, но не доведена до финальной проверки. Чтобы она не мешала запуску проекта, пользовательский вход в репосты отключён в UI, а сервер больше не принимает новые `TEXT_REPOST` через `AddBlock`.
|
|
||||||
|
|
||||||
## Что должна делать фича
|
|
||||||
|
|
||||||
Репост должен позволять взять сообщение из канала или треда и опубликовать его в один из своих каналов с комментарием.
|
|
||||||
|
|
||||||
Ожидаемый пользовательский сценарий после возврата к задаче:
|
|
||||||
|
|
||||||
1. Пользователь открывает сообщение в канале или треде.
|
|
||||||
2. Нажимает `Репост`.
|
|
||||||
3. Выбирает один из своих каналов.
|
|
||||||
4. Добавляет комментарий.
|
|
||||||
5. Отправляет репост.
|
|
||||||
6. В целевом канале появляется новый пост-репост.
|
|
||||||
7. У репоста есть переход к исходному сообщению через действие `Оригинал`.
|
|
||||||
|
|
||||||
## Что уже есть в коде
|
|
||||||
|
|
||||||
- В блокчейн-формате зарезервирован и описан подтип `TEXT_REPOST (30)`.
|
|
||||||
- Парсер блокчейна умеет распознавать тело репоста как `TextLineBody`.
|
|
||||||
- В UI есть функция сборки тела репоста:
|
|
||||||
`shine-UI/js/services/auth-service.js`, `makeTextRepostBodyBytes`.
|
|
||||||
- В UI есть клиентская операция:
|
|
||||||
`shine-UI/js/services/auth-service.js`, `addBlockRepost`.
|
|
||||||
- В экране канала был обработчик репоста:
|
|
||||||
`shine-UI/js/pages/channel-view.js`, `onRepost`.
|
|
||||||
- В экране треда был обработчик репоста:
|
|
||||||
`shine-UI/js/pages/channel-thread-view.js`, `onRepost`.
|
|
||||||
- Серверная выдача каналов и тредов частично учитывает `TEXT_REPOST` и target-поля:
|
|
||||||
`targetBlockchainName`, `targetBlockNumber`, `targetBlockHash`.
|
|
||||||
- В списке подписок `TEXT_REPOST` считается публикацией канала.
|
|
||||||
|
|
||||||
## Что сейчас отключено
|
|
||||||
|
|
||||||
- В `shine-UI/js/pages/channel-view.js` кнопка `Репост` больше не создаётся и не добавляется в список действий сообщения.
|
|
||||||
- В `shine-UI/js/pages/channel-thread-view.js` кнопка `Репост` больше не создаётся и не добавляется в список действий ответа/сообщения треда.
|
|
||||||
- В `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/handlers/blockchain/Net_AddBlock_Handler.java` добавлена явная временная блокировка:
|
|
||||||
если новый блок имеет `type=1` и `subType=TEXT_REPOST (30)`, `AddBlock` возвращает ошибку `repost_disabled`.
|
|
||||||
|
|
||||||
## Что осталось активным намеренно
|
|
||||||
|
|
||||||
- Константа `TEXT_REPOST (30)` остаётся в коде и документации как зарезервированный формат.
|
|
||||||
- Парсер блокчейна продолжает знать формат `TEXT_REPOST`, чтобы не потерять уже написанную основу и не ломать потенциальное чтение старых тестовых данных.
|
|
||||||
- Код формирования репоста в `auth-service.js` не удалён: его можно будет использовать как основу при возвращении к задаче.
|
|
||||||
- Код отображения target-полей и перехода к оригиналу не удалён: он нужен для будущей проверки и возможной совместимости с уже созданными тестовыми блоками.
|
|
||||||
|
|
||||||
## Почему это не лежит в Pending_Features
|
|
||||||
|
|
||||||
`Dev_Docs/Pending_Features/` предназначена для фич, которые уже реализованы и ждут ручной проверки.
|
|
||||||
|
|
||||||
Репосты сейчас не подходят под этот статус: они не должны проверяться как готовая фича, потому что пользовательский сценарий временно закрыт, а серверная запись новых репостов заблокирована. Поэтому старый pending-файл удалён, а задача перенесена сюда как будущая.
|
|
||||||
|
|
||||||
## Что сделать при возврате к реализации
|
|
||||||
|
|
||||||
1. Решить, остаётся ли формат `TEXT_REPOST (30)` финальным.
|
|
||||||
2. Если формат меняется, заранее предупредить пользователя и получить отдельное подтверждение на изменение блокчейн-формата.
|
|
||||||
3. Вернуть UI-кнопки репоста в:
|
|
||||||
- `shine-UI/js/pages/channel-view.js`;
|
|
||||||
- `shine-UI/js/pages/channel-thread-view.js`.
|
|
||||||
4. Снять временную блокировку `repost_disabled` в:
|
|
||||||
`shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/handlers/blockchain/Net_AddBlock_Handler.java`.
|
|
||||||
5. Проверить `auth-service.js`:
|
|
||||||
- `makeTextRepostBodyBytes`;
|
|
||||||
- `addBlockRepost`;
|
|
||||||
- актуализацию вершины блокчейна перед `AddBlock`;
|
|
||||||
- корректность target-полей исходного сообщения.
|
|
||||||
6. Проверить серверное чтение:
|
|
||||||
- `GetChannelMessages`;
|
|
||||||
- `GetMessageThread`;
|
|
||||||
- отображение `targetBlockchainName`, `targetBlockNumber`, `targetBlockHash`.
|
|
||||||
7. Добавить или обновить тесты на успешный репост и отказ некорректных target-полей.
|
|
||||||
8. Обновить документацию:
|
|
||||||
- `Dev_Docs/Blockchain/11_TEXT_Blocks.md`;
|
|
||||||
- `Dev_Docs/Blockchain/CHANGELOG.md`;
|
|
||||||
- `Dev_Docs/API/04_Add_Block_to_Blockchain_API.md`;
|
|
||||||
- документы API чтения каналов/тредов, если изменятся поля ответа.
|
|
||||||
9. После реализации перенести задачу из `Dev_Docs/Future_Features/` в `Dev_Docs/Pending_Features/` как фичу, требующую ручной проверки.
|
|
||||||
|
|
||||||
## Минимальный чек-лист ручной проверки в будущем
|
|
||||||
|
|
||||||
1. Репост из сообщения канала в свой канал.
|
|
||||||
2. Репост из ответа в треде в свой канал.
|
|
||||||
3. Ошибка при попытке репоста в чужой канал.
|
|
||||||
4. Переход `Оригинал` из репоста к исходному сообщению.
|
|
||||||
5. Корректное отображение комментария к репосту.
|
|
||||||
6. Корректная работа после перезагрузки страницы.
|
|
||||||
7. Отсутствие поломки обычных постов, ответов, лайков и отправки ссылки.
|
|
||||||
@ -1,62 +0,0 @@
|
|||||||
# Кошелёк и пополнение баланса сияния
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`medium`
|
|
||||||
- Ориентир:
|
|
||||||
среднесрочно
|
|
||||||
- Статус:
|
|
||||||
`proposal`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
Нужно добавить кошелёк для внутреннего баланса сияния и пополнение этого баланса через блокчейн-логику проекта. Задача связана с регистрацией пользователя и будущим учётом баланса.
|
|
||||||
|
|
||||||
## Предполагаемый сценарий
|
|
||||||
|
|
||||||
1. Пользователь регистрируется и получает/подключает нужные кошельки.
|
|
||||||
2. В интерфейсе появляется баланс сияния.
|
|
||||||
3. Пользователь открывает пополнение баланса сияния.
|
|
||||||
4. Система создаёт или принимает блокчейн-операцию пополнения.
|
|
||||||
5. После подтверждения баланса UI обновляет значение.
|
|
||||||
|
|
||||||
## Что нужно продумать
|
|
||||||
|
|
||||||
1. Что именно является единицей баланса сияния.
|
|
||||||
2. Где хранится состояние баланса: в существующем блокчейне SHiNE, Solana-модуле или комбинированно.
|
|
||||||
3. Какая операция отвечает за пополнение.
|
|
||||||
4. Нужно ли делать отдельную регистрацию кошелька сияния или использовать существующую регистрацию пользователя.
|
|
||||||
5. Как баланс восстанавливается после перезагрузки клиента.
|
|
||||||
6. Какие права нужны для пополнения и списания.
|
|
||||||
7. Нужна ли история операций баланса.
|
|
||||||
|
|
||||||
## Вопросы перед реализацией
|
|
||||||
|
|
||||||
1. Пополнение баланса сияния должно идти через основной блокчейн SHiNE или через Solana-программу.
|
|
||||||
2. Нужна ли конвертация из SOL/AR в сияние.
|
|
||||||
3. Кто может выпускать или начислять сияние.
|
|
||||||
4. Нужно ли поддерживать перевод сияния между пользователями.
|
|
||||||
5. Нужны ли лимиты, комиссии или статусы подтверждения.
|
|
||||||
6. Какой экран должен показывать баланс: регистрация, профиль, кошелёк или отдельная страница.
|
|
||||||
7. Нужно ли отображать неподтверждённый баланс отдельно от подтверждённого.
|
|
||||||
|
|
||||||
## Важное ограничение
|
|
||||||
|
|
||||||
Если для баланса сияния потребуется новый формат блокчейн-блока или изменение существующего формата, перед реализацией нужно отдельно предупредить пользователя и получить явное подтверждение на изменение формата блокчейна.
|
|
||||||
|
|
||||||
Если потребуется новый серверный API или изменение существующих `op`, перед реализацией нужно отдельно предупредить пользователя и получить явное подтверждение на изменение API.
|
|
||||||
|
|
||||||
## Документы, которые обновить при реализации
|
|
||||||
|
|
||||||
- `Dev_Docs/Blockchain/`, если появятся или изменятся блоки баланса.
|
|
||||||
- `Dev_Docs/Blockchain/CHANGELOG.md`, если меняется блокчейн-формат.
|
|
||||||
- `Dev_Docs/API/`, если меняется серверный API.
|
|
||||||
- `Dev_Docs/Pending_Features/` - добавить файл ручной проверки после реализации.
|
|
||||||
- Документацию Solana-регистрации, если баланс будет связан с Solana-модулем.
|
|
||||||
|
|
||||||
## Минимальная проверка в будущем
|
|
||||||
|
|
||||||
1. Новый пользователь видит корректный начальный баланс.
|
|
||||||
2. Пополнение создаёт правильную операцию.
|
|
||||||
3. Баланс обновляется после подтверждения.
|
|
||||||
4. После перезагрузки UI баланс остаётся корректным.
|
|
||||||
5. Ошибочные или повторные операции не начисляют баланс дважды.
|
|
||||||
@ -1,44 +0,0 @@
|
|||||||
# ESP32S3 как личное файловое хранилище SHiNE
|
|
||||||
|
|
||||||
## Горизонт
|
|
||||||
|
|
||||||
Среднесрочный: ближайшие недели или 1-2 месяца.
|
|
||||||
|
|
||||||
## Зачем нужна фича
|
|
||||||
|
|
||||||
Нужно проработать маленький физический сервер на ESP32S3 как персональное или доверенное файловое хранилище SHiNE.
|
|
||||||
|
|
||||||
Идея: при обмене сообщениями пользователи смогут использовать такой сервер для хранения своих файлов, вложений, файлов общих переписок и связанных данных.
|
|
||||||
|
|
||||||
## Что нужно сделать
|
|
||||||
|
|
||||||
- Описать роль ESP32S3-сервера в общей архитектуре ключей и сессий.
|
|
||||||
- Определить, какие ключи может хранить такое устройство.
|
|
||||||
- Решить, хранит ли устройство только файлы или также подписывает пользовательские операции.
|
|
||||||
- Описать протокол загрузки, скачивания и удаления файлов.
|
|
||||||
- Определить правила шифрования файлов до отправки на устройство.
|
|
||||||
- Продумать индексацию файлов для личных и общих переписок.
|
|
||||||
- Решить, как устройство авторизуется на основном сервере SHiNE.
|
|
||||||
|
|
||||||
## Вопросы перед реализацией
|
|
||||||
|
|
||||||
- ESP32S3 должен работать как полностью локальное устройство или как публично доступный мини-сервер?
|
|
||||||
- Нужен ли внешний relay, если устройство находится за NAT?
|
|
||||||
- Какие ограничения по размеру файла считаем допустимыми?
|
|
||||||
- Хранит ли устройство метаданные переписок или только зашифрованные blob-файлы?
|
|
||||||
- Как восстанавливать доступ, если устройство потеряно или заменено?
|
|
||||||
|
|
||||||
## Что уже сделано
|
|
||||||
|
|
||||||
Код не реализован. Идея зафиксирована как будущая задача после описания модели ключей.
|
|
||||||
|
|
||||||
## Документы, которые нужно обновить при возврате
|
|
||||||
|
|
||||||
- `Dev_Docs/Keys/README.md`
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md`
|
|
||||||
- `Dev_Docs/API/`
|
|
||||||
- `Dev_Docs/Blockchain/`, если появятся новые блоки или команды для файлов.
|
|
||||||
|
|
||||||
## С какого места продолжать
|
|
||||||
|
|
||||||
Начать с короткого протокольного документа: роли устройства, авторизация, шифрование файлов, минимальные API-операции и сценарии восстановления.
|
|
||||||
@ -1,105 +0,0 @@
|
|||||||
# Сессионные homeserver-ы в PDA пользователя
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`future`
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`medium`
|
|
||||||
|
|
||||||
- Ориентир:
|
|
||||||
после завершения первого этапа по пользовательским сессиям
|
|
||||||
|
|
||||||
- Основание:
|
|
||||||
Идея зафиксирована после обсуждения архитектуры пользовательских сессий и внутренних homeserver-ов. Сейчас задача сознательно отложена: сначала нужно аккуратно ввести базовую модель сессий, а затем возвращаться к расширенной серверной роли.
|
|
||||||
|
|
||||||
## Зачем нужна фича
|
|
||||||
|
|
||||||
У одного пользователя может быть несколько доверенных внутренних homeserver-ов, и каждый из них должен жить как отдельная пользовательская сессия, а не как отдельная особая сущность вне общей модели.
|
|
||||||
|
|
||||||
Это нужно, чтобы:
|
|
||||||
|
|
||||||
- хранить несколько homeserver-ов у одного пользователя одновременно;
|
|
||||||
- различать обычные клиентские сессии и серверные сессии по явному типу;
|
|
||||||
- дать расширяемый формат записи с версией;
|
|
||||||
- использовать единый подход для DM, звонков и внутренних команд между сессиями.
|
|
||||||
|
|
||||||
## Целевая идея
|
|
||||||
|
|
||||||
В пользовательском PDA должен появиться список записей сессий, где каждая запись содержит как минимум:
|
|
||||||
|
|
||||||
- `sessionType` (`u8`);
|
|
||||||
- `sessionVersion` (`u8`);
|
|
||||||
- `sessionName`;
|
|
||||||
- `sessionPubKey`.
|
|
||||||
|
|
||||||
Предварительные значения:
|
|
||||||
|
|
||||||
- тип `1` - обычная пользовательская сессия;
|
|
||||||
- тип `100` - homeserver пользователя;
|
|
||||||
- версия `1` - первая рабочая версия формата записи сессии.
|
|
||||||
|
|
||||||
На текущем этапе под это уже зарезервирован отдельный блок `SessionsBlock` с `block_type = 55`, а `TrustedStateBlock` остаётся на `50`.
|
|
||||||
|
|
||||||
Важно: homeserver-ов у одного пользователя может быть несколько.
|
|
||||||
|
|
||||||
## Архитектурный принцип
|
|
||||||
|
|
||||||
Внутренний протокол взаимодействия должен оставаться транспортным.
|
|
||||||
|
|
||||||
То есть SHiNE-сервер не должен разбирать прикладной смысл внутренней нагрузки homeserver-а, а должен:
|
|
||||||
|
|
||||||
- доставлять сообщения между сессиями;
|
|
||||||
- доставлять сигналы звонков между сессиями;
|
|
||||||
- хранить и маршрутизировать адресацию;
|
|
||||||
- не принимать на себя бизнес-логику содержимого внутренних команд.
|
|
||||||
|
|
||||||
## Что уже подтверждается текущим кодом
|
|
||||||
|
|
||||||
- Личные сообщения уже доставляются по всем сессиям целевого пользователя с отдельным учётом доставки на каждую сессию.
|
|
||||||
- Подтверждение доставки DM уже идёт отдельно по каждой сессии.
|
|
||||||
- Вызов звонка уже рассылается по нескольким активным сессиям пользователя.
|
|
||||||
- Сигналы звонка уже адресуются конкретной сессии, а stop-сигналы дублируются на остальные сессии того же пользователя.
|
|
||||||
|
|
||||||
Иными словами, текущая серверная логика ближе к модели "сервер доставляет между сессиями", чем к модели "сервер понимает внутренний протокол homeserver-а".
|
|
||||||
|
|
||||||
## Что нужно сделать при возврате к задаче
|
|
||||||
|
|
||||||
1. Согласовать финальный бинарный формат записи сессии в PDA пользователя.
|
|
||||||
2. Проверить, не меняет ли это уже опубликованный формат пользовательской PDA-записи.
|
|
||||||
3. Если формат PDA меняется, заранее предупредить пользователя и получить отдельное подтверждение.
|
|
||||||
4. Решить, где именно хранится массив сессий:
|
|
||||||
- в основной записи пользователя;
|
|
||||||
- в отдельной PDA-структуре расширения;
|
|
||||||
- или в смешанной схеме с базовой записью и внешними индексами.
|
|
||||||
5. Зафиксировать ограничения:
|
|
||||||
- максимальное число сессий;
|
|
||||||
- максимальную длину `sessionName`;
|
|
||||||
- правила удаления и обновления записи;
|
|
||||||
- правила ротации `sessionPubKey`.
|
|
||||||
6. Продумать, как UI и сервер будут отличать тип `1` и тип `100`.
|
|
||||||
7. Определить, какие внутренние сообщения homeserver-а останутся полностью прозрачными для SHiNE-сервера, а какие потребуют только технической маршрутизации.
|
|
||||||
8. Добавить API/операции чтения и обновления списка сессий, если для этого не хватит существующих механизмов.
|
|
||||||
9. После реализации обязательно обновить документацию.
|
|
||||||
|
|
||||||
## Что нужно обновить при реализации
|
|
||||||
|
|
||||||
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
|
|
||||||
- `Dev_Docs/Solana_Architecture/README.md`
|
|
||||||
- `Dev_Docs/Инициализация_Solana_регистрации/README.md`
|
|
||||||
- `Dev_Docs/Keys/README.md`
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md`, если изменится адресация DM по типам сессий
|
|
||||||
- `Dev_Docs/API/`, если появятся новые серверные операции или изменятся ответы
|
|
||||||
|
|
||||||
## Что пока не делать
|
|
||||||
|
|
||||||
- Не включать это автоматически в основной deploy сервера.
|
|
||||||
- Не менять сейчас Solana PDA-формат без отдельного подтверждения.
|
|
||||||
- Не добавлять временные поля в публичный API "на всякий случай".
|
|
||||||
|
|
||||||
## С какого места продолжать
|
|
||||||
|
|
||||||
Продолжать после завершения первой части:
|
|
||||||
|
|
||||||
1. описать минимальный формат записи пользовательской сессии;
|
|
||||||
2. отдельно решить, живут ли homeserver-ы в том же списке, что и обычные сессии;
|
|
||||||
3. затем уже проектировать операции регистрации, обновления и отключения таких сессий.
|
|
||||||
@ -1,45 +0,0 @@
|
|||||||
# Подключение других устройств через QR
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`medium`
|
|
||||||
- Ориентир:
|
|
||||||
позже, не сейчас
|
|
||||||
- Статус:
|
|
||||||
`future`
|
|
||||||
|
|
||||||
## Зачем нужна фича
|
|
||||||
|
|
||||||
Нужно нормально довести подключение другого устройства через QR-код. Сейчас есть полуготовая заготовка, но сценарий работает нестабильно и требует отдельной доработки.
|
|
||||||
|
|
||||||
## Что уже есть
|
|
||||||
|
|
||||||
- В UI уже есть экраны:
|
|
||||||
- `shine-UI/js/pages/connect-device-view.js`
|
|
||||||
- `shine-UI/js/pages/device-qr-view.js`
|
|
||||||
- Есть сервис переноса ключей через QR:
|
|
||||||
- `shine-UI/js/services/qr-key-transfer-service.js`
|
|
||||||
- Логика частично собрана, но её нельзя считать завершённой или надёжной.
|
|
||||||
|
|
||||||
## Что нужно будет сделать потом
|
|
||||||
|
|
||||||
1. Проверить и довести формат QR-передачи.
|
|
||||||
2. Проверить сканирование и ручной ввод QR-текста.
|
|
||||||
3. Проверить перенос `device`, `blockchain`, `root` ключей только по реальному наличию на исходном устройстве.
|
|
||||||
4. Проверить, что после переноса очищается старая история нужного логина и не ломается вход.
|
|
||||||
5. Отдельно проверить сценарий без `BarcodeDetector`.
|
|
||||||
6. Довести экран подтверждения на втором устройстве.
|
|
||||||
|
|
||||||
## Что сейчас важно
|
|
||||||
|
|
||||||
- Не считать эту часть готовой.
|
|
||||||
- Не возвращать её в активную разработку без отдельной команды пользователя.
|
|
||||||
- Если вернёмся к задаче, сначала нужно понять, что именно уже работает, а что нет, и потом починить целиком.
|
|
||||||
|
|
||||||
## Что обновить при возврате
|
|
||||||
|
|
||||||
- `Dev_Docs/Pending_Features/README.md`
|
|
||||||
- `shine-UI/js/pages/connect-device-view.js`
|
|
||||||
- `shine-UI/js/pages/device-qr-view.js`
|
|
||||||
- `shine-UI/js/services/qr-key-transfer-service.js`
|
|
||||||
- документацию по ключам, если формат переноса меняется
|
|
||||||
|
|
||||||
@ -1,94 +0,0 @@
|
|||||||
# Telegram-агент для разрешённых игроков
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`near`
|
|
||||||
- Ориентир:
|
|
||||||
сегодня/завтра
|
|
||||||
- Статус:
|
|
||||||
`proposal`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
Нужно расширить `SHiNE-agent-bot-coder`, чтобы агент мог принимать личные сообщения от заранее разрешённых пользователей, вести по каждому отдельную рабочую папку и историю, помогать им с обсуждениями/документами без изменения кода, а краткий результат публиковать в общий канал.
|
|
||||||
|
|
||||||
## Пользовательский сценарий
|
|
||||||
|
|
||||||
1. Разрешённый пользователь пишет агенту в личные сообщения текстом или голосом.
|
|
||||||
2. Голосовое сообщение распознаётся так же, как сейчас распознаются voice/audio-задачи.
|
|
||||||
3. Сервис определяет пользователя по разрешённому списку логинов.
|
|
||||||
4. Для пользователя используется отдельная папка в `Players/`.
|
|
||||||
5. Codex запускается с системным контекстом: от имени какого человека он работает, где лежит его папка, какие у него локальные инструкции.
|
|
||||||
6. Агент может читать код и документацию проекта, но писать должен только в папку этого пользователя, если нет отдельного согласования на изменение общего проекта.
|
|
||||||
7. После ответа пользователю агент отправляет в общий канал короткую сводку двумя сообщениями или двумя блоками: вопрос пользователя и полученный ответ.
|
|
||||||
8. Команда `/new` или `New` сбрасывает только сессию этого пользователя.
|
|
||||||
|
|
||||||
## Предлагаемая структура
|
|
||||||
|
|
||||||
- `Players/`
|
|
||||||
- `Ivan/`
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `history/`
|
|
||||||
- `files/`
|
|
||||||
- `Sergey/`
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `history/`
|
|
||||||
- `files/`
|
|
||||||
- `Milana/`
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `history/`
|
|
||||||
- `files/`
|
|
||||||
|
|
||||||
Имена папок можно уточнить после получения точных Telegram-логинов.
|
|
||||||
|
|
||||||
## Что нужно сделать
|
|
||||||
|
|
||||||
1. Добавить конфигурацию разрешённых Telegram-пользователей.
|
|
||||||
2. Описать соответствие `telegram username -> имя игрока -> папка`.
|
|
||||||
3. Создавать или использовать отдельную историю диалога для каждого игрока.
|
|
||||||
4. Поддержать личные сообщения от разрешённых пользователей.
|
|
||||||
5. Запретить постановку задач от неизвестных пользователей.
|
|
||||||
6. Для групп/каналов оставить текущую логику: команды Айдара имеют приоритет.
|
|
||||||
7. При запуске Codex для игрока добавлять отдельный системный контекст:
|
|
||||||
- имя пользователя;
|
|
||||||
- путь к его папке;
|
|
||||||
- правило записи только в эту папку;
|
|
||||||
- путь к персональному `AGENTS.md`.
|
|
||||||
8. После ответа игроку отправлять краткую сводку в общий канал.
|
|
||||||
9. Поддержать `/new`/`New` как сброс только персональной сессии игрока.
|
|
||||||
10. Добавить защиту от случайного изменения общего кода в режиме игрока.
|
|
||||||
|
|
||||||
## Вопросы перед реализацией
|
|
||||||
|
|
||||||
1. Точные Telegram-логины Ивана, Сергея и Миланы.
|
|
||||||
2. Какой общий канал использовать для сводок: текущий `@shine_writing` или отдельный чат.
|
|
||||||
3. Нужно ли отправлять в общий канал полный текст вопроса/ответа или краткую выжимку.
|
|
||||||
4. Нужно ли пересылать вложения игроков в общий канал или только текстовые сводки.
|
|
||||||
5. Разрешить ли игрокам читать все документы проекта, включая технические заметки деплоя.
|
|
||||||
6. Что делать, если пользователь просит изменить код: отказать, создать предложение в своей папке или просить подтверждение Айдара.
|
|
||||||
7. Нужны ли русские имена папок (`Иван`, `Сергей`, `Милана`) или ASCII-имена (`Ivan`, `Sergey`, `Milana`).
|
|
||||||
8. Нужно ли хранить истории игроков в общей папке сервиса или внутри `Players/<name>/history/`.
|
|
||||||
|
|
||||||
## Риски и ограничения
|
|
||||||
|
|
||||||
- Нужно аккуратно разделить режим Айдара и режим игрока, чтобы игроки не могли случайно запустить изменение общего кода.
|
|
||||||
- Нужно не смешать истории разных пользователей.
|
|
||||||
- Нужно ограничить публикацию в общий канал, чтобы не утекали личные или слишком длинные ответы.
|
|
||||||
- Нужна проверка Telegram-идентификации: username может меняться, поэтому желательно хранить и `user_id`.
|
|
||||||
|
|
||||||
## Документы, которые обновить при реализации
|
|
||||||
|
|
||||||
- `SHiNE-agent-bot-coder/AGENTS.md`
|
|
||||||
- `SHiNE-agent-bot-coder/AGENT.md`
|
|
||||||
- `SHiNE-agent-bot-coder/README.md`
|
|
||||||
- `Dev_Docs/deploy/agent-bot-coder-local-systemd.md`, если появятся новые переменные окружения или настройки сервиса.
|
|
||||||
|
|
||||||
## Минимальная проверка
|
|
||||||
|
|
||||||
1. Айдар по-прежнему может ставить задачи из `@shine_writing`.
|
|
||||||
2. Неизвестный пользователь не ставит задачу в очередь.
|
|
||||||
3. Разрешённый игрок пишет личное текстовое сообщение и получает ответ.
|
|
||||||
4. Разрешённый игрок отправляет voice, оно распознаётся и обрабатывается.
|
|
||||||
5. История одного игрока не попадает в историю другого.
|
|
||||||
6. `/new` сбрасывает только историю текущего игрока.
|
|
||||||
7. Сводка вопрос/ответ появляется в общем канале.
|
|
||||||
8. В режиме игрока агент не пишет за пределы `Players/<name>/` без отдельного подтверждения.
|
|
||||||
@ -1,71 +0,0 @@
|
|||||||
# Пополнение Solana и Arweave через внешний сервис покупки
|
|
||||||
|
|
||||||
- Горизонт:
|
|
||||||
`near`
|
|
||||||
- Ориентир:
|
|
||||||
сегодня/завтра
|
|
||||||
- Статус:
|
|
||||||
`proposal`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
Нужно добавить удобное пополнение кошельков на экране регистрации/кошелька: для Solana и Arweave дать отдельные действия `Пополнить`, которые ведут на международный сервис покупки криптовалюты с карты и помогают пользователю скопировать адрес кошелька.
|
|
||||||
|
|
||||||
## Пользовательский сценарий
|
|
||||||
|
|
||||||
1. Пользователь видит адрес кошелька Solana или Arweave.
|
|
||||||
2. Нажимает `Пополнить`.
|
|
||||||
3. Открывается промежуточное окно с инструкцией:
|
|
||||||
- сейчас пользователь перейдёт на страницу покупки/пополнения;
|
|
||||||
- нужно указать или проверить адрес кошелька;
|
|
||||||
- после оплаты нужно закрыть внешнюю страницу и вернуться назад;
|
|
||||||
- Solana обычно приходит быстро, ориентир 10-15 секунд после подтверждения сети;
|
|
||||||
- Arweave может идти дольше, точное время нужно уточнить по выбранному сервису.
|
|
||||||
4. В окне есть кнопки:
|
|
||||||
- `Скопировать адрес и перейти`;
|
|
||||||
- `Перейти без копирования`.
|
|
||||||
5. Для Solana и Arweave используются разные окна/инструкции и, возможно, разные внешние ссылки.
|
|
||||||
|
|
||||||
## Что нужно сделать
|
|
||||||
|
|
||||||
1. Найти текущий экран, где показываются кошельки при регистрации и пополнении.
|
|
||||||
2. Найти текущую ссылку покупки Arweave, если она уже есть в UI.
|
|
||||||
3. Выбрать международный сервис покупки Solana с карты, не российский.
|
|
||||||
4. Проверить, поддерживает ли сервис deep link с предзаполненным адресом кошелька.
|
|
||||||
5. Если deep link невозможен, реализовать промежуточное окно с копированием адреса.
|
|
||||||
6. Добавить отдельные действия для Solana и Arweave.
|
|
||||||
7. Сделать текст инструкции коротким и понятным.
|
|
||||||
8. Проверить, что адрес копируется в буфер обмена в браузере.
|
|
||||||
9. Проверить мобильный сценарий и desktop-сценарий.
|
|
||||||
|
|
||||||
## Вопросы перед реализацией
|
|
||||||
|
|
||||||
1. Какой сервис покупки Solana использовать: тот же провайдер, что для Arweave, или другой международный on-ramp.
|
|
||||||
2. Нужно ли разрешать покупку только SOL или также USDC/SPL-токены на Solana.
|
|
||||||
3. Где именно показывать кнопку `Пополнить`: только регистрация, настройки кошелька или оба места.
|
|
||||||
4. Нужно ли показывать предупреждение о комиссиях и стороннем сервисе.
|
|
||||||
5. Нужно ли открывать внешнюю страницу в новой вкладке или в текущем окне.
|
|
||||||
6. Нужно ли логировать факт нажатия `Пополнить` на сервере.
|
|
||||||
7. Какой точный текст использовать для времени прихода Arweave.
|
|
||||||
|
|
||||||
## Риски и ограничения
|
|
||||||
|
|
||||||
- On-ramp-сервисы меняют ссылки и параметры, поэтому deep link нужно проверять перед реализацией.
|
|
||||||
- Clipboard API может требовать HTTPS и пользовательский жест.
|
|
||||||
- Нельзя обещать точное время поступления средств: лучше писать ориентир и зависимость от сети/провайдера.
|
|
||||||
- Внешний сервис может быть недоступен в отдельных странах или для отдельных карт.
|
|
||||||
|
|
||||||
## Документы, которые обновить при реализации
|
|
||||||
|
|
||||||
- Документацию UI/кошельков, если такая есть.
|
|
||||||
- `Dev_Docs/Pending_Features/` - добавить файл ручной проверки после реализации.
|
|
||||||
- `Dev_Docs/API/`, только если появится новый серверный API или логирование.
|
|
||||||
|
|
||||||
## Минимальная проверка
|
|
||||||
|
|
||||||
1. На Solana-кошельке открывается правильное окно пополнения.
|
|
||||||
2. Кнопка `Скопировать адрес и перейти` копирует Solana-адрес и открывает внешний сервис.
|
|
||||||
3. Кнопка `Перейти без копирования` открывает внешний сервис без копирования.
|
|
||||||
4. Аналогичный сценарий работает для Arweave.
|
|
||||||
5. На мобильном экране текст и кнопки не перекрываются.
|
|
||||||
6. Возврат назад в приложение не ломает состояние регистрации/кошелька.
|
|
||||||
@ -1,154 +0,0 @@
|
|||||||
# Деривация секрета и ключей SHiNE (формулы)
|
|
||||||
|
|
||||||
> **Статус: ИСТОЧНИК ИСТИНЫ (single source of truth) по конкретной деривации.**
|
|
||||||
> Этот файл описывает, как из пароля получается секрет и как из секрета выводятся
|
|
||||||
> все ключи (root, blockchain, device/Solana, homeserver) — формулами, байт-в-байт.
|
|
||||||
> Если в коде меняется деривация (формула секрета, параметры Argon2id, соль, формула
|
|
||||||
> ключа, разделитель `|`, набор/имена суффиксов, формат homeserver-ключа, связь
|
|
||||||
> dev-ключ ↔ Solana-адрес) — **в том же изменении обязательно править этот документ**.
|
|
||||||
> Роли и назначение ключей описаны отдельно в `Dev_Docs/Keys/README.md` (архитектура).
|
|
||||||
> Здесь — только механика. Документ намеренно краткий.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Секрет (masterSecret)
|
|
||||||
|
|
||||||
`masterSecret` — 32 байта. Два источника:
|
|
||||||
|
|
||||||
**А. Из пароля пользователя (основной путь, UI).**
|
|
||||||
|
|
||||||
```
|
|
||||||
login = trim(lowercase(login))
|
|
||||||
salt = SHA-256("shine-auth-v2|login=" + login + "|suffix=master.secret")[0..16) // первые 16 байт
|
|
||||||
material = utf8(login + "\n" + password)
|
|
||||||
masterSecret(32) = Argon2id(material, salt, t=2, m=65536 KiB, p=1, dkLen=32)
|
|
||||||
```
|
|
||||||
|
|
||||||
- Параметры Argon2id фиксированы: `t=2`, `m=65536` (64 МиБ), `p=1`, `dkLen=32`.
|
|
||||||
- Логин входит и в соль, и в начало `material` (склейка через `\n`).
|
|
||||||
- Пустой пароль **запрещён**: легаси-fallback без Argon2 удалён, `deriveMasterSecretFromPassword` бросает ошибку на пустом пароле, а форма регистрации в UI блокирует пустой пароль (`register-view.js`).
|
|
||||||
|
|
||||||
**Б. Случайный (прошивка ESP32, новый аккаунт без пароля).**
|
|
||||||
|
|
||||||
```
|
|
||||||
masterSecret(32) = 32 случайных байта (esp_random) // хранится на устройстве как base58
|
|
||||||
```
|
|
||||||
|
|
||||||
Дальше деривация ключей одинакова независимо от источника секрета.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Производные ключи
|
|
||||||
|
|
||||||
Все ключи выводятся из `masterSecret` по **одной формуле**, отличается только суффикс:
|
|
||||||
|
|
||||||
```
|
|
||||||
material = base64_std(masterSecret) + "|" + <суффикс>
|
|
||||||
seed(32) = SHA-256(material)
|
|
||||||
(pub, priv) = Ed25519_keypair_from_seed(seed)
|
|
||||||
```
|
|
||||||
|
|
||||||
- `base64_std` — стандартный base64 (не url-safe).
|
|
||||||
- Разделитель — символ `|`.
|
|
||||||
- Суффиксы значимы байт-в-байт (регистр и точки важны).
|
|
||||||
|
|
||||||
| Ключ | Суффикс | Назначение (кратко) |
|
|
||||||
|------|---------|---------------------|
|
|
||||||
| root | `root.key` | Личность. Подписывает unsigned-часть PDA-записи (`RootKeyBlock`). |
|
|
||||||
| blockchain | `bch.key` | Подписывает `LastBlockState` персонального блокчейна (`blockchain_public_key`). |
|
|
||||||
| device / **Solana** | `client.key` | Ключ устройства = Solana-ключ. Fee payer и подпись Solana-транзакций; адрес кошелька = `base58(clientPub)`. См. §3. |
|
|
||||||
| homeserver | `homeserver.key:<имя>` | Ключ homeserver-устройства, по одному на каждый homeserver (различитель — имя). См. §4. |
|
|
||||||
|
|
||||||
Полные роли каждого ключа — в `Dev_Docs/Keys/README.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Solana-ключ
|
|
||||||
|
|
||||||
Отдельного «солана-ключа» нет. На Solana работают два ключа:
|
|
||||||
|
|
||||||
- **`client.key` (device) — пополняемый кошелёк и fee payer.** Solana-адрес = `base58(clientPub)`.
|
|
||||||
Этим ключом оплачиваются и подписываются `create_user_pda` / `update_user_pda`.
|
|
||||||
Пополнять SOL нужно именно на этот адрес.
|
|
||||||
- **`root.key` — авторитет записи**, подписывает unsigned-часть PDA через Ed25519-инструкцию, но **не** является fee payer.
|
|
||||||
|
|
||||||
Соответствует формату PDA `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` §2.1
|
|
||||||
(«create/update оплачиваются с `client_key`», «root_key — не fee payer»).
|
|
||||||
|
|
||||||
Кратко про роли на Solana: `root.key` — это **главный (master) ключ**: им управляют PDA-записью
|
|
||||||
(`create/update`) и через это можно заменить все остальные ключи; `client.key` — это **пополняемый
|
|
||||||
кошелёк и плательщик комиссий**. Полное описание ролей — `Dev_Docs/Keys/README.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Ключи homeserver
|
|
||||||
|
|
||||||
У пользователя может быть несколько homeserver-ов. Каждый имеет **своё имя** и **свой приватный ключ**,
|
|
||||||
выведенный из секрета по той же формуле с именованным суффиксом:
|
|
||||||
|
|
||||||
```
|
|
||||||
suffix = "homeserver.key:" + <имя homeserver> // имя по умолчанию: "homeserver1"
|
|
||||||
material = base64_std(masterSecret) + "|" + suffix
|
|
||||||
seed(32) = SHA-256(material)
|
|
||||||
(pub, priv) = Ed25519_keypair_from_seed(seed)
|
|
||||||
```
|
|
||||||
|
|
||||||
Пример для двух homeserver-ов:
|
|
||||||
|
|
||||||
```
|
|
||||||
homeserver.key:home-a -> ключ A
|
|
||||||
homeserver.key:home-b -> ключ B
|
|
||||||
```
|
|
||||||
|
|
||||||
Публичный ключ homeserver-а публикуется в `SessionsBlock` пользовательской PDA как
|
|
||||||
`session_pub_key` с `session_type = 100`, имя — в `session_name` (формат PDA §13).
|
|
||||||
|
|
||||||
> Это переименование прежней схемы `subserver.key:<имя>` → `homeserver.key:<имя>`.
|
|
||||||
> Термин «саб-сервер» по проекту заменяется на «homeserver».
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Где это в коде
|
|
||||||
|
|
||||||
### Деривация секрета и ключей (UI, каноническая)
|
|
||||||
- `shine-UI/js/services/crypto-utils.js`
|
|
||||||
- секрет из пароля: `makeArgon2Salt`, `deriveMasterSecretArgon2id`, `deriveMasterSecretFromPassword` (~129–218);
|
|
||||||
- ключ из секрета: `deriveEd25519FromMasterSecret` (~220).
|
|
||||||
- `shine-UI/js/services/auth-service.js` — набор root/bch/dev из `masterSecret` (~732–758).
|
|
||||||
- `shine-UI/server-ui/js/server-ui-shared.js` — те же root/bch/dev для серверного UI (~147–160).
|
|
||||||
|
|
||||||
### Solana-ключ / адрес кошелька (UI)
|
|
||||||
- `shine-UI/js/pages/registration-payment-view.js` — `deriveUserWalletAddress`: адрес = `base58(clientPub)` (~113).
|
|
||||||
- `shine-UI/js/pages/topup-view.js` — `clientWalletAddressFromBundle`: тот же канонический адрес из `preGeneratedKeyBundle.clientPair`.
|
|
||||||
Прежний расходящийся путь `deriveWalletFromPassword` (прямой Argon2 по `client.key`, мимо `masterSecret`) удалён.
|
|
||||||
|
|
||||||
### Деривация ключей (прошивка ESP32)
|
|
||||||
- `ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/main-device/shine_homeserver_main/shine_homeserver_main.ino`
|
|
||||||
- основной скетч ESP32-проекта `SHiNE`; `deriveKeysFromMasterSecret` (~782), `restoreDerivedKeysFromSecret` (~806), `deriveFreshSecretAndWallet` (~829);
|
|
||||||
- регистрация/подпись Solana: `registerHomeserverOnSolana` (~1182), `signMessageEd25519` (~1147).
|
|
||||||
- `ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/main-device/shine_homeserver_ui/shine_homeserver_ui.ino`
|
|
||||||
- старый тестовый вариант; оставлен как legacy-скетч для сравнения и диагностики.
|
|
||||||
|
|
||||||
### Формат PDA (куда попадают ключи)
|
|
||||||
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
|
|
||||||
— `RootKeyBlock` §6, `ClientKeyBlock` §7, `blockchain_public_key` §9, `SessionsBlock`/`session_type=100` §13, оплата §2.1.
|
|
||||||
|
|
||||||
### Сервер (тестовый seed)
|
|
||||||
- `SHiNE-server/src/test/java/test/it/cases/SeedDataPopulationHelper.java` `deriveKeysFromPassword` (~246) —
|
|
||||||
выводит ключи как `Ed25519(SHA-256(base64(SHA-256(password)) + suffix))`, **без** Argon2 и **без** разделителя `|`.
|
|
||||||
Это **не баг**, а точное повторение легаси-пути UI `derivePasswordSeed` (для пустого пароля), у которого тоже нет `|`.
|
|
||||||
С современным путём `masterSecret`-bundle (Argon2 + `base64(secret)|suffix`) он **не совпадает** by design.
|
|
||||||
Если потребуется, чтобы seed совпадал с реальными клиентами на Argon2 — нужно отдельно портировать
|
|
||||||
Argon2id+masterSecret в Java (на сервере Argon2 сейчас нет). Простое добавление `|` было бы **неверным**:
|
|
||||||
сломало бы совпадение с легаси-путём и всё равно не дало бы совпадения с Argon2-путём.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Правило синхронизации (обязательно)
|
|
||||||
|
|
||||||
1. Этот документ — источник истины по деривации секрета и ключей.
|
|
||||||
2. Любое изменение кода, затрагивающее формулу секрета, параметры Argon2id, соль, формулу ключа,
|
|
||||||
разделитель `|`, набор/имена суффиксов, формат homeserver-ключа или связь dev-ключ ↔ Solana-адрес —
|
|
||||||
**обязательно** отражать здесь в том же изменении.
|
|
||||||
3. Пункты, помеченные ⚠️, — это долг к устранению, а не норма.
|
|
||||||
4. Нельзя сознательно оставлять код и этот документ в рассинхроне без отдельной явной договорённости.
|
|
||||||
@ -1,176 +0,0 @@
|
|||||||
# Ключи SHiNE
|
|
||||||
|
|
||||||
Этот документ описывает роли ключей в SHiNE и их связь с Solana, персональным блокчейном, личными сообщениями, сессиями и будущими аппаратными устройствами.
|
|
||||||
|
|
||||||
Документ является архитектурной справкой. Он не меняет текущие форматы API, DM-блоков или блокчейна сам по себе.
|
|
||||||
|
|
||||||
## Коротко
|
|
||||||
|
|
||||||
В SHiNE у пользователя есть несколько уровней ключей:
|
|
||||||
|
|
||||||
- `root key` - главный (master) ключ пользователя: тот, кто им владеет, управляет пользовательской PDA в Solana и может заменить все остальные ключи. Это не пополняемый кошелёк (комиссии платит `client key`).
|
|
||||||
- `blockchain key` - ключ записи в персональный SHiNE-блокчейн пользователя.
|
|
||||||
- `client key` - общий ключ пользовательских устройств для повседневной работы, звонков, DM и мелких платежей.
|
|
||||||
- `session key` - ключ конкретной сессии или конкретного устройства для авторизации на сервере.
|
|
||||||
|
|
||||||
Главная идея: самые важные ключи можно держать на доверенном серверном или аппаратном устройстве, а обычные клиентские устройства получают только ключи, нужные для текущей работы.
|
|
||||||
|
|
||||||
## `root key`
|
|
||||||
|
|
||||||
`root key` - главный ключ пользователя.
|
|
||||||
|
|
||||||
Назначение:
|
|
||||||
|
|
||||||
- регистрация пользователя в Solana;
|
|
||||||
- создание и обновление пользовательской PDA-записи;
|
|
||||||
- вызов критически важных Solana-функций;
|
|
||||||
- изменение главных настроек пользователя;
|
|
||||||
- управление остальными ключами;
|
|
||||||
- подтверждение операций, которые должны иметь максимальный уровень доверия.
|
|
||||||
|
|
||||||
`root key` — это **главный (master) ключ** в следующем смысле: зная `root key`, можно управлять пользовательской PDA-записью в Solana (`create_user_pda` / `update_user_pda`) и тем самым **заменить все остальные ключи** пользователя (device, blockchain, homeserver). Поэтому компрометация `root key` равносильна компрометации всей личности пользователя.
|
|
||||||
|
|
||||||
Важно не путать авторитет и кошелёк: `root key` — это авторитет над PDA-записью, а **SOL-комиссии за create/update платит `client key`** (он же fee payer и адрес для пополнения). Подробнее о том, какой ключ за что отвечает на Solana, — в `Dev_Docs/Keys/DERIVATION.md`, §3.
|
|
||||||
|
|
||||||
## `blockchain key`
|
|
||||||
|
|
||||||
`blockchain key` - ключ записи в персональный SHiNE-блокчейн пользователя.
|
|
||||||
|
|
||||||
Назначение:
|
|
||||||
|
|
||||||
- подпись записей в персональном блокчейне пользователя;
|
|
||||||
- подтверждение действий, которые должны попасть в SHiNE-блокчейн;
|
|
||||||
- разделение полномочий между главным Solana-ключом и ключом ежедневной записи.
|
|
||||||
|
|
||||||
У пользователя может быть несколько персональных блокчейнов или веток. При смене `blockchain key` фактически создаётся новая ветка записи:
|
|
||||||
|
|
||||||
- `username-001` - первая ветка;
|
|
||||||
- `username-002` - вторая ветка;
|
|
||||||
- `username-003` - третья ветка.
|
|
||||||
|
|
||||||
Рабочая логика по умолчанию должна использовать последнюю актуальную ветку. Старые ветки остаются читаемыми и показывают историю смены ключей.
|
|
||||||
|
|
||||||
## `client key`
|
|
||||||
|
|
||||||
`client key` - общий ключ, который знают доверенные устройства пользователя.
|
|
||||||
|
|
||||||
Назначение:
|
|
||||||
|
|
||||||
- повседневные входящие и исходящие личные сообщения;
|
|
||||||
- звонки и связанные с ними сообщения;
|
|
||||||
- self-messages, то есть внутренние сообщения пользователя самому себе;
|
|
||||||
- мелкие Solana-расходы на текущие операции;
|
|
||||||
- derivation Arweave-кошелька;
|
|
||||||
- оплата или подготовка добавления данных в Arweave-кошелек по отдельному протоколу.
|
|
||||||
|
|
||||||
Arweave-кошелёк должен выводиться из `client key` по протоколу:
|
|
||||||
|
|
||||||
- `Dev_Docs/Протоколы/SHINE_ARWEAVE_DERIVATION_V1.md`
|
|
||||||
|
|
||||||
Если пользователь теряет только `client key`, в худшем случае ломается повседневная переписка и доступ конкретных устройств к ежедневным операциям. `root key` и `blockchain key` при правильной архитектуре остаются отдельно защищёнными.
|
|
||||||
|
|
||||||
## `session key`
|
|
||||||
|
|
||||||
`session key` - уникальный ключ конкретной сессии или устройства.
|
|
||||||
|
|
||||||
Возможные форматы:
|
|
||||||
|
|
||||||
- `Ed25519` - предпочтительный современный вариант;
|
|
||||||
- `RSA` - legacy-вариант, полезный для устройств, где системное защищённое хранилище хорошо поддерживает RSA-ключи и не позволяет извлекать приватный ключ.
|
|
||||||
|
|
||||||
Назначение:
|
|
||||||
|
|
||||||
- авторизация сессии на сервере;
|
|
||||||
- привязка устройства к пользователю;
|
|
||||||
- подтверждение запросов от конкретной сессии;
|
|
||||||
- доступ к зашифрованному `client key` после успешной авторизации.
|
|
||||||
|
|
||||||
Одна и та же сессия может быть пригодна для подключения к нескольким серверам пользователя, если архитектура конкретного пользователя это допускает.
|
|
||||||
|
|
||||||
У сессии должны быть:
|
|
||||||
|
|
||||||
- имя сессии;
|
|
||||||
- тип сессии;
|
|
||||||
- публичная часть ключа;
|
|
||||||
- ссылка на пользователя;
|
|
||||||
- информация о сервере или серверах, которым эта сессия доверена.
|
|
||||||
|
|
||||||
Имя сессии может создаваться автоматически из названия устройства и короткого случайного идентификатора, например `Android-a1b2c3`, `Ubuntu-f47a90`. Пользователь может переименовать сессию.
|
|
||||||
|
|
||||||
## Типы сессий
|
|
||||||
|
|
||||||
Базовые типы:
|
|
||||||
|
|
||||||
- обычная пользовательская сессия;
|
|
||||||
- серверная сессия;
|
|
||||||
- аппаратная или доверенная сессия с доступом к расширенным ключам.
|
|
||||||
|
|
||||||
Обычное устройство обычно имеет:
|
|
||||||
|
|
||||||
- собственный `session key`;
|
|
||||||
- зашифрованный `client key`, который открывается после авторизации;
|
|
||||||
- доступ к DM, звонкам и обычным пользовательским операциям.
|
|
||||||
|
|
||||||
Доверенное серверное или аппаратное устройство может иметь:
|
|
||||||
|
|
||||||
- `root key`;
|
|
||||||
- `blockchain key`;
|
|
||||||
- `client key`;
|
|
||||||
- собственный `session key`.
|
|
||||||
|
|
||||||
Такая сессия может подписывать операции повышенной важности по запросам пользователя.
|
|
||||||
|
|
||||||
## Внутренние self-messages
|
|
||||||
|
|
||||||
Self-message - это сообщение пользователя самому себе.
|
|
||||||
|
|
||||||
Такие сообщения нужны, чтобы обычное устройство могло попросить доверенное устройство выполнить действие:
|
|
||||||
|
|
||||||
- подписать запись `blockchain key` и передать её в SHiNE-блокчейн;
|
|
||||||
- подписать изменение настройки через `root key`;
|
|
||||||
- обновить ключи;
|
|
||||||
- сохранить внутреннюю команду или настройку;
|
|
||||||
- отправить сообщение другому пользователю с сохранением копии себе;
|
|
||||||
- сохранить сообщение только себе.
|
|
||||||
|
|
||||||
Важно: self-message не является публичной командой сервера. Это пользовательская внутренняя команда, которую сервер или доверенное устройство обрабатывает в рамках прав конкретного пользователя.
|
|
||||||
|
|
||||||
## Шифрование входящих сообщений
|
|
||||||
|
|
||||||
Входящее сообщение может быть зашифровано:
|
|
||||||
|
|
||||||
- `client key`;
|
|
||||||
- `session key`;
|
|
||||||
- отдельным ключом конкретного чата;
|
|
||||||
- другим ключом, который уже известен клиенту.
|
|
||||||
|
|
||||||
В сообщении не должно быть лишнего раскрытия того, каким именно ключом оно зашифровано. Клиент пробует расшифровать сообщение доступными ключами по порядку. Если расшифровка не удалась, сообщение остаётся непонятным для этого устройства.
|
|
||||||
|
|
||||||
## Копии сообщений
|
|
||||||
|
|
||||||
Для отправки сообщений нужны несколько режимов:
|
|
||||||
|
|
||||||
- сообщение другому пользователю с исходящей копией себе;
|
|
||||||
- сообщение другому пользователю без локальной исходящей копии;
|
|
||||||
- сообщение только себе.
|
|
||||||
|
|
||||||
Это должно позволить строить обычные DM, внутренние команды, личные заметки и зашифрованные пользовательские чаты поверх одной общей модели сообщений.
|
|
||||||
|
|
||||||
## Связанные документы
|
|
||||||
|
|
||||||
- `Dev_Docs/Keys/DERIVATION.md` - **источник истины по конкретной деривации** секрета и ключей (формулы Argon2id, `base64|suffix→SHA-256→Ed25519`, суффиксы `root.key`/`bch.key`/`client.key`/`homeserver.key:<имя>`, Solana-ключ, ссылки на код).
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md` - текущая документация личных сообщений.
|
|
||||||
- `Dev_Docs/Blockchain/README.md` - точка входа по форматам SHiNE-блокчейна.
|
|
||||||
- `Dev_Docs/Solana_Architecture/README.md` - архитектура Solana-программ, PDA-счетов, DAO и движения средств.
|
|
||||||
- `Dev_Docs/Инициализация_Solana_регистрации/README.md` - деплой и первичная инициализация Solana-регистрации.
|
|
||||||
- `Dev_Docs/Протоколы/SHINE_ARWEAVE_DERIVATION_V1.md` - derivation Arweave-кошелька из `client key`.
|
|
||||||
|
|
||||||
## Что нужно уточнить перед реализацией
|
|
||||||
|
|
||||||
- точный формат записи списка ключей в Solana PDA;
|
|
||||||
- как именно обозначать активную ветку персонального блокчейна;
|
|
||||||
- какие операции требуют `root key`, а какие достаточно подписывать `blockchain key`;
|
|
||||||
- формат self-message-команд;
|
|
||||||
- порядок перебора ключей при расшифровке входящих сообщений;
|
|
||||||
- правила ротации `client key` и восстановления доступа после потери устройства;
|
|
||||||
- какие типы серверных и аппаратных сессий нужны в первой реализации.
|
|
||||||
@ -1,22 +0,0 @@
|
|||||||
# Быстрое скрытие экрана звонка и остановка гудков при отклонении
|
|
||||||
|
|
||||||
- краткое описание фичи:
|
|
||||||
- Исправлена нижняя подпись вкладки личных сообщений на `личные`.
|
|
||||||
- Исправлена логика звонка, когда одна из входящих сессий отклоняет вызов до принятия: исходящая сессия теперь должна прекращать гудки даже если ранее `RINGING` пришёл от другой входящей сессии.
|
|
||||||
- На устройстве, где пользователь нажимает отмену/сброс звонка, экран вызова теперь скрывается сразу локально, без ожидания сетевого ответа.
|
|
||||||
|
|
||||||
- что именно проверять:
|
|
||||||
- В нижней панели с 5 кнопками подпись первой кнопки должна отображаться как `личные`.
|
|
||||||
- Сценарий: один пользователь звонит, у второго входящий вызов приходит на несколько устройств; на любом одном входящем устройстве нажать `Сбросить`.
|
|
||||||
- Проверить, что у звонящего сразу прекращаются гудки и экран вызова корректно завершается.
|
|
||||||
- Проверить, что на устройстве, где нажали `Сбросить` или `Положить трубку`, overlay звонка исчезает сразу, без заметной задержки.
|
|
||||||
- Проверить, что после принятия звонка на одном устройстве поздние отмены с других устройств не ломают уже выбранную пару соединения.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- Подпись в нижней панели корректная.
|
|
||||||
- При отклонении входящего звонка любым устройством звонящего не оставляет в состоянии бесконечных гудков.
|
|
||||||
- Локальный экран звонка скрывается мгновенно после нажатия кнопки отмены.
|
|
||||||
- Уже зафиксированный сценарий соединения после `ACCEPT` не сбивается другими сессиями.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- `pending`
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
# Отключение устаревшего TURN-узла `45.136.124.227`
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- из конфигурации звонков убран устаревший TURN-узел `45.136.124.227:3478`;
|
|
||||||
- основным и единственным выдаваемым TURN-узлом оставлен `93.170.12.154:3478`.
|
|
||||||
- что проверять:
|
|
||||||
- сделать несколько тестовых звонков между разными устройствами/сетями;
|
|
||||||
- убедиться, что звонок доходит до стадии соединения и появляется звук;
|
|
||||||
- убедиться, что в логах `CallDeliveryReport` больше не фигурирует `45.136.124.227`.
|
|
||||||
- ожидаемый результат:
|
|
||||||
- клиентам больше не выдаётся устаревший TURN-адрес;
|
|
||||||
- звонки не заваливаются из-за попыток использовать отключённый TURN-узел.
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,15 +0,0 @@
|
|||||||
# Фикс самообрыва звонка из-за `stop_call` push своей же сессии
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- исправлена ситуация, когда активный звонок мог оборваться сразу после соединения;
|
|
||||||
- причина была в том, что `stop_call` push, предназначенный для других сессий того же пользователя, обрабатывался и в исходной сессии.
|
|
||||||
- что проверять:
|
|
||||||
- открыть несколько вкладок/устройств одного пользователя;
|
|
||||||
- принять звонок на одной сессии;
|
|
||||||
- убедиться, что активная сессия не обрывает звонок сразу после соединения;
|
|
||||||
- убедиться, что лишние сессии при этом закрывают свой локальный экран звонка.
|
|
||||||
- ожидаемый результат:
|
|
||||||
- звонок не завершается сразу после `call_connected`;
|
|
||||||
- `accepted_on_other_device` и связанные `stop_call` события больше не убивают исходную активную сессию.
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,16 +0,0 @@
|
|||||||
# Фикс привязки call push к целевой sessionId
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- push-события `incoming_call` и `stop_call` теперь помечаются целевой `sessionId`;
|
|
||||||
- UI и service worker обрабатывают call push только для своей целевой сессии;
|
|
||||||
- `stop_call` для лишних сессий закрывает локальный экран тихо, без обратных сигналов и без лишних тех-сообщений.
|
|
||||||
- что проверять:
|
|
||||||
- держать несколько сессий одного пользователя в одном браузере/на одном origin;
|
|
||||||
- позвонить этому пользователю и убедиться, что входящий экран закрывается корректно только на целевых сессиях;
|
|
||||||
- после `ACCEPT` одной сессии остальные должны тихо убрать экран вызова и не ломать выбранную пару;
|
|
||||||
- после отмены входящей сессией исходящая сессия должна централизованно завершить сценарий.
|
|
||||||
- ожидаемый результат:
|
|
||||||
- push одного session endpoint больше не влияет на чужие сессии этого же origin;
|
|
||||||
- исчезают ложные `stop_call_push:accepted_on_other_device` и `terminal_call_signal_150` на неправильных сессиях.
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,24 +0,0 @@
|
|||||||
# ESP32 homeserver: заявки на подключение устройств
|
|
||||||
|
|
||||||
- краткое описание фичи:
|
|
||||||
- на ESP32 homeserver в `SETTINGS` добавлен первый пункт `Device requests`, который появляется только после авторизации homeserver в SHiNE;
|
|
||||||
- экран показывает список активных pairing-заявок, позволяет открыть каждую заявку и подтвердить или отклонить её;
|
|
||||||
- формат кода подключения изменён на `10` цифр и показывается как `5` пар.
|
|
||||||
|
|
||||||
- что проверять:
|
|
||||||
- на обычном клиенте и в wallet-plugin код отображается как `XX XX XX XX XX`;
|
|
||||||
- на доверенном веб-клиенте экран `Подключить по коду` показывает все активные заявки без поля ручного ввода;
|
|
||||||
- на ESP32 после успешной homeserver-авторизации в `SETTINGS` появляется пункт `Device requests` первым;
|
|
||||||
- `REFRESH` реально загружает активные заявки;
|
|
||||||
- на экране видно две плитки, список листается вертикально;
|
|
||||||
- client-session заявка после `YES` подключается с передачей только `client key`;
|
|
||||||
- wallet-session заявка после `YES` подключается без передачи ключей, через выпуск отдельной wallet-session;
|
|
||||||
- `NO` отклоняет заявку и она исчезает из списка активных.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- все три клиента используют единый формат кода;
|
|
||||||
- активные заявки видны без ручного ввода кода;
|
|
||||||
- ESP32 может одобрять и отклонять живые pairing-заявки пользователя.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,22 +0,0 @@
|
|||||||
# Тестовые deploy-контуры `test2.shineup.me` и `test.shineup.me`
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- default deploy-задачи `deployServer` и `deployUI` переведены на основной тестовый сервер `test2.shineup.me`;
|
|
||||||
- production-задачи вынесены в `deployServerProduction` и `deployUIProduction`;
|
|
||||||
- `test.shineup.me` оставлен как резервный тестовый сервер без обычного deploy по умолчанию.
|
|
||||||
|
|
||||||
- что проверять:
|
|
||||||
- `./gradlew deployServer` и `./gradlew deployUI` действительно направлены на `test2.shineup.me`;
|
|
||||||
- `./gradlew deployServerProduction` и `./gradlew deployUIProduction` больше не используются как default;
|
|
||||||
- `https://test2.shineup.me` открывает UI;
|
|
||||||
- `wss://test2.shineup.me/ws` отвечает;
|
|
||||||
- на `test2.shineup.me` после deploy есть копия продовой `shine.sqlite` и `.bch`.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- default deploy идёт только на `test2.shineup.me`;
|
|
||||||
- production `shineup.me` меняется только после отдельного подтверждения;
|
|
||||||
- `test.shineup.me` остаётся резервным тестовым сервером;
|
|
||||||
- тестовый deploy не гоняет удалённые тесты и не создаёт пустую БД.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,25 +0,0 @@
|
|||||||
# Регистрация: FAQ и режим пароля из 12 слов
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- на экране регистрации добавлен блок частых вопросов с переходом на отдельный экран справки;
|
|
||||||
- добавлен альтернативный режим ввода пароля через 12 полей-слов в кошелёчном формате, которые склеиваются в одну строку без изменения API;
|
|
||||||
- такой же режим добавлен и на экран входа по логину и паролю.
|
|
||||||
|
|
||||||
- что проверять:
|
|
||||||
- на стартовом экране открыть `Зарегистрироваться`;
|
|
||||||
- убедиться, что внизу экрана есть кнопки FAQ;
|
|
||||||
- открыть несколько вопросов и проверить возврат обратно на регистрацию;
|
|
||||||
- включить галочку `Представить пароль в виде 12 слов`;
|
|
||||||
- убедиться, что появляется сетка с нумерованными полями в 3 колонки;
|
|
||||||
- ввести часть слов, перейти дальше и проверить, что шаг подтверждения и генерация ключей работают;
|
|
||||||
- выключить галочку и проверить, что пароль остаётся собранным в одном поле;
|
|
||||||
- открыть экран входа по паролю и повторить те же проверки для режима `12 слов`;
|
|
||||||
- пройти регистрацию до шага оплаты без ошибок интерфейса.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- FAQ открывается отдельным экраном и содержит понятные ответы;
|
|
||||||
- режим `12 слов` не ломает регистрацию и вход и даёт тот же поток, что и обычный пароль;
|
|
||||||
- пароль не отправляется в новом формате, а продолжает использоваться как одна строка.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,25 +0,0 @@
|
|||||||
# Временная бесплатная загрузка аватара в Arweave
|
|
||||||
|
|
||||||
- краткое описание фичи:
|
|
||||||
Добавлены два временных `Test...` API для бесплатной загрузки маленьких аватаров в Arweave через серверный кошелёк с лимитом `3` загрузки на пользователя. В UI мастера смены аватара добавлен пункт `Залить аватар бесплатно`.
|
|
||||||
|
|
||||||
- что именно проверять:
|
|
||||||
1. Пользователь с активной сессией открывает редактирование профиля.
|
|
||||||
2. По нажатию на аватар открывается мастер `Сменить аватар`.
|
|
||||||
3. В мастере есть пункт `Залить аватар бесплатно`.
|
|
||||||
4. До первой загрузки UI показывает остаток `3 из 3`.
|
|
||||||
5. Маленький JPEG/PNG/WebP после уменьшения до файла <= `128 KB` успешно уходит через `TestUploadFreeAvatar`.
|
|
||||||
6. После загрузки приходит `txId`, и аватар сохраняется в профиль как `avatar.ar`.
|
|
||||||
7. Остаток уменьшается: `2`, `1`, `0`.
|
|
||||||
8. На четвёртой попытке сервер отвечает понятной ошибкой про исчерпанный бесплатный лимит.
|
|
||||||
9. Если итоговый уменьшенный файл всё ещё > `128 KB`, UI не отправляет его и показывает понятную ошибку.
|
|
||||||
10. Если серверный Arweave JWK/path не настроен, UI получает понятную ошибку временной функции.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- первые 3 маленькие аватарки загружаются через серверный Arweave-кошелёк;
|
|
||||||
- после каждой успешной загрузки `ava` в профиле указывает на новый `txId`;
|
|
||||||
- после исчерпания лимита дальнейшая бесплатная загрузка блокируется без записи в профиль;
|
|
||||||
- обычная загрузка через свой Arweave-кошелёк продолжает работать отдельно.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
pending
|
|
||||||
@ -1,19 +0,0 @@
|
|||||||
# Исправление chatId личных сообщений через lowercase
|
|
||||||
|
|
||||||
- краткое описание фичи:
|
|
||||||
- В клиентском UI SHiNE для личных сообщений технический `chatId` теперь канонизируется через `trim().toLowerCase()` при приёме DM, открытии чата и восстановлении сообщений из IndexedDB.
|
|
||||||
- Цель: исключить рассинхрон, когда unread-индикатор есть, а входящие сообщения конкретного собеседника не видны из-за разного регистра логина.
|
|
||||||
|
|
||||||
- что именно проверять:
|
|
||||||
- Отправить личные сообщения между двумя пользователями, у одного из которых логин отображается с заглавными буквами.
|
|
||||||
- Убедиться, что входящие сообщения показываются внутри открытого чата, а не только в общем unread-индикаторе.
|
|
||||||
- Перезагрузить страницу и проверить, что история чата после гидрации из IndexedDB остаётся в одном диалоге.
|
|
||||||
- Проверить, что переход в чат из списка диалогов и из графа связей открывает тот же диалог без дублирования.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- Все сообщения одного собеседника попадают в один и тот же DM-чат независимо от регистра логина.
|
|
||||||
- Общий unread, список диалогов и содержимое открытого чата совпадают между собой.
|
|
||||||
- После перезагрузки UI не появляется отдельный дубль диалога с тем же логином в другом регистре.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,27 +0,0 @@
|
|||||||
# ESP32 выбор кошелька и wallet RPC для browser extension
|
|
||||||
|
|
||||||
- краткое описание:
|
|
||||||
- в ESP32 заменён домашний блок `баланс + QR` на единый вход в экран кошелька;
|
|
||||||
- добавлен выбор активного кошелька `ClientKey / RootKey / Custom`;
|
|
||||||
- для browser extension добавлен первый RPC `get_wallet_public_key` через существующий `wallet-session` и `CallSignalToSession`;
|
|
||||||
- в popup расширения добавлен запрос текущего кошелька и копирование `publicKeyBase58`.
|
|
||||||
|
|
||||||
- что проверять:
|
|
||||||
- на ESP32 после ввода секрета на главном экране видна кнопка `Кошелёк: ...`;
|
|
||||||
- экран `WALLET` открывается и показывает текущий тип кошелька;
|
|
||||||
- экран `WALLET_SELECT` переключает `ClientKey`, `RootKey` и `Custom`;
|
|
||||||
- для `Custom` открывается ввод имени и после сохранения derivation работает;
|
|
||||||
- `Показать баланс кошелька` читает баланс именно активного кошелька;
|
|
||||||
- `Показать QR-код кошелька` показывает QR и адрес именно активного кошелька;
|
|
||||||
- browser extension после подключения wallet-session может запросить текущий кошелёк у ESP32;
|
|
||||||
- extension показывает тип кошелька, полный `publicKeyBase58`, результат проверки через PDA и копирует ключ в буфер;
|
|
||||||
- для `client.key` и `root.key` проверка через PDA даёт ожидаемое совпадение.
|
|
||||||
|
|
||||||
- ожидаемый результат:
|
|
||||||
- активный кошелёк на ESP32 реально влияет на баланс, QR и ответ `get_wallet_public_key`;
|
|
||||||
- browser extension получает ответ без ручного ввода `walletSelector`;
|
|
||||||
- homeserver выбирается из опубликованных в PDA sessions и запрос приходит в нужное устройство;
|
|
||||||
- копирование ключа из extension работает.
|
|
||||||
|
|
||||||
- статус:
|
|
||||||
- pending
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# ESP32 English UI and trusted login fix
|
|
||||||
|
|
||||||
- Краткое описание:
|
|
||||||
переведён экранный UI ESP32 homeserver на английский язык; добавлена локальная инструкция для AGENTS по ограничению кириллицы; исправлено падение `StartTrustedDeviceLogin`, когда у пользователя ещё нет записи `esp_pairing_settings`.
|
|
||||||
|
|
||||||
- Что проверять:
|
|
||||||
1. На ESP32 открыть `HOME`, `WALLET`, `SELECT WALLET`, `WALLET QR` и убедиться, что пользовательские строки на экране только на английском.
|
|
||||||
2. Проверить сценарий выбора `ClientKey`, `RootKey`, `Custom` и чтение баланса/QR после переключения.
|
|
||||||
3. В расширении открыть popup, запустить `Подключить` для логина, у которого ещё не настраивался trusted-device login.
|
|
||||||
4. Убедиться, что `StartTrustedDeviceLogin` больше не падает с `NullPointerException`.
|
|
||||||
5. После создания pairing-запроса проверить, что homeserver/UI может его увидеть и обработать как раньше.
|
|
||||||
|
|
||||||
- Ожидаемый результат:
|
|
||||||
- ESP32 UI читается на устройстве без кириллических строк.
|
|
||||||
- Подключение через trusted-device login стартует без server-side `INTERNAL_HANDLER_ERROR`, даже если настройки pairing ещё ни разу не сохранялись.
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`pending`
|
|
||||||
@ -1,20 +0,0 @@
|
|||||||
# Browser wallet side panel
|
|
||||||
|
|
||||||
- Краткое описание:
|
|
||||||
browser extension `SHiNE Wallet` переведён с toolbar popup на штатный Chromium side panel.
|
|
||||||
|
|
||||||
- Что проверять:
|
|
||||||
1. Перезагрузить unpacked extension в Chromium-браузере.
|
|
||||||
2. Нажать на иконку `SHiNE Wallet` в toolbar.
|
|
||||||
3. Убедиться, что открывается side panel, а не всплывающий popup.
|
|
||||||
4. Проверить, что панель можно держать открытой при навигации по сайтам.
|
|
||||||
5. Проверить сценарии `Подключить`, `Отключить`, `Обновить устройства`, `Запросить кошелёк`.
|
|
||||||
6. Проверить, что сторона панели управляется браузером, а UI корректно выглядит и слева, и справа.
|
|
||||||
|
|
||||||
- Ожидаемый результат:
|
|
||||||
- расширение открывается в штатной боковой панели Chromium;
|
|
||||||
- UI работает так же, как раньше в popup;
|
|
||||||
- панель остаётся доступной как постоянная колонка браузера.
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`pending`
|
|
||||||
@ -1,23 +0,0 @@
|
|||||||
# Wallet provider and ESP sign_transaction
|
|
||||||
|
|
||||||
- Краткое описание:
|
|
||||||
browser extension `SHiNE Wallet` теперь внедряет `window.solana` для сайтов и умеет выполнять `connect` и `signTransaction`; подпись транзакции уходит на ESP32 через wallet RPC `sign_transaction`, а подтверждение делается на устройстве.
|
|
||||||
|
|
||||||
- Что проверять:
|
|
||||||
1. Перезагрузить unpacked extension в Chromium.
|
|
||||||
2. Открыть сайт/тестовую страницу, которая вызывает `window.solana.connect()`.
|
|
||||||
3. Подтвердить подключение кошелька и убедиться, что сайт получает публичный ключ.
|
|
||||||
4. Открыть сайт/тестовую страницу, которая вызывает `window.solana.signTransaction(...)`.
|
|
||||||
5. Убедиться, что на ESP32 открывается экран `SIGN REQUEST` с комментарием.
|
|
||||||
6. Проверить оба варианта:
|
|
||||||
- `APPROVE` возвращает сайту подписанную транзакцию;
|
|
||||||
- `REJECT` возвращает отказ.
|
|
||||||
7. Проверить сценарии для `ClientKey`, `RootKey`, `Custom`.
|
|
||||||
|
|
||||||
- Ожидаемый результат:
|
|
||||||
- сайт может подключить кошелёк через provider расширения;
|
|
||||||
- транзакция подписывается только после подтверждения на ESP32;
|
|
||||||
- отказ на ESP32 корректно доходит до сайта.
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`pending`
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# Wallet Standard support
|
|
||||||
|
|
||||||
- Краткое описание:
|
|
||||||
расширение `SHiNE Wallet` теперь не только внедряет legacy `window.solana`, но и регистрирует себя как `Wallet Standard` wallet для Solana dapp.
|
|
||||||
|
|
||||||
- Что проверять:
|
|
||||||
1. Перезагрузить unpacked extension.
|
|
||||||
2. Открыть dapp, который использует Wallet Standard, например `app.realms.today` на `devnet`.
|
|
||||||
3. Открыть список кошельков и убедиться, что `SHiNE Wallet` появился отдельным вариантом.
|
|
||||||
4. Проверить `connect`.
|
|
||||||
5. Проверить подпись транзакции через сценарий dapp, который использует стандартный wallet interface.
|
|
||||||
|
|
||||||
- Ожидаемый результат:
|
|
||||||
- dapp видит `SHiNE Wallet` как standard wallet, а не только как legacy Phantom-style provider.
|
|
||||||
- connect и подпись работают через тот же ESP32 approval-flow.
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`pending`
|
|
||||||
@ -1,26 +0,0 @@
|
|||||||
## Кратко
|
|
||||||
|
|
||||||
Исправлена ESP32-ветка обновления `user_pda` для добавления `homeserver`-сессии после миграции формата PDA на `RecoveryKeyBlock`.
|
|
||||||
|
|
||||||
## Что сделано
|
|
||||||
|
|
||||||
- В `shine_homeserver_main.ino` синхронизирован `create/update` payload с новым форматом `shine_users`.
|
|
||||||
- В сериализацию и парсинг PDA добавлен `RecoveryKeyBlock`.
|
|
||||||
- Для ветки `Add Homeserver` добавлены промежуточные checkpoint-записи в NVS, чтобы после crash или reset было видно, на каком шаге оборвалась операция.
|
|
||||||
- В `ESP32/AGENTS.md` добавлена памятка по чтению `last_error`.
|
|
||||||
|
|
||||||
## Что проверять
|
|
||||||
|
|
||||||
- Зарегистрировать или использовать уже существующий аккаунт на ESP32.
|
|
||||||
- Дойти до состояния `homeserver not in PDA`.
|
|
||||||
- Нажать `Add Homeserver`.
|
|
||||||
- Если операция не успешна, считать `last_error` по USB serial и убедиться, что видна свежая запись именно по шагам `Homeserver PDA update ...`, а не старый diag.
|
|
||||||
|
|
||||||
## Ожидаемый результат
|
|
||||||
|
|
||||||
- `Add Homeserver` добавляет `homeserver1` в `sessions` блока `SessionsBlock`.
|
|
||||||
- Если операция падает, в NVS сохраняется свежая диагностическая запись с текущим этапом, а не устаревший лог регистрации.
|
|
||||||
|
|
||||||
## Статус
|
|
||||||
|
|
||||||
`pending`
|
|
||||||
@ -1,28 +0,0 @@
|
|||||||
# Общий список каналов без stories
|
|
||||||
|
|
||||||
- Краткое описание:
|
|
||||||
вкладка `Каналы` переведена на единый список без разделения на "мои" и "подписки".
|
|
||||||
Название канала в списке теперь показывается как `login_владельца/название_канала`.
|
|
||||||
Служебный канал `stories` скрыт из списка каналов, поиска, подписки и связанных UI-сценариев.
|
|
||||||
|
|
||||||
- Что проверять:
|
|
||||||
1. Открыть вкладку `Каналы`.
|
|
||||||
2. Убедиться, что сразу показывается один общий список.
|
|
||||||
3. Проверить, что свои и чужие каналы отображаются вместе.
|
|
||||||
4. Проверить формат названий: `ownerLogin/channelName`.
|
|
||||||
5. Открыть свой канал и убедиться, что внутри сохраняется UI владельца.
|
|
||||||
6. Открыть чужой канал и убедиться, что внутри сохраняется UI подписчика.
|
|
||||||
7. Проверить, что `stories` не отображается:
|
|
||||||
- в общем списке;
|
|
||||||
- в поиске каналов;
|
|
||||||
- в подписке на канал;
|
|
||||||
- в списках выбора канала для репоста.
|
|
||||||
|
|
||||||
- Ожидаемый результат:
|
|
||||||
- вкладка `Каналы` больше не делится на два режима;
|
|
||||||
- все видимые каналы идут единым списком;
|
|
||||||
- `stories` нигде не виден и не предлагается пользователю;
|
|
||||||
- переход в канал сохраняет корректный UI в зависимости от владельца.
|
|
||||||
|
|
||||||
- Статус:
|
|
||||||
`pending`
|
|
||||||
@ -1,20 +0,0 @@
|
|||||||
# Недопроверенные фичи
|
|
||||||
|
|
||||||
Эта папка хранит список доработок, которые уже реализованы, но ещё не подтверждены ручной проверкой.
|
|
||||||
|
|
||||||
## Как использовать
|
|
||||||
|
|
||||||
1. При каждом коммите с новыми пользовательскими фичами (если нужна ручная проверка) добавить новый файл:
|
|
||||||
- формат: `YYYY-MM-DD_HHMM_<short-feature-name>.md`
|
|
||||||
- название `<short-feature-name>` и текст файла по возможности писать на русском языке
|
|
||||||
2. В файле указать:
|
|
||||||
- что сделано;
|
|
||||||
- как проверять;
|
|
||||||
- ожидаемый результат;
|
|
||||||
- текущий статус (`pending` / `in_progress` / `done`).
|
|
||||||
3. После подтверждения работоспособности — удалить файл фичи из этой папки.
|
|
||||||
|
|
||||||
## Важно
|
|
||||||
|
|
||||||
- `README.md` не удаляется.
|
|
||||||
- Количество недопроверенных фич = число файлов `*.md` в этой папке, кроме `README.md`.
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# AGENTS
|
|
||||||
|
|
||||||
## Документация DM в этой папке
|
|
||||||
|
|
||||||
- Основной актуальный документ по личным сообщениям:
|
|
||||||
- `README.md`
|
|
||||||
- Его считать единственным источником истины по текущей реализованной логике DM.
|
|
||||||
|
|
||||||
## Черновик будущих вложений
|
|
||||||
|
|
||||||
- Файл `Черновик_будущих_DM_вложений.md` не является актуальной спецификацией.
|
|
||||||
- В нём описан только ранний черновик того, как когда-то планировались:
|
|
||||||
- формат вложений в DM;
|
|
||||||
- внешние и внутренние поля вложения;
|
|
||||||
- предполагаемая механика загрузки файлов.
|
|
||||||
- Эта схема не была реализована в таком виде и может существенно измениться в будущем.
|
|
||||||
- Любые решения по текущему коду, протоколу и UI нельзя принимать по этому черновику.
|
|
||||||
- Если есть расхождение между `README.md` и черновиком вложений, верным всегда считается `README.md`.
|
|
||||||
@ -1,203 +0,0 @@
|
|||||||
# Личные сообщения (DM)
|
|
||||||
|
|
||||||
## Текущее состояние
|
|
||||||
|
|
||||||
Сейчас в проекте реализованы:
|
|
||||||
|
|
||||||
- новый формат контентных личных сообщений `SHiNE_DM`;
|
|
||||||
- ревизии сообщений через `revisionTimeMs`;
|
|
||||||
- редактирование сообщения через повторную отправку той же логической пары;
|
|
||||||
- удаление сообщения через пустую ревизию;
|
|
||||||
- `upsert` последней версии сообщения на сервере.
|
|
||||||
|
|
||||||
Сейчас в проекте **не реализованы**:
|
|
||||||
|
|
||||||
- вложения в DM;
|
|
||||||
- upload/download файлов для DM;
|
|
||||||
- UI-кнопка прикрепления файла;
|
|
||||||
- серверное хранение файловых связей для DM.
|
|
||||||
|
|
||||||
Черновик будущих вложений вынесен отдельно:
|
|
||||||
|
|
||||||
- `Dev_Docs/Personal_Messages/Черновик_будущих_DM_вложений.md`
|
|
||||||
|
|
||||||
## Общая схема
|
|
||||||
|
|
||||||
Личное сообщение по-прежнему отправляется парой signed-блоков:
|
|
||||||
|
|
||||||
- `type=1` — входящий блок для получателя;
|
|
||||||
- `type=2` — исходящая копия для отправителя.
|
|
||||||
|
|
||||||
Read-receipt пока остаются в legacy-формате:
|
|
||||||
|
|
||||||
- `type=3` — входящее подтверждение прочтения;
|
|
||||||
- `type=4` — исходящая копия подтверждения.
|
|
||||||
|
|
||||||
Ключи сообщения:
|
|
||||||
|
|
||||||
- `baseKey = fromLogin|toLogin|timeMs|nonce`
|
|
||||||
- `messageKey = baseKey|messageType`
|
|
||||||
|
|
||||||
Логический идентификатор письма задаётся парой:
|
|
||||||
|
|
||||||
- `timeMs`
|
|
||||||
- `nonce`
|
|
||||||
|
|
||||||
Эти поля не меняются при редактировании или удалении. Меняется только:
|
|
||||||
|
|
||||||
- `revisionTimeMs`
|
|
||||||
- содержимое `encryptedBody`
|
|
||||||
|
|
||||||
Сервер хранит только последнюю версию записи для каждого `messageKey`.
|
|
||||||
|
|
||||||
## Формат контентного DM: `SHiNE_DM`
|
|
||||||
|
|
||||||
Префикс бинарного блока:
|
|
||||||
|
|
||||||
- `SHiNE_DM`
|
|
||||||
|
|
||||||
Поля идут в big-endian порядке:
|
|
||||||
|
|
||||||
1. `formatVersionMajor` (`u8`) = `1`
|
|
||||||
2. `formatVersionMinor` (`u8`) = `0`
|
|
||||||
3. `toLoginLen` (`u8`) + `toLogin` (ASCII, `1..60`)
|
|
||||||
4. `fromLoginLen` (`u8`) + `fromLogin` (ASCII, `1..60`)
|
|
||||||
5. `timeMs` (`u64`)
|
|
||||||
6. `nonce` (`u32`)
|
|
||||||
7. `messageType` (`u16`) — только `1` или `2`
|
|
||||||
8. `revisionTimeMs` (`u64`)
|
|
||||||
9. `attachmentsCount` (`u8`)
|
|
||||||
10. `encryptedBodyLen` (`u32`)
|
|
||||||
11. `encryptedBody` (`bytes`)
|
|
||||||
12. `signature` (`64 bytes`, Ed25519)
|
|
||||||
|
|
||||||
### Ограничения
|
|
||||||
|
|
||||||
- `attachmentsCount` сейчас всегда должен быть `0`
|
|
||||||
- `encryptedBodyLen` сейчас ограничен сервером до `16384` байт
|
|
||||||
- `revisionTimeMs` не может быть отрицательным
|
|
||||||
|
|
||||||
Если приходит `attachmentsCount != 0`, сервер отклоняет такой DM как:
|
|
||||||
|
|
||||||
- `ATTACHMENTS_DISABLED`
|
|
||||||
|
|
||||||
## Legacy read-receipt: `SHiNE_dm2`
|
|
||||||
|
|
||||||
Подтверждения прочтения `type=3/4` пока используют старый контейнер `SHiNE_dm2`:
|
|
||||||
|
|
||||||
1. `toLoginLen` (`u8`) + `toLogin`
|
|
||||||
2. `fromLoginLen` (`u8`) + `fromLogin`
|
|
||||||
3. `timeMs` (`u64`)
|
|
||||||
4. `nonce` (`u32`)
|
|
||||||
5. `messageType` (`u16`) — `3` или `4`
|
|
||||||
6. `payloadLen` (`u16`)
|
|
||||||
7. `payloadBytes`
|
|
||||||
8. `signature`
|
|
||||||
|
|
||||||
## Редактирование
|
|
||||||
|
|
||||||
Редактирование делается новой отправкой той же логической пары сообщения:
|
|
||||||
|
|
||||||
- `timeMs` и `nonce` остаются теми же;
|
|
||||||
- `messageType` остаётся `1/2`;
|
|
||||||
- `revisionTimeMs` становится больше;
|
|
||||||
- `encryptedBody` содержит новую версию текста.
|
|
||||||
|
|
||||||
Если на сервер приходит более старая ревизия, она игнорируется.
|
|
||||||
|
|
||||||
Если приходит та же ревизия и тот же бинарный блок, сервер тоже её не применяет повторно.
|
|
||||||
|
|
||||||
## Удаление
|
|
||||||
|
|
||||||
Удаление личного сообщения делается как новая ревизия того же сообщения:
|
|
||||||
|
|
||||||
- `timeMs` и `nonce` остаются прежними;
|
|
||||||
- `revisionTimeMs` увеличивается;
|
|
||||||
- `attachmentsCount = 0`;
|
|
||||||
- `encryptedBodyLen = 0`;
|
|
||||||
- `encryptedBody` пустой.
|
|
||||||
|
|
||||||
В UI такое сообщение не показывается.
|
|
||||||
|
|
||||||
На сервере это не отдельный тип сообщения, а просто последняя пустая ревизия того же `messageKey`.
|
|
||||||
|
|
||||||
## Поведение сервера
|
|
||||||
|
|
||||||
Для контентных DM сервер:
|
|
||||||
|
|
||||||
1. принимает пару signed-блоков `type=1/2`;
|
|
||||||
2. валидирует формат, подпись и совпадение ключевых полей пары;
|
|
||||||
3. проверяет, что для обеих сторон пары совпадают:
|
|
||||||
- `fromLogin`
|
|
||||||
- `toLogin`
|
|
||||||
- `timeMs`
|
|
||||||
- `nonce`
|
|
||||||
- `revisionTimeMs`
|
|
||||||
- `encryptedBody`
|
|
||||||
4. делает `upsert` последней версии в `signed_messages_v2`;
|
|
||||||
5. сбрасывает pending-доставку по сессиям для новой ревизии;
|
|
||||||
6. рассылает актуальную версию адресатам через `SignedMessageArrived`.
|
|
||||||
|
|
||||||
История старых ревизий сейчас не хранится отдельно: в таблице остаётся только последняя версия по каждому `messageKey`.
|
|
||||||
|
|
||||||
## Хранение в БД
|
|
||||||
|
|
||||||
Основная таблица:
|
|
||||||
|
|
||||||
- `signed_messages_v2`
|
|
||||||
|
|
||||||
Для контентных DM в ней используются:
|
|
||||||
|
|
||||||
- `message_key`
|
|
||||||
- `base_key`
|
|
||||||
- `target_login`
|
|
||||||
- `from_login`
|
|
||||||
- `to_login`
|
|
||||||
- `time_ms`
|
|
||||||
- `nonce`
|
|
||||||
- `message_type`
|
|
||||||
- `revision_time_ms`
|
|
||||||
- `raw_block`
|
|
||||||
- `created_at_ms`
|
|
||||||
|
|
||||||
Отдельных таблиц файлов для DM сейчас нет.
|
|
||||||
|
|
||||||
## События и доставка
|
|
||||||
|
|
||||||
Запрос на отправку по WebSocket остаётся прежним:
|
|
||||||
|
|
||||||
- `SendMessagePair`
|
|
||||||
- `ReceiveOutcomingMessage` как алиас
|
|
||||||
|
|
||||||
Клиент отправляет:
|
|
||||||
|
|
||||||
- `incomingBlobB64`
|
|
||||||
- `outgoingBlobB64`
|
|
||||||
|
|
||||||
Событие в активные сессии:
|
|
||||||
|
|
||||||
- `SignedMessageArrived`
|
|
||||||
|
|
||||||
Если пришла новая ревизия того же сообщения, `messageKey` остаётся прежним, а внутри `blobB64` будет более новый `revisionTimeMs`.
|
|
||||||
|
|
||||||
Подтверждение доставки в сессию:
|
|
||||||
|
|
||||||
- `AckSessionDelivery`
|
|
||||||
|
|
||||||
## Правила UI
|
|
||||||
|
|
||||||
UI сейчас работает так:
|
|
||||||
|
|
||||||
- показывает только текст `encryptedBody`;
|
|
||||||
- умеет обновлять уже существующее сообщение по тому же `messageKey`;
|
|
||||||
- не показывает удалённые сообщения;
|
|
||||||
- позволяет владельцу сообщения вызвать меню `Скопировать как текст / Прочесть / Изменить / Удалить`;
|
|
||||||
- при редактировании показывает над полем ввода полоску `Редактируем сообщение: ...` с кнопкой отмены;
|
|
||||||
- после редактирования показывает под временем отдельную строку `изменено: <дата время>`;
|
|
||||||
- не показывает и не принимает вложения.
|
|
||||||
|
|
||||||
## Что обязательно помнить
|
|
||||||
|
|
||||||
- вложения в DM сейчас отключены на уровне протокола и UI;
|
|
||||||
- любые старые описания `/f/...`, `/upload` и файловых таблиц для DM больше не актуальны;
|
|
||||||
- если позже вложения вернутся, их формат и серверная логика могут быть другими.
|
|
||||||
@ -1,42 +0,0 @@
|
|||||||
# TODO: доработка персональных сообщений для агентов
|
|
||||||
|
|
||||||
Статус: отложено.
|
|
||||||
|
|
||||||
## Что хотели сделать
|
|
||||||
|
|
||||||
Добавить упрощённую маршрутизацию персональных сообщений через служебную инструкцию в начале текстового payload (внутри подписанного DM-блока), чтобы:
|
|
||||||
|
|
||||||
- отличать сообщения человеку от сообщений агенту;
|
|
||||||
- отличать сообщения от человека и от агента;
|
|
||||||
- скрывать в обычном UI сообщения, адресованные агенту (`target=agent`);
|
|
||||||
- поддержать сценарий «сообщения самому себе между своими клиентами/устройствами», где один клиент/агент пишет другому в рамках одного логина.
|
|
||||||
|
|
||||||
## Базовая идея формата (черновик)
|
|
||||||
|
|
||||||
Пример префикса:
|
|
||||||
|
|
||||||
```text
|
|
||||||
@shine:pm:v1 {"target":"agent","agentId":"assistant","author":"human"}
|
|
||||||
Текст сообщения...
|
|
||||||
```
|
|
||||||
|
|
||||||
Пример ответа агента:
|
|
||||||
|
|
||||||
```text
|
|
||||||
@shine:pm:v1 {"target":"user","author":"agent","agentId":"assistant","agentLabel":"My Bot"}
|
|
||||||
Ответ агента...
|
|
||||||
```
|
|
||||||
|
|
||||||
## Почему отложено
|
|
||||||
|
|
||||||
- нужно отдельно согласовать финальный формат инструкции;
|
|
||||||
- нужно определить строгие правила UI-фильтрации и fallback;
|
|
||||||
- нужно определить, нужен ли позднее отдельный серверный роутинг для agent-сессий.
|
|
||||||
|
|
||||||
## Что сделать при возвращении к задаче
|
|
||||||
|
|
||||||
1. Зафиксировать окончательный формат префикса и JSON-полей.
|
|
||||||
2. Описать правила парсинга/валидации (включая битые/неполные префиксы).
|
|
||||||
3. Добавить UI-логику показа/скрытия agent-сообщений.
|
|
||||||
4. Добавить маркировку «ответ агента» в диалоге.
|
|
||||||
5. Продумать режим self-chat (между своими клиентами/агентом) в рамках одного логина.
|
|
||||||
@ -1,73 +0,0 @@
|
|||||||
# Черновик будущих вложений в DM
|
|
||||||
|
|
||||||
## Важно
|
|
||||||
|
|
||||||
Этот документ описывает только ранний черновик идеи.
|
|
||||||
|
|
||||||
Сейчас в проекте **нет** поддержки вложений в личных сообщениях:
|
|
||||||
|
|
||||||
- в реализованном формате `SHiNE_DM` поле `attachmentsCount` пока всегда должно быть `0`;
|
|
||||||
- UI не показывает кнопку прикрепления файлов;
|
|
||||||
- сервер не принимает upload файлов для DM;
|
|
||||||
- сервер не раздаёт специальные DM-файлы по отдельным endpoints;
|
|
||||||
- сервер не хранит отдельные файловые связи для личных сообщений.
|
|
||||||
|
|
||||||
Этот документ нужен только для того, чтобы рядом с актуальной документацией было явно видно:
|
|
||||||
|
|
||||||
- какие идеи обсуждались;
|
|
||||||
- что это **не реализовано**;
|
|
||||||
- что формат, хранение и способ загрузки потом могут сильно измениться.
|
|
||||||
|
|
||||||
## Что обсуждалось
|
|
||||||
|
|
||||||
Рассматривался такой общий подход:
|
|
||||||
|
|
||||||
- у контентного DM есть внешний список вложений;
|
|
||||||
- во внешнем формате лежат только технические данные;
|
|
||||||
- человекочитаемые данные о файле живут внутри зашифрованного тела сообщения;
|
|
||||||
- один и тот же blob-файл теоретически мог бы переиспользоваться в нескольких сообщениях.
|
|
||||||
|
|
||||||
Черновой вариант внешнего списка:
|
|
||||||
|
|
||||||
- `attachmentsCount`
|
|
||||||
- далее для каждого вложения:
|
|
||||||
- `encFileHashSHA256` (`32 bytes`)
|
|
||||||
- `encFileSize` (`u64`)
|
|
||||||
|
|
||||||
Черновой вариант внутреннего маркера в тексте:
|
|
||||||
|
|
||||||
```text
|
|
||||||
<<file:file-format(1.0):type|fileName|origSize|origHashB64u|encHashB64u|encSize|keyB64u|nonceB64u>>
|
|
||||||
```
|
|
||||||
|
|
||||||
Где обсуждались поля:
|
|
||||||
|
|
||||||
- `type`
|
|
||||||
- `fileName`
|
|
||||||
- `origSize`
|
|
||||||
- `origHashB64u`
|
|
||||||
- `encHashB64u`
|
|
||||||
- `encSize`
|
|
||||||
- `keyB64u`
|
|
||||||
- `nonceB64u`
|
|
||||||
|
|
||||||
## Что может измениться
|
|
||||||
|
|
||||||
В будущем могут измениться любые части идеи:
|
|
||||||
|
|
||||||
- сам бинарный формат;
|
|
||||||
- способ привязки файлов к сообщению;
|
|
||||||
- момент загрузки файла относительно отправки сообщения;
|
|
||||||
- серверное хранение blob-файлов;
|
|
||||||
- права доступа к скачиванию;
|
|
||||||
- способ рендера вложения в UI.
|
|
||||||
|
|
||||||
Именно поэтому этот файл не надо воспринимать как актуальную спецификацию.
|
|
||||||
|
|
||||||
## Источник истины на сейчас
|
|
||||||
|
|
||||||
Актуальное состояние личных сообщений описано только в:
|
|
||||||
|
|
||||||
- `Dev_Docs/Personal_Messages/README.md`
|
|
||||||
|
|
||||||
Если между этим черновиком и основным README есть расхождение, верным считается `README.md`.
|
|
||||||
@ -1,482 +0,0 @@
|
|||||||
# Solana user_pda: итоговый целевой формат пользовательской записи
|
|
||||||
|
|
||||||
Документ описывает целевой формат пользовательской PDA-записи `user_pda` для Solana-программы `shine_users`.
|
|
||||||
|
|
||||||
Это не формат основного блокчейна SHiNE и не документация по `AddBlock`. Основной блокчейн SHiNE описан отдельно в `Dev_Docs/Blockchain/`.
|
|
||||||
|
|
||||||
Статус документа: итоговый согласованный формат, к которому приведены `create_user_pda`, `update_user_pda` и тестовый сериализатор Solana-модуля.
|
|
||||||
|
|
||||||
## 1. Назначение user_pda
|
|
||||||
|
|
||||||
`user_pda` хранит публичное состояние пользователя в Solana:
|
|
||||||
|
|
||||||
- логин пользователя;
|
|
||||||
- неизменяемые параметры создания записи;
|
|
||||||
- публичный recovery-ключ пользователя;
|
|
||||||
- корневой публичный ключ пользователя;
|
|
||||||
- клиентский публичный ключ пользователя;
|
|
||||||
- данные одного или нескольких пользовательских блокчейнов SHiNE;
|
|
||||||
- серверные данные пользователя, если пользователь выступает сервером;
|
|
||||||
- серверы доступа пользователя;
|
|
||||||
- счетчики/лимиты;
|
|
||||||
- подпись записи.
|
|
||||||
|
|
||||||
На первом этапе поддерживается один пользовательский блокчейн SHiNE, но формат блока блокчейна сразу допускает повторение таких блоков в будущем.
|
|
||||||
|
|
||||||
## 2. Адрес PDA
|
|
||||||
|
|
||||||
Адрес пользовательской PDA вычисляется по логину:
|
|
||||||
|
|
||||||
- seed prefix: `user_login=`;
|
|
||||||
- второй seed: нормализованный логин в нижнем регистре;
|
|
||||||
- program id: программа `shine_users`.
|
|
||||||
|
|
||||||
Один логин соответствует одной `user_pda`.
|
|
||||||
|
|
||||||
## 2.1. Кто оплачивает create/update PDA
|
|
||||||
|
|
||||||
- Инструкции `create_user_pda` и `update_user_pda` оплачиваются с `client_key`.
|
|
||||||
- `root_key` используется для подписи unsigned части записи через Ed25519 instruction и не является fee payer.
|
|
||||||
- Для server PDA это правило то же самое: пополнять SOL нужно на адрес `client_key`.
|
|
||||||
|
|
||||||
## 3. Общие правила кодирования
|
|
||||||
|
|
||||||
- Числа кодируются в Little Endian.
|
|
||||||
- `u8`, `u16`, `u32`, `u64` имеют обычный фиксированный размер.
|
|
||||||
- Публичный ключ Solana/Ed25519: 32 байта.
|
|
||||||
- Ed25519-подпись: 64 байта.
|
|
||||||
- SHA-256/Solana hash: 32 байта.
|
|
||||||
- Строка переменной длины: `len: u8` + `bytes[len]` в UTF-8.
|
|
||||||
- Arweave `tx_id`: строка переменной длины. Ожидаемая практическая длина base64url tx id - 43 байта, но формат хранит длину явно.
|
|
||||||
- Все типизированные блоки после фиксированного заголовка начинаются с `block_type: u8` и `block_version: u8`.
|
|
||||||
- Отдельный `block_len` у типизированных блоков не хранится: блоки парсятся по известным полям, счетчикам и строкам с `len: u8`.
|
|
||||||
|
|
||||||
## 4. Верхний формат записи
|
|
||||||
|
|
||||||
Первые 9 полей фиксированы и идут строго в указанном порядке. Это общий заголовок записи.
|
|
||||||
|
|
||||||
| N | Поле | Тип | Размер | Правило |
|
|
||||||
|---|------|-----|--------|---------|
|
|
||||||
| 1 | `magic` | bytes | 5 | Всегда `SHiNE`. |
|
|
||||||
| 2 | `format_major` | `u8` | 1 | Для первого формата: `1`. |
|
|
||||||
| 3 | `format_minor` | `u8` | 1 | Для первой версии нового формата: `0`. |
|
|
||||||
| 4 | `record_len` | `u16` | 2 | Длина полезной записи от `magic` до `signature` включительно, без padding. |
|
|
||||||
| 5 | `created_at_ms` | `u64` | 8 | Время создания записи, Unix time в миллисекундах. Не меняется. |
|
|
||||||
| 6 | `updated_at_ms` | `u64` | 8 | Время последнего обновления записи. |
|
|
||||||
| 7 | `record_number` | `u32` | 4 | Номер версии записи пользователя. При создании `0`, при обновлении +1. |
|
|
||||||
| 8 | `prev_record_hash` | bytes | 32 | Хэш unsigned-части предыдущей записи. При создании 32 нулевых байта. |
|
|
||||||
| 9 | `login` | string | `1 + len` | Логин пользователя. Не меняется. |
|
|
||||||
|
|
||||||
После первых 9 полей идет набор типизированных блоков:
|
|
||||||
|
|
||||||
```text
|
|
||||||
UserPdaRecordV1
|
|
||||||
- fixed_header: поля 1..9
|
|
||||||
- blocks_count: u8
|
|
||||||
- blocks: TypedBlock[blocks_count]
|
|
||||||
- signature: [u8; 64]
|
|
||||||
- padding: bytes до размера PDA, если нужен
|
|
||||||
```
|
|
||||||
|
|
||||||
`blocks_count` входит в unsigned-часть записи и подписывается.
|
|
||||||
|
|
||||||
## 5. Типы блоков
|
|
||||||
|
|
||||||
Зарезервированные значения `block_type`:
|
|
||||||
|
|
||||||
| block_type | Блок | Назначение |
|
|
||||||
|------------|------|------------|
|
|
||||||
| `0` | `RecoveryKeyBlock` | Ключ восстановления пользователя. |
|
|
||||||
| `1` | `RootKeyBlock` | Корневой ключ пользователя. |
|
|
||||||
| `2` | `ClientKeyBlock` | Клиентский ключ пользователя. |
|
|
||||||
| `3` | `BlockchainRegistryBlock` | Один или несколько блокчейнов пользователя. |
|
|
||||||
| `30` | `ServerProfileBlock` | Серверные данные пользователя. |
|
|
||||||
| `40` | `AccessServersBlock` | Серверы доступа/relay. |
|
|
||||||
| `50` | `SessionsBlock` | Опубликованные пользовательские сессии и homeserver-ы. |
|
|
||||||
| `70` | `TrustedStateBlock` | Счетчик trusted-связей. |
|
|
||||||
| `255` | `ReservedBlock` | Зарезервировано, пока не используется. |
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- неизвестный `block_type` в `format_major = 1` считается ошибкой;
|
|
||||||
- обязательные блоки: `RecoveryKeyBlock`, `RootKeyBlock`, `ClientKeyBlock`, `BlockchainRegistryBlock`;
|
|
||||||
- необязательные блоки: `ServerProfileBlock`, `AccessServersBlock`, `SessionsBlock`, `TrustedStateBlock`;
|
|
||||||
- каждый обязательный блок должен встречаться ровно один раз;
|
|
||||||
- порядок блоков в записи фиксируется для простоты проверки:
|
|
||||||
`RecoveryKey`, `RootKey`, `ClientKey`, `BlockchainRegistry`, `ServerProfile`, `AccessServers`, `Sessions`, `TrustedState`.
|
|
||||||
|
|
||||||
## 6. RecoveryKeyBlock
|
|
||||||
|
|
||||||
Recovery-ключ нужен для будущих сценариев восстановления и ротации остальных ключей. В текущей версии он только публикуется в записи и не меняется через обычный `update_user_pda`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
RecoveryKeyBlock
|
|
||||||
- block_type: u8 = 0
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- recovery_key: [u8; 32]
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- при создании задается публичный recovery-ключ пользователя;
|
|
||||||
- при обновлении `recovery_key` должен совпадать с предыдущей записью;
|
|
||||||
- приватный `recovery.key` в PDA не хранится;
|
|
||||||
- отдельная ротация recovery-ключа будет отдельным форматом/сценарием в будущем.
|
|
||||||
|
|
||||||
## 7. RootKeyBlock
|
|
||||||
|
|
||||||
Смена `root_key` пока не проектируется и не реализуется. Блок фиксирует только стадию `0`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
RootKeyBlock
|
|
||||||
- block_type: u8 = 1
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- root_key: [u8; 32]
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- при создании задается корневой публичный ключ пользователя;
|
|
||||||
- при обновлении `root_key` должен совпадать с предыдущей записью;
|
|
||||||
- ротация root-key будет отдельным форматом/сценарием в будущем.
|
|
||||||
|
|
||||||
## 8. ClientKeyBlock
|
|
||||||
|
|
||||||
Смена `client_key` пока также не проектируется как отдельная ротация. В версии `0` хранится один клиентский ключ пользователя.
|
|
||||||
|
|
||||||
```text
|
|
||||||
ClientKeyBlock
|
|
||||||
- block_type: u8 = 2
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- client_key: [u8; 32]
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- при создании задается текущий клиентский публичный ключ пользователя;
|
|
||||||
- при обновлении `client_key` должен совпадать с предыдущей записью;
|
|
||||||
- история устройств и несколько клиентских ключей в этом формате не хранятся.
|
|
||||||
|
|
||||||
## 9. BlockchainRegistryBlock
|
|
||||||
|
|
||||||
Блок хранит данные пользовательских блокчейнов SHiNE. Сейчас используется один блокчейн, но структура сразу сделана как список.
|
|
||||||
|
|
||||||
```text
|
|
||||||
BlockchainRegistryBlock
|
|
||||||
- block_type: u8 = 3
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- blockchain_count: u8
|
|
||||||
- blockchain_records: BlockchainRecord[blockchain_count]
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- на первом этапе `blockchain_count = 1`;
|
|
||||||
- в будущем можно увеличить количество записей без изменения смысла `BlockchainRecord`;
|
|
||||||
- каждый `BlockchainRecord` описывает один пользовательский SHiNE-блокчейн.
|
|
||||||
|
|
||||||
## 10. BlockchainRecord
|
|
||||||
|
|
||||||
```text
|
|
||||||
BlockchainRecord
|
|
||||||
- blockchain_type: u8
|
|
||||||
- blockchain_name: string
|
|
||||||
- blockchain_public_key: [u8; 32]
|
|
||||||
- paid_limit_bytes: u64
|
|
||||||
- used_bytes: u64
|
|
||||||
- last_block_number: u32
|
|
||||||
- last_block_hash: [u8; 32]
|
|
||||||
- last_block_signature: [u8; 64]
|
|
||||||
- arweave_present: u8
|
|
||||||
- arweave_tx_id: string, только если arweave_present = 1
|
|
||||||
```
|
|
||||||
|
|
||||||
`blockchain_type`:
|
|
||||||
|
|
||||||
| Значение | Смысл |
|
|
||||||
|----------|-------|
|
|
||||||
| `1` | Основной пользовательский SHiNE-блокчейн. |
|
|
||||||
|
|
||||||
Поля:
|
|
||||||
|
|
||||||
- `blockchain_name` - строковое имя пользовательского блокчейна, например `login-001`. На первом этапе для основного блокчейна пользователя используется имя вида `<login>-001`, потому что это первый блокчейн этого пользователя.
|
|
||||||
- `blockchain_public_key` - публичный ключ блокчейна пользователя.
|
|
||||||
- `paid_limit_bytes` - оплаченный лимит хранения/записей в байтах.
|
|
||||||
- `used_bytes` - сколько байт уже занято в пользовательском SHiNE-блокчейне.
|
|
||||||
- `last_block_number` - номер последнего известного блока пользовательского блокчейна.
|
|
||||||
- `last_block_hash` - хэш последнего известного блока.
|
|
||||||
- `last_block_signature` - подпись хэша специального сообщения о вершине блокчейна ключом `blockchain_public_key`.
|
|
||||||
- `arweave_present` - `0`, если ссылки нет; `1`, если ссылка есть.
|
|
||||||
- `arweave_tx_id` - Arweave transaction id, где лежит выгруженный пользовательский канал/состояние.
|
|
||||||
|
|
||||||
Arweave `tx_id` - обычное поле внутри записи конкретного блокчейна. Solana-программа не проверяет, что такой Arweave transaction действительно существует и содержит корректные данные; это ответственность клиента/сервера/пользователя.
|
|
||||||
|
|
||||||
## 11. Правила обновления BlockchainRecord
|
|
||||||
|
|
||||||
При обновлении записи:
|
|
||||||
|
|
||||||
- `blockchain_type` для существующей записи не меняется;
|
|
||||||
- `blockchain_public_key` пока не ротируется автоматически; смена ключа требует отдельного согласованного сценария;
|
|
||||||
- `paid_limit_bytes` может только увеличиваться или оставаться прежним;
|
|
||||||
- при увеличении `paid_limit_bytes` пользователь платит комиссию в Solana по тарифам программы;
|
|
||||||
- `used_bytes` может только увеличиваться или оставаться прежним;
|
|
||||||
- `last_block_number` может только увеличиваться или оставаться прежним;
|
|
||||||
- `used_bytes <= paid_limit_bytes`;
|
|
||||||
- если `last_block_number` увеличился, то должны быть переданы новый `last_block_hash` и новая `last_block_signature`;
|
|
||||||
- `last_block_signature` проверяется через Ed25519-инструкцию Solana: подпись должна соответствовать хэшу сообщения `LastBlockState` и `blockchain_public_key`;
|
|
||||||
- в транзакции `create_user_pda` / `update_user_pda` две Ed25519-инструкции должны идти непосредственно перед вызовом `shine_users`: сначала подпись `root_key`, затем подпись `blockchain_public_key`;
|
|
||||||
- `arweave_tx_id` можно добавить или заменить на новый, если пользователь выгрузил более актуальное состояние в Arweave;
|
|
||||||
- уменьшать лимит, число блоков или занятый размер нельзя.
|
|
||||||
|
|
||||||
Сообщение `LastBlockState`, которое хэшируется и подписывается ключом `blockchain_public_key`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
LastBlockState
|
|
||||||
- constant: bytes = "SHiNE_LAST_BLOCK"
|
|
||||||
- login: string
|
|
||||||
- blockchain_name: string
|
|
||||||
- last_block_number: u32
|
|
||||||
- last_block_hash: [u8; 32]
|
|
||||||
- used_bytes: u64
|
|
||||||
```
|
|
||||||
|
|
||||||
Алгоритм:
|
|
||||||
|
|
||||||
```text
|
|
||||||
message = SHA-256(LastBlockState bytes)
|
|
||||||
last_block_signature = Ed25519(blockchain_public_key, message)
|
|
||||||
```
|
|
||||||
|
|
||||||
Причина проверки подписи `LastBlockState`: `root_key` управляет Solana-записью пользователя, а `blockchain_public_key` подтверждает состояние конкретного пользовательского блокчейна. Подписывается не голый хэш, а связка логина, имени блокчейна, номера последнего блока, хэша последнего блока и занятого размера.
|
|
||||||
|
|
||||||
## 12. ServerProfileBlock
|
|
||||||
|
|
||||||
Блок присутствует, если пользователь выступает сервером.
|
|
||||||
|
|
||||||
```text
|
|
||||||
ServerProfileBlock
|
|
||||||
- block_type: u8 = 30
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- is_server: u8
|
|
||||||
- address_format_type: u8, только если is_server = 1
|
|
||||||
- address_format_version: u8, только если is_server = 1
|
|
||||||
- server_address: string, только если is_server = 1
|
|
||||||
- sync_servers_count: u8, только если is_server = 1
|
|
||||||
- sync_servers: string[sync_servers_count], только если is_server = 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- `is_server = 0` означает, что серверных данных нет;
|
|
||||||
- `is_server = 1` означает, что пользователь публикует серверный профиль;
|
|
||||||
- `address_format_type` — тип формата адреса сервера: `1` = URL-строка (например `https://shineup.me/ws`);
|
|
||||||
- `address_format_version` — версия формата адреса, сейчас `0`;
|
|
||||||
- `sync_servers_count` максимум `32`;
|
|
||||||
- `server_address` - строковый адрес сервера в соответствии с `address_format_type`;
|
|
||||||
- `sync_servers` - логины SHiNE-пользователей, зарегистрированных как серверы, с которыми этот сервер синхронизирует блокчейн и личные сообщения. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы.
|
|
||||||
|
|
||||||
## 13. AccessServersBlock
|
|
||||||
|
|
||||||
Блок хранит серверы доступа/relay для пользователя.
|
|
||||||
|
|
||||||
```text
|
|
||||||
AccessServersBlock
|
|
||||||
- block_type: u8 = 40
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- access_servers_count: u8
|
|
||||||
- access_servers: string[access_servers_count]
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- блок может отсутствовать, если серверы доступа не заданы;
|
|
||||||
- список может обновляться при изменении маршрутизации пользователя;
|
|
||||||
- `access_servers` - логины пользователей системы, используемых как серверы доступа/relay. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы;
|
|
||||||
- точная семантика выбора сервера доступа определяется клиентской/серверной логикой SHiNE.
|
|
||||||
|
|
||||||
## 14. SessionsBlock
|
|
||||||
|
|
||||||
Блок хранит опубликованные пользовательские сессии. На текущем этапе регистрация пользователя не добавляет туда записи автоматически, поэтому стандартный create/update продолжает работать с пустым списком.
|
|
||||||
|
|
||||||
```text
|
|
||||||
SessionsBlock
|
|
||||||
- block_type: u8 = 50
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- sessions_mode: u8
|
|
||||||
- sessions_count: u8
|
|
||||||
- sessions: SessionRecord[sessions_count]
|
|
||||||
```
|
|
||||||
|
|
||||||
`sessions_mode`:
|
|
||||||
|
|
||||||
| Значение | Смысл |
|
|
||||||
|----------|-------|
|
|
||||||
| `1` | Можно использовать и сессии, зарегистрированные в PDA, и сессии, созданные вне PDA. |
|
|
||||||
| `10` | Зарезервировано на будущее: можно использовать только сессии, опубликованные в PDA. |
|
|
||||||
|
|
||||||
Сейчас рабочий режим по умолчанию: `sessions_mode = 1`. Серверная логика пока не реализует особое поведение для `10`; это задел под будущее расширение.
|
|
||||||
|
|
||||||
```text
|
|
||||||
SessionRecord
|
|
||||||
- session_type: u8
|
|
||||||
- session_version: u8
|
|
||||||
- session_name: string
|
|
||||||
- session_pub_key: [u8; 32]
|
|
||||||
```
|
|
||||||
|
|
||||||
`session_type`:
|
|
||||||
|
|
||||||
| Значение | Смысл |
|
|
||||||
|----------|-------|
|
|
||||||
| `1` | Обычная пользовательская сессия. |
|
|
||||||
| `50` | Кошелёк пользователя. |
|
|
||||||
| `100` | Homeserver пользователя. |
|
|
||||||
|
|
||||||
Правила:
|
|
||||||
|
|
||||||
- максимум `64` записей на пользователя;
|
|
||||||
- `session_name` не пустой, максимум `64` байта;
|
|
||||||
- `session_name` может содержать только символы `[A-Za-z0-9_]`;
|
|
||||||
- `session_version` сейчас должна быть равна `1`;
|
|
||||||
- внутри одного блока должны быть уникальны и `session_name`, и `session_pub_key`;
|
|
||||||
- на текущем этапе UI и регистрация не обязаны добавлять туда записи автоматически.
|
|
||||||
|
|
||||||
## 15. TrustedStateBlock
|
|
||||||
|
|
||||||
Пока trusted-логика не реализована полностью, поэтому блок хранит только счетчик.
|
|
||||||
|
|
||||||
```text
|
|
||||||
TrustedStateBlock
|
|
||||||
- block_type: u8 = 70
|
|
||||||
- block_version: u8 = 0
|
|
||||||
- trusted_count: u8 = 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Пока блок с доверенными лицами не реализуется, потому что полный формат trusted-логики еще не составлен. В будущем trusted-связи, очереди, таймеры и подтверждения должны быть вынесены в отдельный формат.
|
|
||||||
|
|
||||||
## 16. Подпись user_pda
|
|
||||||
|
|
||||||
Подписывается не вся PDA целиком, а unsigned-часть записи:
|
|
||||||
|
|
||||||
- от `magic` до последнего байта последнего типизированного блока включительно;
|
|
||||||
- включая `record_len`, `blocks_count`, все заголовки блоков и тела блоков;
|
|
||||||
- без поля `signature`;
|
|
||||||
- без padding.
|
|
||||||
|
|
||||||
Алгоритм:
|
|
||||||
|
|
||||||
```text
|
|
||||||
message = hash(unsigned_record_bytes)
|
|
||||||
signature = Ed25519(root_key, message)
|
|
||||||
```
|
|
||||||
|
|
||||||
Solana-программа проверяет подпись через встроенную Ed25519-инструкцию. Подписантом должен быть `root_key` из `RootKeyBlock`.
|
|
||||||
Для `shine_users` эта инструкция должна стоять в транзакции сразу перед Ed25519-инструкцией `last_block_signature` и непосредственно перед самой `create/update`-инструкцией программы.
|
|
||||||
|
|
||||||
Смену формата подписи сейчас не трогаем.
|
|
||||||
|
|
||||||
## 17. Регистрация пользователя
|
|
||||||
|
|
||||||
При регистрации:
|
|
||||||
|
|
||||||
- PDA еще не должна существовать;
|
|
||||||
- логин проходит проверку формата и login guard;
|
|
||||||
- `record_number = 0`;
|
|
||||||
- `prev_record_hash = 0x00...00`;
|
|
||||||
- `created_at_ms = updated_at_ms`;
|
|
||||||
- обязательные блоки присутствуют;
|
|
||||||
- создается минимум один `BlockchainRecord`;
|
|
||||||
- новый `SessionsBlock` может присутствовать, но при обычной регистрации сейчас записывается пустой список с `sessions_mode = 1`;
|
|
||||||
- стартовый `paid_limit_bytes` равен стартовому бонусу плюс оплаченный дополнительный лимит;
|
|
||||||
- `used_bytes <= paid_limit_bytes`;
|
|
||||||
- пользователь платит регистрационную комиссию;
|
|
||||||
- если покупается дополнительный лимит, пользователь платит комиссию за этот лимит;
|
|
||||||
- вся unsigned-часть записи подписана `root_key`.
|
|
||||||
|
|
||||||
## 18. Обновление пользователя
|
|
||||||
|
|
||||||
При обновлении:
|
|
||||||
|
|
||||||
- PDA должна существовать;
|
|
||||||
- `login`, `created_at_ms`, `recovery_key`, `root_key`, `client_key` не меняются;
|
|
||||||
- `record_number = previous_record_number + 1`;
|
|
||||||
- `prev_record_hash` равен хэшу unsigned-части предыдущей записи;
|
|
||||||
- `updated_at_ms` обновляется;
|
|
||||||
- unsigned-часть новой записи подписана `root_key`;
|
|
||||||
- лимиты блокчейнов могут только увеличиваться;
|
|
||||||
- занятый размер и номер последнего блока не могут уменьшаться;
|
|
||||||
- при увеличении оплаченного лимита пользователь доплачивает комиссию;
|
|
||||||
- Arweave `tx_id` может быть пустым или обновленным, но его содержимое Solana не валидирует.
|
|
||||||
|
|
||||||
## 19. Отличия от старого линейного формата
|
|
||||||
|
|
||||||
Старый формат после `login` хранил поля линейно:
|
|
||||||
|
|
||||||
- `root_key_status`;
|
|
||||||
- `root_key`;
|
|
||||||
- `blockchain_key_status`;
|
|
||||||
- `blockchain_key`;
|
|
||||||
- `client_key_status`;
|
|
||||||
- `client_key`;
|
|
||||||
- `chain_number`;
|
|
||||||
- `balance`;
|
|
||||||
- серверные поля;
|
|
||||||
- access-серверы;
|
|
||||||
- `trusted_count`;
|
|
||||||
- `reserved`;
|
|
||||||
- `signature`.
|
|
||||||
|
|
||||||
Новый целевой формат сохраняет первые 9 фиксированных полей как заголовок, но дальше переходит на типизированные блоки:
|
|
||||||
|
|
||||||
- recovery-ключ становится отдельным обязательным блоком;
|
|
||||||
- ключи становятся отдельными блоками;
|
|
||||||
- данные блокчейна становятся расширенным блоком со своим публичным ключом, лимитом, занятым размером, вершиной цепочки и Arweave `tx_id`;
|
|
||||||
- серверные данные и access-серверы отделяются от данных блокчейна;
|
|
||||||
- расширение формата делается добавлением новых версий блоков или новых `block_type`, а не вставкой полей в середину линейной записи.
|
|
||||||
|
|
||||||
## 20. Деривация ключей из master secret
|
|
||||||
|
|
||||||
Сама Solana-программа не вычисляет ключи из секрета и не хранит приватные ключи. Но текущая согласованная клиентская схема деривации для публичной версии формата фиксируется здесь как reference для UI/ESP32/внешних клиентов.
|
|
||||||
|
|
||||||
Базовая формула:
|
|
||||||
|
|
||||||
```text
|
|
||||||
seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || suffix_utf8)
|
|
||||||
```
|
|
||||||
|
|
||||||
Где:
|
|
||||||
|
|
||||||
- `master_secret32` — 32-байтовый master secret пользователя;
|
|
||||||
- `suffix_utf8` — строка назначения ключа.
|
|
||||||
|
|
||||||
Согласованные suffix:
|
|
||||||
|
|
||||||
```text
|
|
||||||
"recovery.key"
|
|
||||||
"root.key"
|
|
||||||
"blockchain.key"
|
|
||||||
"client.key"
|
|
||||||
```
|
|
||||||
|
|
||||||
Соответствие:
|
|
||||||
|
|
||||||
```text
|
|
||||||
recovery.seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "recovery.key")
|
|
||||||
root.seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "root.key")
|
|
||||||
blockchain.seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "blockchain.key")
|
|
||||||
client.seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "client.key")
|
|
||||||
```
|
|
||||||
|
|
||||||
Далее каждая строка `seed` интерпретируется off-chain как `seed32` для отдельной пары Ed25519.
|
|
||||||
|
|
||||||
## 21. Что пока не входит в формат
|
|
||||||
|
|
||||||
Пока не проектируем:
|
|
||||||
|
|
||||||
- ротацию `recovery_key`;
|
|
||||||
- ротацию `root_key`;
|
|
||||||
- сложную ротацию `client_key`;
|
|
||||||
- ротацию `blockchain_public_key`;
|
|
||||||
- проверку содержимого Arweave transaction;
|
|
||||||
- хранение полной истории пользовательского блокчейна внутри Solana;
|
|
||||||
- подключение Solana-модуля к сборке/деплою основного сервера SHiNE.
|
|
||||||
@ -1,166 +0,0 @@
|
|||||||
# Архитектура Solana-программ SHiNE
|
|
||||||
|
|
||||||
Документ описывает рабочую архитектуру Solana-части SHiNE: три Anchor-программы, DAO, ключи управления, PDA-счета и движение денег.
|
|
||||||
|
|
||||||
Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.
|
|
||||||
|
|
||||||
Статус: актуализировано по коду `shine-solana/shine/programs/*` на 2026-05-25.
|
|
||||||
|
|
||||||
Связанные документы:
|
|
||||||
|
|
||||||
- `Dev_Docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей.
|
|
||||||
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` — точный формат `user_pda` для `shine_users`.
|
|
||||||
- `shine-solana/shine/doc/FUNDS_FLOW.md` — короткая справка по денежным потокам внутри Solana-модуля.
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
В Solana-модуле сейчас три основные программы:
|
|
||||||
|
|
||||||
1. `shine_login_guard` — проверяет логин и возвращает класс логина: обычный, premium или trademark.
|
|
||||||
2. `shine_users` — создает и обновляет пользовательскую PDA-запись, проверяет подписи и берет оплату за регистрацию/увеличение лимита.
|
|
||||||
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.
|
|
||||||
|
|
||||||
DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.
|
|
||||||
|
|
||||||
## Общая схема
|
|
||||||
|
|
||||||
Редактируемая Mermaid-схема находится в [schemes/architecture.mmd](schemes/architecture.mmd).
|
|
||||||
|
|
||||||
Картинки:
|
|
||||||
|
|
||||||
- [schemes/architecture.svg](schemes/architecture.svg)
|
|
||||||
- [schemes/architecture.png](schemes/architecture.png)
|
|
||||||
|
|
||||||
## Программы и функции
|
|
||||||
|
|
||||||
| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| 1 | `shine_login_guard` | `classify_login` | Проверка логина перед регистрацией. |
|
|
||||||
| 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_user_pda`, `update_user_pda` | Регистрация пользователя, обновление записи, экономика лимита. |
|
|
||||||
| 3 | `shine_payments` | `init`, `update_coef_limit`, `grant_manager_limits`, `buy_ticket`, `buy_ticket_usd`, `buy_ticket_sol`, `manager_add_ticket`, `step_payout`, `change_ticket_recipient` | Vault, билеты, очереди, выплаты, DAO-настройки, лимиты менеджеров. |
|
|
||||||
| DAO | governance/authority | Вызовы через governance и управляющие ключи | Управление правами, казной, настройками и будущими обновлениями программ. |
|
|
||||||
|
|
||||||
## Актуальные program id
|
|
||||||
|
|
||||||
Актуальные адреса заданы одновременно в `Anchor.toml`, `declare_id!` программ и `programs/common/src/deploy_config.rs`:
|
|
||||||
|
|
||||||
| Программа | Program ID |
|
|
||||||
| --- | --- |
|
|
||||||
| `shine_login_guard` | `3xkopA7cXagxzMFrKdv3NCBfV6BKiRJCk69kr27M2sRo` |
|
|
||||||
| `shine_users` | `3bYrnXwLc56oVPUBAjY8zTMLwHCYq29b5rUMu3b64SQJ` |
|
|
||||||
| `shine_payments` | `c4yTa4JT9EtQDCBX9LmWFK6T2gp4JGsuymFbom2EudW` |
|
|
||||||
|
|
||||||
Если эти адреса меняются, нужно синхронно обновить:
|
|
||||||
|
|
||||||
1. `shine-solana/shine/Anchor.toml`
|
|
||||||
2. `declare_id!` в `programs/*/src/lib.rs`
|
|
||||||
3. `programs/common/src/deploy_config.rs`
|
|
||||||
4. UI/серверные константы, перечисленные в `Dev_Docs/Инициализация_Solana_регистрации/README.md`
|
|
||||||
|
|
||||||
## Ключи и authority
|
|
||||||
|
|
||||||
Для удобного понимания на старте можно считать, что есть четыре группы ключей:
|
|
||||||
|
|
||||||
1. `key_1` / authority программы `shine_login_guard`.
|
|
||||||
- Сейчас программа только классифицирует логин.
|
|
||||||
- На первом этапе ее можно оставить под отдельным ключом.
|
|
||||||
- В будущем право обновления можно передать DAO.
|
|
||||||
|
|
||||||
2. `key_2` / authority программы `shine_users`.
|
|
||||||
- Отвечает за деплой/upgrade второй программы.
|
|
||||||
- Защищенное обновление economy-конфига в коде уже проверяет `DAO_AUTHORITY`.
|
|
||||||
- В целевой модели upgrade-authority второй программы нужно передать DAO.
|
|
||||||
|
|
||||||
3. `key_3` / authority программы `shine_payments`.
|
|
||||||
- Отвечает за деплой/upgrade третьей программы.
|
|
||||||
- Защищенные методы `update_coef_limit` и `grant_manager_limits` проверяют `dao_wallet` из `ConfigState`.
|
|
||||||
- В целевой модели upgrade-authority третьей программы нужно передать DAO.
|
|
||||||
|
|
||||||
4. DAO-ключи.
|
|
||||||
- Это управляющие кошельки/токены/realm governance.
|
|
||||||
- DAO может добавлять и отзывать управляющие ключи по голосованию.
|
|
||||||
- DAO-казна получает деньги от покупки тикетов и DAO-часть выплат из `inflow_vault`.
|
|
||||||
|
|
||||||
Адреса program id сейчас берутся из `programs/common/src/deploy_config.rs`. Для production/devnet можно подбирать vanity-адреса с понятным началом вроде `SHi...`, но это отдельная операция генерации ключей и деплоя.
|
|
||||||
|
|
||||||
## Счета и PDA
|
|
||||||
|
|
||||||
Постоянные PDA и счета:
|
|
||||||
|
|
||||||
1. `shine_users`
|
|
||||||
- `user_pda` — пользовательская запись по seed `login=<login>`, создается для каждого логина.
|
|
||||||
- `users_economy_config_pda` — общие параметры экономики регистрации и лимита.
|
|
||||||
|
|
||||||
2. `shine_payments`
|
|
||||||
- `config_pda` — хранит `dao_wallet` и адрес `inflow_vault`.
|
|
||||||
- `coef_limit_pda` — хранит коэффициент выплат, лимит очереди и награду вызывающему `step_payout`.
|
|
||||||
- `queues_pda` — агрегаты очередей выплат.
|
|
||||||
- `inflow_vault_pda` — PDA-вольт, куда `shine_users` переводит оплату регистрации и увеличения лимита.
|
|
||||||
- `ticket_pda` — отдельная PDA-запись тикета на каждую покупку/менеджерскую выдачу.
|
|
||||||
- `manager_allowance_pda` — PDA лимитов конкретного менеджера.
|
|
||||||
|
|
||||||
3. DAO
|
|
||||||
- `dao_wallet` / treasury — казна DAO.
|
|
||||||
- governance-аккаунты DAO — realm, governance, proposal/vote records и связанные аккаунты SPL Governance, если используется эта модель.
|
|
||||||
|
|
||||||
## Правило разделения с основным сервером
|
|
||||||
|
|
||||||
Solana-модуль лежит в основном репозитории как отдельная папка `shine-solana/shine/`, но не подключается автоматически к сборке или деплою основного сервера SHiNE. Команды `deployServer` и `deployUI` не должны деплоить Anchor-программы. Solana build/deploy выполняется отдельно из папки `shine-solana/shine/` по локальным правилам модуля.
|
|
||||||
|
|
||||||
## Движение денег
|
|
||||||
|
|
||||||
Основные потоки:
|
|
||||||
|
|
||||||
1. Регистрация пользователя через `shine_users::create_user_pda`.
|
|
||||||
- Платит `signer`.
|
|
||||||
- Деньги идут в `shine_payments::inflow_vault_pda`.
|
|
||||||
- Сумма состоит из регистрационной комиссии и оплаты дополнительного лимита.
|
|
||||||
|
|
||||||
2. Увеличение лимита через `shine_users::update_user_pda`.
|
|
||||||
- Платит `signer`.
|
|
||||||
- Деньги идут в тот же `inflow_vault_pda`.
|
|
||||||
- Сумма равна оплате дополнительного лимита.
|
|
||||||
|
|
||||||
3. Покупка тикета через `shine_payments::buy_ticket*`.
|
|
||||||
- Платит покупатель.
|
|
||||||
- Деньги сразу идут в `dao_wallet`.
|
|
||||||
- Одновременно создается тикет на выплату.
|
|
||||||
|
|
||||||
4. Выплата через `shine_payments::step_payout`.
|
|
||||||
- Вызвать может любой подписант.
|
|
||||||
- Деньги берутся из `inflow_vault_pda`.
|
|
||||||
- Часть идет получателю тикета.
|
|
||||||
- Часть идет в `dao_wallet`.
|
|
||||||
- Небольшая награда идет вызвавшему шаг выплат.
|
|
||||||
- Если очереди пустые, весь доступный остаток `inflow_vault_pda` переводится в DAO.
|
|
||||||
|
|
||||||
## Передача прав DAO
|
|
||||||
|
|
||||||
Минимальная целевая модель:
|
|
||||||
|
|
||||||
1. `shine_login_guard`
|
|
||||||
- Пока оставить на отдельном ключе `key_1`.
|
|
||||||
- Передачу DAO сделать позже, когда логика premium/trademark стабилизируется.
|
|
||||||
|
|
||||||
2. `shine_users`
|
|
||||||
- Economy-настройки уже должны обновляться DAO-authority.
|
|
||||||
- Upgrade-authority программы после проверки можно передать DAO.
|
|
||||||
|
|
||||||
3. `shine_payments`
|
|
||||||
- DAO уже управляет настройками выплат и лимитами менеджеров через `dao_wallet`.
|
|
||||||
- Upgrade-authority программы после проверки можно передать DAO.
|
|
||||||
|
|
||||||
4. DAO
|
|
||||||
- Управляет казной.
|
|
||||||
- Принимает решения голосованием.
|
|
||||||
- Добавляет/отзывает управляющие ключи.
|
|
||||||
- Вызывает защищенные методы второй и третьей программ.
|
|
||||||
- В будущем может принять управление первой программой.
|
|
||||||
|
|
||||||
## Детальные файлы
|
|
||||||
|
|
||||||
- [details/shine_login_guard.md](details/shine_login_guard.md)
|
|
||||||
- [details/shine_users.md](details/shine_users.md)
|
|
||||||
- [details/shine_payments.md](details/shine_payments.md)
|
|
||||||
- [details/shine_dao.md](details/shine_dao.md)
|
|
||||||
- [details/accounts_and_money_flow.md](details/accounts_and_money_flow.md)
|
|
||||||
@ -1,110 +0,0 @@
|
|||||||
# Счета, ключи и движение денег
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
В архитектуре есть три типа объектов:
|
|
||||||
|
|
||||||
1. Ключи программ и DAO.
|
|
||||||
2. PDA-счета состояния.
|
|
||||||
3. Денежные счета, через которые проходят SOL/lamports.
|
|
||||||
|
|
||||||
## Ключи
|
|
||||||
|
|
||||||
Минимальный набор для понимания:
|
|
||||||
|
|
||||||
1. `key_1` — deploy/upgrade authority `shine_login_guard`.
|
|
||||||
2. `key_2` — deploy/upgrade authority `shine_users`.
|
|
||||||
3. `key_3` — deploy/upgrade authority `shine_payments`.
|
|
||||||
4. `DAO_AUTHORITY` — адрес, который имеет право менять защищенные настройки.
|
|
||||||
5. `DAO_TREASURY_WALLET` / `dao_wallet` — казна DAO.
|
|
||||||
6. `manager_wallet` — кошелек менеджера, которому DAO выдает лимиты на создание тикетов.
|
|
||||||
7. `user root_key` — корневой ключ пользователя для подписи пользовательской записи.
|
|
||||||
8. `user client_key` — ключ устройства пользователя.
|
|
||||||
9. `server_key` — ключ сервера пользователя, если пользователь является сервером.
|
|
||||||
|
|
||||||
Текущие адреса из `programs/common/src/deploy_config.rs`:
|
|
||||||
|
|
||||||
| Роль | Адрес |
|
|
||||||
| --- | --- |
|
|
||||||
| `SHINE_LOGIN_GUARD_PROGRAM_ID` | `3xkopA7cXagxzMFrKdv3NCBfV6BKiRJCk69kr27M2sRo` |
|
|
||||||
| `SHINE_USERS_PROGRAM_ID` | `3bYrnXwLc56oVPUBAjY8zTMLwHCYq29b5rUMu3b64SQJ` |
|
|
||||||
| `SHINE_PAYMENTS_PROGRAM_ID` | `c4yTa4JT9EtQDCBX9LmWFK6T2gp4JGsuymFbom2EudW` |
|
|
||||||
| `DAO_AUTHORITY` | `FUc28vNixp7F3nnkpGVt6nuJbgvJ4429v4B5wS52Df6P` |
|
|
||||||
| `DAO_TREASURY_WALLET` | `FUc28vNixp7F3nnkpGVt6nuJbgvJ4429v4B5wS52Df6P` |
|
|
||||||
|
|
||||||
## Постоянные PDA
|
|
||||||
|
|
||||||
`shine_users`:
|
|
||||||
|
|
||||||
- `user_pda` — создается для каждого логина, seed `login=` + normalized login.
|
|
||||||
- `users_economy_config_pda` — один PDA с экономикой регистрации, seed `shine_users_economy_config`.
|
|
||||||
|
|
||||||
`shine_payments`:
|
|
||||||
|
|
||||||
- `config_pda` — один PDA конфига, seed `shine_payments_config`.
|
|
||||||
- `coef_limit_pda` — один PDA коэффициента/лимита/награды, seed `shine_payments_coef_limit`.
|
|
||||||
- `queues_pda` — один PDA агрегатов очередей, seed `shine_payments_queues`.
|
|
||||||
- `inflow_vault_pda` — один PDA-вольт входящих средств, seed `shine_payments_inflow_vault`.
|
|
||||||
- `ticket_pda` — много PDA, по одному на тикет, seed `shine_payments_q1_ticket` или `shine_payments_q2_ticket` + индекс.
|
|
||||||
- `manager_allowance_pda` — много PDA, по одному на менеджера, seed `shine_p_manager_allow` + адрес менеджера.
|
|
||||||
|
|
||||||
## Денежные потоки
|
|
||||||
|
|
||||||
### Регистрация
|
|
||||||
|
|
||||||
```text
|
|
||||||
user signer -> shine_users::create_user_pda -> shine_payments::inflow_vault_pda
|
|
||||||
```
|
|
||||||
|
|
||||||
Состав платежа:
|
|
||||||
|
|
||||||
- регистрационная комиссия;
|
|
||||||
- оплата `additional_limit`.
|
|
||||||
|
|
||||||
### Увеличение лимита
|
|
||||||
|
|
||||||
```text
|
|
||||||
user signer -> shine_users::update_user_pda -> shine_payments::inflow_vault_pda
|
|
||||||
```
|
|
||||||
|
|
||||||
Состав платежа:
|
|
||||||
|
|
||||||
- только оплата `additional_limit`.
|
|
||||||
|
|
||||||
### Покупка тикета
|
|
||||||
|
|
||||||
```text
|
|
||||||
buyer signer -> shine_payments::buy_ticket* -> dao_wallet
|
|
||||||
```
|
|
||||||
|
|
||||||
При этом создается `ticket_pda`, но деньги в `inflow_vault_pda` на этом шаге не идут.
|
|
||||||
|
|
||||||
### Выплата
|
|
||||||
|
|
||||||
```text
|
|
||||||
shine_payments::inflow_vault_pda -> ticket_recipient_wallet
|
|
||||||
shine_payments::inflow_vault_pda -> dao_wallet
|
|
||||||
shine_payments::inflow_vault_pda -> step_payout caller
|
|
||||||
```
|
|
||||||
|
|
||||||
Если очереди пустые:
|
|
||||||
|
|
||||||
```text
|
|
||||||
shine_payments::inflow_vault_pda -> dao_wallet
|
|
||||||
```
|
|
||||||
|
|
||||||
## Что нужно создать на старте
|
|
||||||
|
|
||||||
Минимально:
|
|
||||||
|
|
||||||
1. Три program id для `shine_login_guard`, `shine_users`, `shine_payments`.
|
|
||||||
2. Три upgrade-authority ключа или один временный deploy-ключ с четким планом передачи прав.
|
|
||||||
3. DAO authority/treasury.
|
|
||||||
4. `users_economy_config_pda`.
|
|
||||||
5. `shine_payments` PDA: `config_pda`, `coef_limit_pda`, `queues_pda`, `inflow_vault_pda`.
|
|
||||||
|
|
||||||
Динамически будут создаваться:
|
|
||||||
|
|
||||||
- `user_pda` на каждого пользователя;
|
|
||||||
- `ticket_pda` на каждый тикет;
|
|
||||||
- `manager_allowance_pda` на каждого менеджера.
|
|
||||||
@ -1,74 +0,0 @@
|
|||||||
# SHiNE DAO
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
DAO — управляющий слой Solana-части SHiNE. В текущем коде это не отдельная Anchor-программа в `programs/`, а модель управления через DAO-кошелек, DAO-authority, governance-скрипты и будущую передачу upgrade-authority программ.
|
|
||||||
|
|
||||||
## Что DAO должно уметь
|
|
||||||
|
|
||||||
1. Управлять казной.
|
|
||||||
- Принимать средства на `dao_wallet`.
|
|
||||||
- Выплачивать средства со счета DAO по решениям голосования.
|
|
||||||
|
|
||||||
2. Управлять настройками `shine_users`.
|
|
||||||
- Обновлять регистрационную комиссию.
|
|
||||||
- Обновлять цену шага лимита.
|
|
||||||
- Обновлять стартовый бонус лимита.
|
|
||||||
|
|
||||||
3. Управлять настройками `shine_payments`.
|
|
||||||
- Обновлять коэффициент выплат.
|
|
||||||
- Обновлять лимит очереди.
|
|
||||||
- Обновлять награду за вызов `step_payout`.
|
|
||||||
|
|
||||||
4. Управлять менеджерами.
|
|
||||||
- Выдавать менеджеру лимит на добавление тикетов.
|
|
||||||
- Отдельно учитывать лимиты Q1 и Q2.
|
|
||||||
|
|
||||||
5. Управлять правами программ.
|
|
||||||
- Принять upgrade-authority `shine_users`.
|
|
||||||
- Принять upgrade-authority `shine_payments`.
|
|
||||||
- Позже принять upgrade-authority `shine_login_guard`, если это потребуется.
|
|
||||||
|
|
||||||
6. Управлять ключами DAO.
|
|
||||||
- Добавлять управляющие ключи.
|
|
||||||
- Отзывать или сжигать управляющие ключи.
|
|
||||||
- Делать это через голосование, а не вручную одним админом.
|
|
||||||
|
|
||||||
7. Фиксировать решения.
|
|
||||||
- Делать заявления/решения через governance-механику.
|
|
||||||
- Привязывать важные изменения к proposal/vote/execute.
|
|
||||||
|
|
||||||
## Текущие адреса управления
|
|
||||||
|
|
||||||
В общем deploy-конфиге сейчас есть два важных адреса:
|
|
||||||
|
|
||||||
- `DAO_AUTHORITY` — используется `shine_users` для проверки права менять economy-конфиг.
|
|
||||||
- `DAO_TREASURY_WALLET` — используется `shine_payments` как `dao_wallet`.
|
|
||||||
|
|
||||||
Сейчас они могут совпадать. В целевой DAO-модели их лучше рассматривать как разные роли:
|
|
||||||
|
|
||||||
- authority/governance signer — кто имеет право исполнять управленческие инструкции;
|
|
||||||
- treasury wallet — счет, куда приходят деньги DAO.
|
|
||||||
|
|
||||||
## Передача прав
|
|
||||||
|
|
||||||
Рекомендуемый порядок:
|
|
||||||
|
|
||||||
1. Сначала стабилизировать и проверить `shine_users` и `shine_payments`.
|
|
||||||
2. Передать DAO право обновлять настройки, если оно еще не передано.
|
|
||||||
3. Передать DAO upgrade-authority второй и третьей программ.
|
|
||||||
4. Оставить `shine_login_guard` на отдельном ключе до стабилизации словарей и правил логинов.
|
|
||||||
5. После стабилизации решить отдельным голосованием, передавать ли первую программу DAO.
|
|
||||||
|
|
||||||
## Важное разделение
|
|
||||||
|
|
||||||
Есть два разных типа прав:
|
|
||||||
|
|
||||||
1. Право вызвать защищенную функцию программы.
|
|
||||||
- Например, `update_coef_limit` или `grant_manager_limits`.
|
|
||||||
- Проверяется внутри программы по `dao_wallet` или `DAO_AUTHORITY`.
|
|
||||||
|
|
||||||
2. Право обновить саму программу.
|
|
||||||
- Это upgrade-authority Solana ProgramData.
|
|
||||||
- Оно передается отдельной Solana-командой/DAO-транзакцией и не равно обычному PDA-счету.
|
|
||||||
|
|
||||||
@ -1,58 +0,0 @@
|
|||||||
# `shine_login_guard`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
`shine_login_guard` — первая программа Solana-модуля SHiNE. Она проверяет логин перед регистрацией пользователя и возвращает класс логина.
|
|
||||||
|
|
||||||
Папка программы: `shine-solana/shine/programs/shine_login_guard/`.
|
|
||||||
|
|
||||||
## Текущая функция
|
|
||||||
|
|
||||||
1. `classify_login(login: String)`
|
|
||||||
- Нормализует логин.
|
|
||||||
- Проверяет длину и допустимые символы.
|
|
||||||
- Сравнивает части логина со словарями premium/trademark.
|
|
||||||
- Возвращает результат через `set_return_data`.
|
|
||||||
|
|
||||||
Классы результата:
|
|
||||||
|
|
||||||
- `0` — обычный логин, регистрацию можно продолжать.
|
|
||||||
- `1` — premium-логин.
|
|
||||||
- `2` — trademark-логин, нужна отдельная проверка/разрешение.
|
|
||||||
|
|
||||||
## Правила нормализации и классификации
|
|
||||||
|
|
||||||
Текущая логика из `programs/shine_login_guard/src/lib.rs`:
|
|
||||||
|
|
||||||
- пустой логин или логин длиннее 20 символов получает класс `premium`;
|
|
||||||
- `_` при нормализации удаляется;
|
|
||||||
- допустимы только ASCII-буквы и цифры, остальные символы дают класс `premium`;
|
|
||||||
- после удаления `_` результат приводится к нижнему регистру;
|
|
||||||
- логины длиной 7 символов или меньше считаются `premium`;
|
|
||||||
- логин разбивается максимум на 3 словарных фрагмента;
|
|
||||||
- если среди найденных фрагментов есть trademark-слово, результат `trademark`;
|
|
||||||
- если найдены только premium-слова, результат `premium`;
|
|
||||||
- если разбиение по словарям не найдено, результат `free`.
|
|
||||||
|
|
||||||
Словари собираются на этапе build из файлов:
|
|
||||||
|
|
||||||
- `programs/shine_login_guard/src/dictionaries/premium/*.txt`
|
|
||||||
- `programs/shine_login_guard/src/dictionaries/trademarks/*.txt`
|
|
||||||
|
|
||||||
## Роль в общей схеме
|
|
||||||
|
|
||||||
`shine_users::create_user_pda` вызывает `shine_login_guard` через CPI и продолжает регистрацию только если логин получил класс `0`.
|
|
||||||
|
|
||||||
## Ключи и управление
|
|
||||||
|
|
||||||
На старте удобно считать, что у программы есть отдельный управляющий ключ `key_1`.
|
|
||||||
|
|
||||||
Текущая рекомендация:
|
|
||||||
|
|
||||||
- пока оставить `shine_login_guard` под отдельным ключом;
|
|
||||||
- не передавать ее DAO до стабилизации правил premium/trademark;
|
|
||||||
- позже можно передать upgrade-authority DAO, чтобы изменения словарей и правил проходили через голосование.
|
|
||||||
|
|
||||||
## Счета
|
|
||||||
|
|
||||||
Собственных постоянных PDA-счетов у программы сейчас нет. Для проверки нужен только подписант транзакции в `ClassifyLogin`.
|
|
||||||
@ -1,173 +0,0 @@
|
|||||||
# `shine_payments`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
`shine_payments` — третья программа Solana-модуля SHiNE. Она отвечает за vault входящих средств, DAO-казну, покупку тикетов, менеджерские лимиты, очереди выплат и пошаговое исполнение выплат.
|
|
||||||
|
|
||||||
Папка программы: `shine-solana/shine/programs/shine_payments/`.
|
|
||||||
|
|
||||||
## Текущие функции
|
|
||||||
|
|
||||||
1. `init`
|
|
||||||
- Создает основные PDA: `config_pda`, `coef_limit_pda`, `queues_pda`, `inflow_vault_pda`.
|
|
||||||
- Записывает `dao_wallet` и стартовые параметры выплат.
|
|
||||||
|
|
||||||
2. `update_coef_limit`
|
|
||||||
- Обновляет коэффициент выплаты, лимит очереди и награду вызвавшему `step_payout`.
|
|
||||||
- Требует подпись DAO-кошелька из `ConfigState`.
|
|
||||||
|
|
||||||
3. `grant_manager_limits`
|
|
||||||
- DAO выдает менеджеру лимиты на создание тикетов в очередях Q1/Q2.
|
|
||||||
- Создает или обновляет `manager_allowance_pda`.
|
|
||||||
|
|
||||||
4. `buy_ticket`
|
|
||||||
- Покупка тикета с суммой в lamports, пересчетом через Pyth SOL/USD.
|
|
||||||
|
|
||||||
5. `buy_ticket_usd`
|
|
||||||
- Покупка тикета от USD-центов с защитой по максимальному платежу в lamports.
|
|
||||||
|
|
||||||
6. `buy_ticket_sol`
|
|
||||||
- Покупка тикета в lamports с проверкой минимального ожидаемого USD-эквивалента.
|
|
||||||
|
|
||||||
7. `manager_add_ticket`
|
|
||||||
- Менеджер создает тикет за счет выданного ему DAO-лимита.
|
|
||||||
|
|
||||||
8. `step_payout`
|
|
||||||
- Любой подписант может вызвать шаг выплат.
|
|
||||||
- Программа выплачивает следующий тикет, DAO-часть и награду вызывающему.
|
|
||||||
|
|
||||||
9. `change_ticket_recipient`
|
|
||||||
- Текущий получатель тикета может поменять адрес получателя, если тикет еще не следующий на выплату.
|
|
||||||
|
|
||||||
## Аргументы инструкций
|
|
||||||
|
|
||||||
`init` аргументов не принимает.
|
|
||||||
|
|
||||||
`update_coef_limit`:
|
|
||||||
|
|
||||||
- `coef_ppm: u64`
|
|
||||||
- `limit_usd_cents: u64`
|
|
||||||
- `call_reward_lamports: u64`
|
|
||||||
|
|
||||||
`grant_manager_limits`:
|
|
||||||
|
|
||||||
- `manager_wallet: Pubkey`
|
|
||||||
- `add_q1_usd_cents: u64`
|
|
||||||
- `add_q2_usd_cents: u64`
|
|
||||||
|
|
||||||
`buy_ticket`:
|
|
||||||
|
|
||||||
- `amount_lamports: u64`
|
|
||||||
- `recipient_wallet: Pubkey`
|
|
||||||
|
|
||||||
`buy_ticket_usd`:
|
|
||||||
|
|
||||||
- `amount_usd_cents: u64`
|
|
||||||
- `max_pay_lamports: u64`
|
|
||||||
- `recipient_wallet: Pubkey`
|
|
||||||
|
|
||||||
`buy_ticket_sol`:
|
|
||||||
|
|
||||||
- `amount_lamports: u64`
|
|
||||||
- `min_expected_usd_cents: u64`
|
|
||||||
- `recipient_wallet: Pubkey`
|
|
||||||
|
|
||||||
`manager_add_ticket`:
|
|
||||||
|
|
||||||
- `queue_id: u8` — только `1` или `2`
|
|
||||||
- `recipient_wallet: Pubkey`
|
|
||||||
- `payout_usd_cents: u64`
|
|
||||||
|
|
||||||
`change_ticket_recipient`:
|
|
||||||
|
|
||||||
- `new_recipient_wallet: Pubkey`
|
|
||||||
|
|
||||||
## Главные PDA
|
|
||||||
|
|
||||||
1. `config_pda`
|
|
||||||
- Seed: `shine_payments_config`.
|
|
||||||
- Хранит `dao_wallet` и `inflow_vault`.
|
|
||||||
- Размер PDA: `8 + 160` байт.
|
|
||||||
|
|
||||||
2. `coef_limit_pda`
|
|
||||||
- Seed: `shine_payments_coef_limit`.
|
|
||||||
- Хранит коэффициент выплат, лимит и награду `step_payout`.
|
|
||||||
- Размер PDA: `8 + 96` байт.
|
|
||||||
|
|
||||||
3. `queues_pda`
|
|
||||||
- Seed: `shine_payments_queues`.
|
|
||||||
- Хранит агрегаты очередей Q1/Q2.
|
|
||||||
- Размер PDA: `8 + 192` байт.
|
|
||||||
|
|
||||||
4. `inflow_vault_pda`
|
|
||||||
- Seed: `shine_payments_inflow_vault`.
|
|
||||||
- Принимает деньги от `shine_users`.
|
|
||||||
- Из него выполняются выплаты тикетам, DAO и вызывающему `step_payout`.
|
|
||||||
- Размер PDA: `8 + 32` байт.
|
|
||||||
|
|
||||||
5. `ticket_pda`
|
|
||||||
- Seed зависит от очереди и индекса тикета.
|
|
||||||
- Отдельная PDA-запись на каждый тикет.
|
|
||||||
- Q1 seed: `shine_payments_q1_ticket` + `ticket_index`.
|
|
||||||
- Q2 seed: `shine_payments_q2_ticket` + `ticket_index`.
|
|
||||||
- Размер PDA: `8 + 160` байт.
|
|
||||||
|
|
||||||
6. `manager_allowance_pda`
|
|
||||||
- Seed: `shine_p_manager_allow` + адрес менеджера.
|
|
||||||
- Хранит доступный лимит менеджера по Q1/Q2.
|
|
||||||
- Размер PDA: `8 + 128` байт.
|
|
||||||
|
|
||||||
## Текущие параметры
|
|
||||||
|
|
||||||
Параметры initial config из `programs/shine_payments/src/settings.rs`:
|
|
||||||
|
|
||||||
| Поле | Значение | Смысл |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `START_COEF_PPM` | `5_000_000` | коэффициент 5.0x в ppm-масштабе |
|
|
||||||
| `START_LIMIT_USD_CENTS` | `1_000_000` | стартовый лимит Q1: 10_000 USD |
|
|
||||||
| `START_CALL_REWARD_LAMPORTS` | `8_000_000` | награда вызвавшему `step_payout`, 0.008 SOL |
|
|
||||||
| `MAX_CALL_REWARD_LAMPORTS` | `10_000_000` | максимум награды, 0.01 SOL |
|
|
||||||
| `ORACLE_MAX_AGE_SECS` | `120` | максимальный возраст цены Pyth |
|
|
||||||
|
|
||||||
Для расчетов используется Pyth SOL/USD:
|
|
||||||
|
|
||||||
- feed id: `0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d`
|
|
||||||
- price update account: `7UVimffxr9ow1uXYxsr4LHAcV58mLzhmwaeKvJ1pjLiE`
|
|
||||||
|
|
||||||
## Деньги
|
|
||||||
|
|
||||||
Входы:
|
|
||||||
|
|
||||||
- из `shine_users` в `inflow_vault_pda` при регистрации и увеличении лимита;
|
|
||||||
- от покупателя тикета сразу в `dao_wallet` при `buy_ticket*`.
|
|
||||||
|
|
||||||
Выходы:
|
|
||||||
|
|
||||||
- из `inflow_vault_pda` получателю тикета;
|
|
||||||
- из `inflow_vault_pda` в `dao_wallet`;
|
|
||||||
- из `inflow_vault_pda` вызвавшему `step_payout`;
|
|
||||||
- если очереди пустые, весь доступный остаток `inflow_vault_pda` переводится в DAO.
|
|
||||||
|
|
||||||
## Очереди и выплаты
|
|
||||||
|
|
||||||
Выплаты идут строго пошагово:
|
|
||||||
|
|
||||||
- если есть невыплаченные Q1-тикеты, `step_payout` берет следующий Q1;
|
|
||||||
- если Q1 пустая, берется следующий Q2;
|
|
||||||
- для Q1 DAO-часть равна сумме тикета в USD;
|
|
||||||
- для Q2 DAO-часть равна двойной сумме тикета в USD;
|
|
||||||
- перед выплатой суммы пересчитываются из USD-центов в lamports по Pyth SOL/USD;
|
|
||||||
- если в `inflow_vault_pda` не хватает средств на тикет, DAO-часть и награду вызвавшему, шаг отклоняется.
|
|
||||||
|
|
||||||
`change_ticket_recipient` запрещает менять получателя у тикета, который является следующим на выплату.
|
|
||||||
|
|
||||||
## Ключи и управление
|
|
||||||
|
|
||||||
На старте удобно считать, что у программы есть отдельный управляющий ключ `key_3`.
|
|
||||||
|
|
||||||
Целевая модель:
|
|
||||||
|
|
||||||
- `update_coef_limit` вызывает DAO;
|
|
||||||
- `grant_manager_limits` вызывает DAO;
|
|
||||||
- upgrade-authority программы после проверки передается DAO;
|
|
||||||
- `step_payout` остается открытым для любого подписанта, чтобы выплаты не зависели от одного оператора.
|
|
||||||
@ -1,136 +0,0 @@
|
|||||||
# `shine_users`
|
|
||||||
|
|
||||||
## Кратко
|
|
||||||
|
|
||||||
`shine_users` — вторая программа Solana-модуля SHiNE. Она отвечает за создание и обновление пользовательской PDA-записи, проверку подписи записи, проверку логина через `shine_login_guard` и оплату регистрации/дополнительного лимита.
|
|
||||||
|
|
||||||
Папка программы: `shine-solana/shine/programs/shine_users/`.
|
|
||||||
|
|
||||||
## Текущие функции
|
|
||||||
|
|
||||||
1. `init_users_economy_config`
|
|
||||||
- Создает PDA с экономическими настройками пользователей.
|
|
||||||
- Записывает стартовую регистрационную комиссию, цену шага лимита и стартовый бонус лимита.
|
|
||||||
|
|
||||||
2. `update_users_economy_config`
|
|
||||||
- Обновляет экономические настройки.
|
|
||||||
- Требует подпись `DAO_AUTHORITY` из общего deploy-конфига.
|
|
||||||
|
|
||||||
3. `create_user_pda`
|
|
||||||
- Проверяет логин через `shine_login_guard`.
|
|
||||||
- Проверяет структуру полей пользователя.
|
|
||||||
- Проверяет подпись записи root-ключом пользователя.
|
|
||||||
- Создает `user_pda` по seed `login=<normalized_login>`.
|
|
||||||
- Переводит оплату регистрации и дополнительного лимита в `shine_payments::inflow_vault_pda`.
|
|
||||||
|
|
||||||
4. `update_user_pda`
|
|
||||||
- Проверяет неизменяемые поля пользователя.
|
|
||||||
- Проверяет `prev_hash`, новую подпись и новое состояние последнего блока.
|
|
||||||
- При необходимости расширяет PDA.
|
|
||||||
- Переводит оплату дополнительного лимита в `shine_payments::inflow_vault_pda`.
|
|
||||||
|
|
||||||
## Аргументы инструкций
|
|
||||||
|
|
||||||
`init_users_economy_config` аргументов не принимает.
|
|
||||||
|
|
||||||
`update_users_economy_config`:
|
|
||||||
|
|
||||||
- `registration_fee_lamports: u64`
|
|
||||||
- `lamports_per_limit_step: u64`
|
|
||||||
- `start_bonus_limit: u64`
|
|
||||||
|
|
||||||
`create_user_pda`:
|
|
||||||
|
|
||||||
- `login: String`
|
|
||||||
- `root_key: Pubkey`
|
|
||||||
- `created_at_ms: u64`
|
|
||||||
- `additional_limit: u64`
|
|
||||||
- `fields: UserMutableFields`
|
|
||||||
- `signature: Vec<u8>`
|
|
||||||
|
|
||||||
`update_user_pda`:
|
|
||||||
|
|
||||||
- `login: String`
|
|
||||||
- `root_key: Pubkey`
|
|
||||||
- `created_at_ms: u64`
|
|
||||||
- `updated_at_ms: u64`
|
|
||||||
- `version: u32`
|
|
||||||
- `prev_hash: Vec<u8>`
|
|
||||||
- `additional_limit: u64`
|
|
||||||
- `fields: UserMutableFields`
|
|
||||||
- `signature: Vec<u8>`
|
|
||||||
|
|
||||||
`UserMutableFields`:
|
|
||||||
|
|
||||||
- `client_key: Pubkey`
|
|
||||||
- `blockchain_public_key: Pubkey`
|
|
||||||
- `blockchain_name: String`
|
|
||||||
- `used_bytes: u64`
|
|
||||||
- `last_block_number: u32`
|
|
||||||
- `last_block_hash: Vec<u8>` — ровно 32 байта
|
|
||||||
- `last_block_signature: Vec<u8>` — ровно 64 байта
|
|
||||||
- `arweave_tx_id: String`
|
|
||||||
- `is_server: bool`
|
|
||||||
- `server_key: Pubkey`
|
|
||||||
- `server_address: String`
|
|
||||||
- `sync_servers: Vec<String>`
|
|
||||||
- `access_servers: Vec<String>`
|
|
||||||
- `trusted_count: u8`
|
|
||||||
|
|
||||||
## Главные PDA
|
|
||||||
|
|
||||||
1. `user_pda`
|
|
||||||
- PDA записи пользователя.
|
|
||||||
- Seed: `login=<normalized_login>`.
|
|
||||||
- Создается отдельно для каждого логина.
|
|
||||||
- Стартовый размер: `768` байт.
|
|
||||||
- При обновлении может расширяться через `realloc`, но один auto-realloc ограничен `10_000` байт.
|
|
||||||
|
|
||||||
2. `users_economy_config_pda`
|
|
||||||
- PDA с настройками экономики.
|
|
||||||
- Seed: `shine_users_economy_config`.
|
|
||||||
- Хранит регистрационную комиссию, цену шага лимита и стартовый бонус.
|
|
||||||
- Размер PDA: `8 + 96` байт.
|
|
||||||
|
|
||||||
## Текущие параметры экономики
|
|
||||||
|
|
||||||
Параметры initial config из `programs/shine_users/src/settings.rs`:
|
|
||||||
|
|
||||||
| Поле | Значение | Смысл |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `START_REGISTRATION_FEE_LAMPORTS` | `10_000_000` | стартовая комиссия регистрации, 0.01 SOL |
|
|
||||||
| `LIMIT_STEP` | `10_000` | шаг `additional_limit` |
|
|
||||||
| `START_LAMPORTS_PER_LIMIT_STEP` | `100_000` | 0.0001 SOL за один шаг лимита |
|
|
||||||
| `START_BONUS_LIMIT` | `100_000` | стартовый бесплатный лимит при регистрации |
|
|
||||||
|
|
||||||
`additional_limit` в create/update должен быть кратен `LIMIT_STEP`.
|
|
||||||
|
|
||||||
## Связь с другими программами
|
|
||||||
|
|
||||||
`shine_users` зависит от:
|
|
||||||
|
|
||||||
- `shine_login_guard` — для проверки логина при создании пользователя;
|
|
||||||
- `shine_payments` — для вычисления и проверки `inflow_vault_pda`, куда уходят платежи.
|
|
||||||
|
|
||||||
`create_user_pda` делает CPI-вызов `shine_login_guard::classify_login` и принимает только результат `0`. Premium/trademark логины сейчас отклоняются ошибками `PremiumLogin` или `TrademarkLoginRequiresReview`.
|
|
||||||
|
|
||||||
Подпись `user_pda` и подпись состояния последнего блока проверяются через встроенную Solana Ed25519-инструкцию, которая должна идти раньше инструкции `shine_users` в той же транзакции.
|
|
||||||
|
|
||||||
## Деньги
|
|
||||||
|
|
||||||
Деньги из `shine_users` идут только в `inflow_vault_pda` программы `shine_payments`.
|
|
||||||
|
|
||||||
Потоки:
|
|
||||||
|
|
||||||
- `create_user_pda`: регистрационная комиссия + оплата `additional_limit`;
|
|
||||||
- `update_user_pda`: оплата `additional_limit`, если она больше нуля.
|
|
||||||
|
|
||||||
## Ключи и управление
|
|
||||||
|
|
||||||
На старте удобно считать, что у программы есть отдельный управляющий ключ `key_2`.
|
|
||||||
|
|
||||||
Целевая модель:
|
|
||||||
|
|
||||||
- economy-настройки меняет DAO-authority;
|
|
||||||
- upgrade-authority программы после проверки передается DAO;
|
|
||||||
- пользовательские операции `create_user_pda` и `update_user_pda` остаются доступными обычным пользователям при корректных подписях и оплате.
|
|
||||||
@ -1,54 +0,0 @@
|
|||||||
flowchart LR
|
|
||||||
U[Пользователь / signer]
|
|
||||||
B[Покупатель тикета]
|
|
||||||
M[Менеджер]
|
|
||||||
C[Любой caller step_payout]
|
|
||||||
|
|
||||||
LG[1. shine_login_guard<br/>classify_login]
|
|
||||||
USERS[2. shine_users<br/>create_user_pda / update_user_pda]
|
|
||||||
PAY[3. shine_payments<br/>vault / tickets / payouts]
|
|
||||||
DAO[SHiNE DAO<br/>governance / authority / treasury]
|
|
||||||
|
|
||||||
USERPDA[(user_pda<br/>по login)]
|
|
||||||
ECON[(users_economy_config_pda)]
|
|
||||||
CONFIG[(config_pda)]
|
|
||||||
COEF[(coef_limit_pda)]
|
|
||||||
QUEUES[(queues_pda)]
|
|
||||||
VAULT[(inflow_vault_pda)]
|
|
||||||
TICKET[(ticket_pda)]
|
|
||||||
ALLOW[(manager_allowance_pda)]
|
|
||||||
|
|
||||||
U -->|логин| USERS
|
|
||||||
USERS -->|CPI проверка| LG
|
|
||||||
USERS -->|создает/обновляет| USERPDA
|
|
||||||
USERS -->|читает экономику| ECON
|
|
||||||
U -->|регистрация / лимит| VAULT
|
|
||||||
|
|
||||||
DAO -->|update economy| USERS
|
|
||||||
DAO -->|update coef/limit| PAY
|
|
||||||
DAO -->|grant manager limits| PAY
|
|
||||||
DAO -->|создает/отзывает ключи| DAO
|
|
||||||
|
|
||||||
PAY --> CONFIG
|
|
||||||
PAY --> COEF
|
|
||||||
PAY --> QUEUES
|
|
||||||
PAY --> VAULT
|
|
||||||
PAY --> TICKET
|
|
||||||
PAY --> ALLOW
|
|
||||||
|
|
||||||
B -->|buy_ticket*| PAY
|
|
||||||
B -->|оплата покупки тикета| DAO
|
|
||||||
PAY -->|создает тикет| TICKET
|
|
||||||
|
|
||||||
M -->|manager_add_ticket| PAY
|
|
||||||
ALLOW -->|лимиты Q1/Q2| M
|
|
||||||
|
|
||||||
C -->|step_payout| PAY
|
|
||||||
VAULT -->|выплата тикета| U
|
|
||||||
VAULT -->|DAO-часть| DAO
|
|
||||||
VAULT -->|call reward| C
|
|
||||||
|
|
||||||
DAO -. upgrade authority после передачи .-> USERS
|
|
||||||
DAO -. upgrade authority после передачи .-> PAY
|
|
||||||
DAO -. позже возможно .-> LG
|
|
||||||
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 234 KiB |
@ -1,139 +0,0 @@
|
|||||||
<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="900" viewBox="0 0 1400 900" role="img" aria-labelledby="title desc">
|
|
||||||
<title id="title">Архитектура Solana-программ SHiNE</title>
|
|
||||||
<desc id="desc">Схема трех программ, DAO, PDA-счетов и движения денег.</desc>
|
|
||||||
<defs>
|
|
||||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
|
|
||||||
<path d="M0,0 L0,6 L9,3 z" fill="#2f3a45"/>
|
|
||||||
</marker>
|
|
||||||
<marker id="moneyArrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
|
|
||||||
<path d="M0,0 L0,6 L9,3 z" fill="#0a7f62"/>
|
|
||||||
</marker>
|
|
||||||
<style>
|
|
||||||
.bg { fill: #f7f8fa; }
|
|
||||||
.title { font: 700 30px Arial, sans-serif; fill: #1f2933; }
|
|
||||||
.subtitle { font: 400 16px Arial, sans-serif; fill: #52606d; }
|
|
||||||
.box { fill: #ffffff; stroke: #9aa5b1; stroke-width: 2; rx: 8; }
|
|
||||||
.program { fill: #e8f1ff; stroke: #3465a4; }
|
|
||||||
.dao { fill: #fff3d6; stroke: #b7791f; }
|
|
||||||
.pda { fill: #edf7ed; stroke: #2f855a; }
|
|
||||||
.actor { fill: #f3e8ff; stroke: #805ad5; }
|
|
||||||
.txt { font: 700 17px Arial, sans-serif; fill: #1f2933; }
|
|
||||||
.small { font: 400 13px Arial, sans-serif; fill: #3e4c59; }
|
|
||||||
.line { stroke: #2f3a45; stroke-width: 2.2; fill: none; marker-end: url(#arrow); }
|
|
||||||
.money { stroke: #0a7f62; stroke-width: 3; fill: none; marker-end: url(#moneyArrow); }
|
|
||||||
.dashed { stroke-dasharray: 8 7; }
|
|
||||||
.legend { font: 400 14px Arial, sans-serif; fill: #3e4c59; }
|
|
||||||
</style>
|
|
||||||
</defs>
|
|
||||||
|
|
||||||
<rect class="bg" x="0" y="0" width="1400" height="900"/>
|
|
||||||
<text class="title" x="52" y="54">SHiNE Solana: программы, DAO, счета и движение денег</text>
|
|
||||||
<text class="subtitle" x="52" y="82">Текущая модель: три Anchor-программы, DAO/authority как управляющий слой, inflow vault и DAO treasury.</text>
|
|
||||||
|
|
||||||
<rect class="box actor" x="52" y="150" width="210" height="78"/>
|
|
||||||
<text class="txt" x="72" y="181">Пользователь</text>
|
|
||||||
<text class="small" x="72" y="206">signer, root_key, client_key</text>
|
|
||||||
|
|
||||||
<rect class="box actor" x="52" y="310" width="210" height="78"/>
|
|
||||||
<text class="txt" x="72" y="341">Покупатель тикета</text>
|
|
||||||
<text class="small" x="72" y="366">buy_ticket*</text>
|
|
||||||
|
|
||||||
<rect class="box actor" x="52" y="470" width="210" height="78"/>
|
|
||||||
<text class="txt" x="72" y="501">Менеджер</text>
|
|
||||||
<text class="small" x="72" y="526">manager_add_ticket</text>
|
|
||||||
|
|
||||||
<rect class="box actor" x="52" y="630" width="210" height="78"/>
|
|
||||||
<text class="txt" x="72" y="661">Любой caller</text>
|
|
||||||
<text class="small" x="72" y="686">step_payout</text>
|
|
||||||
|
|
||||||
<rect class="box program" x="360" y="126" width="270" height="96"/>
|
|
||||||
<text class="txt" x="382" y="160">1. shine_login_guard</text>
|
|
||||||
<text class="small" x="382" y="186">classify_login</text>
|
|
||||||
<text class="small" x="382" y="205">free / premium / trademark</text>
|
|
||||||
|
|
||||||
<rect class="box program" x="360" y="286" width="270" height="112"/>
|
|
||||||
<text class="txt" x="382" y="320">2. shine_users</text>
|
|
||||||
<text class="small" x="382" y="346">create_user_pda</text>
|
|
||||||
<text class="small" x="382" y="365">update_user_pda</text>
|
|
||||||
<text class="small" x="382" y="384">economy config</text>
|
|
||||||
|
|
||||||
<rect class="box program" x="360" y="518" width="270" height="122"/>
|
|
||||||
<text class="txt" x="382" y="552">3. shine_payments</text>
|
|
||||||
<text class="small" x="382" y="578">vault, tickets, queues</text>
|
|
||||||
<text class="small" x="382" y="597">grant_manager_limits</text>
|
|
||||||
<text class="small" x="382" y="616">step_payout</text>
|
|
||||||
|
|
||||||
<rect class="box dao" x="776" y="126" width="270" height="122"/>
|
|
||||||
<text class="txt" x="798" y="160">SHiNE DAO</text>
|
|
||||||
<text class="small" x="798" y="186">governance / authority</text>
|
|
||||||
<text class="small" x="798" y="205">treasury dao_wallet</text>
|
|
||||||
<text class="small" x="798" y="224">ключи через голосование</text>
|
|
||||||
|
|
||||||
<rect class="box pda" x="776" y="306" width="270" height="84"/>
|
|
||||||
<text class="txt" x="798" y="340">shine_users PDA</text>
|
|
||||||
<text class="small" x="798" y="365">user_pda, economy_config</text>
|
|
||||||
|
|
||||||
<rect class="box pda" x="776" y="500" width="270" height="150"/>
|
|
||||||
<text class="txt" x="798" y="534">shine_payments PDA</text>
|
|
||||||
<text class="small" x="798" y="560">config_pda, coef_limit_pda</text>
|
|
||||||
<text class="small" x="798" y="579">queues_pda</text>
|
|
||||||
<text class="small" x="798" y="598">inflow_vault_pda</text>
|
|
||||||
<text class="small" x="798" y="617">ticket_pda, manager_allowance</text>
|
|
||||||
|
|
||||||
<rect class="box pda" x="1134" y="500" width="214" height="88"/>
|
|
||||||
<text class="txt" x="1156" y="534">inflow_vault</text>
|
|
||||||
<text class="small" x="1156" y="560">деньги регистрации</text>
|
|
||||||
|
|
||||||
<rect class="box dao" x="1134" y="170" width="214" height="88"/>
|
|
||||||
<text class="txt" x="1156" y="204">DAO treasury</text>
|
|
||||||
<text class="small" x="1156" y="230">dao_wallet</text>
|
|
||||||
|
|
||||||
<path class="line" d="M262 189 C300 189, 318 334, 360 334"/>
|
|
||||||
<text class="small" x="270" y="286">регистрация / update</text>
|
|
||||||
|
|
||||||
<path class="line" d="M360 314 C322 250, 320 176, 360 174"/>
|
|
||||||
<text class="small" x="330" y="250">CPI login</text>
|
|
||||||
|
|
||||||
<path class="line" d="M630 342 L776 342"/>
|
|
||||||
<text class="small" x="646" y="329">создает/обновляет</text>
|
|
||||||
|
|
||||||
<path class="money" d="M262 205 C438 432, 1010 390, 1134 530"/>
|
|
||||||
<text class="small" x="430" y="430">регистрация и лимит -> inflow_vault</text>
|
|
||||||
|
|
||||||
<path class="money" d="M262 349 C540 260, 870 244, 1134 214"/>
|
|
||||||
<text class="small" x="538" y="270">покупка тикета -> DAO treasury</text>
|
|
||||||
|
|
||||||
<path class="line" d="M262 509 L360 579"/>
|
|
||||||
<text class="small" x="276" y="540">создать тикет</text>
|
|
||||||
|
|
||||||
<path class="line" d="M630 579 L776 575"/>
|
|
||||||
<text class="small" x="648" y="562">PDA состояния</text>
|
|
||||||
|
|
||||||
<path class="line" d="M1046 575 L1134 548"/>
|
|
||||||
|
|
||||||
<path class="money" d="M1134 560 C970 700, 580 728, 262 669"/>
|
|
||||||
<text class="small" x="650" y="720">call reward caller</text>
|
|
||||||
|
|
||||||
<path class="money" d="M1134 536 C860 754, 426 238, 262 194"/>
|
|
||||||
<text class="small" x="632" y="760">выплата получателю тикета</text>
|
|
||||||
|
|
||||||
<path class="money" d="M1241 500 L1241 258"/>
|
|
||||||
<text class="small" x="1254" y="380">DAO-часть выплат</text>
|
|
||||||
|
|
||||||
<path class="line" d="M776 188 L630 342"/>
|
|
||||||
<text class="small" x="642" y="250">update economy</text>
|
|
||||||
|
|
||||||
<path class="line" d="M776 216 C690 290, 666 516, 630 558"/>
|
|
||||||
<text class="small" x="654" y="438">settings / managers</text>
|
|
||||||
|
|
||||||
<path class="line dashed" d="M910 248 C850 702, 620 720, 520 640"/>
|
|
||||||
<text class="small" x="690" y="690">upgrade-authority: users/payments; login_guard позже</text>
|
|
||||||
|
|
||||||
<rect class="box" x="52" y="808" width="1296" height="54"/>
|
|
||||||
<line x1="74" y1="835" x2="132" y2="835" class="line"/>
|
|
||||||
<text class="legend" x="146" y="840">логические вызовы и управление</text>
|
|
||||||
<line x1="374" y1="835" x2="432" y2="835" class="money"/>
|
|
||||||
<text class="legend" x="446" y="840">движение SOL/lamports</text>
|
|
||||||
<line x1="682" y1="835" x2="740" y2="835" class="line dashed"/>
|
|
||||||
<text class="legend" x="754" y="840">будущая передача upgrade-authority DAO</text>
|
|
||||||
</svg>
|
|
||||||
|
Before Width: | Height: | Size: 7.1 KiB |
@ -1,177 +0,0 @@
|
|||||||
# Аудит безопасности Solana-программ SHiNE — выпуск 2 (11.06.2026)
|
|
||||||
|
|
||||||
Повторный независимый аудит после исправления всех 4 находок первого отчёта
|
|
||||||
(`Solana-audit-by-Claude-File5-9июня2026.md`). Код перечитан целиком:
|
|
||||||
|
|
||||||
- `shine_login_guard` (183 строки) — stateless-классификатор логинов;
|
|
||||||
- `shine_users` (1069 строк) — реестр пользователей, PDA-записи, подписи, экономика лимитов;
|
|
||||||
- `shine_payments` (1381 строка) — очереди тикетов, выплаты из вольта, оракул Pyth.
|
|
||||||
|
|
||||||
Перебраны классы атак: подмена аккаунтов/PDA, авторизация и подписи, арифметика и
|
|
||||||
переполнения, валидация оракула, экономика, реентранси, griefing/DoS, **алиасинг
|
|
||||||
аккаунтов (передача одного аккаунта в несколько слотов инструкции)**.
|
|
||||||
|
|
||||||
## Статус прошлых находок (все закрыты)
|
|
||||||
|
|
||||||
- 🔴 Critical #1 (economy-config PDA в `shine_users`) — закрыто: `validate_users_economy_config_pda` проверяет и адрес, и `owner == program_id`, и вызывается перед чтением и в create, и в update.
|
|
||||||
- 🔴 Critical #2 (singleton-PDA в `shine_payments`) — закрыто: `validate_singleton_state_pda` проверяет точный адрес + `owner == id()` во всех инструкциях (`update_coef_limit`, `grant_manager_limits`, `buy_ticket*`, `manager_add_ticket`, `step_payout`, `change_ticket_recipient`).
|
|
||||||
- 🟠 Medium (валидация Pyth) — закрыто: пин адреса аккаунта `PYTH_SOL_USD_ACCOUNT`, проверка `owner == pyth_receiver`, разбор официальным `PriceUpdateV2`, `get_price_no_older_than` с проверкой `feed_id`, проверка возраста и доверительного интервала (`ORACLE_MAX_CONFIDENCE_PPM`).
|
|
||||||
- 🟡 Low (griefing на предсказуемых адресах) — закрыто: `create_pda_account` в обеих программах переведён на «создание поверх предзаполненного» (allocate + assign + добор ренты).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔴 HIGH (НОВОЕ) — `shine_payments`: тикет с `recipient_wallet == inflow_vault` навсегда замораживает все выплаты — ✅ ИСПРАВЛЕНО (11.06.2026)
|
|
||||||
|
|
||||||
Закрыто: равенство `recipient == inflow_vault` запрещено во всех точках задания
|
|
||||||
получателя — `buy_ticket_by_purchase_usd` (через `config.inflow_vault`),
|
|
||||||
`process_manager_add_ticket` и `process_change_ticket_recipient` (через
|
|
||||||
`find_single_pda(INFLOW_VAULT_SEED)`). Дополнительно в `transfer_from_vault` добавлена
|
|
||||||
защита по умолчанию `require!(vault.key != recipient.key)`. Документация —
|
|
||||||
`doc/programs/shine_payments.md` §10.1. Историческое описание находки ниже.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Где
|
|
||||||
`transfer_from_vault` (строки 1258–1268) переводит лампорты из вольта прямой
|
|
||||||
манипуляцией балансами (вольт — PDA без приватного ключа, обычный system-перевод
|
|
||||||
невозможен):
|
|
||||||
|
|
||||||
```rust
|
|
||||||
fn transfer_from_vault(vault: &AccountInfo, recipient: &AccountInfo, amount: u64) -> ProgramResult {
|
|
||||||
if amount == 0 { return Ok(()); }
|
|
||||||
let mut vault_lamports = vault.try_borrow_mut_lamports()?; // займ #1
|
|
||||||
let mut recipient_lamports = recipient.try_borrow_mut_lamports()?; // займ #2
|
|
||||||
...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
В `step_payout` (строка 849) получатель — это `ticket.recipient_wallet`:
|
|
||||||
|
|
||||||
```rust
|
|
||||||
transfer_from_vault(inflow_vault_pda, ticket_recipient_wallet, ticket_lamports)?;
|
|
||||||
```
|
|
||||||
|
|
||||||
А `recipient_wallet` нигде не валидируется при создании тикета:
|
|
||||||
`buy_ticket*` (строки 696/711/725 → 1031), `manager_add_ticket` (строка 765),
|
|
||||||
`change_ticket_recipient` (строка 900) — берут его «как есть» из аргументов.
|
|
||||||
|
|
||||||
### Суть атаки (алиасинг аккаунта)
|
|
||||||
В Solana, если один и тот же аккаунт передан в инструкцию в нескольких слотах,
|
|
||||||
рантайм отдаёт для всех слотов **один и тот же** `RefCell` (механизм дублей).
|
|
||||||
Поэтому если `ticket.recipient_wallet` равен адресу `inflow_vault` PDA, то в
|
|
||||||
`step_payout` аккаунт вольта попадает и в слот `inflow_vault_pda`, и в слот
|
|
||||||
`ticket_recipient_wallet`. Тогда внутри `transfer_from_vault`:
|
|
||||||
|
|
||||||
- `vault.try_borrow_mut_lamports()` — берёт mutable-займ (успех);
|
|
||||||
- `recipient.try_borrow_mut_lamports()` — это **тот же** аккаунт → второй
|
|
||||||
mutable-займ → `Err(AccountBorrowFailed)` → `?` возвращает ошибку → инструкция
|
|
||||||
падает.
|
|
||||||
|
|
||||||
### Почему это «заморозка всего», а не один тикет
|
|
||||||
Выплаты идут строго по возрастанию индекса. `step_payout` всегда обслуживает
|
|
||||||
сначала очередь Q1 (если в ней есть pending), затем Q2, затем Q3, и в каждой —
|
|
||||||
ровно «следующий неоплаченный» тикет (`paid + 1`). Тикет с `recipient == vault`:
|
|
||||||
|
|
||||||
- не может быть оплачен (`step_payout` всегда падает на нём);
|
|
||||||
- не может быть пропущен (нет механизма «skip»);
|
|
||||||
- блокирует все тикеты после него в своей очереди;
|
|
||||||
- если он в Q1 — блокирует обслуживание Q2 и Q3 (до них очередь не доходит);
|
|
||||||
- лампорты вольта (накопленные регистрационные комиссии) перестают выплачиваться
|
|
||||||
и не уходят в DAO (слив в DAO происходит только когда `pending == 0` по всем
|
|
||||||
очередям, а это состояние недостижимо).
|
|
||||||
|
|
||||||
### Эксплуатация (тривиальная, перестановочная)
|
|
||||||
Q1 — публичная очередь (`buy_ticket` доступен любому). Атакующий покупает **один**
|
|
||||||
дешёвый тикет Q1, указав `recipient_wallet = <адрес inflow_vault PDA>`. Адрес вольта
|
|
||||||
детерминирован и публичен (`find_single_pda(INFLOW_VAULT_SEED)`). С этого момента вся
|
|
||||||
подсистема выплат и средства вольта заморожены за стоимость одного тикета + ренты.
|
|
||||||
|
|
||||||
Дополнительно: даже при защите на этапе покупки остаётся вектор через
|
|
||||||
`change_ticket_recipient` (строка 900) — владелец любого своего неоплаченного тикета
|
|
||||||
может выставить `new_recipient_wallet = vault` позже.
|
|
||||||
|
|
||||||
### Класс и серьёзность
|
|
||||||
Класс: «account aliasing / duplicate-account mutable borrow» + отсутствие
|
|
||||||
валидации адреса получателя. Прямой кражи средств нет, но это перманентный
|
|
||||||
отказ в обслуживании (availability) с блокировкой средств вольта, триггер —
|
|
||||||
копеечный и доступен анонимно. Оценка: **HIGH**.
|
|
||||||
|
|
||||||
### Рекомендуемый фикс
|
|
||||||
Запретить `recipient`, равный адресу вольта, во всех точках, где он задаётся, чтобы
|
|
||||||
тикет с таким получателем вообще не мог появиться:
|
|
||||||
|
|
||||||
1. в `buy_ticket_by_purchase_usd` — `require!(recipient_wallet != config.inflow_vault, …)`
|
|
||||||
(config уже прочитан);
|
|
||||||
2. в `process_manager_add_ticket` — сверять с `find_single_pda(INFLOW_VAULT_SEED).0`;
|
|
||||||
3. в `process_change_ticket_recipient` — то же для `new_recipient_wallet`.
|
|
||||||
|
|
||||||
Дополнительно (defense-in-depth) — в `transfer_from_vault` явно
|
|
||||||
`require!(vault.key != recipient.key, …)` с понятной ошибкой, чтобы любой будущий
|
|
||||||
вызов был защищён от алиасинга. Этого `require` недостаточно как единственной меры
|
|
||||||
(тикет всё равно застрял бы), поэтому основная защита — на входе.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟡 LOW / INFO — наблюдения без прямой эксплуатации
|
|
||||||
|
|
||||||
### L1. `change_ticket_recipient` и `buy_ticket` не проверяют получателя на «опасные» адреса
|
|
||||||
Связано с HIGH выше; после фикса основной проблемы стоит заодно зафиксировать
|
|
||||||
правило «получатель не должен совпадать с системными PDA программы».
|
|
||||||
|
|
||||||
### L2. Гонка за логином (first-come) в `shine_users`
|
|
||||||
Адрес `user_pda` выводится из логина. После закрытия griefing-подсева остаётся
|
|
||||||
обычное состязание: увидев в мемпуле регистрацию `alice`, атакующий может
|
|
||||||
зарегистрировать `alice` со своим `root_key` первым. On-chain это решается только
|
|
||||||
commit-reveal; для текущей модели — приемлемый риск, отметить как известный.
|
|
||||||
|
|
||||||
### L3. `step_payout` без slippage-параметра
|
|
||||||
Выплата считается по текущей цене оракула без верхней границы лампортов. Цена
|
|
||||||
ограничена возрастом (120с) и доверительным интервалом (10%), аккаунт оракула
|
|
||||||
запинен — манипуляция маловероятна, но при резком движении цены SOL объём выплаты
|
|
||||||
в лампортах плавает. Риск низкий; при желании добавить верхнюю границу на шаг.
|
|
||||||
|
|
||||||
### L4. Экономическая устойчивость вольта (дизайн, не баг)
|
|
||||||
Деньги за покупку тикетов (`buy_ticket`) уходят на `dao_wallet`, а выплаты в
|
|
||||||
`step_payout` идут из `inflow_vault`, который наполняется **регистрационными
|
|
||||||
комиссиями** `shine_users`. Если поток регистраций меньше обязательств по выплатам,
|
|
||||||
вольт истощается и выплаты останавливаются (без потери средств, но с остановкой
|
|
||||||
сервиса). Это свойство экономической модели — стоит явно держать в уме и
|
|
||||||
мониторить баланс вольта/обязательств.
|
|
||||||
|
|
||||||
### L5. Заполнение Q1 до лимита как мягкий DoS
|
|
||||||
`buy_ticket` блокируется при `q1_sum_total >= limit_usd_cents`. Атакующий может
|
|
||||||
наполнить Q1 своими тикетами и приостановить покупки. Дорого (тратит SOL в DAO и
|
|
||||||
ренту) и его же тикеты потом оплачиваются из вольта, поэтому это скорее
|
|
||||||
экономический, а не дешёвый griefing. Риск низкий.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ Проверено и подтверждено как корректное
|
|
||||||
|
|
||||||
- **Подмена singleton-PDA** невозможна: везде сверяется точный адрес и владелец.
|
|
||||||
- **Авторизация**: `update_coef_limit`/`grant_manager_limits` требуют `signer == config.dao_wallet`; `manager_add_ticket` — `signer == allowance.manager_wallet`; `change_ticket_recipient` — `signer == ticket.recipient_wallet`; обновление economy-config — `signer == DAO_AUTHORITY`.
|
|
||||||
- **Ed25519 в `shine_users`**: строгие относительные индексы (−1/−2), `num_signatures == 1`, все три `ix_index == u16::MAX` (данные внутри самой ed25519-инструкции), сверка pubkey/signature/message по хэшу. Подмена и указание на чужую инструкцию исключены.
|
|
||||||
- **Цепочка версий записи** (`version == record_number+1`, `prev_hash == hash(old)`) — корректная защита от replay; сигнатура записи завязана на `root_key`, а не на плательщика.
|
|
||||||
- **Монотонность** `used_bytes`/`last_block_number` и `used_bytes <= paid_limit_bytes`.
|
|
||||||
- **Арифметика**: повсеместные `checked_*`, `overflow-checks = true`, расчёты оракула в `u128` с `u64::try_from` на сужении.
|
|
||||||
- **Оракул Pyth**: пин аккаунта + owner + feed_id + возраст + confidence через официальный SDK.
|
|
||||||
- **Рент-экземпт вольта** сохраняется: `available_vault_lamports` вычитает `minimum_balance`, а суммарная проверка `available >= needed` гарантирует, что после выплат вольт не опустится ниже ренты.
|
|
||||||
- **Двойная оплата тикета** исключена: `is_paid` + инкремент `*_tickets_paid`, следующий шаг адресует следующий индекс.
|
|
||||||
- **Реентранси отсутствует**: CPI только в System Program (transfer/allocate/assign) и в stateless `shine_login_guard` (с проверкой возвращённого `program_id`); обратных вызовов в наши программы нет.
|
|
||||||
- **create_pda_account (новый)**: устойчив к подсеву лампортов; атакующий не может ни выделить данные, ни сменить владельца PDA (нет ключа/seeds), поэтому ветка allocate+assign безопасна.
|
|
||||||
- **shine_login_guard**: stateless, без аккаунтов и средств; DFS-классификация ограничена (`MAX_WORDS_PER_LOGIN = 3`, длина ≤ 20) — без compute-DoS.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Приоритет действий
|
|
||||||
|
|
||||||
1. **HIGH** — запретить `recipient == inflow_vault` в `buy_ticket*`, `manager_add_ticket`,
|
|
||||||
`change_ticket_recipient`; добавить `require!(vault.key != recipient.key)` в
|
|
||||||
`transfer_from_vault` как защиту по умолчанию. Закрыть до mainnet.
|
|
||||||
2. **LOW** — зафиксировать правило «получатель ≠ системные PDA» (L1), оценить
|
|
||||||
добавление верхней границы выплаты на шаг (L3).
|
|
||||||
3. **INFO** — формально задокументировать экономику вольта (L4) и known-issue
|
|
||||||
гонки за логином (L5/L2).
|
|
||||||
|
|
||||||
Изменений в код в рамках этого аудита не вносил — это анализ. Готов подготовить патч
|
|
||||||
по пункту 1, если подтвердите.
|
|
||||||
@ -1,134 +0,0 @@
|
|||||||
# Аудит безопасности Solana-программ SHiNE — выпуск 3 (12.06.2026)
|
|
||||||
|
|
||||||
Тематический аудит с фокусом на **полноту проверок входных аккаунтов**
|
|
||||||
(signer / owner / каноничный PDA-адрес / system-program / sysvar инструкций /
|
|
||||||
аккаунт оракула) — отвечает на вопрос «точно ли хватает всех проверок входных
|
|
||||||
аккаунтов». Код перечитан целиком после исправлений аудита №2
|
|
||||||
(`Solana-audit-2-by-Claude-11июня2026.md`):
|
|
||||||
|
|
||||||
- `shine_login_guard` (183 строки) — stateless-классификатор логинов, аккаунтами не пользуется;
|
|
||||||
- `shine_users` (1068 строк) — реестр пользователей, PDA-записи, ed25519-подписи, экономика лимитов;
|
|
||||||
- `shine_payments` (1398 строк) — очереди тикетов, выплаты из вольта, оракул Pyth.
|
|
||||||
|
|
||||||
Это ручная (не-Anchor `#[derive(Accounts)]`) реализация на `solana_program`, поэтому
|
|
||||||
каждая проверка аккаунта выполняется явно в коде handler-а. Перебраны: подмена
|
|
||||||
аккаунтов/PDA, подмена владельца, bump-seed атаки, отсутствие signer/authority,
|
|
||||||
подмена system-program и sysvar, подмена аккаунта оракула, неинициализированные/
|
|
||||||
повторно инициализируемые PDA, «лишние» аккаунты.
|
|
||||||
|
|
||||||
## Итоговый вердикт
|
|
||||||
|
|
||||||
**Проверок входных аккаунтов достаточно во всех трёх программах.** По каждому
|
|
||||||
handler присутствуют все требуемые классы проверок; грубых дыр (подмена PDA на
|
|
||||||
чужой аккаунт, отсутствие owner/signer-проверки, использование пользовательского
|
|
||||||
bump, подмена аккаунта оракула) не найдено. Все Critical/HIGH из аудитов №1 и №2
|
|
||||||
закрыты и в этом проходе подтверждены в коде. Новых эксплуатируемых пробелов в
|
|
||||||
валидации аккаунтов нет; есть несколько LOW/INFO-замечаний «by design».
|
|
||||||
|
|
||||||
## Статус прошлых находок (подтверждено в коде на 12.06.2026)
|
|
||||||
|
|
||||||
- 🔴 Critical #1 (economy-config PDA, `shine_users`) — закрыто: `validate_users_economy_config_pda` (адрес + `owner == program_id`) вызывается и в create, и в update перед чтением.
|
|
||||||
- 🔴 Critical #2 (singleton-PDA, `shine_payments`) — закрыто: `validate_singleton_state_pda` (адрес + `owner == id()`) во всех инструкциях.
|
|
||||||
- 🟠 Medium (валидация Pyth) — закрыто: пин адреса `PYTH_SOL_USD_ACCOUNT`, `owner == pyth_receiver`, `PriceUpdateV2`, `feed_id`, возраст, доверительный интервал.
|
|
||||||
- 🟡 Low (griefing на предсказуемых адресах) — закрыто: `create_pda_account` создаёт «поверх предзаполненного» в обеих программах.
|
|
||||||
- 🔴 HIGH аудита №2 (`recipient_wallet == inflow_vault` замораживает выплаты) — закрыто: запрет `recipient == inflow_vault` в `buy_ticket_by_purchase_usd` (стр. 1026), `process_manager_add_ticket` (стр. 747), `process_change_ticket_recipient` (стр. 878) + защита по умолчанию `require!(vault.key != recipient.key)` в `transfer_from_vault` (стр. 1278).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Матрица проверок входных аккаунтов
|
|
||||||
|
|
||||||
### shine_users
|
|
||||||
|
|
||||||
| Инструкция | signer | owner PDA | адрес/seed PDA | system | sysvar / подпись | прочее |
|
|
||||||
|---|---|---|---|---|---|---|
|
|
||||||
| `init_users_economy_config` | ✓ | `owner == system` + `data_is_empty` (анти-reinit) | деривация + сверка | ✓ | — | значения из `settings`, не из ввода |
|
|
||||||
| `update_users_economy_config` | ✓ + `signer == DAO_AUTHORITY` | `owner == program_id` | деривация + сверка | — | — | `lamports_per_limit_step > 0` |
|
|
||||||
| `create_user_pda` | ✓ + `signer == client_key` | user_pda `owner == system` + empty; econ_config `owner == program_id` | user_pda, econ_config, inflow_vault, login_guard — все сверены | ✓ | ed25519 (record sig idx −2, last_block idx −1) | `inflow_vault` сверен с PDA `shine_payments`; login_guard сверен дважды |
|
|
||||||
| `update_user_pda` | ✓ + `signer == client_key` | user_pda `owner == program_id`; econ_config `owner == program_id` | деривация + сверка | ✓ | ed25519 + `version == old+1` + `prev_hash == hash(old)` | immutable-поля сверены с прежней записью |
|
|
||||||
|
|
||||||
### shine_payments
|
|
||||||
|
|
||||||
| Инструкция | signer | owner / валидация PDA | адрес PDA | system | прочее |
|
|
||||||
|---|---|---|---|---|---|
|
|
||||||
| `init` | ✓ payer | все 4 PDA `is_uninitialized` | деривация + сверка | ✓ | `dao_wallet` из `settings`, нет лишних аккаунтов |
|
|
||||||
| `update_coef_limit` | ✓ + `signer == config.dao_wallet` | config/coef `owner == id()` | деривация + сверка | — | границы coef/limit/reward; нет лишних аккаунтов |
|
|
||||||
| `grant_manager_limits` | ✓ + `signer == config.dao_wallet` | config `owner == id()`; allowance create/read | allowance из `manager_wallet` | ✓ | `state.manager_wallet == args.manager_wallet` |
|
|
||||||
| `buy_ticket` / `_usd` / `_sol` | ✓ | config/coef/queues `owner == id()` | ticket деривация + сверка + `is_uninitialized` | ✓ | oracle (key+owner+возраст+confidence), `dao_wallet == config.dao_wallet`, `recipient != inflow_vault`, slippage |
|
|
||||||
| `manager_add_ticket` | ✓ | allowance/queues `owner == id()` | allowance из `signer`; ticket деривация + сверка + uninit | ✓ | `allowance.manager_wallet == signer`, `queue_id ∈ {1,2,3}`, `recipient != inflow_vault` |
|
|
||||||
| `step_payout` | ✓ | все singleton-PDA `owner == id()` | ticket деривация + сверка | — | `dao_wallet == config.dao_wallet`, `inflow == config.inflow_vault`, ticket `queue/index/!is_paid/recipient`, oracle |
|
|
||||||
| `change_ticket_recipient` | ✓ + `signer == ticket.recipient_wallet` | queues + ticket `owner == id()` (через `read_state`) | ticket деривация из своих `queue_id/index` + сверка | — | `!is_paid`, запрет менять «следующий к выплате», `recipient != inflow_vault` |
|
|
||||||
|
|
||||||
### shine_login_guard
|
|
||||||
|
|
||||||
Аккаунты не используются (`_accounts`); программа stateless, средствами не владеет.
|
|
||||||
Защита со стороны вызова реализована в `shine_users`: сверяется и адрес вызываемой
|
|
||||||
программы (`login_guard_program.key == SHINE_LOGIN_GUARD_PROGRAM_ID`), и `program_id`
|
|
||||||
в `get_return_data`. Подмена/подделка ответа исключены. Отдельных проверок входных
|
|
||||||
аккаунтов внутри программы не требуется.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🟡 LOW / INFO — наблюдения без прямой эксплуатации
|
|
||||||
|
|
||||||
### L1. Permissionless `init` в обеих программах
|
|
||||||
`shine_payments::init` и `shine_users::init_users_economy_config` может вызвать кто
|
|
||||||
угодно первым. Практического эксплойта нет: все значения (включая `dao_wallet` и
|
|
||||||
`DAO_AUTHORITY`) берутся из констант `settings`, а не из ввода, повторная
|
|
||||||
инициализация заблокирована проверками `is_uninitialized` / `data_is_empty`. Риск
|
|
||||||
низкий; при желании привязать init к ожидаемому деплой-кошельку. Совпадает с моделью
|
|
||||||
«первый init = деплой».
|
|
||||||
|
|
||||||
### L2. В `shine_users` нет явной проверки «лишних аккаунтов» — ✅ ИСПРАВЛЕНО (12.06.2026)
|
|
||||||
`shine_payments` в каждом handler делает `require!(account_iter.next().is_none())`.
|
|
||||||
В `shine_users` такой проверки не было — лишние аккаунты в конце списка просто
|
|
||||||
игнорировались (читается строго нужное количество через `next_account_info`). Это
|
|
||||||
безвредно (на безопасность не влияло), но для симметрии и явности добавлено.
|
|
||||||
Класс: гигиена, не уязвимость.
|
|
||||||
|
|
||||||
Закрыто: во все 4 инструкции `shine_users` (`init_users_economy_config`,
|
|
||||||
`update_users_economy_config`, `create_user_pda`, `update_user_pda`) после чтения
|
|
||||||
фиксированного набора аккаунтов добавлено `require!(it.next().is_none(),
|
|
||||||
ShineUsersError::InvalidInstruction)`. Документация — `doc/programs/shine_users.md` §3.4.
|
|
||||||
|
|
||||||
### L3. Гонка за логином (first-come) в `shine_users` — known issue
|
|
||||||
Адрес `user_pda` детерминирован из логина; после закрытия griefing-подсева остаётся
|
|
||||||
обычное состязание за регистрацию (front-run в мемпуле). On-chain решается только
|
|
||||||
commit-reveal; для текущей модели — приемлемый риск, ранее зафиксирован в аудите №2
|
|
||||||
(L2). К проверкам аккаунтов не относится.
|
|
||||||
|
|
||||||
### L4. Экономическая устойчивость вольта (дизайн, не баг)
|
|
||||||
Деньги за покупку тикетов уходят на `dao_wallet`, а выплаты `step_payout` идут из
|
|
||||||
`inflow_vault`, наполняемого регистрационными комиссиями `shine_users` (коэффициент
|
|
||||||
по умолчанию `START_COEF_PPM = 5x`). При недостаточном притоке регистраций вольт
|
|
||||||
истощается и выплаты останавливаются (без потери средств). Это свойство
|
|
||||||
экономической модели «очередь/билеты», а не дефект валидации аккаунтов — отмечено
|
|
||||||
для полноты (ранее L4 в аудите №2). Мониторить баланс вольта vs обязательств.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ Проверено и подтверждено как корректное (по входным аккаунтам)
|
|
||||||
|
|
||||||
- **Подмена PDA** невозможна нигде: всюду пара «деривация `find_program_address` + сверка полного адреса». Пользовательский bump не принимается, `create_program_address` с внешним bump не используется — bump-seed атаки исключены.
|
|
||||||
- **Проверка владельца** при каждом чтении PDA: `read_state` и `validate_singleton_state_pda` (`shine_payments`) требуют `owner == id()`; `validate_users_economy_config_pda` и проверка `user_pda.owner == program_id` (`shine_users`) — перед десериализацией данных.
|
|
||||||
- **Создаваемые PDA**: проверка `is_uninitialized` / `owner == system && data_is_empty` исключает повторную инициализацию и перезапись чужого аккаунта.
|
|
||||||
- **signer / authority**: все handler начинают с обязательного `is_signer`; привилегированные операции дополнительно сверяют ключ с авторитетом (`config.dao_wallet`, `DAO_AUTHORITY`, `allowance.manager_wallet`, `ticket.recipient_wallet`, `client_key`).
|
|
||||||
- **system-program** сверяется с `system_program::ID` там, где идёт создание аккаунта/перевод; **sysvar инструкций** сверяется с `sysvar::instructions::id()` перед ed25519-интроспекцией.
|
|
||||||
- **Аккаунт оракула**: пин адреса `PYTH_SOL_USD_ACCOUNT` + `owner == pyth_receiver` + `feed_id` + возраст (120 с) + доверительный интервал (10%).
|
|
||||||
- **Ed25519 в `shine_users`**: относительные индексы −1/−2, `num_signatures == 1`, все три `ix_index == u16::MAX` (offset-данные внутри самой ed25519-инструкции), сверка `program_id == ed25519_program` и pubkey/signature/message по хэшу — указать на чужую инструкцию нельзя.
|
|
||||||
- **Алиасинг аккаунтов**: `recipient != inflow_vault` запрещён на входе во всех точках задания получателя + `vault.key != recipient.key` в `transfer_from_vault`.
|
|
||||||
- **`inflow_vault` в `shine_users`** сверяется с PDA, выведенным из `SHINE_PAYMENTS_PROGRAM_ID` и `SHINE_PAYMENTS_INFLOW_VAULT_SEED` — комиссия не может уйти на чужой адрес.
|
|
||||||
- **Реентранси** отсутствует: CPI только в System Program и в stateless `shine_login_guard` (с проверкой возвращённого `program_id`); обратных вызовов в наши программы нет.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Приоритет действий
|
|
||||||
|
|
||||||
1. **LOW** — ✅ выполнено 12.06.2026: добавлено `require!(it.next().is_none(), …)` во
|
|
||||||
все инструкции `shine_users` для симметрии с `shine_payments` (L2).
|
|
||||||
2. **INFO** — зафиксировать в эксплуатационной документации known-issue гонки за
|
|
||||||
логином (L3) и экономику вольта (L4); рассмотреть привязку `init` к ожидаемому
|
|
||||||
деплой-кошельку (L1).
|
|
||||||
|
|
||||||
Критичных и высоких находок по полноте проверок входных аккаунтов в этом проходе
|
|
||||||
нет. Единственная LOW-правка (L2) применена в рамках этого же изменения; код
|
|
||||||
`shine_users` собирается успешно (`cargo build -p shine_users`).
|
|
||||||
@ -1,114 +0,0 @@
|
|||||||
Аудит безопасности Solana-программ SHiNE
|
|
||||||
|
|
||||||
Проверены три программы в shine-solana/shine/programs/:
|
|
||||||
- shine_login_guard (183 строки) — stateless-классификатор логинов
|
|
||||||
- shine_users (1035 строк) — реестр пользователей, PDA-записи, подписи, экономика лимитов
|
|
||||||
- shine_payments (1330 строк) — очереди тикетов, выплаты, оракул Pyth
|
|
||||||
|
|
||||||
Общая инженерная культура высокая: везде checked_*-арифметика, overflow-checks = true, ручная верификация ed25519 через sysvar инструкций, аккуратный bounds-checked парсинг. Но есть две критические дыры одного класса — отсутствие проверки адреса PDA, которые позволяют обойти всю экономику и украсть средства из вольта.
|
|
||||||
|
|
||||||
---
|
|
||||||
🔴 CRITICAL #1 — shine_users: economy-config PDA не валидируется → бесплатная регистрация и бесконечный лимит
|
|
||||||
|
|
||||||
В process_create_user_pda (строка 448) и process_update_user_pda (строка 525):
|
|
||||||
|
|
||||||
let economy = read_users_economy_config(users_economy_config_pda)?;
|
|
||||||
|
|
||||||
А read_users_economy_config (строки 633–643) не проверяет ни адрес, ни владельца аккаунта — просто читает байты:
|
|
||||||
|
|
||||||
fn read_users_economy_config(pda: &AccountInfo) -> Result<...> {
|
|
||||||
let raw = read_pda_all(pda)?; // try_borrow_data, без проверок
|
|
||||||
require!(raw.len() >= 25, ...);
|
|
||||||
Ok(UsersEconomyConfigState { version: raw[0], registration_fee_lamports: ..., ... })
|
|
||||||
}
|
|
||||||
|
|
||||||
Сравните: в init/update_economy_config адрес проверяется через find_users_economy_config_pda (строки 382, 414), а в create/update — нет.
|
|
||||||
|
|
||||||
Эксплуатация. Атакующий создаёт любой свой аккаунт с 25 байтами произвольного содержимого и передаёт его как users_economy_config_pda:
|
|
||||||
- registration_fee_lamports = 0 → регистрация без оплаты;
|
|
||||||
- start_bonus_limit = u64::MAX → запись пользователя сразу получает гигантский paid_limit_bytes (бесплатная безлимитная квота хранилища/блокчейна);
|
|
||||||
- lamports_per_limit_step = 0 → бесплатное пополнение лимита на любую величину.
|
|
||||||
|
|
||||||
Комиссия (когда она ненулевая) уходит в правильный вольт — validate_inflow_vault это проверяет — но атакующему достаточно обнулить комиссию и накрутить лимит. Это полный обход экономической модели программы.
|
|
||||||
|
|
||||||
Фикс: в обеих функциях перед чтением добавить
|
|
||||||
require_keys_eq!(find_users_economy_config_pda(program_id).0, *users_economy_config_pda.key, ShineUsersError::InvalidPdaAddress);
|
|
||||||
require!(users_economy_config_pda.owner == program_id, ShineUsersError::InvalidPdaAddress);
|
|
||||||
|
|
||||||
---
|
|
||||||
🔴 CRITICAL #2 — shine_payments: singleton-PDA не привязаны к адресу → кража из вольта в step_payout
|
|
||||||
|
|
||||||
ensure_expected_pdas вызывается только в process_init (строка 519). Во всех остальных инструкциях config_pda, coef_limit_pda, queues_pda читаются через read_state, который проверяет только владельца (*pda.owner == id()), но не адрес:
|
|
||||||
|
|
||||||
fn read_state<T>(pda) -> ... {
|
|
||||||
require!(!is_uninitialized_account(pda), ...);
|
|
||||||
require_keys_eq!(*pda.owner, id(), ...); // только owner, адрес НЕ проверяется
|
|
||||||
...
|
|
||||||
}
|
|
||||||
|
|
||||||
Программа владеет аккаунтами нескольких типов (config, coef_limit, queues, vault, tickets, manager_allowances), и часть их содержимого атакующий контролирует напрямую. В TicketState поле recipient_wallet (32 байта по смещению 11) — полностью произвольные байты из BuyTicketArgs, это не обязан быть валидный ключ.
|
|
||||||
|
|
||||||
Эксплуатация (конкретная, практически реализуемая). В process_step_payout (строки 783–846) coef_limit_pda не проверяется по адресу. Раскладка CoefLimitState при декодировании: version=byte0, coef_ppm=[1..9], limit=[9..17], call_reward_lamports=[17..25]. Байты [17..25] тикета попадают на recipient_wallet[6..14] — их атакующий задаёт сам при покупке тикета. То есть:
|
|
||||||
|
|
||||||
1. Атакующий покупает тикет с recipient_wallet, чьи байты 6..14 кодируют огромный call_reward_lamports.
|
|
||||||
2. В step_payout подставляет этот тикет как coef_limit_pda.
|
|
||||||
3. transfer_from_vault(inflow_vault_pda, signer, coef_limit.call_reward_lamports) (строка 840) переводит подписанту (атакующему) почти весь доступный баланс вольта, который должен был накопиться для DAO.
|
|
||||||
|
|
||||||
version тикета = 1, decode значение версии не проверяет, поэтому подстановка проходит.
|
|
||||||
|
|
||||||
Подстановка config_pda для обхода DAO-авторизации в update_coef_limit/grant_manager_limits теоретически тоже возможна, но непрактична: там нужный dao_wallet пересекается со структурными полями тикета, и подбор потребовал бы грайндинга ~80 бит ключа. А вот путь через coef_limit/step_payout — реальная кража.
|
|
||||||
|
|
||||||
Фикс: во всех инструкциях, принимающих singleton-PDA, проверять адрес, например вызывать ensure_expected_pdas-подобную проверку (require_keys_eq!(find_single_pda(program_id, SEED).0, *pda.key, …)) для config/coef_limit/queues/inflow_vault, а для queues_pda в change_ticket_recipient — тоже.
|
|
||||||
|
|
||||||
---
|
|
||||||
🟠 MEDIUM — shine_payments: слабая валидация оракула Pyth
|
|
||||||
|
|
||||||
read_sol_usd_price / parse_pyth_price_update_v2 (строки 1038–1075):
|
|
||||||
|
|
||||||
1. Не проверяется владелец аккаунта цены (что он принадлежит Pyth receiver). Спасает только то, что адрес жёстко закреплён константой PYTH_SOL_USD_ACCOUNT. Это делает подмену невозможной, но защита держится на одном инварианте.
|
|
||||||
2. feed_id не проверяется. Константа PYTH_SOL_USD_FEED_ID объявлена в settings.rs, но в коде нигде не используется — программа доверяет, что в закреплённом аккаунте лежит именно SOL/USD.
|
|
||||||
3. Фиксированные смещения (73/89/93) предполагают VerificationLevel::Full. Borsh сериализует enum переменной длиной: Partial{num_signatures} занимает 2 байта вместо 1, что сдвигает все поля на 1 байт и приведёт к чтению мусорной цены. Уровень верификации не проверяется.
|
|
||||||
4. Confidence (conf) игнорируется — нет защиты от широкого ценового интервала.
|
|
||||||
|
|
||||||
Проверка возраста цены (ORACLE_MAX_AGE_SECS = 120) есть и сделана корректно. Рекомендация: проверять владельца аккаунта, сверять feed_id с константой и валидировать verification_level == Full (или парсить через официальный pyth_solana_receiver_sdk, который уже завендорен в .vendor/).
|
|
||||||
|
|
||||||
---
|
|
||||||
🟡 LOW — DoS через предсказуемые адреса тикетов — ✅ ИСПРАВЛЕНО (11.06.2026)
|
|
||||||
|
|
||||||
Закрыто: `create_pda_account` в `shine_payments` и `shine_users` переведён на паттерн
|
|
||||||
«создание поверх предзаполненного» (allocate + assign + добор ренты вместо строгого
|
|
||||||
`system_instruction::create_account`). «Подсев» лампортов на заранее известный адрес
|
|
||||||
тикета или пользовательской записи больше не блокирует создание PDA. Проверка
|
|
||||||
`is_uninitialized_account` в payments перестала зависеть от нулевого баланса. Тот же фикс
|
|
||||||
закрывает аналогичный сквоттинг логинов в `shine_users` (адрес выводится из логина).
|
|
||||||
Подробности — в `doc/programs/shine_payments.md` §3.4 и `doc/programs/shine_users.md` §3.3.
|
|
||||||
|
|
||||||
Историческое описание находки ниже.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
is_uninitialized_account (строка 1195) считает аккаунт неинициализированным только если lamports() == 0. Адреса тикетов детерминированы (queue_seed + index), а индекс последователен и предсказуем. Любой может заранее перевести немного лампортов на адрес следующего тикета — тогда create_pda_account упадёт (PdaAlreadyExists / ошибка create_account), заблокировав покупку/добавление тикета. Это griefing-DoS, не кража. Митигировать можно паттерном «create поверх предзаполненного» (allocate + assign + добор ренты) вместо system_instruction::create_account.
|
|
||||||
|
|
||||||
---
|
|
||||||
✅ Что проверено и сделано корректно
|
|
||||||
|
|
||||||
- Верификация подписей ed25519 в shine_users (строки 885–922): строго пинятся относительные индексы инструкций (−1/−2), требуется num_signatures == 1, все три ix-index == u16::MAX (данные внутри самой ed25519-инструкции — нельзя указать на чужую инструкцию), и сверяются pubkey/signature/message. Сделано грамотно.
|
|
||||||
- Цепочка версий записи (version == record_number+1, prev_hash == hash(old)) — корректная защита от replay (строки 535–536).
|
|
||||||
- Авторизация обновления записи завязана на ed25519-подпись root_key, а не на подписанта-плательщика — случайный аккаунт обновить чужую запись не может.
|
|
||||||
- Монотонность used_bytes/last_block_number и used_bytes <= paid_limit_bytes (строки 979–986).
|
|
||||||
- inflow_vault валидируется по derive из программы payments (строки 988–993).
|
|
||||||
- transfer_from_vault сохраняет рент-экземпт (вычитает minimum_balance через available_vault_lamports).
|
|
||||||
- init обеих программ безопасен к front-run: значения берутся из констант, а не от вызывающего; повторная инициализация заблокирована проверкой «uninitialized».
|
|
||||||
- Арифметика: overflow-checks = true в release-профиле + повсеместные checked_add/sub/mul. Парсинг везде с проверкой границ.
|
|
||||||
- manager_allowance PDA — единственный из payments, чей адрес проверяется корректно во всех путях (строки 645–646, 739–740).
|
|
||||||
- shine_login_guard — stateless, без аккаунтов и средств; рисков безопасности не несёт.
|
|
||||||
|
|
||||||
---
|
|
||||||
Приоритет действий
|
|
||||||
|
|
||||||
1. Critical #1 — добавить проверку адреса+владельца economy-config в create/update shine_users. Тривиальный фикс, помощник find_users_economy_config_pda уже есть.
|
|
||||||
2. Critical #2 — добавить проверку адресов всех singleton-PDA во все инструкции shine_payments (минимум coef_limit_pda/config_pda/queues_pda в step_payout и change_ticket_recipient).
|
|
||||||
3. Medium — ужесточить парсинг Pyth (owner + feed_id + verification_level), либо перейти на завендоренный SDK.
|
|
||||||
4. Low — учесть griefing-DoS на предсказуемых адресах тикетов.
|
|
||||||
|
|
||||||
Обе критические находки относятся к одному классу (Solana «missing ownership/address check» — самая частая категория эксплойтов), их стоит закрыть до любого деплоя в mainnet. Изменений в код я не вносил — это только анализ; готов подготовить патчи на оба критических пункта, если подтвердите.
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user