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) Единый список полей в порядке хранения

magic
Размер: 5 байт.
Значение: "SHiNE".
Назначение: маркер формата записи.
format_major
Размер: 1 байт (u8).
Текущее значение: 1.
Назначение: major-версия формата.
format_minor
Размер: 1 байт (u8).
Текущее значение: 0.
Назначение: minor-версия формата.
record_len
Размер: 2 байта (u16, LE).
Назначение: длина полезных данных записи (без padding).
created_at_ms
Размер: 8 байт (u64, LE).
Назначение: время создания записи (Unix time, ms).
updated_at_ms
Размер: 8 байт (u64, LE).
Назначение: время последнего обновления записи (Unix time, ms).
record_number (version)
Размер: 4 байта (u32, LE).
Назначение: порядковый номер записи пользователя.
Правило обновления: новая запись должна иметь last_record_number + 1; проверяется программой.
prev_record_hash (prev_hash)
Размер: 32 байта.
Назначение: хэш unsigned-части предыдущей записи для связи истории.
login_len
Размер: 1 байт (u8).
Назначение: длина поля login в байтах.
login
Размер: login_len байт (UTF-8).
Назначение: логин пользователя.
Текущие ограничения: от 1 до 25 символов, только a-z, 0-9, _.
root_key_status
Размер: 1 байт (u8).
Текущее значение: 0.
Назначение: статус root_key.
Комментарий: будущие статусы ротации зарезервированы, смена root-ключа пока не реализована.
root_key
Размер: 32 байта (Pubkey).
Назначение: корневой ключ пользователя для подписи записи.
blockchain_key_status
Размер: 1 байт (u8).
Текущее значение: 0.
Назначение: статус blockchain_key.
Комментарий: будущие статусы ротации зарезервированы.
blockchain_key
Размер: 32 байта (Pubkey).
Назначение: рабочий блокчейн-ключ пользователя.
device_key_status
Размер: 1 байт (u8).
Текущее значение: 0.
Назначение: статус device_key.
Комментарий: будущие статусы ротации зарезервированы.
device_key
Размер: 32 байта (Pubkey).
Назначение: ключ устройства пользователя.
chain_number
Размер: 2 байта (u16, LE).
Назначение: номер блокчейн-профиля пользователя.
Текущее использование: базовый сценарий с одним профилем (обычно 1).
balance
Размер: 8 байт (u64, LE).
Назначение: лимит/баланс пользователя.
is_server
Размер: 1 байт (u8).
Значения: 0 или 1.
Назначение: флаг серверного профиля.
server_key (только если is_server = 1)
Размер: 32 байта (Pubkey).
Назначение: публичный ключ сервера.
server_address_len (только если is_server = 1)
Размер: 1 байт (u8).
Назначение: длина строки server_address.
server_address (только если is_server = 1)
Размер: server_address_len байт (UTF-8).
Назначение: адрес сервера.
connection_servers_count
Размер: 1 байт (u8).
Назначение: количество серверов в списке подключения.
Повтор connection_servers_count раз:
server_login_len — 1 байт (u8),
server_login — server_login_len байт (UTF-8).
Назначение: логины серверов подключения.
trusted_count
Размер: 1 байт (u8).
Назначение: текущее число trusted-контактов.
Текущее состояние: пока только счетчик, без отдельной trusted-логики.
reserved
Размер: 5 байт.
Текущее значение: 0x00 0x00 0x00 0x00 0x00.
Назначение: резерв под будущие расширения.
signature
Размер: 64 байта.
Назначение: Ed25519-подпись хэша unsigned-части записи.
padding
Размер: до полного USER_PDA_SPACE.
Текущее значение: 0x00.
Назначение: добивка до фиксированного размера PDA.

4) Что подписывается

Подписывается SHA-256 от unsigned-части записи:

от magic до reserved включительно;
без signature;
без padding.

5) Что сейчас работает в логике

Сейчас в рабочем потоке используются 2 операции:

create_user_pda — регистрация пользователя.
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, но пока не реализованы программно.

Смена ключей пока недоступна
root_key, blockchain_key, device_key считаются без ротации; статусные поля пока фактически только 0.
Multi-chain профили пока не реализованы
Пока используется один базовый профиль (chain_number), расширение до нескольких профилей/форков — отдельный этап.
Trusted-логика пока не реализована
Пока хранится только trusted_count; список trusted, очередь, таймеры и голосование будут добавляться отдельно.
Работа с несколькими серверами на уровне приложения ограничена
В записи можно хранить несколько connection_servers, но в клиентском приложении может использоваться только первый сервер до внедрения полной multi-server логики.

7) Константы и фиксированные значения (точки будущего расширения)

Ниже перечислены места, где сейчас используются константы/фиксированные значения, а в будущем возможна доработка:

Версия формата: format_major = 1, format_minor = 0.
Расширение: переход на следующую минорную/мажорную версию при изменении бинарной схемы.
Размер PDA: USER_PDA_SPACE = 768.
Расширение: увеличение размера или переход на иное хранение при росте структуры.
Статусы ключей: все три *_key_status пока равны 0.
Расширение: добавить коды состояний для ротации/восстановления ключей.
chain_number: текущий рабочий сценарий с одним профилем (обычно 1).
Расширение: поддержка нескольких блокчейн-форков.
trusted_count: пока только счетчик, обычно 0.
Расширение: отдельные структуры trusted-списка, очередей и таймеров.
reserved (5 байт): сейчас всегда нули.
Расширение: использовать как флаги/дополнительные поля без слома общей схемы.

11 KiB Raw Blame History Unescape Escape