SHA256
117 lines
5.2 KiB
Markdown
117 lines
5.2 KiB
Markdown
# Интеграция синхронизации `shine_users` в основной сервер
|
|
|
|
Этот документ описывает, что нужно для встраивания Solana sync-модуля пользовательских PDA в основной SHiNE-server.
|
|
|
|
Основной архитектурный документ:
|
|
|
|
- [docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md](/home/ai/work/SHiNE/SHiNE-server-sha256/SHiNE-product/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 сервера должен считаться неуспешным.
|
|
|
|
## Переменные окружения сервера
|
|
|
|
На сервере должны быть доступны:
|
|
|
|
```text
|
|
SOLANA_RPC_URL=
|
|
SOLANA_WS_URL=
|
|
SOLANA_PROGRAM_ID=SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6
|
|
SYNC_POLL_INTERVAL_SECONDS=300
|
|
```
|
|
|
|
Для PostgreSQL sync-модуль может использовать уже существующую server PostgreSQL-конфигурацию, если сервер уже предоставляет:
|
|
|
|
```text
|
|
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.
|