Files
SHiNE-server/shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md
T

51 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SHiNE — Namespace PDA, бинарные форматы 1.0 и 1.1
Статус: **черновая реализация в объединённом патче этапов 1–3**, не развёрнута; формат предложен как протокол V1. Перед деплоем обязательна компиляция Rust и тесты localnet/devnet.
## Идентичность и адреса
- `login@namespace`: localpart допускает ASCII `[A-Za-z0-9_]+`, namespace только lowercase `[a-z0-9_]+`, ровно один `@`.
- Полная длина имени — не более **30 байт**; `min_localpart_len` из namespace. Никаких обрезаний, удаления `_`, автоматических преобразований регистра; некорректный ввод отвергается.
- Пользовательский PDA: `seed=SHA256(UTF8("user_login=" + fullLogin))`, **один seed из 32 сырых байт**; `findProgramAddress([seed], shine_users_program_id)`.
- Namespace PDA: `seed=SHA256(UTF8("namespace=" + namespace))`, **один seed из 32 сырых байт**; `findProgramAddress([seed], shine_users_program_id)`.
- `program_id` из тестовых векторов: `SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6`. При другой программе адреса PDA изменятся.
## NamespaceState 1.0/1.1, байтовая раскладка
| Смещение | Значение | Байты |
|---|---|---:|
| 0 | major=1 | 1 |
| 1 | minor=0 (исторический) либо minor=1 (актуальный) | 1 |
| 2 | namespace_type: 1 платный; 2 бесплатный сертификат | 1 |
| 3 | min_localpart_len: u8, не менее 1, вместе с названием укладывается в 30 байт | 1 |
| 4 | namespace_len: u8 | 1 |
| 5 | namespace: lowercase ASCII | namespace_len |
| следующий | registration_fee: u64 little-endian (lamports), для SOL это **вся цена регистрации** без сетевой комиссии | 8 |
| только minor=1 | currency_code: u8; **1=SOL**; **2 зарезервировано под USDT, сейчас запрещено** | 1 |
| только type=2 | registrar_pubkey: Ed25519 | 32 |
| только type=2 | server_login_len: u8; server_login в формате `login@namespace` | 1+N |
**Размер аккаунта ровно соответствует сериализованному размеру. Padding в namespace-PDA отсутствует.** Старые 1.0 записи продолжают читаться с `currency_code=1` по умолчанию. Новые namespace записываются сразу как 1.1; при первом update существующий 1.0 PDA увеличивается на 1 байт, а upgrade authority при необходимости доплачивает rent за расширение. Десериализатор отвергает лишние/недостающие байты, неверные версии, неизвестные типы, пустые/невалидные имена, несоответствие PDA, owner, namespace. В type=1 НЕ существует дополнительных нулевых полей. В type=2 оба поля обязательны. Цена допускает `0` для тестового namespace; защищённый signer authority выбирает значение до создания аккаунта. Изменение цены доступно текущей upgrade authority программой `shine_users` (opcode 8); rename, удаление и изменение типа namespace по-прежнему запрещены. Код `2` пока не поддержан ни для обновлений, ни для регистрации, курсовой пересчёт отсутствует.
## Полномочия и создание
Создавать namespaces может только **текущая upgrade authority именно этой программы**. Программа читает аккаунт самой программы (`UpgradeableLoaderState::Program`) и связанный с ним ProgramData, проверяет владельца upgradeable loader, совпадение programData address и `Some(upgrade_authority)` с фактическим подписантом. При immutable программе — отказ. Для type=2 обязательная дополнительная read-only мета с **настоящим PDA v1.2** указанного `server_login`, у записи должен быть ServerProfile адрес; сначала регистрируется сервер в платном namespace. Economy PDA должен существовать, передаётся read-only, чтобы транзакция находилась через его историю `getSignaturesForAddress`. Уведомление `accountSubscribe` только из-за read-only меты не гарантировано.
## Векторы и воспроизводимость
- `tests/fixtures/registration-v2.json` — полный вектор, включая реальные синтетические ANS-104 bytes.
- `tests/fixtures/registration-v2.properties` — общий простой формат для Rust/Java/JS.
- `node --test tests/registration-v2-vectors.test.mjs` — проверка в Node без npm.
- `javac --release 17 -d /tmp/shine-reg-v2 tests/java/RegistrationV2VectorsCheck.java && java -cp /tmp/shine-reg-v2 RegistrationV2VectorsCheck tests/fixtures/registration-v2.properties`.
- `cargo test --test registration_v2_vectors` — в Rust окружении с toolchain (здесь недоступно).
Детерминированные приватные ключи, которыми построены фикстуры, **никогда не использовать** как настоящие ключи пользователей/регистратора.
## Инструкция изменения цены (opcode 8)
`[8:u8, name:string_u8, currency_code:u8, registration_fee:u64LE]`. Имя namespace не изменяется, валюта обязана быть `1`, цена в lamports может меняться. Подпись — **текущей upgrade authority** из ProgramData `shine_users`, а не произвольного регистратора.
Порядок account metas: (1) signer/fee-payer writable signer; (2) namespace PDA writable; (3) system program read-only; (4) users economy PDA read-only (индексация синхронизатором); (5) shine_users Program read-only executable; (6) upgradeable ProgramData read-only. До записи программа сверяет PDA по имени и owner, проверяет полномочия, корректность economy PDA и currency code. При изменении старого формата — доплата rent и realloc +1 байт.
После confirmed-транзакции сервер-синхронизатор видит opcode 8 в истории `economy PDA`, читает **текущий** namespace PDA, применяет `UPSERT` к `shine_namespace_current` и обновляет `registration_fee_lamports`, `currency_code`, `slot`, `raw_data_base64`. Клиент непосредственно перед отправкой платёжной транзакции перечитывает namespace из Solana — запись на сервере служит только кэшем/первичным отображением.