diff --git a/SHINY_USER_FORMAT_V1_1_DRAFT.md b/SHINY_USER_FORMAT_V1_1_DRAFT.md new file mode 100644 index 0000000..b7f3a6c --- /dev/null +++ b/SHINY_USER_FORMAT_V1_1_DRAFT.md @@ -0,0 +1,180 @@ +# SHINY USER FORMAT v1.1 (DRAFT) + +Документ описывает единый бинарный формат пользовательской записи в `user_pda` для программы `shine_users`. + +Цель версии `v1.1`: сохранить текущую рабочую логику регистрации/обновления и добавить задел под будущую смену ключей через 3 статус-байта: +- `root_key_status` +- `blockchain_key_status` +- `device_key_status` + +Сейчас во всех трех полях используется значение `0` (ключ создан и ни разу не менялся). + +## 1) Общие правила кодирования + +- Числа: Little Endian (`LE`). +- Строки: `UTF-8` с префиксом длины `u8`. +- Публичные ключи: 32 байта (`Pubkey`). +- Подпись: 64 байта (Ed25519). +- Размер PDA фиксированный: `USER_PDA_SPACE` (сейчас 768 байт). +- `record_len` хранит длину полезной записи от `magic` до `signature` включительно (без `padding`). + +## 2) Единый список полей в порядке хранения + +1. `magic` + - Размер: 5 байт + - Значение: `"SHiNE"` + - Назначение: маркер формата записи. + +2. `format_major` + - Размер: 1 байт (`u8`) + - Назначение: major-версия формата. + +3. `format_minor` + - Размер: 1 байт (`u8`) + - Назначение: minor-версия формата. + +4. `record_len` + - Размер: 2 байта (`u16`, LE) + - Назначение: длина полезных данных записи (без `padding`). + +5. `created_at_ms` + - Размер: 8 байт (`u64`, LE) + - Назначение: время создания записи (Unix time, ms). + +6. `updated_at_ms` + - Размер: 8 байт (`u64`, LE) + - Назначение: время последнего обновления записи (Unix time, ms). + +7. `version` + - Размер: 4 байта (`u32`, LE) + - Назначение: номер версии записи. + - Правило: при обновлении должен быть строго `old_version + 1`; это проверяется программой. + +8. `prev_hash` + - Размер: 32 байта + - Назначение: хэш unsigned-предыдущей версии для связывания истории. + +9. `login_len` + - Размер: 1 байт (`u8`) + - Назначение: длина поля `login` в байтах. + +10. `login` + - Размер: `login_len` байт (UTF-8) + - Назначение: логин пользователя. + - Текущие ограничения: от 1 до 30 символов, только `a-z`, `0-9`, `_`. + +11. `root_key_status` + - Размер: 1 байт (`u8`) + - Текущее значение: `0` + - Назначение: статус `root_key`. + - Комментарий: `0` = ключ создан и не менялся; другие статусы зарезервированы на будущее, сейчас ротация root-ключа не реализована. + +12. `root_key` + - Размер: 32 байта (`Pubkey`) + - Назначение: корневой ключ пользователя для подписи записи. + +13. `blockchain_key_status` + - Размер: 1 байт (`u8`) + - Текущее значение: `0` + - Назначение: статус `blockchain_key`. + - Комментарий: `0` = ключ создан и не менялся; другие статусы зарезервированы на будущее. + +14. `blockchain_key` + - Размер: 32 байта (`Pubkey`) + - Назначение: рабочий блокчейн-ключ пользователя. + +15. `device_key_status` + - Размер: 1 байт (`u8`) + - Текущее значение: `0` + - Назначение: статус `device_key`. + - Комментарий: `0` = ключ создан и не менялся; другие статусы зарезервированы на будущее. + +16. `device_key` + - Размер: 32 байта (`Pubkey`) + - Назначение: ключ устройства пользователя. + +17. `blockchain_number` + - Размер: 2 байта (`u16`, LE) + - Назначение: номер/версия пользовательского блокчейн-профиля. + - Текущее использование: базовый сценарий с одним профилем; обычно значение `1` (только основной блокчейн-профиль без форков). + +18. `balance` + - Размер: 8 байт (`u64`, LE) + - Назначение: лимит/баланс пользователя. + +19. `is_server` + - Размер: 1 байт (`u8`) + - Значения: `0` или `1` + - Назначение: флаг серверного профиля. + +20. `server_key` (только если `is_server = 1`) + - Размер: 32 байта (`Pubkey`) + - Назначение: публичный ключ сервера. + +21. `server_address_len` (только если `is_server = 1`) + - Размер: 1 байт (`u8`) + - Назначение: длина строки `server_address`. + +22. `server_address` (только если `is_server = 1`) + - Размер: `server_address_len` байт (UTF-8) + - Назначение: адрес сервера. + +23. `connection_servers_count` + - Размер: 1 байт (`u8`) + - Назначение: количество серверов в списке подключения. + +24. Повтор `connection_servers_count` раз: + - `server_login_len` — 1 байт (`u8`) + - `server_login` — `server_login_len` байт (UTF-8) + - Назначение: логины серверов подключения. + +25. `trusted_count` + - Размер: 1 байт (`u8`) + - Назначение: текущее число trusted-контактов. + - Текущее состояние: пока только счетчик; в текущем рабочем потоке обычно `0`, расширенная trusted-логика еще не включена. + +26. `reserved` + - Размер: 5 байт + - Текущее значение: все `0x00` + - Назначение: резерв под будущие расширения. + +27. `signature` + - Размер: 64 байта + - Назначение: Ed25519 подпись хэша unsigned-части записи. + +28. `padding` + - Размер: до полного `USER_PDA_SPACE` + - Текущее значение: `0x00` + - Назначение: добивка до фиксированного размера PDA. + +## 3) Что подписывается + +Подписывается SHA-256 от unsigned-части записи: +- от `magic` до `reserved` включительно; +- без `signature`; +- без `padding`. + +## 4) Что сейчас ограничено и зарезервировано на будущее + +1. Статусы ключей (`root_key_status`, `blockchain_key_status`, `device_key_status`) +Сейчас только значение `0`; будущие значения для ротации ключей пока не введены. + +2. Trusted-часть (`trusted_count`) +Пока хранится только счетчик. Полная логика trusted-пользователей (список, очередь, таймауты) еще не реализована. + +3. `reserved` (5 байт) +Полностью нулевой резерв под будущие поля/флаги. + +4. Блокчейн-профили +Сейчас рабочая модель ориентирована на один базовый профиль; расширение до нескольких профилей/форков будет отдельным этапом. + +5. Версия формата +Текущий документ описывает `v1.1 (DRAFT)`. В тестовой разработке формат можно не повышать до момента внедрения новой on-chain логики. + +6. Текущие рабочие операции +Сейчас по факту поддерживаются: +- регистрация пользователя (`create_user_pda`); +- обновление записи (`update_user_pda`) с увеличением `balance` через `additional_limit`; +- инкремент `version` на каждом успешном update; +- оплата уходит на адрес, заданный в `REGISTRATION_FEE_RECEIVER` (а не в DAO по умолчанию). + diff --git a/shine/scripts/dao_legacy/README.md b/shine/scripts/del/dao_legacy/README.md similarity index 100% rename from shine/scripts/dao_legacy/README.md rename to shine/scripts/del/dao_legacy/README.md diff --git a/shine/scripts/dao_legacy/create_realm_dao_build_exec.js b/shine/scripts/del/dao_legacy/create_realm_dao_build_exec.js similarity index 100% rename from shine/scripts/dao_legacy/create_realm_dao_build_exec.js rename to shine/scripts/del/dao_legacy/create_realm_dao_build_exec.js diff --git a/shine/scripts/dao_legacy/create_realm_dao_test.sh b/shine/scripts/del/dao_legacy/create_realm_dao_test.sh similarity index 100% rename from shine/scripts/dao_legacy/create_realm_dao_test.sh rename to shine/scripts/del/dao_legacy/create_realm_dao_test.sh diff --git a/shine/scripts/dao_legacy/create_realm_dao_without_burn_build_exec.js b/shine/scripts/del/dao_legacy/create_realm_dao_without_burn_build_exec.js similarity index 100% rename from shine/scripts/dao_legacy/create_realm_dao_without_burn_build_exec.js rename to shine/scripts/del/dao_legacy/create_realm_dao_without_burn_build_exec.js diff --git a/shine/scripts/devnet/README.md b/shine/scripts/del/devnet/README.md similarity index 100% rename from shine/scripts/devnet/README.md rename to shine/scripts/del/devnet/README.md diff --git a/shine/scripts/devnet/quick_devnet_e2e.js b/shine/scripts/del/devnet/quick_devnet_e2e.js similarity index 100% rename from shine/scripts/devnet/quick_devnet_e2e.js rename to shine/scripts/del/devnet/quick_devnet_e2e.js diff --git a/shine/scripts/devnet/quick_devnet_e2e_multi.js b/shine/scripts/del/devnet/quick_devnet_e2e_multi.js similarity index 100% rename from shine/scripts/devnet/quick_devnet_e2e_multi.js rename to shine/scripts/del/devnet/quick_devnet_e2e_multi.js