SHiNE-server/deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md

Интеграция синхронизации shine_users в основной сервер

Этот документ описывает, что нужно для встраивания Solana sync-модуля пользовательских PDA в основной SHiNE-server.

Основной архитектурный документ:

• docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md

Что уже готово

Отдельный модуль sync-solana уже умеет:

• подключаться к Solana RPC и WebSocket;
• вычислять users_economy_config_pda;
• хранить checkpoint синхронизации в PostgreSQL;
• читать историю через getSignaturesForAddress(users_economy_config_pda);
• поддерживать realtime через websocket;
• выполнять страховочный periodic poll раз в 5 минут;
• хранить:
  • solana_sync_state
  • solana_sync_tx_history
  • solana_user_pda_current
  • solana_user_pda_history
• блокировать дальнейший startup до входа в READY.

Что нужно перенести в основной сервер

Из sync-solana в сервер нужно перенести рабочие классы:

• sync-solana/src/main/java/sync-solana/config/
• sync-solana/src/main/java/sync-solana/service/
• sync-solana/src/main/java/sync-solana/source/
• sync-solana/src/main/java/sync-solana/source/rpc/
• sync-solana/src/main/java/sync-solana/storage/postgres/
• sync-solana/src/main/java/sync-solana/codec/
• sync-solana/src/main/java/sync-solana/model/
• sync-solana/src/main/java/sync-solana/util/

Main.java нужен только как reference для bootstrap и как отдельный main в сервере уже не понадобится.

Рекомендуемый вариант:

• оформить это как отдельный Gradle submodule внутри SHiNE-server;
• запускать его из server startup как lifecycle-сервис.

Порядок запуска в сервере

При старте основного сервера последовательность должна быть такой:

1. прочитать общий server config;
2. создать Solana users sync service;
3. вызвать start();
4. вызвать awaitReady();
5. только после этого продолжать остальной startup сервера:
   • синхронизацию с другими нодами;
   • запуск WS/HTTP;
   • остальную серверную инициализацию.

Если Solana initial sync не дошёл до READY, startup сервера должен считаться неуспешным.

Переменные окружения сервера

На сервере должны быть доступны:

SOLANA_RPC_URL=
SOLANA_WS_URL=
SOLANA_PROGRAM_ID=SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6
SYNC_POLL_INTERVAL_SECONDS=300

Для PostgreSQL sync-модуль может использовать уже существующую server PostgreSQL-конфигурацию, если сервер уже предоставляет:

DATABASE_URL=
PGUSER=
PGPASSWORD=

Если в сервере используется другая схема конфигов, нужно сделать адаптер на уровне server config, а не менять саму логику sync.

Логи

Sync-модуль должен писать в общие server logs через тот же slf4j/logback, что и основной сервер.

Минимум, который должен быть виден в логах:

• старт sync-модуля;
• вход в READY;
• realtime sync;
• periodic poll;
• reconnect websocket;
• fallback на full snapshot;
• ошибки RPC/WS/DB.

Что потребуется по deploy

Отдельных deploy-скриптов для sync-модуля не требуется, если он встроен в основной server jar.

По deploy нужно:

• обновить server env/override-конфиг новыми переменными SOLANA_* и SYNC_POLL_INTERVAL_SECONDS;
• убедиться, что на сервере доступен PostgreSQL, в который модуль будет писать свои таблицы;
• при необходимости описать новые env в документации конкретного server-контура.

Что ещё проверить после интеграции

После встраивания в основной сервер нужно отдельно проверить:

• startup сервера с ожиданием awaitReady();
• создание таблиц в server PostgreSQL;
• initial sync после пустой БД;
• restart recovery после уже существующего checkpoint;
• realtime update через websocket;
• periodic poll без новых транзакций;
• fallback на full snapshot при потере history anchor.