Files
SHiNE-server/shine-solana/shine/doc/programs/shine_users.md
T

187 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Программа `shine_users`
Актуальный пользовательский формат — `user_pda 1.2`.
Полный бинарный формат: `doc/formats/shine-user-pda-format-v.1.2.md`.
Legacy 1.0 считается тестовым и не мигрируется.
## Что хранит программа
- `root_key` — cold recovery authority;
- `client_key`;
- append-only список blockchain fork keys с временем создания и оплаченной квотой;
- один optional server address;
- ноль или один access server;
- `record_number`, `prev_record_hash` и переносимую Ed25519-подпись состояния.
Пользовательские SHiNE-блоки/Arweave этим патчем не меняются.
## Инструкции
### `1 init_users_economy_config`
Без изменений.
### `2 update_users_economy_config`
Меняется **только** право доступа: текущая upgrade authority из ProgramData данного `shine_users`, а не статическая DAO-константа. Accounts: `signer writable?` (signer), `users_economy_config_pda writable`, `program read-only executable`, `programdata read-only`. `init` (opcode 1) остаётся доступным любому подписанту один раз.
### `3 create_user_pda` — новая V2-инструкция
**Важно для развёртывания:** этот патч изменяет экономику `create_user_pda`, но не wire-формат и не список account metas. Обновление on-chain программы `shine_users` должно предшествовать выкладке UI с новой формулой. Старый контракт списывает депозит PDA поверх цены namespace, новый — внутри неё. Ни тестирование, ни публикация программы в сеть не входят в подготовку патча.
```text
tag:u8 = 3
login:string_u8 // исходный регистр localpart, lowercase namespace, <= 30 байт
root_key:[32]
created_at_ms:u64 LE // новая Solana дата в пределах +-5 мин
additional_limit:u64 LE // кратно LIMIT_STEP
client_key:[32]
blockchain_key:[32]
address_count:u8 // 0 или 1
[address] // type:u8, version:u8, address:string_u8
access_server_count:u8 // 0 или 1
[access_server:string_u8]
record_signature:[64] // подпись текущего blockchain-key, сохраняется в PDA
registrar_signature_present:u8 // 0 для type 1, 1 для type 2
[registrar_signature:[64]] // только type 2, внутренняя подпись сертификата
```
Accounts в неизменном порядке:
1. `payer` — signer, writable;
2. `user_pda` — writable (SHA-256 нормализованного полного логина);
3. `system_program` — read-only;
4. `shine_payments` inflow vault — writable;
5. `sysvar::instructions` — read-only;
6. `users_economy_config_pda` — **read-only**;
7. `namespace_pda` — read-only, owner `shine_users`.
Проверки: namespace реально существует в программе, `localPart >= min_localpart_len`, общая длина <= 30, localpart допускает ASCII `[A-Za-z0-9_]+`, namespace остаётся ASCII lowercase `[a-z0-9_]+`, PDA соответствует `SHA256("user_login="+ASCII-lowercase(fullLogin))`, схема v1.2, root и blockchain Ed25519 proof-of-possession. Цена создания PDA для подписанта (без комиссии самой сети) = `namespace.registration_fee + additional_limit/LIMIT_STEP * economy.lamports_per_limit_step`.
На создание PDA направляется `top_up = max(0, Rent::minimum_balance(USER_PDA_SPACE) - user_pda.lamports())`, сумма `namespace.registration_fee - top_up` переводится в существующий `shine_payments` vault. Оплата дополнительного лимита направляется в тот же vault полностью. Схема учитывает заранее пополненный system-owned адрес PDA: подписант платит **ровно цену namespace** за регистрацию вне зависимости от ранее зачисленных lamports; их наличие уменьшает top-up и увеличивает остаток, направляемый в vault.
Если `namespace.registration_fee < Rent::minimum_balance(USER_PDA_SPACE)`, транзакция отклоняется независимо от заранее внесённых lamports ошибкой `RegistrationFeeBelowRent` (код 45). Сетевая комиссия Solana оплачивается подписантом **сверх** цены namespace; её определяет сеть, она не переводится в vault. Цену можно изменить только отдельной инструкцией `8 update_namespace_price` по подписи текущей upgrade authority. Код валюты проверяется: пока разрешён лишь `1=SOL`; пересчёт в USD/USDT не реализован. На create сохраняется существующая схема starter quota из economy-PDA: при переходе free→paid внешняя БД обязана учесть уже использованный бонус и не выдать его снова.
**Ed25519 инструкции перед opcode 3 (строго непосредственно):**
- Тип 1: `[root_verify(unsigned_hash), blockchain_verify(unsigned_hash), create_user]`; смещения `-2`, `-1`.
- Тип 2: `[registrar_verify(inner_message), root_verify(unsigned_hash), blockchain_verify(unsigned_hash), create_user]`; смещения `-3`, `-2`, `-1`.
Всем проверкам нужны именно требуемые `pubkey`, `message`, а blockchain также сопоставляется с `record_signature`. Проверка сертификата использует `registrar_pubkey` **из указанного namespace-PDA**, а не ключ клиента. Порядок байтов inner message см. `docs/Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md`. Solana подтверждает право создать PDA, но не утверждает успешную публикацию сертификата в Arweave.
**Upgrade free→paid** — тот же opcode 3 на том же полном логине и публичных ключах. Старые приватные ключи клиента не раскрываются; сохранение исходных публикаций обеспечивают синхронизатор/сервер (не Solana). Дата создания on-chain PDA может быть новой. Повторное создание PDA отвергается.
### `4 update_user_pda`
Работает только с PDA 1.2. Для нового `login@namespace` ищет SHA-256 PDA; для существующего старого логина без `@` сохраняет прежнюю схему `[b"user_login=", lowercase_login]`, чтобы не блокировать прежние аккаунты. Оплата дополнительных лимитов и авторизация обновлений не меняются.
```text
tag:u8 = 4
login:string_u8
new_root_key:[32]
updated_at_ms:u64
additional_limit:u64
new_client_key:[32]
auth_mode:u8 // 0 blockchain, 1 root
new_blockchain_present:u8
[new_blockchain_key:[32]]
address_count:u8 // 0 или 1
[address]
access_server_count:u8 // 0 или 1
[access_server]
record_signature:[64]
```
Программа сама вычисляет `record_number=old+1` и `prev_record_hash`.
`updated_at_ms` должен быть в пределах ±5 минут от Solana Clock.
Перед update идут две Ed25519 instructions по hash нового unsigned state:
1. старый authority разрешает переход;
2. authority нового состояния подписывает запись; эта подпись сохраняется в PDA.
Blockchain-mode:
- используется для всех обычных update;
- старый authority = последний blockchain key;
- `signature[64]` нового состояния = активный blockchain key либо новый blockchain key, если добавляется fork;
- root/client менять нельзя;
- новый fork — только после 72 часов от времени активного fork.
Root-mode:
- допустим только для recovery/полной ротации ключей;
- старый authority = текущий root;
- полная ротация одной транзакцией меняет `root_key`, `client_key` и добавляет новый blockchain fork;
- transition-подпись делает старый root, а `signature[64]` нового состояния делает новый blockchain key;
- recovery fork может обходить 72-часовой cooldown;
- смена root без одновременной смены client key и добавления нового blockchain fork отклоняется.
Обе Ed25519-подписи проверяются по одному и тому же hash нового unsigned PDA state, поэтому новые root/client/blockchain public keys входят в подписываемое состояние.
### `5` — зарезервированная старая promo instruction
В V2 диспетчер не исполняет opcode 5. Новая регистрация не обращается в `shine_login_guard`, не использует promo seller и premium классы. Исторические standalone программы не удалялись.
### `6 close_legacy_pda`
Временная cleanup-инструкция для тестовых PDA 1.0.
```text
tag:u8 = 6
login:string_u8
```
Accounts:
1. caller signer + writable;
2. legacy user PDA writable.
Программа проверяет PDA seed/owner и `format=1.0`, переводит все lamports PDA вызывающему и обнуляет account data. PDA 1.2 этой инструкцией закрыть нельзя.
### `7 create_namespace`
```text
tag:u8=7
namespace_type:u8 // 1 paid-direct / 2 free-cert
min_localpart_len:u8
namespace:string_u8
registration_fee:u64 LE
[if type=2: registrar_pubkey:[32]; server_login:string_u8]
```
Accounts: `payer signer writable`, `namespace_pda writable`, `system_program read-only`, `economy_pda read-only`, `shine_users program executable read-only`, `shine_users ProgramData read-only`; **только type=2** — `registered_access_server_user_pda` (read-only) настоящего зарегистрированного сервера с ServerProfile.
Проверки: точный PDA по 32-байтному SHA-256 seed `namespace=NAME`, owner, пустой system PDA, на создание пишется версия 1.1 с `currency_code=1`, длина имени, тип, поля регистратора; economy валиден и read-only; `ProgramData` строго относится к этому исполняемому program ID и `upgrade_authority=Some(signer)`. У immutable программы создание запрещено; цену можно обновлять только opcode 8, удалить/переименовать namespace нельзя. Отдельная документация: `doc/formats/shine-namespace-pda-format-v1.md`.
## BlockchainRegistry 1.2
```text
fork_count:u16
forks[]:
blockchain_key:[32]
created_at_ms:u64
paid_limit_bytes:u32
```
Последний fork активный. Старые записи неизменяемы.
## Server/access limits в 1.2
Бинарный формат использует count/arrays для forward compatibility, но текущая программа намеренно ограничивает:
- `ServerProfileBlock`: один адрес;
- `AccessServersBlock`: 0 или 1 сервер доступа.
Позже лимиты можно увеличить без изменения структуры блоков.
### Регистронезависимая идентичность (28.10.2026)
Локальная часть полного `login@namespace` допускает латинские буквы `A–Z` и `a–z`, цифры и `_`; `namespace` допускает только нижний ASCII-регистр. Выбранный при регистрации регистр логина неизменяем. Адрес user PDA вычисляется по `SHA256(UTF8("user_login=" + ASCII-lowercase(fullLogin)))` и bump для `find_program_address`. Сама запись PDA 1.2 содержит **оригинальное** написание `login`; подписи записи и регистраторского сертификата проверяются по исходному регистру без нормализации. Это изменение правила seed, не бинарного формата PDA.
### `8 update_namespace_price` — настройка цены пространства имён
Формат: `tag=8; namespace:string_u8; currency_code:u8; registration_fee:u64LE`. Код `1` = SOL, код `2` зарезервирован для USDT и **отвергается** (`UnsupportedNamespaceCurrency=46`). Цена `registration_fee` в lamports включает rent user PDA, без комиссии транзакции.
Accounts: signer/current upgrade authority writable, namespace PDA writable, system program read-only, economy PDA read-only, `shine_users` executable read-only, ProgramData read-only. Проверяется реальная текущая upgrade authority, а не ключ по умолчанию. У старого namespace 1.0 цена обновляется с миграцией бинарной записи до v1.1 и возможной доплатой rent за 1 байт. Изменение полей registrar/server/type не допускается.
Синхронизатор получает новую цену по истории economy PDA с разбором opcode 8 и чтением обновлённого namespace PDA. Новые регистрации в обоих сценариях всегда проверяют стоимость по on-chain namespace непосредственно перед отправкой транзакции.