# 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 байт): сейчас всегда нули. Расширение: использовать как флаги/дополнительные поля без слома общей схемы.