SHA256
721 lines
82 KiB
Markdown
721 lines
82 KiB
Markdown
# 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=test5591` плюс отдельный тег типа `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, **патч не готов**. Сохранение единой личности — центральное требование всей работы.
|