Миграция PDA на client.key

shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md

@@ -12,8 +12,9 @@
 
 - логин пользователя;
 - неизменяемые параметры создания записи;
+- публичный recovery-ключ пользователя;
 - корневой публичный ключ пользователя;
-- ключ устройства;
+- клиентский публичный ключ пользователя;
 - данные одного или нескольких пользовательских блокчейнов SHiNE;
 - серверные данные пользователя, если пользователь выступает сервером;
 - серверы доступа пользователя;
@@ -34,9 +35,9 @@
 
 ## 2.1. Кто оплачивает create/update PDA
 
-- Инструкции `create_user_pda` и `update_user_pda` оплачиваются с `device_key`.
+- Инструкции `create_user_pda` и `update_user_pda` оплачиваются с `client_key`.
 - `root_key` используется для подписи unsigned части записи через Ed25519 instruction и не является fee payer.
-- Для server PDA это правило то же самое: пополнять SOL нужно на адрес `device_key`.
+- Для server PDA это правило то же самое: пополнять SOL нужно на адрес `client_key`.
 
 ## 3. Общие правила кодирования
 
@@ -85,8 +86,9 @@ UserPdaRecordV1
 
 | block_type | Блок | Назначение |
 |------------|------|------------|
+| `0` | `RecoveryKeyBlock` | Ключ восстановления пользователя. |
 | `1` | `RootKeyBlock` | Корневой ключ пользователя. |
-| `2` | `DeviceKeyBlock` | Ключ устройства пользователя. |
+| `2` | `ClientKeyBlock` | Клиентский ключ пользователя. |
 | `3` | `BlockchainRegistryBlock` | Один или несколько блокчейнов пользователя. |
 | `30` | `ServerProfileBlock` | Серверные данные пользователя. |
 | `40` | `AccessServersBlock` | Серверы доступа/relay. |
@@ -97,13 +99,31 @@ UserPdaRecordV1
 Правила:
 
 - неизвестный `block_type` в `format_major = 1` считается ошибкой;
-- обязательные блоки: `RootKeyBlock`, `DeviceKeyBlock`, `BlockchainRegistryBlock`;
+- обязательные блоки: `RecoveryKeyBlock`, `RootKeyBlock`, `ClientKeyBlock`, `BlockchainRegistryBlock`;
 - необязательные блоки: `ServerProfileBlock`, `AccessServersBlock`, `SessionsBlock`, `TrustedStateBlock`;
 - каждый обязательный блок должен встречаться ровно один раз;
 - порядок блоков в записи фиксируется для простоты проверки:
-  `RootKey`, `DeviceKey`, `BlockchainRegistry`, `ServerProfile`, `AccessServers`, `Sessions`, `TrustedState`.
+  `RecoveryKey`, `RootKey`, `ClientKey`, `BlockchainRegistry`, `ServerProfile`, `AccessServers`, `Sessions`, `TrustedState`.
 
-## 6. RootKeyBlock
+## 6. RecoveryKeyBlock
+
+Recovery-ключ нужен для будущих сценариев восстановления и ротации остальных ключей. В текущей версии он только публикуется в записи и не меняется через обычный `update_user_pda`.
+
+```text
+RecoveryKeyBlock
+- block_type: u8 = 0
+- block_version: u8 = 0
+- recovery_key: [u8; 32]
+```
+
+Правила:
+
+- при создании задается публичный recovery-ключ пользователя;
+- при обновлении `recovery_key` должен совпадать с предыдущей записью;
+- приватный `recovery.key` в PDA не хранится;
+- отдельная ротация recovery-ключа будет отдельным форматом/сценарием в будущем.
+
+## 7. RootKeyBlock
 
 Смена `root_key` пока не проектируется и не реализуется. Блок фиксирует только стадию `0`.
 
@@ -120,24 +140,24 @@ RootKeyBlock
 - при обновлении `root_key` должен совпадать с предыдущей записью;
 - ротация root-key будет отдельным форматом/сценарием в будущем.
 
-## 7. DeviceKeyBlock
+## 8. ClientKeyBlock
 
