Files
SHiNE-server/docs/registration-v2/MASTER_PLAN_V2_2026-10-23.md
T
AidarKC 94d4665185 Исправить регистрацию free-пользователей без учёта регистра
НЕ ПРОВЕРЕНО: учтены логины с большими и маленькими буквами.

Добавлен временный devnet-смарт-контракт для очистки тестового аккаунта от старых логинов; после сброса его необходимо удалить и восстановить штатный контракт.
2026-10-28 12:19:19 +03:00

721 lines
82 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 — МАСТЕР-ПЛАН РЕАЛИЗАЦИИ РЕГИСТРАЦИИ V2
**Дата:** 23 октября 2026 года
**Тип:** автономное техническое задание и инструкция для нового чата / Codex
**Базовый архив:** `SHiNE-bundle-2026.10.22-12.53.20(1).zip`
**Связанный предыдущий план:** `SHiNE_registration_roadmap_2026-10-23.md`
**Статус:** проектирование; изменения в исходный код этим документом НЕ внесены.
**Принцип:** один этап = один контролируемый патч. Не реализовывать весь документ за одну генерацию.
> **ВАЖНО ДЛЯ СЛЕДУЮЩЕГО ИСПОЛНИТЕЛЯ.** Не воспринимай этот документ как свидетельство, что код уже изменён. Сперва открой архив / рабочий репозиторий, прочитай локальные AGENTS.md, проверь текущую ветку и выполни только тот этап, который явно поручен. Все пути ниже сверены с архивом от 22.10.2026; в другой версии они могут отличаться. Если обнаружишь техническую неточность плана, исправь её обоснованно, сохранив согласованные продуктовые правила. Не менять API и формат существующего пользовательского блокчейна без предусмотренного проектом согласования.
---
## КАК ПЕРЕДАТЬ В НОВЫЙ ЧАТ (важнее всего)
Передать **оба вложения**:
1. Полный исходный архив проекта `SHiNE-bundle-2026.10.22-12.53.20(1).zip` либо актуальную версию репозитория.
2. **Этот файл мастер-плана V2**, а также последний журнал завершённых этапов, если работа уже начата.
В новом чате дать инструкцию:
> «Это проект SHiNE. Прочитай `SHiNE_registration_implementation_masterplan_v2_2026-10-23.md`, затем AGENTS.md в корне и в изменяемых модулях. Сначала сверь план с реальным исходным кодом. Выполни **только этап № N**, включая тесты, актуализацию обязательной документации и отчёт по шаблону из конца плана. Не придумывай другую схему регистрации. Не трогай production, не меняй публичный API/формат старого блокчейна без отдельного разрешения. После выполнения остановись».
Если кодовая база изменилась после архива, **источником истины для расположения кода является актуальный репозиторий**, а этот документ — источник согласованных требований и порядка действий.
---
# А. ПРОДУКТОВОЕ ТЗ: ЧТО ДОЛЖНО ПОЛУЧИТЬСЯ
## А1. Три допустимых состояния одного аккаунта
| Состояние | Кто удостоверяет имя | Пользовательский PDA Solana | Сервер доступа | Смена ключей |
|---|---|---|---|---|
| `PAID_DIRECT` | `shine_users` | есть | определяется своим PDA | разрешена по правилам PDA |
| `FREE_CERT` | сертификат регистратора в Arweave | нет | общий сервер из namespace-PDA | запрещена |
| `PAID_UPGRADED` | `shine_users` + ранее выданный сертификат | есть | определяется своим PDA | разрешена по правилам PDA |
`FREE_CERT → PAID_UPGRADED` **не создаёт нового пользователя**: полное имя `login@namespace`, root/client/blockchain публичные и приватные ключи, старые публикации, каналы и история блокчейна остаются прежними. Приватные ключи доступны только пользователю и не попадают на сервер.
**Уточнение по времени:** дата создания Solana PDA при upgrade может быть новой датой on-chain регистрации; дата первоначальной бесплатной регистрации и история Arweave остаются отдельно. Нельзя выдавать новую on-chain дату за дату создания исходного аккаунта или обнулять историю/расход лимитов.
## А2. Полные логины и пространства имён
- Каждый пользователь имеет имя `login@namespace` (пример: `alice@shine`, `bob@free`).
- Namespace — реально существующий аккаунт PDA программы `shine_users`, а не hardcoded список в UI.
- Тип `1`: прямая платная регистрация в Solana.
- Тип `2`: первоначальная бесплатная регистрация с сертификатом регистратора; позднее возможна платная регистрация PDA.
- Оба namespace имеют стоимость создания пользовательского PDA. Цена в типе `2` списывается **в момент перехода на Solana**.
- У каждого namespace есть нижняя граница длины части `login`; общая максимальная длина `login@namespace` на этом этапе — 30 байт при ASCII-алфавите.
- Не продавать отдельные короткие логины, не вводить premium-классы.
- Пространства создаются действующей **upgrade authority Solana-программы `shine_users`**, а не отдельной константой DAO. В будущем upgrade authority сможет принадлежать DAO.
- Пока разрешено **создавать**, но не редактировать или удалять namespace.
## А3. Ключи и пароль
- Клиент получает root key, blockchain key, client key из своего существующего механизма восстановления по **полному нормализованному логину и паролю**; не придумывать новый KDF.
- При регистрации бесплатного пользователя сервер видит **только три публичных ключа**.
- Приватный ключ **регистратора** — совершенно другой ключ. Пока находится в защищённой конфигурации сервера (вне Git); в будущем замещается аппаратным регистратором.
- Публичный ключ регистратора записывается в PDA бесплатного namespace.
- Нельзя связывать бесплатную регистрацию с хранением пароля или приватных ключей пользователя на сервере.
## А4. Сертификат и две подписи
Последовательность данных внутри подписанного ANS-104 DataItem:
1. Версия сертификата.
2. Полный `login@namespace`.
3. Три публичных ключа (порядок однозначно зафиксировать в протоколе; предлагается `root`, `blockchain`, `client`).
4. **Внутренняя Ed25519-подпись регистратора** только от полей идентичности — версии, полного имени и трёх публичных ключей (плюс протокольный domain separator).
5. SHA-256 от нормализованного email — **после внутренней подписи**, не входит в её сообщение.
6. Весь ANS-104 DataItem, включая поле хеша email и теги, подписывается **внешней подписью ANS-104 тем же ключом регистратора**.
Внутренняя подпись нужна для последующей проверки в Solana, внешняя — для удостоверения полного DataItem при его импорте. Это **две разные подписи от разных последовательностей байтов**.
Теги DataItem следует отделять от обычных пользовательских блоков, например существующим `App=test5592` плюс отдельный тег типа `t=reg`; точный набор тегов утвердить в документе протокола, не смешивать с `t=prof|conn|tech`.
## А5. Email
- При free-регистрации пользователь вводит email.
- Пока **проверка учебная**, реальная почта не отправляется; правильный код `1111` и это явно сказано в UI.
- В Arweave публикуется **только `SHA256(normalized_email)`**; исходный email не публикуется и не передаётся в Solana.
- Один нормализованный email-хеш должен соответствовать максимум одной бесплатной регистрации в известном реестре SHiNE.
- Пользователь понимает принятое ограничение: простой SHA-256 допускает проверку догадок об email; это не обещание полной анонимности.
- Пока единственный доверенный регистратор; не реализовывать сложную распределённую выдачу/резервирование и защиту от кражи ключа.
- Важная честная оговорка: `1111` доказывает только ввод фиксированного кода, **не подтверждает владение email**. Глобальная уникальность зависит от полноты синхронизации и единственного регистратора; не объявлять это криптографически абсолютной гарантией.
## А6. Источники идентичности и приоритет
- Для платных пользователей источником полномочий служит настоящий Solana PDA.
- Для бесплатных — проверенный сертификат Arweave, связанный с PDA бесплатного namespace.
- После upgrade статус меняется **у существующей логической личности**; Arweave-сертификат сохраняется как историческое основание исходной выдачи имени.
- При импорте сертификата всегда проверяется полномочие подписавшего ключа; сам факт хранения в Arweave не делает запись доверенной.
- Если запись уже принята, произвольная другая запись того же логина **не должна её заменять**. Дополнительную модель кражи ключа пока не строить.
## А7. Сервер доступа и ограничения free
- До Solana upgrade сервер доступа всех аккаунтов бесплатного namespace задаёт его namespace-PDA.
- Для платного пользователя сервер доступа берётся из собственного PDA v1.2.
- `FREE_CERT` не может менять root, blockchain и client keys; не может менять сервер доступа; не может запускать fork/key rotation, если это меняет ключи.
- Ограничение действует не только в UI, но и в серверных проверках; обязательно найти альтернативные пути соответствующих операций.
- Публикации, каналы, связи, личные сообщения и чтение истории должны работать обычным образом.
- После upgrade смена ключей/сервера работает по существующим правилам Solana.
## А8. Экономика и управление
- `init_users_economy_config` остаётся доступной любому подписанту; она инициализирует детерминированные исходные параметры только один раз.
- `update_users_economy_config` вместо постоянной `DAO_AUTHORITY` проверяет **действующую upgrade authority через ProgramData**.
- Стоимость **регистрации** — из соответствующего namespace-PDA; стоимость покупки дополнительных лимитов и иные параметры остаются в economy-PDA.
- При `create_namespace` и каждой новой регистрации economy-PDA присутствует в account metas как read-only для текущего механизма history/poll синхронизации.
- Чтение economy-PDA не обязано генерировать WebSocket account-change notification; для истории продолжает работать `getSignaturesForAddress`/периодический poll.
- Удалить использование promo_seller и shine_login_guard из **новой пользовательской регистрации**, связанные инструкционные ветки `shine_users`, клиентские поля промокодов и premium-проверки. Отдельные legacy-программы без необходимости не удалять.
## А9. Мгновенный вход после Turbo
`код 1111 → выпуск подписанного DataItem → успешный ACK Turbo → импорт тех же raw signed bytes локально → пользователь получает доступ`.
- **Не ждать** высоты блока Arweave для первого входа.
- Другие серверы обнаружат запись позже через Arweave, и это нормально.
- Локально различать `TURBO_ACCEPTED` и `ARWEAVE_CONFIRMED`; не путать приём Turbo с окончательным подтверждением сети.
- При сетевой ошибке или неизвестном результате публикации не терять пользовательские ключи, не создавать бессмысленно новый сертификат и новый DataItem при каждом повторе.
## А10. Не входит в этот релиз
Нет реального SMTP, восстановления ключей через email, изменения/удаления namespace, аппаратного регистратора, мультиподписей регистраторов, обработки компрометации его ключа, управления DAO, продажи премиальных имён, автоматической миграции старых Solana PDA/логинов, масштабного редизайна остальных экранов.
---
# Б. КАРТА РЕАЛЬНОГО ИСХОДНОГО КОДА (архив 22.10.2026)
Эти файлы **существуют** в проверенном архиве. Для новых классов ниже будет явно сказано «создать».
| Компонент | Существующие точки входа | Что там сейчас / зачем менять |
|---|---|---|
| Solana | `shine-solana/shine/programs/shine_users/src/lib.rs` | instruction dispatcher, `create_user_pda`, `update_user_pda`, Ed25519 precompile, экономика, promo и guard |
| Настройки Solana | `shine-solana/shine/programs/shine_users/src/settings.rs` | `USER_PDA_SEED_PREFIX="user_login="`, старые константы `DAO_AUTHORITY`, guard, promo |
| Документ Solana | `shine-solana/shine/doc/programs/shine_users.md` | контракт, аккаунты, инструкции |
| Документ PDA v1.2 | `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md` | существующий формат полноценного PDA; сохранять |
| Solana UI codec | `shine-UI/js/services/shine-user-pda-service.js` | seed, сериализация, транзакции регистрации, promo |
| Solana UI facade | `shine-UI/js/services/solana-register-service.js` | guard/premium precheck, доступность имени, вызов общего сервиса |
| Адреса программ | `shine-UI/js/solana-programs.js` | реальные program id считывать из актуального окружения |
| Получение ключей | `shine-UI/js/services/auth-service.js` | `derivePasswordKeyBundle(login,password)`; полный login входит в Argon2id/KDF |
| Регистрация UI | `shine-UI/js/pages/register-view.js`, `registration-payment-view.js`, `registration-draft-keys-view.js` | старая платная форма, лимиты длины и promo UI |
| Логин / настройки | `shine-UI/js/pages/login-view.js`, `login-password-view.js`, `settings-view.js`, `key-rotation-view.js` | вход и функции ключей |
| UI router/state | `shine-UI/js/router.js`, `shine-UI/js/state.js` | новые страницы и черновики регистрации |
| Solana sync | `SHiNE-server/shine-server-solana-users-sync/src/main/java/sync/service/SolanaUsersSyncService.java` | историю отслеживает по economy-PDA; snapshot и checkpoint |
| Solana parser | `.../sync/codec/ShineUsersCodec.java` | декодирование инструкций и записей |
| Solana PDA utility | `.../sync/util/SolanaPdaUtil.java` | вычисляет findProgramAddress на Java |
| Solana sync DB | `.../sync/storage/postgres/PostgresStorageRepository.java` | upsert/account snapshot; нужны namespaces и новые статусы |
| База | `SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql` и `migration_v31.sql`, `migration_v32.sql` | baseline и текущие миграции; следующая — новая по порядку, НЕ переписывать прошлые |
| DB login facade | `SHiNE-server/shine-server-db/src/main/java/shine/db/sql/CurrentUsersSql.java` | сейчас возвращает пользователей только из `solana_user_pda_current` |
| DB DAO | `.../shine/db/dao/CurrentUsersDAO.java`, `SolanaUserPdaCurrentDAO.java`, `UserAccessServersCurrentDAO.java` | проверки пользователей, ключей, сервера |
| Авторизация | `SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/handlers/auth/` | `SolanaUserPdaImportService`, `Net_ResolveLoginForAuth_Handler`, `Net_CreateAuthSession__Handler` и связанные классы |
| Ротация | `.../handlers/keyRotation/`, `KeyRotationSessionsDAO.java` | запреты для `FREE_CERT` |
| Config | `SHiNE-server/shine-server-config/src/main/java/utils/config/AppConfig.java` | встраивание параметров регистратора без Git-секрета |
| ANS-104 | `SHiNE-server/shine-server-blockchain/src/main/java/blockchain/Ans104DataItem.java` | сериализация, deep-hash, Ed25519 signature verify |
| Turbo | `SHiNE-server/shine-server-archive/src/main/java/server/archive/TurboDataItemUploader.java` | принимает **уже подписанный** DataItem, проверяет и отправляет |
| Arweave import | `SHiNE-server/shine-server-archive/src/main/java/server/archive/ArweaveBlockSyncService.java` | GraphQL discovery, блоки, фильтр `block.height`; нужен отдельный путь регистрации |
| API dispatch | `SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java` | подключение новых WS операций |
| Документация API | `docs/API/01_User_Registration_API.md`, `docs/API/09_Operations_Index.md` | новые операции и ошибки: согласовать изменения |
| Документация sync | `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`, `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md` | алгоритм и эксплуатация sync |
| Деплой | `deploy/AGENTS.md`, `deploy/TEST_SERVERS.md`, `docs/Инициализация_Solana_регистрации/README.md` | тестовый контур и порядок инициализации |
**Подтверждённые особенности кода:**
- В `shine_users` opcode 1 = init economy, 2 = update economy, 3 = create user, 4 = update user, 5 = upsert promo seller, 6 = close legacy. Новым инструкциям назначать непересекающиеся id, зафиксировать их в документации.
- Текущее `create_user_pda` подтверждает root и blockchain через Ed25519 instructions sysvar (разбор относительно текущей инструкции). Дополнительная подпись регистратора потребует тщательно задать расположение этих инструкций.
- Пользовательский PDA v1.2 содержит root, client, forks blockchain key, access servers, а не простую запись «три ключа + имя».
- `solana_user_pda_current` сейчас является центральной таблицей и целью внешних ключей; **нельзя** подделывать наличие on-chain PDA для free.
- В `CurrentUsersSql.usersSubquery` список сейчас берётся только из `solana_user_pda_current`.
- `TurboDataItemUploader.upload` не подписывает DataItem за клиента: raw signed DataItem нужно сформировать до вызова.
- В `ArweaveBlockSyncService` текущая основная выборка пропускает GraphQL-записи без `block.height`; free-registration требует отдельной ветки и немедленного локального пути.
- В `register-view.js` есть временная логика нормализации `<=20` и пропуск `_` для guard. Для новой системы `_` не удалять из идентичности: `a_b` и `ab` не должны внезапно стать одним именем.
**Читать перед началом:** корневой `AGENTS.md`, `COMMIT_AND_VERSION_RULES.md` и локальные `shine-solana/shine/AGENTS.md`, `SHiNE-server/AGENTS.md`, `shine-UI/AGENTS.md` при работе с соответствующими модулями. Особенно: проект требует отдельного согласования перед **изменением публичного WebSocket API** или **формата существующего блокчейна**. Утверждённая архитектура не отменяет эти рабочие правила.
---
# В. ПРОТОКОЛ V1: ПРЕДЛАГАЕМАЯ ТОЧНАЯ КОНКРЕТИЗАЦИЯ
**Статус подраздела В:** проект формата для принятия на этапе 1. Дальше его нельзя «чуть изменить в одном месте»; изменение только одновременно в Rust, JS, Java, документах, фикстурах. Здесь изложены технические детали уже согласованного поведения, не новые продуктовые возможности.
## В1. Канонический login
- `localPart` и `namespace` — ASCII lowercase, разрешённые символы утвердить по совместимости с кодом; практичный набор: `[a-z0-9_]`, без пробелов, без второго `@`.
- Полное имя: `${localPart}@${namespace}`.
- `normalizedFullLogin` — байты UTF-8 ровно этой lowercase-строки, без пробелов по краям. Для проверки нового аккаунта отклонять неоднозначные формы, не преобразовывать «почти такие же» имена молча.
- Общее ограничение полного имени: 30 **UTF-8 байт** на этой версии; минимальная длина localPart — из namespace PDA, считать байты (ASCII = символы).
- Никогда не отбрасывать `_`, не обрезать строку, не менять namespace после создания.
## В2. Seed пользовательского PDA
```text
preimage = UTF8("user_login=" + normalizedFullLogin)
seed32 = SHA256(preimage) // именно 32 СЫРЫХ БАЙТА
userPda = findProgramAddress([seed32], shineUsersProgramId)
```
**Не** base58-строку хеша, не hex-строку, не два старых seed. На адрес дополнительно влияет programId и bump стандартного findProgramAddress. Для подписания `create_program_address` программа использует `[seed32, bump]`.
## В3. Seed namespace PDA
```text
preimage = UTF8("namespace=" + normalizedNamespace)
seed32 = SHA256(preimage)
namespacePda = findProgramAddress([seed32], shineUsersProgramId)
```
Префикс `namespace=` здесь предложен как **окончательная константа v1 после утверждения на этапе 1**; его нельзя менять после первых созданных PDA.
## В4. Бинарный namespace-PDA
```text
major u8 // 1
minor u8 // 0
namespace_type u8 // 1 paid-direct / 2 free-cert
min_localpart_len u8
namespace_len u8 // N
namespace u8[N] // lowercase ASCII
registration_fee u64 LE // lamports; и для будущего upgrade free
if namespace_type == 2:
registrar_pubkey u8[32] // Ed25519
server_login_len u8 // M
server_login u8[M] // полный login@namespace зарегистрированного сервера
```
Сериализатор и парсер должны отвергать неизвестные версии/типы, неправильную длину данных, некорректный namespace и подставленный PDA. Если Solana-аккаунт создаётся с дополнительной областью из-за выравнивания/rent, определить однозначную политику padding и её проверку. Для type 1 поля регистратора/сервера отсутствуют, а не заполнены «нулевой фикцией».
## В5. Внутренняя подпись бесплатного сертификата
Пример детерминированного массива байтов (предлагается как v1):
```text
identity_fields =
major:u8 (=1) || minor:u8 (=0) ||
full_login_len:u8 || full_login_utf8 ||
root_pubkey:32 || blockchain_pubkey:32 || client_pubkey:32
inner_message = UTF8("SHiNE_FREE_REG_V1\u0000") || identity_fields
inner_signature64 = Ed25519.sign(registrar_private_key, inner_message)
```
- Domain separator убирает риск приравнивания подписи к подписи чужого протокола.
- Контракт должен проверить **байты** `inner_message`, а не локальный JSON/строковую интерпретацию.
- Внешняя ANS-104 подпись использует стандартный `deepHash(...)` и **не заменяет** внутреннюю подпись.
- Тот же публичный ключ регистратора должен быть в namespace PDA и в owner внешнего DataItem.
## В6. Payload DataItem
```text
payload = identity_fields || inner_signature64:64 || normalized_email_sha256:32
```
Плюс теги, отделяющие регистрационный DataItem от пользовательского блока. Email внутри `inner_message` отсутствует **осознанно**, по решению владельца проекта.
**Не включать:** пароль, masterSecret, root/blockchain/client private keys, приватный ключ регистратора, исходный email.
## В7. Нормализация email
- `trim` пробелы с краёв.
- Unicode NFC, lowercase без зависимости от локали.
- Не удалять `+tag` и точки: разные почтовые сервисы трактуют их неодинаково.
- `email_hash = SHA256(UTF8(normalizedEmail))`.
- Хеш проверяется по индексу, а не принимается на веру со слов клиента: пока сервер получает email по защищённому каналу, нормализует сам.
## В8. On-chain Ed25519-инструкции и экономическая транзакция
Упорядочить инструкции в Solana-транзакции так, чтобы контракт надёжно проверял (а) подпись root над хешем записи пользователя, (б) подпись blockchain над тем же хешем и (в) для type 2 подпись регистратора над `inner_message`. Количество/индексы Ed25519 IX и номера инструкций должны быть зафиксированы в документах **и тестах на отрицательные случаи**. Не делать проверку «подпись где-то есть в транзакции» без проверки конкретного сообщения, ключа и содержания.
Регистрационную комиссию переводить в существующий `shine_payments` inflow-vault с сохранением текущего расчёта дополнительного лимита. Считывать цену регистрации из namespace, не из economy. Economy PDA участвует read-only и используется для параметров лимитов и истории транзакций.
---
# Г. ВЫПОЛНЕНИЕ: 14 ПОСЛЕДОВАТЕЛЬНЫХ ЭТАПОВ
Каждый этап начинается с аудита указанных файлов, завершается **сборкой, целевыми тестами, документацией и отчётом**. Завершение одного этапа не равно завершению всего проекта.
## ЭТАП 0. Подготовить ветку, матрицу зависимостей и базовый тестовый стенд
**Зачем:** зафиксировать исходное состояние и не выполнять изменения вслепую.
**Файлы/места:** корень, все `AGENTS.md`, `COMMIT_AND_VERSION_RULES.md`, `deploy/TEST_SERVERS.md`, `shine-solana/shine/`, `SHiNE-server/`, `shine-UI/`.
**Действия:**
1. Распаковать/клонировать исходник. Зафиксировать commit/архив, рабочую ветку, версии tools, Rust/Anchor/Solana, Java/Gradle, Node, PostgreSQL.
2. Прочитать инструкции по модулям. Разрешения на production **не подразумеваются**.
3. Установить базовые команды сборки/тестов по реальным файлам проекта; выполнить smoke baseline и записать результаты (включая уже существующие ошибки).
4. Найти все вызовы `find_user_pda`, `user_login=`, `getProgramAccounts`, константы 20/8, `shine_login_guard`, `promo_seller`, `registration_fee_lamports`, `solana_user_pda_current`, `resolveLogin`.
5. Выписать все SQL FK на `solana_user_pda_current`, PostgreSQL triggers/views и клиентов `CurrentUsersSql`; отдельным списком — операции, зависящие от real Solana PDA.
6. Создать в ветке `docs/registration-v2/IMPLEMENTATION_STATUS.md` (или отдельный рабочий журнал), заполнять после каждого этапа.
**Готово, когда:** известны реальные точки редактирования, baseline сборки и правила релиза; основной код пока неизменён.
## ЭТАП 1. Зафиксировать протоколы и тест-векторы Rust/Java/JS
**Зависимость:** этап 0.
**Создать/изменить:**
- `shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md` (новый).
- `docs/Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md` (новый).
- `shine-solana/shine/doc/programs/shine_users.md` (разделы новых IX и seed).
- Общие тестовые фикстуры по одному логину/ключам/email; место выбрать так, чтобы тесты трёх языков могли читать их.
**Задачи:**
1. Застолбить все поля форматов, версии, число байт, encoding `u64 LE`, `full login`, запрет неоднозначных имён.
2. Застолбить доменные префиксы seed и внутренней подписи.
3. Зафиксировать структуру подписанного `inner_message` и `ANS-104 payload`, уникальные теги для регистраций.
4. Фиксировать максимумы, ошибка/результат на некорректном типе, парсинге, padding, цене, серверном логине.
5. Подготовить тест-векторы: `alice@shine`, `bob@free`, `_` в имени, минимальная длина, 30-й байт, 31-й байт; один детерминированный email.
6. Записать ожидаемые хеши и PDA **для конкретного program ID теста**. Проверка в Rust/Java/JS обязана давать побайтово одинаковые значения.
7. Зафиксировать как обрабатывается созданная ранее история free пользователя: ключи/блоки неизменны; создание Solana PDA может иметь новую timestamp без сброса логической регистрации.
**Тесты:** round-trip кодирования; одинаковые хеши; подмена одного ключа ломает внутреннюю подпись; подмена email ломает внешнюю ANS-104 подпись.
**Готово, когда:** ни исполнитель Solana, ни исполнитель UI не должен выбирать форматы заново.
## ЭТАП 2. Solana: Namespace PDA и полномочия upgrade authority
**Зависимость:** этап 1.
**Изменить:**
- `shine-solana/shine/programs/shine_users/src/lib.rs`;
- `.../settings.rs`;
- `shine-solana/shine/tests/shine.ts` и документацию программы.
**Задачи:**
1. Добавить типы `NamespaceState`/`CreateNamespaceArgs`, строгий parser/serializer.
2. Добавить **новый opcode** `IX_CREATE_NAMESPACE` без конфликта с текущими 1–6.
3. Проверять правильный PDA из SHA-256 seed `namespace=...`, owner, rent, размер, неповторяемость имени.
4. Проверять владельца `ProgramData`: это ProgramData **конкретной** программы, принадлежащий BPF upgradeable loader, с текущей `upgrade_authority_address`; signer должен совпадать. Если программа immutable — отказ.
5. В `update_users_economy_config` применить ту же проверку ProgramData. Инициализацию economy не менять.
6. В `create_namespace` принять economy-PDA как read-only account meta; проверить его ожидаемый адрес. Цена хранится в namespace.
7. Сделать CLI/скрипт подготовки создания двух test namespaces и независимый декодер.
**Тесты:** админ создаёт; посторонний не создаёт; чужой/поддельный ProgramData не помогает; тот же namespace повторно отвергается; неверный type/version/данные отвергаются; economy init всё ещё открыт, economy update закрыт.
**Готово, когда:** два test namespace создаются и читаются в localnet/devnet; **пока не изменять production**.
## ЭТАП 3. Solana: создание PDA пользователем напрямую и по сертификату
**Зависимость:** этап 2.
**Изменить:** `shine_users/src/lib.rs`, `settings.rs`, `shine/tests/shine.ts`, документы формата PDA v1.2 и программы.
**Задачи:**
1. Во всех местах create/update/close (где нужно) заменить вычисление пользовательского PDA на SHA-256 от **полного** имени, включая `@namespace`.
2. Проверять `(localPart, namespace)`, тип, min local length, max full length 30 байт, правильный namespace-PDA.
3. Оставить бинарный payload существующего PDA пользователя **версии 1.2**, если нет объективной необходимости его менять.
4. Для type 1: проверка доступности имени, root/blockchain подтверждение, создание PDA, комиссия по namespace + лимит из economy.
5. Для type 2: дополнительно требовать внутреннюю подпись регистрирующего ключа над тем же полным именем и **теми же** root/blockchain/client public keys. Ключ проверки брать из on-chain namespace.
6. Передать economy-PDA в account list read-only при любой регистрации; сохранить `shine_payments` inflow-vault.
7. Обновить Ed25519 instruction index: корректно отличать root, blockchain, registrar; отрицательные тесты на путаницу индексов.
8. Удалить из новой регистрации guard CPI, premium-classification, promo seller args/promo IX и связанные комиссии. Старые отдельные Solana-программы не трогать без причины.
9. Для upgrade не допускать повторного Solana PDA, не требовать создания заново пользовательского Arweave блокчейна.
10. Продумать состояние лимитов: бесплатный пользователь мог уже писать и тратить стартовый ресурс — не объявлять оплаченный лимит или баланс «с нуля» без согласования с реальным текущим учётом блоков. Не давать дополнительных стартовых бонусов за сам факт upgrade без явного правила.
**Тесты:** прямой paid create; free→paid create; цена для разных namespaces; заблокирован type2 без сертификата; неверный регистратор; изменённый client/root/blockchain; чужой namespace; 30 vs 31 байт; повторное создание; корректность PDA; существующий paid update без регрессии.
**Готово, когда:** новая Solana-программа умеет создавать обе категории PDA и корректно обновлять существующую v1.2 запись. UI можно внедрять позже.
## ЭТАП 4. Клиентский Solana codec, поиск PDA и bootstrap namespace
**Зависимость:** этап 3.
**Изменить:**
- `shine-UI/js/services/shine-user-pda-service.js`;
- `shine-UI/js/services/solana-register-service.js`;
- `shine-UI/js/solana-programs.js` при необходимости;
- `shine-UI/server-ui/` (если инструменты управления серверным аккаунтом используют прежний seed).
**Задачи:**
1. Добавить JS encode/decode NamespaceState, `deriveNamespacePda()` и `deriveUserPda(fullLogin)`.
2. Удалить `getProgramAccounts`/поиск по старой строке-логину или адаптировать под хеш seed и новый формат. Не предполагать, что seed можно восстановить из PDA без данных.
3. Переделать сериализацию `create_user_pda`, account metas (namespace, economy), fee display, IX order.
4. Для type2 сформировать и подключить Ed25519 ix с **готовой** внутренней подписью сертификата; приватный ключ регистратора в браузер не попадает.
5. Убрать UI service API `promoCode` и premium guard precheck там, где они обслуживают регистрацию.
6. Обновить код **создания серверного аккаунта**, который тоже является user PDA и тоже требует полный `login@namespace`.
7. Создать независимые JS unit tests на PDA, namespace decode, transaction serialization, equality signature message.
**Готово, когда:** тестовый JS может создать correct paid/free Solana transaction по контракту без рабочего пользовательского экрана.
## ЭТАП 5. PostgreSQL: единый логический пользователь вместо фиктивного free PDA
**Зависимость:** этап 1; желательно готов этап 3 для схемы Solana полей.
**Изменить:** schema/migrations `SHiNE-server/shine-server-db/src/main/resources/postgres/`; `CurrentUsersSql`, `CurrentUsersDAO`, `SolanaUserPdaCurrentDAO`, `UserAccessServersCurrentDAO`, зависимые views/triggers/DAO, отдельные entities.
**Главный риск:** **текущие FK, stats и queries считают `solana_user_pda_current` полным списком пользователей.** Нельзя просто положить сертификаты в новую таблицу и надеяться, что всё заработает.
**Предпочтительное решение:** создать каноническую таблицу **логических пользователей**, например `user_identity_current` (название финализировать по реальному SQL), с уникальным `normalized_login` и ключами; оставить `solana_user_pda_current` таблицей **только настоящих** PDA, связанной с логической личностью. Хранить `namespace`, `registration_source`, `registration_status`, `registered_at_ms`, `free_data_item_id`, `solana_pda_address (nullable)` и текущие ключи. В свободном состоянии `solana_pda_address = NULL`, не выдумывать адрес «как будто on-chain аккаунт есть».
**Задачи:**
1. На основе полного поиска SQL составить список всех FK/views/triggers/запросов и миграционный граф.
2. Создать новую **следующую** миграцию после существующей v32 (номер брать из актуального исходника, если новее). Не переписывать исторические миграции.
3. Добавить таблицу синхронизированных namespaces, таблицу сертификатов (полный signed payload/ID/hash email/внутренняя подпись/публикационный статус) и индексы уникальности.
4. Сформировать общий индекс `user_identity_current`, связать paid/free; изменить зависимости SQL на него там, где нужна любая идентичность, а не именно реальный PDA.
5. Обновить `CurrentUsersSql.usersSubquery()` и соответствующие DAO на общее представление пользователя. В частях, где необходим фактический PDA (rotation, Solana-specific reads), делать явную проверку `has_solana_pda`.
6. Учитывать сервер доступа: `FREE_CERT` → namespace.defaultServerLogin; `PAID_DIRECT`/`PAID_UPGRADED` → account access servers из PDA.
7. Добавить атомарную операцию **upgrade существующего логического аккаунта** без дублирования `login`, ссылок, каналов и связей.
8. Для уже существующих реальных PDA подготовить idempotent backfill в канонический индекс; старая база не должна разрушаться.
9. Добавить интеграционные тесты на restart/re-run migration; FK, статистику, связи, access routing, уникальность.
**Готово, когда:** тот же логин может существовать как `FREE_CERT` без PDA и затем приобрести настоящий PDA без новой строки логического пользователя. На чистой и обновляемой тестовой базе старые DAO продолжают работать.
## ЭТАП 6. Java синхронизация Solana: namespaces + новые PDA + события
**Зависимость:** этапы 3 и 5.
**Изменить:**
- `SHiNE-server/shine-server-solana-users-sync/src/main/java/sync/service/SolanaUsersSyncService.java`;
- `.../sync/codec/ShineUsersCodec.java`;
- `.../sync/storage/postgres/PostgresStorageRepository.java`;
- `.../sync/util/SolanaPdaUtil.java`;
- `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`;
- `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`.
**Задачи:**
1. Кодеки namespace PDA, новой инструкции и нового расчёта seed.
2. History parse: `IX_CREATE_NAMESPACE`, новый `IX_CREATE_USER_PDA` и существующие update. Сохранять `economy PDA` как индекс RPC истории.
3. Snapshot bootstrap должен находить **все актуальные namespace** и **все реальные пользовательские PDA**, а не зависеть только от уже обработанных событий.
4. На каждое подтверждённое создание/обновление делать идемпотентный upsert в реестр, не изменять кэш бесплатного сертификата без проверок.
5. Если пришёл paid upgrade для существующего free логина — обновить ту же логическую личность, а не удалить/recreate.
6. Реализовать корректный checkpoint/retry при RPC timeout, ошибках декодера, дубликатах signature, задержках сети.
7. Сохранять доступ к деталям economy после init/update для прежней модели лимитов.
8. Проверить, что сервер умеет различать `free cert есть`, `Solana PDA ещё нет` и `Solana PDA уже появился`.
**Готово, когда:** из clean snapshot и из history replay получается одна и та же PostgreSQL-сущность для пользователей и namespaces; upgrade не плодит дубли.
## ЭТАП 7. Сервер: доверенный регистратор (временная программная заглушка)
**Зависимость:** этапы 1, 5 и импорт namespace из 6.
**Изменить/создать:** `SHiNE-server/shine-server-config/src/main/java/utils/config/AppConfig.java`; новый сервис/интерфейс registrar в подходящем Java модуле; unit tests; новый конфигурационный README.
**Задачи:**
1. Настройки: включено ли бесплатное регистрирование, какие namespace обслуживает сервер, публичный ключ и **путь/secret reference** к приватному ключу регистратора; не хранить ключ в Git или логе.
2. При старте сверять локальный public key с public key **соответствующего** on-chain namespace; при несоответствии блокировать новые выдачи, не ломая работу старых пользователей.
3. Выделить интерфейс `RegistrarSigner.sign(byte[])` и software-реализацию. В будущем можно заменить на hardware signer.
4. Подготовить детерминированный `identity_fields` и `inner_message`; получить внутреннюю Ed25519-подпись.
5. Собрать `payload` и внешнюю ANS-104 подпись тем же keypair; задать отличающиеся от user block теги.
6. Проверять формат имени, min/max длины, неповторяемость известных login/email, тестовый код `1111` и соответствие namespace type2.
7. Не принимать приватные ключи пользователя даже «временно», не хранить пароли.
8. Не вводить сейчас аппаратное устройство и сложный распределённый mutex/компрометацию ключа; достаточно корректного последовательного выполнения обычной выдачи на одном регистраторе.
**Тесты:** повторяемые фикстуры; правильная внутренняя + внешняя подпись; неверный namespace; отсутствие ключа; несоответствие pubkey; неправильный email code; секреты не появляются в диагностике.
**Готово, когда:** Java локально выдаёт raw signed ANS-104 bytes с обеими проверяемыми подписями без Turbo и UI.
## ЭТАП 8. Arweave: отдельный импорт сертификатов и немедленное принятие после Turbo
**Зависимость:** этапы 5, 6 и 7.
**Изменить:** `SHiNE-server/shine-server-archive/src/main/java/server/archive/ArweaveBlockSyncService.java`, `TurboDataItemUploader.java` **переиспользовать**, `Ans104DataItem.java` **переиспользовать**; новая ветка/сервис регистрации и DAO. Не менять формат существующих обычных блоков.
**Задачи:**
1. Создать **отдельный importer** для `t=reg` DataItem, а не подделывать пользовательский блок.
2. Парсер payload; проверка внешней ANS104 подписи, owner = on-chain registrar pubkey, внутренней Ed25519 подписи, имени, namespace, структурных границ.
3. Проверить уникальность ID DataItem; не дать повторному discovery создать двойника или переписать существующий login.
4. После успешного Turbo upload сразу прогонять **точно те же raw signed bytes** через этот importer в локальную БД.
5. Обновить GraphQL discovery / типовые фильтры, чтобы независимый сервер мог получить `t=reg` и восстановить сертификаты позже. Не ограничиваться существующим фильтром только блоков/высот без учёта регистраций.
6. Хранить `TURBO_ACCEPTED`, последующее подтверждение Arweave, отметки retries, ID и ошибку при необходимости.
7. Idempotent import: immediate → GraphQL повторный импорт должен дать «уже учтено» и сохранить те же ключи/identity.
8. При Turbo timeout/неопределённости не выдавать ложный окончательный успех; предусмотреть проверку известного DataItem ID и повторную отправку идентичных байтов.
9. Сервер B импортирует записи, созданные сервером A, при достижении Arweave и наличии namespace registry.
**Готово, когда:** подтверждение Turbo даёт первый вход на принимающем сервере без ожидания GraphQL; второй сервер узнаёт пользователя после sync; дубли harmless.
## ЭТАП 9. Сервер: WS/API операции бесплатной регистрации
**Зависимость:** этапы 7 и 8.
**До изменения API:** прочитать `AGENTS.md`, `docs/API/*` и **получить отдельное согласование пользователя на конкретные новые операции/поля** — это правило репозитория, даже когда общая функциональность одобрена.
**Изменить:** `JsonHandlerRegistry.java`, новые handler/DTO классы в `shine-server-net-protocol`, `docs/API/01_User_Registration_API.md`, `docs/API/09_Operations_Index.md`.
**Предложение минимального протокола (ИМЕНА ОПЕРАЦИЙ — ПРОЕКТ, не существующий код):**
| Операция | Ввод | Результат |
|---|---|---|
| `GetNamespaces` | — | список существующих namespace + type/fee/min/server |
| `CheckRegistrationAvailability` | fullLogin, email (для free) | доступен ли login/email; не считать результат резервированием |
| `StartFreeRegistration` | fullLogin, 3 public keys, email | продолжение проверки кода, id временного процесса при необходимости |
| `ConfirmFreeRegistration` | id/данные процесса, code=`1111` | Turbo dataItemId, статус, подтверждённый fullLogin |
| `GetRegistrationStatus` | login или ID операции | `FREE_CERT`, `PAID_DIRECT`, `PAID_UPGRADED`, `PENDING`, ошибка |
**Задачи:**
1. Выбрать окончательные `op` имена по текущему стилю API, чтобы не ломать существующий клиент.
2. Согласовать поля/ответы/ошибки, зафиксировать в `docs/API/` **до редактирования реализации**.
3. Интегрировать `RegistrarSigner`, Turbo uploader, импортёр и logical identity DAO.
4. Не помещать приватные пользовательские ключи в requests/responses. Не отдавать приватный registrar key.
5. Любую выдачу завершать только после валидного signed DataItem и успешного локального импорта.
6. Возвращать явный статус `Turbo accepted, chain confirmation pending` без обещания финального подтверждения.
7. Сделать обработку ошибочного/отменённого запроса, потерянного ответа и retry.
8. Добавить unit/integration tests handler и документированные errors.
**Готово, когда:** WS-клиент может пройти free-регистрацию и получить подтверждённую локальную идентичность без UI.
## ЭТАП 10. Сервер: единая авторизация и реальные ограничения `FREE_CERT`
**Зависимость:** этапы 5, 8, 9.
**Изменить:** `.../handlers/auth/{SolanaUserPdaImportService,Net_ResolveLoginForAuth_Handler,Net_CreateAuthSession__Handler}` и соседние обработчики, `CurrentUsersDAO`, `UserAccessServersCurrentDAO`, `.../handlers/keyRotation/`, соответствующие docs/API.
**Задачи:**
1. Определить единый объект `ResolvedIdentity`: fullLogin, root/client/blockchain public keys, source, status, namespace, accessServer, hasSolanaPda.
2. Разрешить login как через PDA, так и через сертификат; обе ветки выдают общую структуру авторизации, но не одинаковые права.
3. Проверять пароль локально через получение ключей, а серверу предоставлять существующие криптографические proofs; сервер не получает пароль или приватные ключи.
4. До upgrade routing `FREE_CERT` берёт сервер из namespace. После upgrade — из пользовательского PDA.
5. Закрыть все варианты server-side смены ключей, access server и fork rotation для free (искать как прямые обработчики, так и фоновые сервисы/обходные API).
6. Убедиться, что бесплатные могут создавать подписанные блоки, читать/писать в каналах и работать с direct messages как обычные пользователи.
7. Не использовать «наличие строки в solana_user_pda_current» как единственный признак существования человека в общих обработчиках.
8. При upgrade переключать источник полномочий без потери session, graph, messages, user profile, saved files.
**Готово, когда:** free/paid login и работа с контентом функционируют; попытки обойти ограничения free отвергаются именно сервером.
## ЭТАП 11. UI: выбор типа регистрации, формы и мгновенный вход
**Зависимость:** этапы 4, 9 и 10.
**Изменить:** `shine-UI/js/pages/{register-view,registration-payment-view,registration-draft-keys-view,login-view,settings-view,key-rotation-view}.js`, `js/state.js`, `js/router.js`, `js/services/solana-register-service.js`. При необходимости создать `registration-method-view.js`, `registration-email-view.js` и собственный контролируемый onboarding step.
**Задачи:**
1. Первый экран: «Через Solana» или «Бесплатно»; UI не диктует namespace из захардкоженных названий.
2. Drop-down подгружает on-chain namespace list, показывает fee/min/type и разрешает выбирать соответствующие способу регистрации.
3. Пользователь вводит localPart и видит `localPart@namespace`; длина проверяется включая суффикс. Старые 20/8 и premium/promo form logic отключить в новой ветке.
4. Локальная генерация keyBundle из **полного имени и пароля**, одинаковая для free/direct paid/последующего входа.
5. Бесплатный flow: public keys + email → экран с текстом «Тест: код 1111; письмо не отправляется» → server-confirm → Turbo ACK → локальный sign-in.
6. Любая ошибка Turbo/сети **не должна заставлять генерировать новые ключи** или терять корректно введённый логин/пароль до понятного завершения процесса; обеспечить осознанную очистку чувствительного UI state.
7. Платный flow использует новую транзакцию, цену namespace и текущую существующую оплату.
8. У free отображается статус, фиксированный access server, ограничения ключей и будущая кнопка перехода в Solana.
9. Сохранить текущую архитектуру UI из `shine-UI/AGENTS.md`: App/Router единственный mount owner, shared components, никакого нового UI-framework.
10. Обновить FAQ, подсказки и ошибки; не обещать, что Arweave окончательно подтвердил запись при одном Turbo ACK.
**Готово, когда:** новый человек может пройти paid или free регистрацию и войти с обычного экрана без ручных CLI/WS команд.
## ЭТАП 12. Upgrade UI и end-to-end free → Solana без смены личности
**Зависимость:** этапы 3, 4, 6, 10, 11.
**Изменить:** `shine-UI/js/services/shine-user-pda-service.js`, `shine-UI/js/pages/settings-view.js` (или отдельная `registration-upgrade-view.js`), серверный статус identity при Solana sync.
**Задачи:**
1. Кнопка «Зарегистрировать аккаунт в Solana» видна только `FREE_CERT`.
2. Показать **сумму из namespace type2**, получаемую из Solana, а не старую цену economy.
3. Прочитать сохранённый подписанный сертификат; предъявить **внутреннюю** подпись и идентификационные поля.
4. Использовать существующие три ключа пользователя. Root + blockchain подписывают актуальную запись PDA по правилам Solana; registrar private key не участвует в upgrade.
5. Сформировать новую Solana транзакцию; оплатить PDA и комиссию; дождаться корректного on-chain результата.
6. Синхронизация связывает PDA с **тем же normalized full login**; меняет регистрацию на `PAID_UPGRADED` без новой logical-user строки.
7. Не сбрасывать старые Arweave блоки, used bytes, channel ownership, connections, profile, DM адресацию, session state.
8. В интерфейсе после синхронизации показывать «Зарегистрирован в Solana», разрешать обычную key rotation/access-server operations.
9. Если Solana транзакция упала или UI перезагрузился — пользователь остаётся бесплатным, сертификат и история сохранены, повторная попытка безопасна.
**Готово, когда:** пользователь Bob создал публикации/канал будучи free, оплатил Solana и затем видит все старые данные теми же ключами и именем.
## ЭТАП 13. Сквозные тесты, тестовый релиз и выпускная проверка
**Зависимость:** этапы 0–12.
**Стенд:** localnet/devnet Solana; отдельная тестовая PostgreSQL; тестовый сервер SHiNE; Turbo (помнить, что публикация может быть реальной и долговечной); второй независимый тестовый сервер.
**Сценарии приёмки:**
1. `create_namespace(@shine, type1)` и `create_namespace(@free, type2)` выполняет upgrade authority; посторонний отклонён.
2. Economy init разрешён любому, update только upgrade authority.
3. Серверный аккаунт регистрируется полноценным full login и имеет доступный server profile; free namespace ссылается на реально разрешаемый сервер.
4. `alice@shine` direct paid: PDA создан, сумма правильная, вход/профиль/публикации работают.
5. `bob@free`: три пары ключей генерируются локально, код 1111 принят, внутри и снаружи подпись правильная, email hash опубликован без email.
6. Turbo ACK → быстрый локальный импорт → вход Bob **без ожидания Arweave height**.
7. Независимый сервер импортирует Bob через Arweave и распознаёт тот же namespace/identity.
8. Повторный login/email отклоняется, повторный импорт того же DataItem идемпотентен.
9. Подменённый inner signature/root/client/blockchain/namespace/owner не проходит.
10. Bob не может менять ключи/access server до оплаты, включая прямой серверный вызов.
11. Bob создаёт профиль, публикацию, канал, связь и сообщение до Solana PDA.
12. Bob делает платный upgrade с сертификатом. Проверяются адрес PDA, fee, неизменность имени/3 ключей/блоков и отсутствие дублирующего пользователя.
13. После upgrade доступны штатные операции PDA/update/key rotation/access-server (по существующим ограничениям).
14. Перезапуск каждого сервера, новая БД + snapshot, обработка GraphQL повторно, задержка Turbo и Solana RPC не портят данные.
15. Две цены namespace ведут к двум разным корректным платежам.
16. Старые экраны, каналы, ссылки, DM, websocket auth, поиск, статистика и публикации не деградируют.
17. Проверить все места `getProgramAccounts`/PDA derivation; old seed не используется для **новых** регистраций.
18. Фактические сборки и тесты Rust/JS/Java, списки skip/fail, ручной smoke browser.
19. Обновлены документы Solana, DB, sync, API и runbooks. Разрешения на изменение API/формата соблюдены.
20. Все runtime secrets вне Git/logs/browser и test fixtures. Секрет регистратора не возвращается ни одним API.
**Только после этого:** отдельная подготовка к production, backup и план переключения. Сам факт прохождения devnet **не является разрешением** деплоя на боевой контур.
---
# Д. ОСОБЫЕ ЗАВИСИМОСТИ И СЛОЖНЫЕ УЧАСТКИ
## Д1. Первоначальное развёртывание — устраняем «курица или яйцо»
Один бесплатный namespace содержит **полный login сервера доступа**, а сервер сам является user PDA. Поэтому при развёртывании чистого проекта придерживаться порядка:
1. Deploy тестовой `shine_users`, затем economy init.
2. Upgrade authority создаёт платный namespace, например `@shine`.
3. Создать **платный серверный аккаунт** с полным именем вроде `server@shine`, оформить ServerProfileBlock и адрес сервера.
4. Настроить в тестовом сервере публичный/временный приватный registrar key.
5. Upgrade authority создаёт `@free` type2, указывая public registrar key и **уже зарегистрированный** `server@shine`.
6. Синхронизировать namespaces/server account во всех тестовых серверах; только после этого открывать бесплатную регистрацию.
Иначе free-пользователи получат несуществующий access-server login и не смогут подключаться.
## Д2. Данные после перехода free → paid
Создание Solana PDA — это **изменение статуса идентичности**, не новое начало пользовательского блокчейна. В E2E сравнивать до/после как минимум: fullLogin, 3 ключа, hash последнего блока, количество/ID публикаций, каналов, связей, значение used bytes, доступность DM. Не менять `blockchain_name` произвольно.
## Д3. Консистентность подписей
`inner signature` подтверждает только идентичность (имя + 3 публичных ключа), а **не email**. Solana проверяет `inner_message`, а не внешний DataItem и не email hash. Сервер, импортирующий Arweave, проверяет **обе** подписи и наличие email hash. Изменение email hash без нового ANS-104 DataItem изменит внешнюю подпись/ID, но не внутреннюю; это ожидаемое разделение функций.
## Д4. Синхронизация Solana против Arweave
Источник on-chain регистрации — Solana PDA. Источник бесплатной регистрации — подписанный Arweave DataItem. Локальная PostgreSQL — **индекс и рабочая проекция**, не третий независимый источник правды. При рестарте восстанавливать один и тот же логический набор. До Arweave confirmation локальная видимость законна после Turbo ACK, но межсерверная не обязана быть мгновенной.
## Д5. Нельзя оставлять обход для free-ограничений
Не ограничиваться disabled-кнопками. Free identity должна быть read-only по части **ротируемых прав** во всех server-side обработчиках. Для платного пользователя управление изменениями выполняется через существующий Solana PDA; нужно проверять, что после upgrade не осталось fallback на старый free certificate как источник прав смены ключей.
## Д6. Legacy программы и история
В этой версии нет миграции старых коротких Solana логинов. Не удалять старые PDA «для чистоты», не пересоздавать production. Удаление `promo_seller` из новой логики не означает обязательного удаления существующих PDA в блокчейне или программы `shine_login_guard`; это отдельное решение.
## Д7. Правила, которые не стоит молча менять
- Цена едина для всех имён одного namespace, нет premium tiers.
- Подпись регистратора не включает email.
- Один физический источник подписи пока программный.
- Код подтверждения строго `1111` и явно маркирован тестовым.
- Namespace creation через upgrade authority, economy-init остаётся открытым.
- Нет исправления угрозы украденного registrar key.
- Не меняются три ключа, логин, пользовательская цепочка при upgrade.
- До upgrade сервер доступа определяется только namespace.
Если рабочий код требует продукта, меняющего эти правила, **остановиться только по конкретному архитектурному противоречию**, не изобретать новый продукт. Мелкие инженерные вопросы решать в соответствии с протоколом и фиксировать в документации.
---
# Е. ПОШАГОВАЯ МАТРИЦА РЕЗУЛЬТАТОВ
| № | Выходной артефакт | Не начинать без | Минимальный тест готовности |
|---:|---|---|---|
| 0 | Исходный аудит и status file | Архив/репо | baseline и карта SQL зависимостей |
| 1 | Протокол + fixtures | 0 | одинаковые байты Rust/Java/JS |
| 2 | create namespace + authority | 1 | 2 namespace, чужой signer отклонён |
| 3 | Solana register 2 types | 2 | on-chain create paid/free-upgrade |
| 4 | JS codecs, tx builder | 3 | сериализация, реальные Solana tests |
| 5 | Unified PostgreSQL identity | 1, 3 | free identity без fake PDA |
| 6 | Sync Solana | 3, 5 | snapshot/history = одинаковая БД |
| 7 | Registrar signer stub | 1, 5, 6 | 2 подписи валидны |
| 8 | Arweave registration importer | 5–7 | локально сразу, второй сервер потом |
| 9 | WS free registration API | 7–8 + API approval | успешный WS flow |
| 10 | Auth/free permissions | 5, 8, 9 | login works, rotation blocked |
| 11 | UI registration | 4, 9, 10 | free и paid через браузер |
| 12 | UI upgrade | 3, 4, 6, 10, 11 | free→paid без новых данных |
| 13 | E2E / devnet / release checks | 0–12 | full regression suite |
**Условие завершения:** одно слово «готово» ничего не означает без доказанных тестов и списка изменённых файлов.
---
# Ж. СТАНДАРТНЫЙ ОТЧЁТ ПОСЛЕ КАЖДОГО ЭТАПА
В конце каждого этапа исполнитель обязан заполнить текст ниже и сохранить в `docs/registration-v2/IMPLEMENTATION_STATUS.md` (или приложить файл, если исходный репозиторий на этом этапе недоступен):
```text
SHiNE Registration V2 — журнал выполнения
Дата и время:
Базовая ветка / коммит / архив:
Этап №:
Статус: COMPLETED / PARTIAL / BLOCKED / NOT STARTED
1. Что было поручено:
2. Что реально изменено (полный список файлов):
3. Новые форматы / op codes / DB migrations / конфиги:
4. Команды сборки и тестов + результаты:
5. Ручная проверка и её фактический результат:
6. Что НЕ сделано или не проверено:
7. Совместимость с уже завершёнными этапами:
8. Обновлённые документы:
9. Коммит(ы) / diff / ссылка на патч:
10. Риски / открытые технические проблемы:
11. Следующий конкретный этап №:
12. Где следующий исполнитель должен начать чтение:
13. Нужны ли дополнительные разрешения по AGENTS.md:
Запрещено:
- считать partial этап завершённым;
- утверждать, что тесты прошли, если они не запускались;
- раскрывать секреты и реальные приватные ключи;
- деплоить production без согласования;
- менять формат пользовательских блоков незаметно;
- брать новую архитектуру «из головы» вместо этого документа.
```
**Контроль перед началом новой сессии:** открыть этот журнал, прочитать решения из раздела А, проверить статус этапов, продолжать с первого незавершённого этапа. Если исходник изменился, сначала обновить карту файлов и тестовые ожидания.
---
# З. КОНЕЧНАЯ ПРИЁМКА ПРОЕКТА
Работа завершена только если одновременно верно следующее:
- `[ ]` У каждого аккаунта формат полного логина `login@namespace`.
- `[ ]` Namespace-PDA обоих типов читаются любым сервером/клиентом.
- `[ ]` Namespace создаёт только действующая upgrade authority.
- `[ ]` Update economy контролируется upgrade authority; init economy остался публичным.
- `[ ]` PDA seed использует SHA-256, 32 сырых байта и полное имя.
- `[ ]` У paid direct есть полноценный PDA; цена берётся из namespace.
- `[ ]` Бесплатный DataItem содержит публичные ключи, две подписи и хеш email, но не секреты.
- `[ ]` Сертификат проходит внутреннюю Solana проверку и внешнюю ANS-104 проверку.
- `[ ]` Free user появляется локально после Turbo ACK без ожидания Arweave height.
- `[ ]` Другие серверы догоняют через Arweave sync, не создавая дублей.
- `[ ]` Free user реально входит и пользуется каналами/публикациями/связями/сообщениями.
- `[ ]` У free нельзя сменить ключи или access server через UI и через сервер.
- `[ ]` Free user платит за создание PDA, предъявляет сертификат и получает status paid.
- `[ ]` После upgrade сохраняются логин, три ключа, блокчейн, история, каналы, связи.
- `[ ]` Нет `shine_login_guard`/`promo_seller` в новом registration flow.
- `[ ]` Тестовые ошибочные подписи, суммы, seed, дубли и retry обрабатываются корректно.
- `[ ]` PostgreSQL migration/restart и Solana snapshot/history восстанавливают одинаковую картину.
- `[ ]` Документация соответствует Rust/Java/JS и текущему коду API.
- `[ ]` Тестовый стенд пройден; production не тронут без отдельного разрешения.
**Финальное правило:** если новая регистрация работает, но пользователь теряет прежние данные при upgrade, **патч не готов**. Сохранение единой личности — центральное требование всей работы.