Актуализировать документацию и навигацию для агентов

This commit is contained in:
AidarKC
2026-11-05 22:50:31 +03:00
parent 3c6021a290
commit 4f8c2a72e9
31 changed files with 315 additions and 927 deletions
+12 -11
View File
@@ -1,23 +1,24 @@
# Архитектура Solana-программ SHiNE
Документ описывает рабочую архитектуру Solana-части SHiNE: три Anchor-программы, DAO, ключи управления, PDA-счета и движение денег.
Документ описывает архитектуру трёх Solana-программ SHiNE, DAO, ключи управления, PDA-счета и движение денег. Текущие `shine_users` и `shine_payments` имеют собственный обработчик инструкций на Rust; не следует считать все три программы Anchor-программами.
Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.
Статус: актуализировано по коду `shine-solana/shine/programs/*` на 2026-05-25.
Статус: обзорная справка. Состав инструкций `shine_users`, program ID и seed сверен с кодом; экономические сценарии и фактическое состояние развёрнутых программ требуют отдельной проверки в сети.
Связанные документы:
- `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-модуля.
- `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` — создает и обновляет пользовательскую PDA-запись, проверяет подписи и берет оплату за регистрацию/увеличение лимита.
2. `shine_users` — создаёт namespace и пользовательские PDA, проверяет подписи и обрабатывает оплату регистрации/увеличения лимита. В коде есть платный путь через Solana и upgrade бесплатного сертификата.
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.
DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.
@@ -36,13 +37,13 @@ DAO в текущем виде не является отдельной Anchor-
| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
| --- | --- | --- | --- |
| 1 | `shine_login_guard` | `classify_login` | Временная on-chain проверка логина перед регистрацией. |
| 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_user_pda`, `update_user_pda` | Регистрация пользователя, обновление записи, экономика лимита. |
| 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
Актуальные адреса заданы одновременно в `Anchor.toml`, `declare_id!` программ и `programs/common/src/deploy_config.rs`:
Program ID в этом checkout заданы в `Anchor.toml` и `declare_id!` программ. Дополнительные константы и адреса в UI/сервере проверяйте по инструкции инициализации:
| Программа | Program ID |
| --- | --- |
@@ -54,8 +55,7 @@ DAO в текущем виде не является отдельной Anchor-
1. `shine-solana/shine/Anchor.toml`
2. `declare_id!` в `programs/*/src/lib.rs`
3. `programs/common/src/deploy_config.rs`
4. UI/серверные константы, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
3. константы и настройки UI/сервера, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
## Ключи и authority
@@ -81,14 +81,15 @@ DAO в текущем виде не является отдельной Anchor-
- DAO может добавлять и отзывать управляющие ключи по голосованию.
- DAO-казна получает деньги от покупки тикетов и DAO-часть выплат из `inflow_vault`.
Адреса program id сейчас берутся из `programs/common/src/deploy_config.rs`. Для production/devnet можно подбирать vanity-адреса с понятным началом вроде `SHi...`, но это отдельная операция генерации ключей и деплоя.
Для отдельных программ зависимости от ID других программ задаются в их исходниках и настройках; например ID `shine_payments` указан в `programs/shine_users/src/settings.rs`. Перед сменой адреса нужно искать все ссылки в коде и конфигурации.
## Счета и PDA
Постоянные PDA и счета:
1. `shine_users`
- `user_pda` — пользовательская запись по seed `login=<login>`, создается для каждого логина.
- `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`
@@ -20,9 +20,9 @@
6. `manager_wallet` — кошелек менеджера, которому DAO выдает лимиты на создание тикетов.
7. `user root_key` — корневой ключ пользователя для подписи пользовательской записи.
8. `user client_key` — ключ устройства пользователя.
9. `server_key` — ключ сервера пользователя, если пользователь является сервером.
9. Серверный профиль пользователя публикует endpoint в `user_pda`; отдельной постоянной роли `server_key` в формате PDA 1.2 нет.
Текущие адреса из `programs/common/src/deploy_config.rs`:
Program ID сверяйте с `Anchor.toml` и `declare_id!` в исходниках программ; значения ниже приведены для ориентира. Для конфигурации деплоя используйте [инструкцию инициализации](../../Инициализация_Solana_регистрации/README.md):
| Роль | Адрес |
| --- | --- |
@@ -36,7 +36,8 @@
`shine_users`:
- `user_pda` — создается для каждого логина, seed `login=` + normalized login.
- `user_pda` — создаётся для каждого логина, seed вычисляется как SHA-256 строки `user_login=` + нормализованный логин.
- `namespace_pda` — запись namespace, seed вычисляется как SHA-256 строки `namespace=` + имя namespace.
- `users_economy_config_pda` — один PDA с экономикой регистрации, seed `shine_users_economy_config`.
`shine_payments`: