# Интеграция Solana users sync в сервер SHiNE Этот документ фиксирует серверную конфигурацию модуля синхронизации `shine_users` и базовую инициализацию новой PostgreSQL runtime-схемы сервера. ## Что уже есть - основной сервер сначала инициализирует полную PostgreSQL runtime-схему SHiNE, затем запускает `SolanaUsersSyncStartupService` до продолжения startup; - модуль синхронизации держит актуальными таблицы: - `solana_sync_state` - `solana_sync_tx_history` - `solana_user_pda_current` - `user_access_servers_current` - `solana_user_pda_history` - источник истины по пользовательским PDA: `solana_user_pda_current`. - в `solana_user_pda_current` хранятся оба варианта логина: - `login` — display-логин из PDA; - `normalized_login` — канонический lower-case для runtime lookup и части FK; - `user_access_servers_current` — это вторичная локальная проекция для быстрого роутинга DM по access servers; она автоматически пересобирается из `solana_user_pda_current`, включая backfill для уже существующих пользователей. ## Что должно быть настроено в `application.properties` Для текущих production-значений `shineup.me` и `server2.shineup.me` смотреть `deploy/PRODUCTION_SERVERS.md`. Ниже универсальный пример для нового контура. ```properties solana.users.sync.enabled=true solana.users.sync.rpcUrl=https://devnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY solana.users.sync.wsUrl=wss://devnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY solana.users.sync.databaseUrl=jdbc:postgresql://127.0.0.1:5432/ solana.users.sync.dbUser= solana.users.sync.dbPassword=CHANGE_ME solana.users.sync.pollIntervalSeconds=300 ``` Замечания: - `solana.users.sync.enabled=true` обязателен, иначе сервер пропустит startup sync. - `solana.users.sync.databaseUrl` должен указывать на ту же PostgreSQL БД, где создана серверная runtime-схема. - `solana.users.sync.wsUrl` задаётся явно, автоматически из `rpcUrl` не строится. - `YOUR_HELIUS_API_KEY` — плейсхолдер. Замените его в приватном серверном `application.properties`, а не в Git. Ключи из репозитория и прежних UI-деплоев рекомендуется перевыпустить. ## Как создать пустую PostgreSQL runtime БД SQL-скрипт инициализации лежит в: ```text SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql ``` Пример запуска: ```bash psql \ "postgresql://:CHANGE_ME@127.0.0.1:5432/" \ -f SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql ``` Скрипт предназначен **только для полностью пустой PostgreSQL схемы**. На старой/непустой базе он завершится ошибкой и не выполняет in-place migration. При обычном первом запуске вручную выполнять его не нужно: сервер сам первым создаёт полную runtime-схему, и только затем стартует Solana sync; это не даёт sync-таблицам ошибочно выглядеть как legacy-БД. Скрипт: - создаёт жёсткий маркер поколения БД `shine_database_metadata`: `SHiNE_DB_V2`, generation `2`; - создаёт таблицу версии runtime-схемы `db_schema_version` и ставит `schema_version=29`; - создаёт таблицы sync-модуля Solana users; - создаёт server runtime tables; - создаёт триггеры и функции автоматической актуализации `user_access_servers_current`; - не создаёт удалённые legacy-таблицы старого runtime для пользователей и DM; - использует `signed_messages` как единственную таблицу серверных DM. ## Как поднять PostgreSQL в Docker Шаблоны лежат в: ```text deploy/postgres/docker-compose.yml.example deploy/postgres/.env.example ``` Минимальная последовательность: ```bash mkdir -p /home/player/SHiNE/postgres cp deploy/postgres/.env.example /home/player/SHiNE/postgres/.env cp deploy/postgres/docker-compose.yml.example /home/player/SHiNE/postgres/docker-compose.yml cd /home/player/SHiNE/postgres docker compose up -d ``` Шаблон `deploy/postgres/docker-compose.yml.example` рассчитан на `postgres:18`. Для `postgres:18+` он монтирует host-каталог в `/var/lib/postgresql`, это важно для корректного старта контейнера. После старта контейнера: ```bash cp /path/to/SHiNE-product/application.properties ./application.properties # задать db.url/db.user/db.password и запустить сервер ``` Сложность тут низкая: - сам Docker Postgres поднимается просто; - сервер сам создаёт runtime schema v1, если БД пустая и в ней нет `db_schema_version`; - основная аккуратность нужна в паролях, bind-mount каталоге и backup; - для SHiNE важно не открывать `5432` наружу, только `127.0.0.1:5432`. ## Что пока остаётся как есть - runtime-сервер работает с PostgreSQL; - межсерверная доставка DM остаётся отдельным механизмом и не связана с blockchain sync; - прямой blockchain sync через `sync_servers` отключён: пользовательские блоки синхронизируются через Arweave. ## Совместимость с user PDA 1.2 После обновления `shine_users` серверный модуль `shine-server-solana-users-sync` должен обновляться вместе с программой: текущий codec принимает только PDA 1.2. Legacy PDA 1.0 не мигрируются; тестовые legacy-записи можно закрыть временной инструкцией `close_legacy_pda`. Миграция PostgreSQL v25 добавляет `blockchain_forks_json`. Старые compatibility-колонки продолжают содержать активный (последний) fork, а полный список ключей fork сохраняется отдельно и используется для поиска владельца Arweave-записей по любому историческому blockchain key. ## PostgreSQL migration v26: key rotation runtime state Migration v26 добавляет server-local поля `rotation_status` / `rotation_session_id` в `solana_user_pda_current` и таблицу `key_rotation_sessions`. Это локальное состояние длительной смены ключей, а не часть Solana PDA. Solana users sync продолжает обновлять только PDA-поля и не должен затирать rotation-state. После обновления сервера миграция применяется стандартным `DatabaseInitializer` автоматически. ## Миграции key rotation При обновлении сервера DatabaseInitializer последовательно применяет migration v26 (state machine смены ключей) и v27 (отдельные candidate-блоки будущего fork). Ручного создания таблиц не требуется. Candidate-блоки не входят в текущую таблицу `blocks` до финального переключения fork. ## Этапы регистрации V2 4–7: подготовка тестового окружения (23.10.2026) Перед запуском новой синхронизации нужен тестовый `shine_users` (opcode 7, namespace accounts), применённая PostgreSQL v33, бэкап и отдельная БД. Только после этого разрешён импорт namespace в отдельный регистр `shine_namespace_current`. Не совмещать с существующим UI/production. `freeRegistration.enabled` по умолчанию false; `freeRegistration.registrarSeedFile` — локальный secret path (Base64 seed32) вне Git. При несоответствии регистратора публичному ключу on-chain namespace выдача сертификата прекращается. Нет Arweave importer до этапа 8, API/UI до этапов 9–10. Сначала прогоните чистый snapshot, историю, restart/replay, FK и ключевую ротацию на тестовом контуре. ## DB v35: единый платный статус (26.10.2026) `DatabaseInitializer` при запуске сервера последовательно обновляет схему до v35. Старые `PAID_DIRECT` и `PAID_UPGRADED` преобразуются в единый `PAID`; `FREE_CERT` не изменяется. Любой новый пользователь с настоящей PDA Solana получает `PAID` независимо от способа регистрации. Данные аккаунтов, Arweave-сертификаты, начальная дата регистрации и ключи не удаляются. Порядок на тестовом контуре: резервная копия БД → обновление серверного кода с `migration_v35.sql` → перезапуск и проверка `db_schema_version=35` → обновление UI → пробная регистрация и upgrade. До обновления сервера или при неудачной миграции оставьте существующий UI: новое значение `PAID` должно приходить только от сервера с применённой v35. На production — отдельное согласование. Для проверки статусов после миграции: ```sql SELECT registration_status, count(*) FROM user_identity_current GROUP BY registration_status; SELECT schema_version FROM db_schema_version WHERE id=1; ``` ## Регистронезависимый логин (2026-10-28) Для новых баз важно совместное обновление программы `shine_users`, Java Solana sync/архива и UI. После обновления `login` внутри PDA сохраняет регистр, а адрес и `normalized_login` используют lowercase. Перед проверкой смешанного регистра заново инициализируйте **тестовую** БД и разверните обновлённую Solana-программу в devnet; сам ZIP её не разворачивает. ## 2026-10-28 — Неизменяемый регистр логина (PostgreSQL v37) - В `user_identity_current.login` хранится **написание первой регистрации**, включая заглавные буквы. В `normalized_login` — его lowercase-форма для поиска и уникальности. - v37 добавляет BEFORE INSERT/UPDATE-проверку: `normalized_login = lower(btrim(login))`, а после создания идентичности оба поля неизменяемы. - `shine_sync_identity_from_solana()` отклоняет PDA, если для того же нормализованного имени его `login` не совпадает **точно** с Arweave-сертификатом или предыдущей регистрацией. При FREE_CERT → PAID нельзя изменять только регистр. - Сервер перед первым `AddBlock` сверяет HEADER с точным `user_identity_current.login`; нормализованное имя цепочки этому не противоречит. - Никакого преобразования существующих signed-блоков нет; новая тестовая эпоха создаётся с чистой БД и без старых HEADER. ## PostgreSQL v38: ключ blockchain state После обновления сервера `DatabaseInitializer` автоматически применит migration v38 и при старте нормализует `blockchain_state_store.blockchain_key` из исторического Base58 в Base64(32). Ручной SQL-апдейт для free-пользователей не нужен. После запуска проверьте, что первый `AddBlock` нового free-пользователя проходит без `BAD_BLOCKCHAIN_KEY_LEN`. ### Обновление namespace registration_fee / currency_code Серверная БД мигрирует v39→v40 (колонка `shine_namespace_current.currency_code`). Перед активацией нового контракта следует установить совместимый сервер-sync: новый opcode 8 индексируется через историю economy PDA, namespace 1.0/1.1 читаются совместимо, `UPSERT` обновляет цену вместо прежней ошибочной проверки `raw_data_base64 = EXCLUDED.raw_data_base64`. Проверить `GetNamespaces` и `CheckRegistrationLogin` после подтверждения транзакции; при задержке history polling информация может обновиться не мгновенно.