SHiNE-server/Dev_Docs/Solana_Architecture

Архитектура 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.svg
• 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	m48pWRGWrMj3TEHjuU4zsp5Gju4e7ZaPovk8RcVt7kR

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

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_users.md
• details/shine_payments.md
• details/shine_dao.md
• details/accounts_and_money_flow.md