Files
SHiNE-server/docs/Solana_Architecture

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

Картинки:

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

Блок Папка/имя Текущие функции из кода Основной смысл
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=<login>; точный seed определён в programs/shine_users/src/settings.rs и user_pda_seed().
    • namespace_pda — запись namespace по хэшу от namespace=<name>.
    • 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

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

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