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

42 lines
5.0 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–3**, не развёрнута; формат предложен как протокол V1. Перед деплоем обязательна компиляция Rust и тесты localnet/devnet.
## Идентичность и адреса
- `login@namespace`: строго ASCII 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, байтовая раскладка
| Смещение | Значение | Байты |
|---|---|---:|
| 0 | major=1 | 1 |
| 1 | minor=0 | 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) | 8 |
| только type=2 | registrar_pubkey: Ed25519 | 32 |
| только type=2 | server_login_len: u8; server_login в формате `login@namespace` | 1+N |
**Размер аккаунта ровно соответствует сериализованному размеру. Padding в namespace-PDA отсутствует.** Десериализатор отвергает лишние/недостающие байты, неверные версии, неизвестные типы, пустые/невалидные имена, несоответствие PDA, owner, namespace. В type=1 НЕ существует дополнительных нулевых полей. В type=2 оба поля обязательны. Цена допускает `0` для тестового namespace; защищённый signer authority выбирает значение до создания аккаунта. Изменение или удаление namespace пока отсутствует.
## Полномочия и создание
Создавать 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 (здесь недоступно).
Детерминированные приватные ключи, которыми построены фикстуры, **никогда не использовать** как настоящие ключи пользователей/регистратора.