SHA256
158 lines
7.5 KiB
Markdown
158 lines
7.5 KiB
Markdown
# `shine_users`
|
||
|
||
## Кратко
|
||
|
||
`shine_users` — вторая программа Solana-модуля SHiNE. Она отвечает за создание и обновление пользовательской PDA-записи, проверку подписи записи, проверку логина через `shine_login_guard` и оплату регистрации/дополнительного лимита.
|
||
|
||
Папка программы: `shine-solana/shine/programs/shine_users/`.
|
||
|
||
## Текущие функции
|
||
|
||
1. `init_users_economy_config`
|
||
- Создает PDA с экономическими настройками пользователей.
|
||
- Записывает стартовую регистрационную комиссию, цену шага лимита и стартовый бонус лимита.
|
||
|
||
2. `update_users_economy_config`
|
||
- Обновляет экономические настройки.
|
||
- Требует подпись `DAO_AUTHORITY` из общего deploy-конфига.
|
||
|
||
3. `create_user_pda`
|
||
- Проверяет логин через `shine_login_guard`.
|
||
- Проверяет структуру полей пользователя.
|
||
- Проверяет подпись записи root-ключом пользователя.
|
||
- Создает `user_pda` по seed `login=<normalized_login>`.
|
||
- Переводит оплату регистрации и дополнительного лимита в `shine_payments::inflow_vault_pda`.
|
||
|
||
4. `update_user_pda`
|
||
- Проверяет неизменяемые поля пользователя.
|
||
- Проверяет `prev_hash`, новую подпись и новое состояние последнего блока.
|
||
- При необходимости расширяет PDA.
|
||
- Переводит оплату дополнительного лимита в `shine_payments::inflow_vault_pda`.
|
||
|
||
## Аргументы инструкций
|
||
|
||
`init_users_economy_config` аргументов не принимает.
|
||
|
||
`update_users_economy_config`:
|
||
|
||
- `registration_fee_lamports: u64`
|
||
- `lamports_per_limit_step: u64`
|
||
- `start_bonus_limit: u64`
|
||
|
||
`create_user_pda`:
|
||
|
||
- `login: String`
|
||
- `root_key: Pubkey`
|
||
- `created_at_ms: u64`
|
||
- `additional_limit: u64`
|
||
- `fields: UserMutableFields`
|
||
- `signature: Vec<u8>`
|
||
|
||
`update_user_pda`:
|
||
|
||
- `login: String`
|
||
- `root_key: Pubkey`
|
||
- `created_at_ms: u64`
|
||
- `updated_at_ms: u64`
|
||
- `version: u32`
|
||
- `prev_hash: Vec<u8>`
|
||
- `additional_limit: u64`
|
||
- `fields: UserMutableFields`
|
||
- `signature: Vec<u8>`
|
||
|
||
`UserMutableFields`:
|
||
|
||
- `client_key: Pubkey`
|
||
- `blockchain_public_key: Pubkey`
|
||
- `blockchain_name: String`
|
||
- `used_bytes: u64`
|
||
- `last_block_number: u32`
|
||
- `last_block_hash: Vec<u8>` — ровно 32 байта
|
||
- `last_block_signature: Vec<u8>` — ровно 64 байта
|
||
- `arweave_tx_id: String`
|
||
- `is_server: bool`
|
||
- `server_key: Pubkey`
|
||
- `server_address: String`
|
||
- `sync_servers: Vec<String>`
|
||
- `access_servers: Vec<String>` — формат остаётся массивом, но runtime
|
||
использует только первый элемент
|
||
- `trusted_count: u8`
|
||
|
||
## Главные PDA
|
||
|
||
1. `user_pda`
|
||
- PDA записи пользователя.
|
||
- Seed: `login=<normalized_login>`.
|
||
- Создается отдельно для каждого логина.
|
||
- Стартовый размер: `768` байт.
|
||
- При обновлении может расширяться через `realloc`, но один auto-realloc ограничен `10_000` байт.
|
||
|
||
2. `users_economy_config_pda`
|
||
- PDA с настройками экономики.
|
||
- Seed: `shine_users_economy_config`.
|
||
- Хранит регистрационную комиссию, цену шага лимита и стартовый бонус.
|
||
- Размер PDA: `8 + 96` байт.
|
||
|
||
## Текущие параметры экономики
|
||
|
||
Параметры initial config из `programs/shine_users/src/settings.rs`:
|
||
|
||
| Поле | Значение | Смысл |
|
||
| --- | --- | --- |
|
||
| `START_REGISTRATION_FEE_LAMPORTS` | `10_000_000` | стартовая комиссия регистрации, 0.01 SOL |
|
||
| `LIMIT_STEP` | `10_000` | шаг `additional_limit` |
|
||
| `START_LAMPORTS_PER_LIMIT_STEP` | `100_000` | 0.0001 SOL за один шаг лимита |
|
||
| `START_BONUS_LIMIT` | `100_000` | стартовый бесплатный лимит при регистрации |
|
||
|
||
`additional_limit` в create/update должен быть кратен `LIMIT_STEP`.
|
||
|
||
## Связь с другими программами
|
||
|
||
`shine_users` зависит от:
|
||
|
||
- `shine_login_guard` — для проверки логина при создании пользователя;
|
||
- `shine_payments` — для вычисления и проверки `inflow_vault_pda`, куда уходят платежи.
|
||
|
||
`create_user_pda` делает CPI-вызов `shine_login_guard::classify_login` и принимает только результат `0`. Premium/trademark логины сейчас отклоняются ошибками `PremiumLogin` или `TrademarkLoginRequiresReview`.
|
||
|
||
Подпись `user_pda` и подпись состояния последнего блока проверяются через встроенную Solana Ed25519-инструкцию, которая должна идти раньше инструкции `shine_users` в той же транзакции.
|
||
|
||
## Деньги
|
||
|
||
Деньги из `shine_users` идут только в `inflow_vault_pda` программы `shine_payments`.
|
||
|
||
Потоки:
|
||
|
||
- `create_user_pda`: регистрационная комиссия + оплата `additional_limit`;
|
||
- `update_user_pda`: оплата `additional_limit`, если она больше нуля.
|
||
|
||
## Ключи и управление
|
||
|
||
На старте удобно считать, что у программы есть отдельный управляющий ключ `key_2`.
|
||
|
||
Целевая модель:
|
||
|
||
- economy-настройки меняет DAO-authority;
|
||
- upgrade-authority программы после проверки передается DAO;
|
||
- пользовательские операции `create_user_pda` и `update_user_pda` остаются доступными обычным пользователям при корректных подписях и оплате.
|
||
|
||
## ArchiveHeadBlock и серверный SHINE-ARCHIVE
|
||
|
||
Формат User PDA поддерживает необязательный `ArchiveHeadBlock` (`block_type = 100`, `block_version = 0`):
|
||
|
||
```text
|
||
archive_tx_id [32]
|
||
archive_hash [32]
|
||
```
|
||
|
||
Он хранит текущую голову архива конкретного SHiNE-аккаунта: raw Arweave TX ID и SHA-256 соответствующего большого `SHINE-ARCHIVE`. Подробный бинарный формат и серверный workflow находятся в `docs/Archive/01_PROTOCOL_v1.0.md`.
|
||
|
||
Отдельной инструкции программы для архива нет. Используется существующий `update_user_pda`. Парсер update instruction обратно совместим:
|
||
|
||
- legacy payload без archive extension сохраняет старый block `100`;
|
||
- новый payload может заменить/очистить archive head;
|
||
- итоговая полная User PDA запись, включая block `100`, покрывается обычной root-подписью.
|
||
|
||
Это позволяет обычным старым клиентским обновлениям профиля не стирать archive head серверного publisher-а.
|
||
|