Добавить спецификации Solana программ и вынести формат PDA

Dev_Docs/Future_Features/medium/2026-06-02_сессионные_саб_серверы_в_pda.md

@@ -35,9 +35,11 @@
 Предварительные значения:
 
 - тип `1` - обычная пользовательская сессия;
-- тип `10` - саб-сервер пользователя;
+- тип `100` - саб-сервер пользователя;
 - версия `1` - первая рабочая версия формата записи сессии.
 
+На текущем этапе под это уже зарезервирован отдельный блок `SessionsBlock` с `block_type = 55`, а `TrustedStateBlock` остаётся на `50`.
+
 Важно: саб-серверов у одного пользователя может быть несколько.
 
 ## Архитектурный принцип
@@ -74,14 +76,14 @@
    - максимальную длину `sessionName`;
    - правила удаления и обновления записи;
    - правила ротации `sessionPubKey`.
-6. Продумать, как UI и сервер будут отличать тип `1` и тип `10`.
+6. Продумать, как UI и сервер будут отличать тип `1` и тип `100`.
 7. Определить, какие внутренние сообщения саб-сервера останутся полностью прозрачными для SHiNE-сервера, а какие потребуют только технической маршрутизации.
 8. Добавить API/операции чтения и обновления списка сессий, если для этого не хватит существующих механизмов.
 9. После реализации обязательно обновить документацию.
 
 ## Что нужно обновить при реализации
 
-- `shine-solana/shine/doc/SHiNE-user-format-v.1.0.md`
+- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
 - `Dev_Docs/Solana_Architecture/README.md`
 - `Dev_Docs/Инициализация_Solana_регистрации/README.md`
 - `Dev_Docs/Keys/README.md`

Dev_Docs/Solana/user_pda/README.md

@@ -32,6 +32,12 @@
 
 Один логин соответствует одной `user_pda`.
 
+## 2.1. Кто оплачивает create/update PDA
+
+- Инструкции `create_user_pda` и `update_user_pda` оплачиваются с `device_key`.
+- `root_key` используется для подписи unsigned части записи через Ed25519 instruction и не является fee payer.
+- Для server PDA это правило то же самое: пополнять SOL нужно на адрес `device_key`.
+
 ## 3. Общие правила кодирования
 
 - Числа кодируются в Little Endian.
@@ -84,6 +90,7 @@ UserPdaRecordV1
 | `3` | `BlockchainRegistryBlock` | Один или несколько блокчейнов пользователя. |
 | `30` | `ServerProfileBlock` | Серверные данные пользователя. |
 | `40` | `AccessServersBlock` | Серверы доступа/relay. |
+| `55` | `SessionsBlock` | Опубликованные пользовательские сессии и саб-серверы. |
 | `50` | `TrustedStateBlock` | Счетчик trusted-связей. |
 | `255` | `ReservedBlock` | Зарезервировано, пока не используется. |
 
@@ -91,10 +98,10 @@ UserPdaRecordV1
 
 - неизвестный `block_type` в `format_major = 1` считается ошибкой;
 - обязательные блоки: `RootKeyBlock`, `DeviceKeyBlock`, `BlockchainRegistryBlock`;
-- необязательные блоки: `ServerProfileBlock`, `AccessServersBlock`, `TrustedStateBlock`;
+- необязательные блоки: `ServerProfileBlock`, `AccessServersBlock`, `SessionsBlock`, `TrustedStateBlock`;
 - каждый обязательный блок должен встречаться ровно один раз;
 - порядок блоков в записи фиксируется для простоты проверки:
-  `RootKey`, `DeviceKey`, `BlockchainRegistry`, `ServerProfile`, `AccessServers`, `TrustedState`.
+  `RootKey`, `DeviceKey`, `BlockchainRegistry`, `ServerProfile`, `AccessServers`, `Sessions`, `TrustedState`.
 
 ## 6. RootKeyBlock
 
@@ -197,6 +204,7 @@ Arweave `tx_id` - обычное поле внутри записи конкре
 - `used_bytes <= paid_limit_bytes`;
 - если `last_block_number` увеличился, то должны быть переданы новый `last_block_hash` и новая `last_block_signature`;
 - `last_block_signature` проверяется через Ed25519-инструкцию Solana: подпись должна соответствовать хэшу сообщения `LastBlockState` и `blockchain_public_key`;
+- в транзакции `create_user_pda` / `update_user_pda` две Ed25519-инструкции должны идти непосредственно перед вызовом `shine_users`: сначала подпись `root_key`, затем подпись `blockchain_public_key`;
 - `arweave_tx_id` можно добавить или заменить на новый, если пользователь выгрузил более актуальное состояние в Arweave;
 - уменьшать лимит, число блоков или занятый размер нельзя.
 
@@ -230,7 +238,8 @@ ServerProfileBlock
 - block_type: u8 = 30
 - block_version: u8 = 0
 - is_server: u8
-- server_key: [u8; 32], только если is_server = 1
+- address_format_type: u8, только если is_server = 1
+- address_format_version: u8, только если is_server = 1
 - server_address: string, только если is_server = 1
 - sync_servers_count: u8, только если is_server = 1
 - sync_servers: string[sync_servers_count], только если is_server = 1
@@ -240,9 +249,11 @@ ServerProfileBlock
 
 - `is_server = 0` означает, что серверных данных нет;
 - `is_server = 1` означает, что пользователь публикует серверный профиль;
