167 lines
11 KiB
Markdown
167 lines
11 KiB
Markdown
# Архитектура 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` | `3bYrnXwLc56oVPUBAjY8zTMLwHCYq29b5rUMu3b64SQJ` |
|
||
| `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)
|