diff --git a/SHINY_USER_FORMAT_V1_0_DRAFT.md b/SHINY_USER_FORMAT_V1_0_DRAFT.md new file mode 100644 index 0000000..e065528 --- /dev/null +++ b/SHINY_USER_FORMAT_V1_0_DRAFT.md @@ -0,0 +1,215 @@ +# SHINY USER FORMAT v1.0 (DRAFT) + +Документ описывает целевой бинарный формат пользовательской записи в `user_pda` для программы `shine_users`. + +## 1) Статус версии и цель + +- Текущий on-chain формат: `v1.0`. +- Этот документ: `v1.0 (draft)` для текущего этапа. +- Цель текущей версии: зафиксировать рабочий формат и сразу оставить в нем поля для будущего расширения. + +Новые статусные поля: +- `root_key_status` +- `blockchain_key_status` +- `device_key_status` + +Текущее значение каждого статуса: `0` (ключ создан и не менялся). + +## 2) Общие правила кодирования + +- Числа: Little Endian (`LE`). +- Строки: `UTF-8` с префиксом длины `u8`. +- Публичные ключи: 32 байта (`Pubkey`). +- Подпись: 64 байта (Ed25519). +- Размер PDA фиксированный: `USER_PDA_SPACE` (сейчас 768 байт). +- `record_len` хранит длину полезной записи от `magic` до `signature` включительно (без `padding`). + +## 3) Единый список полей в порядке хранения + +1. `magic` + Размер: 5 байт. + Значение: `"SHiNE"`. + Назначение: маркер формата записи. + +2. `format_major` + Размер: 1 байт (`u8`). + Текущее значение: `1`. + Назначение: major-версия формата. + +3. `format_minor` + Размер: 1 байт (`u8`). + Текущее значение: `0`. + Назначение: 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. `record_number` (`version`) + Размер: 4 байта (`u32`, LE). + Назначение: порядковый номер записи пользователя. + Правило обновления: новая запись должна иметь `last_record_number + 1`; проверяется программой. + +8. `prev_record_hash` (`prev_hash`) + Размер: 32 байта. + Назначение: хэш unsigned-части предыдущей записи для связи истории. + +9. `login_len` + Размер: 1 байт (`u8`). + Назначение: длина поля `login` в байтах. + +10. `login` + Размер: `login_len` байт (UTF-8). + Назначение: логин пользователя. + Текущие ограничения: от 1 до 20 символов, только `a-z`, `0-9`, `_`. + +11. `root_key_status` + Размер: 1 байт (`u8`). + Текущее значение: `0`. + Назначение: статус `root_key`. + Комментарий: будущие статусы ротации зарезервированы, смена root-ключа пока не реализована. + +12. `root_key` + Размер: 32 байта (`Pubkey`). + Назначение: корневой ключ пользователя для подписи записи. + +13. `blockchain_key_status` + Размер: 1 байт (`u8`). + Текущее значение: `0`. + Назначение: статус `blockchain_key`. + Комментарий: будущие статусы ротации зарезервированы. + +14. `blockchain_key` + Размер: 32 байта (`Pubkey`). + Назначение: рабочий блокчейн-ключ пользователя. + +15. `device_key_status` + Размер: 1 байт (`u8`). + Текущее значение: `0`. + Назначение: статус `device_key`. + Комментарий: будущие статусы ротации зарезервированы. + +16. `device_key` + Размер: 32 байта (`Pubkey`). + Назначение: ключ устройства пользователя. + +17. `chain_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-контактов. + Текущее состояние: пока только счетчик, без отдельной trusted-логики. + +26. `reserved` + Размер: 5 байт. + Текущее значение: `0x00 0x00 0x00 0x00 0x00`. + Назначение: резерв под будущие расширения. + +27. `signature` + Размер: 64 байта. + Назначение: Ed25519-подпись хэша unsigned-части записи. + +28. `padding` + Размер: до полного `USER_PDA_SPACE`. + Текущее значение: `0x00`. + Назначение: добивка до фиксированного размера PDA. + +## 4) Что подписывается + +Подписывается SHA-256 от unsigned-части записи: +- от `magic` до `reserved` включительно; +- без `signature`; +- без `padding`. + +## 5) Что сейчас работает в логике + +Сейчас в рабочем потоке используются 2 операции: +1. `create_user_pda` — регистрация пользователя. +2. `update_user_pda` — обновление записи пользователя. + +Через `update_user_pda` сейчас можно: +- увеличить `balance` через `additional_limit`; +- обновить серверные поля (`is_server`, `server_key`, `server_address`, `connection_servers`); +- увеличить `record_number` (`version`) на 1. + +Оплата идет на адрес, заданный в `REGISTRATION_FEE_RECEIVER` (не в DAO по умолчанию). + +## 6) Ограничения и отложенные расширения + +Это функции и сценарии, которые предусмотрены структурой данных формата `v1.0`, но пока не реализованы программно. + +1. Смена ключей пока недоступна + `root_key`, `blockchain_key`, `device_key` считаются без ротации; статусные поля пока фактически только `0`. + +2. Multi-chain профили пока не реализованы + Пока используется один базовый профиль (`chain_number`), расширение до нескольких профилей/форков — отдельный этап. + +3. Trusted-логика пока не реализована + Пока хранится только `trusted_count`; список trusted, очередь, таймеры и голосование будут добавляться отдельно. + +4. Работа с несколькими серверами на уровне приложения ограничена + В записи можно хранить несколько `connection_servers`, но в клиентском приложении может использоваться только первый сервер до внедрения полной multi-server логики. + + +## 7) Константы и фиксированные значения (точки будущего расширения) + +Ниже перечислены места, где сейчас используются константы/фиксированные значения, а в будущем возможна доработка: + +1. Версия формата: `format_major = 1`, `format_minor = 0`. + Расширение: переход на следующую минорную/мажорную версию при изменении бинарной схемы. + +2. Размер PDA: `USER_PDA_SPACE = 768`. + Расширение: увеличение размера или переход на иное хранение при росте структуры. + +3. Статусы ключей: все три `*_key_status` пока равны `0`. + Расширение: добавить коды состояний для ротации/восстановления ключей. + +4. `chain_number`: текущий рабочий сценарий с одним профилем (обычно `1`). + Расширение: поддержка нескольких блокчейн-форков. + +5. `trusted_count`: пока только счетчик, обычно `0`. + Расширение: отдельные структуры trusted-списка, очередей и таймеров. + +6. `reserved` (5 байт): сейчас всегда нули. + Расширение: использовать как флаги/дополнительные поля без слома общей схемы. diff --git a/SHINY_USER_FORMAT_V1_1_DRAFT.md b/SHINY_USER_FORMAT_V1_1_DRAFT.md deleted file mode 100644 index b7f3a6c..0000000 --- a/SHINY_USER_FORMAT_V1_1_DRAFT.md +++ /dev/null @@ -1,180 +0,0 @@ -# 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 по умолчанию). -