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

shine-solana/shine/doc/programs/shine_users.md

@@ -154,11 +154,13 @@ system-переводом. Если бы создание шло строго ч
 
 ## 6. Ключи и подписи
 
-В записи участвуют три ключевых роли:
+В записи участвуют четыре ключевых роли:
 
+- `recovery_key`
+  - публичный recovery-ключ пользователя для будущих сценариев восстановления;
 - `root_key`
   - корневая подпись самой записи;
-- `device_key`
+- `client_key`
   - текущий плательщик и signer транзакции create/update;
 - `blockchain_public_key`
   - ключ подтверждения вершины пользовательского SHiNE-блокчейна.
@@ -176,11 +178,26 @@ system-переводом. Если бы создание шло строго ч
 - PKCS#8 контейнеры;
 - PEM;
 - способ хранения приватного ключа на клиенте;
-- откуда клиент извлёк `seed32` для `device_key`.
+- откуда клиент извлёк `seed32` для `client_key`.
 
 ### 6.2. Практика клиентской генерации ключей
 
-Off-chain клиентская логика может хранить приватные ключи в PKCS#8 и извлекать `seed32` для `device`-signer. Это допустимая клиентская реализация, но не часть on-chain формата.
+Off-chain клиентская логика может хранить приватные ключи в PKCS#8 и извлекать `seed32` для `client`-signer. Это допустимая клиентская реализация, но не часть on-chain формата.
+
+Согласованная клиентская схема деривации для первой публичной версии:
+
+```text
+seed = SHA-256("SHiNE-key" || 0x00 || master_secret32 || 0x00 || suffix_utf8)
+```
+
+Согласованные suffix:
+
+```text
+"recovery.key"
+"root.key"
+"blockchain.key"
+"client.key"
+```
 
 On-chain инвариант только один:
 
@@ -277,16 +294,16 @@ On-chain инвариант только один:
 
 Плательщик транзакции и signer инструкции:
 
-- `device_key`
+- `client_key`
 
 Это принципиальное правило:
 
 - `root_key` только подписывает запись;
-- `device_key` оплачивает rent/fees/registration flow.
+- `client_key` оплачивает rent/fees/registration flow.
 
 ### Аккаунты
 
-- signer = `device_key`
+- signer = `client_key`
 - `user_pda`
 - system program
 - inflow vault PDA из `shine_payments`
@@ -297,6 +314,7 @@ On-chain инвариант только один:
 ### Входные данные
 
 - логин
+- `recovery_key`
 - `root_key`
 - `created_at_ms`
 - `additional_limit`
@@ -308,6 +326,7 @@ On-chain инвариант только один:
 ```text
 - tag: u8 = 3
 - login: string_u8
+- recovery_key: [u8; 32]
 - root_key: [u8; 32]
 - created_at_ms: u64 LE
 - additional_limit: u64 LE
@@ -368,13 +387,13 @@ limit_fee(additional_limit) = (additional_limit / LIMIT_STEP) * lamports_per_lim
 
 Те же роли:
 
-- signer/fee payer = `device_key`
+- signer/fee payer = `client_key`
 - подпись записи = `root_key`
 - подпись вершины блокчейна = `blockchain_public_key`
 
 ### Аккаунты
 
-- signer = `device_key`
+- signer = `client_key`
 - `user_pda`
 - system program
 - inflow vault PDA из `shine_payments`
@@ -386,17 +405,19 @@ limit_fee(additional_limit) = (additional_limit / LIMIT_STEP) * lamports_per_lim
 1. PDA существует и принадлежит `shine_users`.
 2. Новый логин совпадает со старым.
 3. `created_at_ms` совпадает со старым.
-4. `root_key` совпадает со старым.
-5. `version = old.record_number + 1`.
-6. `prev_hash = hash(unsigned_old_record)`.
-7. `additional_limit % LIMIT_STEP == 0`.
-8. `blockchain_name` и `blockchain_public_key` не меняются.
-9. `paid_limit_bytes` не уменьшается.
-10. `used_bytes` не уменьшается.
-11. `last_block_number` не уменьшается.
-12. Если состояние блокчейна изменилось, `last_block_signature` заново проверяется через Ed25519.
-13. Новая unsigned часть записи подписана `root_key`.
-14. При необходимости PDA может быть расширена через realloc.
+4. `recovery_key` совпадает со старым.
+5. `root_key` совпадает со старым.
+6. `client_key` совпадает со старым.
+7. `version = old.record_number + 1`.
+8. `prev_hash = hash(unsigned_old_record)`.
+9. `additional_limit % LIMIT_STEP == 0`.
+10. `blockchain_name` и `blockchain_public_key` не меняются.
+11. `paid_limit_bytes` не уменьшается.
+12. `used_bytes` не уменьшается.
+13. `last_block_number` не уменьшается.
+14. Если состояние блокчейна изменилось, `last_block_signature` заново проверяется через Ed25519.
+15. Новая unsigned часть записи подписана `root_key`.
+16. При необходимости PDA может быть расширена через realloc.
 
 ### Экономика
 
@@ -413,6 +434,7 @@ topup_fee = limit_fee(additional_limit)
 ```text
 - tag: u8 = 4
 - login: string_u8
+- recovery_key: [u8; 32]
 - root_key: [u8; 32]
 - created_at_ms: u64 LE
 - updated_at_ms: u64 LE
@@ -461,7 +483,6 @@ signature = Ed25519(blockchain_private_key, message_hash)
 
 Программа допускает обновление:
 
-- `device_key`
 - `used_bytes`
 - `last_block_number`
 - `last_block_hash`
@@ -479,7 +500,9 @@ signature = Ed25519(blockchain_private_key, message_hash)
 
 - `login`
 - `created_at_ms`
+- `recovery_key`
 - `root_key`
+- `client_key`
 - `blockchain_name`
 - `blockchain_public_key`
 - `blockchain_type`
@@ -489,7 +512,7 @@ signature = Ed25519(blockchain_private_key, message_hash)
 ### UserMutableFieldsV1
 
 ```text
-- device_key: [u8; 32]
+- client_key: [u8; 32]
 - blockchain_public_key: [u8; 32]
 - blockchain_name: string_u8
 - used_bytes: u64 LE