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

7.6 KiB
Raw Blame History

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 — запись на сервере служит только кэшем/первичным отображением.