-Смена `device_key` пока также не проектируется как отдельная ротация. В версии `0` хранится один ключ устройства.
+Смена `client_key` пока также не проектируется как отдельная ротация. В версии `0` хранится один клиентский ключ пользователя.
 
 ```text
-DeviceKeyBlock
+ClientKeyBlock
 - block_type: u8 = 2
 - block_version: u8 = 0
-- device_key: [u8; 32]
+- client_key: [u8; 32]
 ```
 
 Правила:
 
-- при создании задается текущий публичный ключ устройства;
-- при обновлении ключ устройства может быть обновлен только если это отдельно разрешено бизнес-логикой инструкции;
-- история устройств и несколько устройств в этом формате не хранятся.
+- при создании задается текущий клиентский публичный ключ пользователя;
+- при обновлении `client_key` должен совпадать с предыдущей записью;
+- история устройств и несколько клиентских ключей в этом формате не хранятся.
 
-## 8. BlockchainRegistryBlock
+## 9. BlockchainRegistryBlock
 
 Блок хранит данные пользовательских блокчейнов SHiNE. Сейчас используется один блокчейн, но структура сразу сделана как список.
 
@@ -155,7 +175,7 @@ BlockchainRegistryBlock
 - в будущем можно увеличить количество записей без изменения смысла `BlockchainRecord`;
 - каждый `BlockchainRecord` описывает один пользовательский SHiNE-блокчейн.
 
