SHiNE-server/Dev_Docs/Solana_Architecture/details/shine_users.md

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