# 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 в том же коммите.
- Язык кода и комментариев: русский.