83 lines
5.2 KiB
Markdown
83 lines
5.2 KiB
Markdown
# AGENTS.md — shine-server-UI
|
||
|
||
## Назначение
|
||
|
||
`shine-server-UI/` — автономная веб-панель администратора для управления серверным аккаунтом SHiNE
|
||
в Solana (регистрация и обновление `user_pda` с флагом `is_server=true`).
|
||
|
||
Это не часть основного клиентского SPA (`shine-UI/`). Страницы — самостоятельные HTML-файлы,
|
||
открываемые напрямую в браузере. Никакого бэкенда нет.
|
||
|
||
## Структура файлов
|
||
|
||
```
|
||
shine-server-UI/
|
||
index.html — главная страница с навигацией
|
||
create-server-pda.html — регистрация нового серверного аккаунта
|
||
update-server-pda.html — обновление адреса/sync_servers существующей PDA
|
||
styles.css — тёмная тема
|
||
js/
|
||
server-pda-core.js — вся логика: парсинг PDA, Borsh, криптография, Solana
|
||
```
|
||
|
||
## Как пользоваться
|
||
|
||
### Регистрация сервера (`create-server-pda.html`)
|
||
|
||
Открыть страницу в браузере (требуется HTTPS для WebCrypto — локально либо через сервер).
|
||
|
||
Ввести:
|
||
- **Логин сервера** — уникальный логин в Solana (только a-z, 0-9, _ ; без точки ; макс. 20 символов).
|
||
- **Адрес сервера** — полный WebSocket/HTTP URL, например `https://shineup.me/ws`.
|
||
- **sync_servers** — логины SHiNE-аккаунтов серверов-партнёров (по одному на строку).
|
||
|
||
**Способ ввода ключей (переключатель):**
|
||
|
||
- **«Из пароля»** — ввести пароль. Ключи автоматически выводятся из логина + пароля
|
||
по той же схеме, что SHiNE-клиент (Argon2id + Ed25519). Занимает 2–5 сек.
|
||
На страницах сервера публичные и приватные ключи показываются в base58, приватный ключ
|
||
хранится как 32-байтовый seed в base58.
|
||
- **«JSON ключей»** — вставить keyBundle JSON с тремя парами (rootPair, devicePair, blockchainPair).
|
||
|
||
На **device-ключе** должно быть достаточно SOL для оплаты транзакции регистрации.
|
||
|
||
### Обновление настроек сервера (`update-server-pda.html`)
|
||
|
||
1. Ввести логин и нажать **«Загрузить PDA»** — страница прочитает существующую PDA из Solana и
|
||
покажет текущие данные.
|
||
2. Изменить адрес сервера или список sync_servers.
|
||
3. Выбрать способ ввода ключей:
|
||
- **«Из пароля»** — ввести пароль (логин берётся из поля выше);
|
||
- **«JSON ключей»** — вставить keyBundle (достаточно rootPair + devicePair).
|
||
Blockchain-ключ для обновления не нужен — существующая подпись из PDA переиспользуется.
|
||
При ручном вводе допустим base58 seed; если blockchain seed не указан, обновление
|
||
использует уже сохранённую подпись последнего блока.
|
||
4. Нажать **«Обновить PDA»**.
|
||
|
||
## Ключевой файл логики
|
||
|
||
`js/server-pda-core.js` — автономный ES-модуль (без зависимостей на shine-UI).
|
||
|
||
Экспортирует:
|
||
- `readServerPdaData({ login, solanaEndpoint })` — читает и парсит PDA из Solana;
|
||
- `registerServerOnSolana({ login, keyBundle, serverAddress, syncServers, ... })`;
|
||
- `updateServerOnSolana({ login, keyBundle, serverAddress, syncServers, ... })`;
|
||
- `parsePdaData(rawBytes)` — парсит бинарный формат PDA (matches Rust `deserialize_record_from_pda`).
|
||
|
||
## Связанные документы
|
||
|
||
- Формат PDA: `shine-solana/shine/doc/SHiNE-user-format-v.1.0.md`
|
||
- Деплой Solana-программ: `Dev_Docs/Инициализация_Solana_регистрации/README.md`
|
||
- Синхронизация между серверами: `Dev_Docs/Blockchain/sync-between-servers.md`
|
||
- Настройки сервера: `SHiNE-server/AGENTS.md`
|
||
|
||
## Правила при доработке
|
||
|
||
- Формат Borsh-аргументов в `server-pda-core.js` должен строго соответствовать
|
||
`UserMutableFields` в `shine-solana/shine/programs/shine_users/src/users.rs`.
|
||
- Бинарный формат PDA в `buildUnsignedRecordBytesServer` должен совпадать с
|
||
`serialize_unsigned_record` в Rust.
|
||
- При любом изменении формата Solana-программы (`users.rs`) — обновлять `server-pda-core.js`
|
||
и документ формата PDA в том же коммите.
|
||
- Язык кода и комментариев: русский.
|