# Архитектура Solana-программ SHiNE Документ описывает архитектуру трёх Solana-программ SHiNE, DAO, ключи управления, PDA-счета и движение денег. Текущие `shine_users` и `shine_payments` имеют собственный обработчик инструкций на Rust; не следует считать все три программы Anchor-программами. Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE. Статус: обзорная справка. Состав инструкций `shine_users`, program ID и seed сверен с кодом; экономические сценарии и фактическое состояние развёрнутых программ требуют отдельной проверки в сети. Связанные документы: - `docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей. - `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md` — текущий формат `user_pda` для `shine_users`; версия v1.0 сохранена как историческая. - `shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md` — формат namespace PDA. - `shine-solana/shine/doc/FUNDS_FLOW.md` — справка по денежным потокам внутри Solana-модуля. ## Кратко В Solana-модуле сейчас три основные программы: 1. `shine_login_guard` — в текущем временном режиме проверяет базовую валидность логина и пропускает on-chain любые валидные логины длиной от 5 символов. 2. `shine_users` — создаёт namespace и пользовательские PDA, проверяет подписи и обрабатывает оплату регистрации/увеличения лимита. В коде есть платный путь через Solana и upgrade бесплатного сертификата. 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` | Временная on-chain проверка логина перед регистрацией. | | 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_namespace`, `create_user_pda`, `update_user_pda`, `close_legacy_user_pda` | Namespace, регистрация, обновление записи и экономика лимита. | | 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 Program ID в этом checkout заданы в `Anchor.toml` и `declare_id!` программ. Дополнительные константы и адреса в UI/сервере проверяйте по инструкции инициализации: | Программа | Program ID | | --- | --- | | `shine_login_guard` | `SHiGxGsXGioQYCYhchQ5R7KWoxN5UjFAFsucPf6sfnh` | | `shine_users` | `SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6` | | `shine_payments` | `SHiPmXbM9Fs9khzRUW3TGKsS2W84aqaXTxs3ZkajW9v` | Если эти адреса меняются, нужно синхронно обновить: 1. `shine-solana/shine/Anchor.toml` 2. `declare_id!` в `programs/*/src/lib.rs` 3. константы и настройки UI/сервера, перечисленные в `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`. Для отдельных программ зависимости от ID других программ задаются в их исходниках и настройках; например ID `shine_payments` указан в `programs/shine_users/src/settings.rs`. Перед сменой адреса нужно искать все ссылки в коде и конфигурации. ## Счета и PDA Постоянные PDA и счета: 1. `shine_users` - `user_pda` — пользовательская запись по хэшу от `user_login=`; точный seed определён в `programs/shine_users/src/settings.rs` и `user_pda_seed()`. - `namespace_pda` — запись namespace по хэшу от `namespace=`. - `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. Скрипты основного server/UI deploy из `deploy/scripts/` не должны деплоить Anchor-программы. Solana build/deploy выполняется отдельно из папки `shine-solana/shine/` по локальным правилам модуля. ## Движение денег Основные потоки: 1. Регистрация пользователя через `shine_users::create_user_pda`. - Платит `signer`. - `namespace.registration_fee` — **полная цена регистрации**, включающая депозит PDA. - Часть цены идёт на создание пользовательского PDA; остаток поступает в `shine_payments::inflow_vault_pda`. - Оплата дополнительного лимита (если запрошен) начисляется отдельно и поступает в vault. - Комиссия транзакции Solana оплачивается кошельком `signer` поверх цены namespace; она не поступает проекту. Если цена namespace ниже необходимого депозита 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)