Aidar/SHiNE-server
SHA256
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
2bd38d8d78
SHiNE-server/Dev_Docs/Solana_Architecture
History
AidarKC b461431197 Смена адреса shine_users и выкладка на test2
2026-06-23 10:40:52 +04:00
..
details Смена адреса shine_users и выкладка на test2 2026-06-23 10:40:52 +04:00
schemes Миграция PDA на client.key 2026-06-22 21:57:09 +04:00
README.md Смена адреса shine_users и выкладка на test2 2026-06-23 10:40:52 +04:00

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.

Картинки:

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

Блок Папка/имя Текущие функции из кода Основной смысл
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

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

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