SHiNE-server/Dev_Docs/Solana_Architecture/README.md

# Архитектура Solana-программ SHiNE

Документ описывает рабочую архитектуру Solana-части SHiNE: три Anchor-программы, DAO, ключи управления, PDA-счета и движение денег.

Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.

Статус: актуализировано по коду `shine-solana/shine/programs/*` на 2026-05-25.

Связанные документы:

- `Dev_Docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей.
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` — точный формат `user_pda` для `shine_users`.
- `shine-solana/shine/doc/FUNDS_FLOW.md` — короткая справка по денежным потокам внутри Solana-модуля.

## Кратко

В Solana-модуле сейчас три основные программы:

1. `shine_login_guard` — проверяет логин и возвращает класс логина: обычный, premium или trademark.
2. `shine_users` — создает и обновляет пользовательскую PDA-запись, проверяет подписи и берет оплату за регистрацию/увеличение лимита.
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.

DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.

## Общая схема

Редактируемая Mermaid-схема находится в [schemes/architecture.mmd](schemes/architecture.mmd).

Картинки:

- [schemes/architecture.svg](schemes/architecture.svg)
- [schemes/architecture.png](schemes/architecture.png)

## Программы и функции

| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
| --- | --- | --- | --- |
| 1 | `shine_login_guard` | `classify_login` | Проверка логина перед регистрацией. |
| 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_user_pda`, `update_user_pda` | Регистрация пользователя, обновление записи, экономика лимита. |
| 3 | `shine_payments` | `init`, `update_coef_limit`, `grant_manager_limits`, `buy_ticket`, `buy_ticket_usd`, `buy_ticket_sol`, `manager_add_ticket`, `step_payout`, `change_ticket_recipient` | Vault, билеты, очереди, выплаты, DAO-настройки, лимиты менеджеров. |
| DAO | governance/authority | Вызовы через governance и управляющие ключи | Управление правами, казной, настройками и будущими обновлениями программ. |

## Актуальные program id

Актуальные адреса заданы одновременно в `Anchor.toml`, `declare_id!` программ и `programs/common/src/deploy_config.rs`:

| Программа | Program ID |
| --- | --- |
| `shine_login_guard` | `3xkopA7cXagxzMFrKdv3NCBfV6BKiRJCk69kr27M2sRo` |
| `shine_users` | `FZS1YctoeEhCkZ5VTjsysUFAXR8CqxYztcLboXcg2Rpm` |
| `shine_payments` | `c4yTa4JT9EtQDCBX9LmWFK6T2gp4JGsuymFbom2EudW` |

Если эти адреса меняются, нужно синхронно обновить:

1. `shine-solana/shine/Anchor.toml`
2. `declare_id!` в `programs/*/src/lib.rs`
3. `programs/common/src/deploy_config.rs`
4. UI/серверные константы, перечисленные в `Dev_Docs/Инициализация_Solana_регистрации/README.md`

## Ключи и authority

Для удобного понимания на старте можно считать, что есть четыре группы ключей:

1. `key_1` / authority программы `shine_login_guard`.
   - Сейчас программа только классифицирует логин.
   - На первом этапе ее можно оставить под отдельным ключом.
   - В будущем право обновления можно передать DAO.

2. `key_2` / authority программы `shine_users`.
   - Отвечает за деплой/upgrade второй программы.
   - Защищенное обновление economy-конфига в коде уже проверяет `DAO_AUTHORITY`.
   - В целевой модели upgrade-authority второй программы нужно передать DAO.

3. `key_3` / authority программы `shine_payments`.
   - Отвечает за деплой/upgrade третьей программы.
   - Защищенные методы `update_coef_limit` и `grant_manager_limits` проверяют `dao_wallet` из `ConfigState`.
   - В целевой модели upgrade-authority третьей программы нужно передать DAO.

4. DAO-ключи.
   - Это управляющие кошельки/токены/realm governance.
   - DAO может добавлять и отзывать управляющие ключи по голосованию.
   - DAO-казна получает деньги от покупки тикетов и DAO-часть выплат из `inflow_vault`.

Адреса program id сейчас берутся из `programs/common/src/deploy_config.rs`. Для production/devnet можно подбирать vanity-адреса с понятным началом вроде `SHi...`, но это отдельная операция генерации ключей и деплоя.

## Счета и PDA

Постоянные PDA и счета:

1. `shine_users`
   - `user_pda` — пользовательская запись по seed `login=<login>`, создается для каждого логина.
   - `users_economy_config_pda` — общие параметры экономики регистрации и лимита.

2. `shine_payments`
   - `config_pda` — хранит `dao_wallet` и адрес `inflow_vault`.
   - `coef_limit_pda` — хранит коэффициент выплат, лимит очереди и награду вызывающему `step_payout`.
   - `queues_pda` — агрегаты очередей выплат.
   - `inflow_vault_pda` — PDA-вольт, куда `shine_users` переводит оплату регистрации и увеличения лимита.
   - `ticket_pda` — отдельная PDA-запись тикета на каждую покупку/менеджерскую выдачу.
   - `manager_allowance_pda` — PDA лимитов конкретного менеджера.

3. DAO
   - `dao_wallet` / treasury — казна DAO.
   - governance-аккаунты DAO — realm, governance, proposal/vote records и связанные аккаунты SPL Governance, если используется эта модель.

## Правило разделения с основным сервером

Solana-модуль лежит в основном репозитории как отдельная папка `shine-solana/shine/`, но не подключается автоматически к сборке или деплою основного сервера SHiNE. Команды `deployServer` и `deployUI` не должны деплоить Anchor-программы. Solana build/deploy выполняется отдельно из папки `shine-solana/shine/` по локальным правилам модуля.

## Движение денег

Основные потоки:

1. Регистрация пользователя через `shine_users::create_user_pda`.
   - Платит `signer`.
   - Деньги идут в `shine_payments::inflow_vault_pda`.
   - Сумма состоит из регистрационной комиссии и оплаты дополнительного лимита.

2. Увеличение лимита через `shine_users::update_user_pda`.
   - Платит `signer`.
   - Деньги идут в тот же `inflow_vault_pda`.
   - Сумма равна оплате дополнительного лимита.

3. Покупка тикета через `shine_payments::buy_ticket*`.
   - Платит покупатель.
   - Деньги сразу идут в `dao_wallet`.
   - Одновременно создается тикет на выплату.

4. Выплата через `shine_payments::step_payout`.
   - Вызвать может любой подписант.
   - Деньги берутся из `inflow_vault_pda`.
   - Часть идет получателю тикета.
   - Часть идет в `dao_wallet`.
   - Небольшая награда идет вызвавшему шаг выплат.
   - Если очереди пустые, весь доступный остаток `inflow_vault_pda` переводится в DAO.

## Передача прав DAO

Минимальная целевая модель:

1. `shine_login_guard`
   - Пока оставить на отдельном ключе `key_1`.
   - Передачу DAO сделать позже, когда логика premium/trademark стабилизируется.

2. `shine_users`
   - Economy-настройки уже должны обновляться DAO-authority.
   - Upgrade-authority программы после проверки можно передать DAO.

3. `shine_payments`
   - DAO уже управляет настройками выплат и лимитами менеджеров через `dao_wallet`.
   - Upgrade-authority программы после проверки можно передать DAO.

4. DAO
   - Управляет казной.
   - Принимает решения голосованием.
   - Добавляет/отзывает управляющие ключи.
   - Вызывает защищенные методы второй и третьей программ.
   - В будущем может принять управление первой программой.

## Детальные файлы

- [details/shine_login_guard.md](details/shine_login_guard.md)
- [details/shine_users.md](details/shine_users.md)
- [details/shine_payments.md](details/shine_payments.md)
- [details/shine_dao.md](details/shine_dao.md)
- [details/accounts_and_money_flow.md](details/accounts_and_money_flow.md)