docs: rename and finalize user format v1.0 draft
This commit is contained in:
AidarKC
parent
ec8221fab2
commit
61fcfd0e3b
215
SHINY_USER_FORMAT_V1_0_DRAFT.md
Normal file
215
SHINY_USER_FORMAT_V1_0_DRAFT.md
Normal file
@ -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 байт): сейчас всегда нули.
|
||||||
|
Расширение: использовать как флаги/дополнительные поля без слома общей схемы.
|
||||||
@ -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 по умолчанию).
|
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user