# `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`:

- `device_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>`
- `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` остаются доступными обычным пользователям при корректных подписях и оплате.