Files
SHiNE-server/shine-solana/shine/doc/programs/shine_users.md
T
AidarKC 94d4665185 Исправить регистрацию free-пользователей без учёта регистра
НЕ ПРОВЕРЕНО: учтены логины с большими и маленькими буквами.

Добавлен временный devnet-смарт-контракт для очистки тестового аккаунта от старых логинов; после сброса его необходимо удалить и восстановить штатный контракт.
2026-10-28 12:19:19 +03:00

177 lines
11 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-инструкция
**Внимание:** wire и account metas здесь уже несовместимы со старым UI. До завершения клиентского этапа №4 **НЕ DEPLOY** программу. Клиентский JS ещё не переписан.
```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. Цена = `namespace.registration_fee + additional_limit/LIMIT_STEP * economy.lamports_per_limit_step` в существующий `shine_payments` vault. На 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.0, длина имени, тип, поля регистратора; economy валиден и read-only; `ProgramData` строго относится к этому исполняемому program ID и `upgrade_authority=Some(signer)`. У immutable программы создание запрещено; изменить/удалить 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.