+- `address_format_type` — тип формата адреса сервера: `1` = URL-строка (например `https://shineup.me/ws`);
+- `address_format_version` — версия формата адреса, сейчас `0`;
 - `sync_servers_count` максимум `32`;
-- `server_address` - строковый адрес сервера в формате, который будет отдельно закреплен на уровне приложения;
-- `sync_servers` - логины пользователей системы, через которых этот сервер пытается синхронизироваться. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы.
+- `server_address` - строковый адрес сервера в соответствии с `address_format_type`;
+- `sync_servers` - логины SHiNE-пользователей, зарегистрированных как серверы, с которыми этот сервер синхронизирует блокчейн и личные сообщения. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы.
 
 ## 12. AccessServersBlock
 
@@ -263,7 +274,53 @@ AccessServersBlock
 - `access_servers` - логины пользователей системы, используемых как серверы доступа/relay. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы;
 - точная семантика выбора сервера доступа определяется клиентской/серверной логикой SHiNE.
 
-## 13. TrustedStateBlock
+## 13. SessionsBlock
+
+Блок хранит опубликованные пользовательские сессии. На текущем этапе регистрация пользователя не добавляет туда записи автоматически, поэтому стандартный create/update продолжает работать с пустым списком.
+
+```text
+SessionsBlock
+- block_type: u8 = 55
+- block_version: u8 = 0
+- sessions_mode: u8
+- sessions_count: u8
+- sessions: SessionRecord[sessions_count]
+```
+
+`sessions_mode`:
+
+| Значение | Смысл |
+|----------|-------|
+| `1` | Можно использовать и сессии, зарегистрированные в PDA, и сессии, созданные вне PDA. |
+| `10` | Зарезервировано на будущее: можно использовать только сессии, опубликованные в PDA. |
+
+Сейчас рабочий режим по умолчанию: `sessions_mode = 1`. Серверная логика пока не реализует особое поведение для `10`; это задел под будущее расширение.
+
+```text
+SessionRecord
+- session_type: u8
+- session_version: u8
+- session_name: string
+- session_pub_key: [u8; 32]
+```
+
+`session_type`:
+
+| Значение | Смысл |
+|----------|-------|
+| `1` | Обычная пользовательская сессия. |
+| `100` | Саб-сервер пользователя. |
+
+Правила:
+
+- максимум `64` записей на пользователя;
+- `session_name` не пустой, максимум `64` байта;
+- `session_name` может содержать только символы `[A-Za-z0-9_]`;
+- `session_version` сейчас должна быть равна `1`;
+- внутри одного блока должны быть уникальны и `session_name`, и `session_pub_key`;
+- на текущем этапе UI и регистрация не обязаны добавлять туда записи автоматически.
+
+## 14. TrustedStateBlock
 
 Пока trusted-логика не реализована полностью, поэтому блок хранит только счетчик.
 
@@ -276,7 +333,7 @@ TrustedStateBlock
 
 Пока блок с доверенными лицами не реализуется, потому что полный формат trusted-логики еще не составлен. В будущем trusted-связи, очереди, таймеры и подтверждения должны быть вынесены в отдельный формат.
 
-## 14. Подпись user_pda
+## 15. Подпись user_pda
 
 Подписывается не вся PDA целиком, а unsigned-часть записи:
 
@@ -293,10 +350,11 @@ signature = Ed25519(root_key, message)
 ```
 
 Solana-программа проверяет подпись через встроенную Ed25519-инструкцию. Подписантом должен быть `root_key` из `RootKeyBlock`.
+Для `shine_users` эта инструкция должна стоять в транзакции сразу перед Ed25519-инструкцией `last_block_signature` и непосредственно перед самой `create/update`-инструкцией программы.
 
 Смену формата подписи сейчас не трогаем.
 
-## 15. Регистрация пользователя
+## 16. Регистрация пользователя
 
 При регистрации:
 
@@ -307,13 +365,14 @@ Solana-программа проверяет подпись через встр
 - `created_at_ms = updated_at_ms`;
 - обязательные блоки присутствуют;
 - создается минимум один `BlockchainRecord`;
+- новый `SessionsBlock` может присутствовать, но при обычной регистрации сейчас записывается пустой список с `sessions_mode = 1`;
 - стартовый `paid_limit_bytes` равен стартовому бонусу плюс оплаченный дополнительный лимит;
 - `used_bytes <= paid_limit_bytes`;
 - пользователь платит регистрационную комиссию;
 - если покупается дополнительный лимит, пользователь платит комиссию за этот лимит;
 - вся unsigned-часть записи подписана `root_key`.
 
-## 16. Обновление пользователя
+## 17. Обновление пользователя
 
 При обновлении:
 
@@ -328,7 +387,7 @@ Solana-программа проверяет подпись через встр
 - при увеличении оплаченного лимита пользователь доплачивает комиссию;
 - Arweave `tx_id` может быть пустым или обновленным, но его содержимое Solana не валидирует.
 
-## 17. Отличия от старого линейного формата
+## 18. Отличия от старого линейного формата
 
 Старый формат после `login` хранил поля линейно:
 

Dev_Docs/Solana_Architecture/README.md

@@ -9,7 +9,7 @@
 Связанные документы:
 
 - `Dev_Docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей.
-- `shine-solana/shine/doc/SHiNE-user-format-v.1.0.md` — точный формат `user_pda` для `shine_users`.
+- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` — точный формат `user_pda` для `shine_users`.
 - `shine-solana/shine/doc/FUNDS_FLOW.md` — короткая справка по денежным потокам внутри Solana-модуля.
 
 ## Кратко