-## 9. BlockchainRecord
+## 10. BlockchainRecord
 
 ```text
 BlockchainRecord
@@ -191,7 +211,7 @@ BlockchainRecord
 
 Arweave `tx_id` - обычное поле внутри записи конкретного блокчейна. Solana-программа не проверяет, что такой Arweave transaction действительно существует и содержит корректные данные; это ответственность клиента/сервера/пользователя.
 
-## 10. Правила обновления BlockchainRecord
+## 11. Правила обновления BlockchainRecord
 
 При обновлении записи:
 
@@ -229,7 +249,7 @@ last_block_signature = Ed25519(blockchain_public_key, message)
 
 Причина проверки подписи `LastBlockState`: `root_key` управляет Solana-записью пользователя, а `blockchain_public_key` подтверждает состояние конкретного пользовательского блокчейна. Подписывается не голый хэш, а связка логина, имени блокчейна, номера последнего блока, хэша последнего блока и занятого размера.
 
-## 11. ServerProfileBlock
+## 12. ServerProfileBlock
 
 Блок присутствует, если пользователь выступает сервером.
 
@@ -255,7 +275,7 @@ ServerProfileBlock
 - `server_address` - строковый адрес сервера в соответствии с `address_format_type`;
 - `sync_servers` - логины SHiNE-пользователей, зарегистрированных как серверы, с которыми этот сервер синхронизирует блокчейн и личные сообщения. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы.
 
-## 12. AccessServersBlock
+## 13. AccessServersBlock
 
 Блок хранит серверы доступа/relay для пользователя.
 
@@ -274,7 +294,7 @@ AccessServersBlock
 - `access_servers` - логины пользователей системы, используемых как серверы доступа/relay. Solana-программа не обязана проверять, что эти логины действительно зарегистрированы как серверы;
 - точная семантика выбора сервера доступа определяется клиентской/серверной логикой SHiNE.
 
-## 13. SessionsBlock
+## 14. SessionsBlock
 
 Блок хранит опубликованные пользовательские сессии. На текущем этапе регистрация пользователя не добавляет туда записи автоматически, поэтому стандартный create/update продолжает работать с пустым списком.
 
@@ -321,7 +341,7 @@ SessionRecord
 - внутри одного блока должны быть уникальны и `session_name`, и `session_pub_key`;
 - на текущем этапе UI и регистрация не обязаны добавлять туда записи автоматически.
 
-## 14. TrustedStateBlock
+## 15. TrustedStateBlock
 
 Пока trusted-логика не реализована полностью, поэтому блок хранит только счетчик.
 
@@ -334,7 +354,7 @@ TrustedStateBlock
 
 Пока блок с доверенными лицами не реализуется, потому что полный формат trusted-логики еще не составлен. В будущем trusted-связи, очереди, таймеры и подтверждения должны быть вынесены в отдельный формат.
 
-## 15. Подпись user_pda
+## 16. Подпись user_pda
 
 Подписывается не вся PDA целиком, а unsigned-часть записи:
 
@@ -355,7 +375,7 @@ Solana-программа проверяет подпись через встр
 
 Смену формата подписи сейчас не трогаем.
 
-## 16. Регистрация пользователя
+## 17. Регистрация пользователя
 
 При регистрации:
 
@@ -373,12 +393,12 @@ Solana-программа проверяет подпись через встр
 - если покупается дополнительный лимит, пользователь платит комиссию за этот лимит;
 - вся unsigned-часть записи подписана `root_key`.
 
-## 17. Обновление пользователя
+## 18. Обновление пользователя
 
 При обновлении:
 
 - PDA должна существовать;
-- `login`, `created_at_ms`, `root_key` не меняются;
+- `login`, `created_at_ms`, `recovery_key`, `root_key`, `client_key` не меняются;
 - `record_number = previous_record_number + 1`;
 - `prev_record_hash` равен хэшу unsigned-части предыдущей записи;
 - `updated_at_ms` обновляется;
@@ -388,7 +408,7 @@ Solana-программа проверяет подпись через встр
 - при увеличении оплаченного лимита пользователь доплачивает комиссию;
 - Arweave `tx_id` может быть пустым или обновленным, но его содержимое Solana не валидирует.
 
-## 18. Отличия от старого линейного формата
+## 19. Отличия от старого линейного формата
 
 Старый формат после `login` хранил поля линейно:
 
@@ -396,8 +416,8 @@ Solana-программа проверяет подпись через встр
 - `root_key`;
 - `blockchain_key_status`;
 - `blockchain_key`;
-- `device_key_status`;
-- `device_key`;
+- `client_key_status`;
+- `client_key`;
 - `chain_number`;
 - `balance`;
 - серверные поля;
@@ -408,17 +428,54 @@ Solana-программа проверяет подпись через встр
 
 Новый целевой формат сохраняет первые 9 фиксированных полей как заголовок, но дальше переходит на типизированные блоки:
 
+- recovery-ключ становится отдельным обязательным блоком;
 - ключи становятся отдельными блоками;
 - данные блокчейна становятся расширенным блоком со своим публичным ключом, лимитом, занятым размером, вершиной цепочки и Arweave `tx_id`;
 - серверные данные и access-серверы отделяются от данных блокчейна;
 - расширение формата делается добавлением новых версий блоков или новых `block_type`, а не вставкой полей в середину линейной записи.
 
-## 18. Что пока не входит в формат
+## 20. Деривация ключей из master secret
+
+Сама Solana-программа не вычисляет ключи из секрета и не хранит приватные ключи. Но текущая согласованная клиентская схема деривации для публичной версии формата фиксируется здесь как reference для UI/ESP32/внешних клиентов.
+
+Базовая формула:
+
+```text
+seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || suffix_utf8)
+```
+
+Где:
+
+- `master_secret32` — 32-байтовый master secret пользователя;
+- `suffix_utf8` — строка назначения ключа.
+
+Согласованные suffix:
+
+```text
+"recovery.key"
+"root.key"
+"blockchain.key"
+"client.key"
+```
+
+Соответствие:
+
+```text
+recovery.seed   = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "recovery.key")
+root.seed       = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "root.key")
+blockchain.seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "blockchain.key")
+client.seed     = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || "client.key")
+```
+
+Далее каждая строка `seed` интерпретируется off-chain как `seed32` для отдельной пары Ed25519.
+
+## 21. Что пока не входит в формат
 
 Пока не проектируем:
 
+- ротацию `recovery_key`;
 - ротацию `root_key`;
-- сложную ротацию `device_key`;
+- сложную ротацию `client_key`;
 - ротацию `blockchain_public_key`;
 - проверку содержимого Arweave transaction;
 - хранение полной истории пользовательского блокчейна внутри Solana;