SHiNE-server/docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md

Модуль синхронизации shine_users из Solana

Назначение

Этот модуль нужен для локальной серверной синхронизации всех пользовательских PDA программы shine_users.

Цель модуля:

• при старте получить актуальное состояние всех пользовательских PDA;
• дальше держать локальную копию в актуальном состоянии;
• хранить историю просмотренных транзакций синхронизации;
• хранить историю всех версий пользовательских PDA;
• уметь после рестарта продолжать синхронизацию без потери изменений;
• в будущем без большого переписывания встраиваться в основной SHiNE-сервер и блокировать дальнейший startup до входа в состояние READY.

На текущем этапе модуль должен запускаться как отдельный Java-процесс со своим main, но внутренняя структура должна быть такой, чтобы потом его можно было перенести в сервер как обычный lifecycle-сервис.

---

Базовая идея

Модуль использует два источника данных:

1. realtime-поток через Solana WebSocket programSubscribe для программы shine_users;
2. историю транзакций через getSignaturesForAddress(economy_config_pda).

Ключевая договорённость:

• каждая транзакция, которая создаёт или обновляет пользовательский user_pda, обязательно читает users_economy_config_pda;
• значит, история по users_economy_config_pda является полным журналом всех релевантных create/update user_pda транзакций;
• дополнительные транзакции, которые тоже читают или меняют users_economy_config_pda, допустимы и не мешают: модуль должен уметь распознавать, что такая транзакция не относится к изменению пользовательского PDA.

users_economy_config_pda вычисляется из:

• program_id = SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6
• seed = shine_users_economy_config

Источник в коде контракта:

• settings::USERS_ECONOMY_CONFIG_SEED = b"shine_users_economy_config"
• create_user_pda и update_user_pda принимают users_economy_config_pda как обязательный аккаунт.

---

Что считается состоянием готовности

Модуль должен иметь внутреннее состояние готовности READY.

В READY он входит только после того, как:

1. установлено websocket-подключение;
2. выполнена начальная актуализация истории;
3. локальная таблица актуальных PDA приведена в консистентное состояние;
4. таблица состояния синхронизации обновлена.

Пока модуль не вошёл в READY, будущий сервер при встраивании не должен продолжать собственный startup.

Для этого модуль должен поддерживать:

• start()
• awaitReady()
• isReady()
• close()

Для отдельного процесса main допустимо также печатать явный лог о входе в READY, но главным механизмом для будущего сервера должен быть Java API, а не парсинг логов.

---

Почему нельзя опираться только на WebSocket

WebSocket programSubscribe хорош для realtime, но недостаточен как единственный источник истины:

• если websocket временно оборвался, часть событий может быть пропущена;
• если соединение формально живо, но какое-то событие было потеряно, это не всегда можно заметить сразу;
• если в интервале не было транзакций, websocket по определению ничего не пришлёт.

Поэтому нужен второй защитный контур:

• периодический аудит истории по users_economy_config_pda;
• запуск такого аудита раз в 5 минут.

---

Общий lifecycle модуля

1. Старт процесса

При старте процесса модуль:

1. читает конфиг;
2. инициализирует локальную PostgreSQL БД;
3. создаёт RPC-клиент;
4. создаёт WebSocket-клиент;
5. создаёт coordinator/service слой;
6. запускает realtime-подписку;
7. после подтверждённой подписки выполняет начальную актуализацию истории;
8. после успешной актуализации выставляет READY.

2. Работа в фоне

После входа в READY модуль одновременно:

• принимает realtime-обновления по websocket;
• раз в 5 минут запускает проверку истории через RPC;
• пишет журнал транзакций;
• пишет историю версий пользовательских PDA;
• обновляет актуальный снимок пользовательских PDA.

3. Реконнект

Если websocket оборвался:

1. запускается reconnect;
2. после успешного переподключения выполняется повторная актуализация истории;
3. модуль снова возвращается в нормальный режим.

4. Остановка

При остановке:

• закрывается websocket;
• останавливаются фоновые scheduler/worker потоки;
• закрывается RPC-клиент;
• закрывается БД.

---

Источник истории: только по сигнатурам

Основной checkpoint модуля должен строиться по сигнатурам транзакций, а не по времени.

Хранить нужно:

• последнюю просмотренную сигнатуру;
• последний просмотренный слот;
• последнюю релевантную сигнатуру;
• время последней успешной актуализации.

Время хранится только как вспомогательная диагностика. Продолжение истории должно идти по сигнатурам и слотам.

---

Поведение начальной актуализации

Сценарий A: локальная БД пустая

Если локальная БД ещё не содержит синхронизированных данных:

1. выполняется первичная загрузка пользовательских PDA;
2. после этого фиксируется начальная точка истории;
3. модуль переходит в READY.

Предпочтительный вариант:

• использовать историю транзакций по users_economy_config_pda как основной механизм синхронизации;
• full snapshot всех program accounts остаётся аварийным fallback, а не штатным путём.

Сценарий B: локальная БД уже есть

Если БД не пуста:

1. берётся последняя обработанная сигнатура;
2. через getSignaturesForAddress(users_economy_config_pda) вытягивается история после неё;
3. новые транзакции разбираются и применяются;
4. после этого модуль входит в READY.

Сценарий C: новых транзакций не было

Если после последней сигнатуры новых транзакций нет:

• это не ошибка;
• модуль всё равно обновляет last_poll_at и last_successful_poll_at;
• фиксирует, что актуализация успешно проверена;
• может переходить в READY.

---

Периодическая актуализация раз в 5 минут

Каждые 5 минут модуль должен:

1. вызвать getSignaturesForAddress(users_economy_config_pda);
2. получить новые сигнатуры после последней сохранённой точки;
3. сохранить все найденные транзакции в журнал истории;
4. выделить релевантные транзакции create/update user_pda;
5. для релевантных транзакций извлечь адрес PDA и логин;
6. подтянуть актуальное состояние затронутых PDA;
7. обновить:
   • solana_user_pda_current
   • solana_user_pda_history
   • solana_sync_state

Если новых транзакций нет:

• модуль ничего не меняет в зеркале PDA;
• но помечает, что polling выполнен успешно и состояние истории актуализировано.

---

Что делать с нерелевантными транзакциями

История должна храниться полностью, включая нерелевантные транзакции.

Примеры нерелевантных транзакций:

• update_users_economy_config
• служебные транзакции, где economy_config_pda присутствовал, но пользовательский user_pda не менялся

Такие транзакции:

• сохраняются в solana_sync_tx_history;
• помечаются is_relevant = 0;
• не приводят к обновлению пользовательских PDA.

Это важно для аудита и отладки.

---

Как распознавать тип транзакции

Для каждой транзакции из истории нужно определить её тип.

Минимальный набор типов:

• create_user_pda
• update_user_pda
• update_users_economy_config
• init_users_economy_config
• other

Также для каждой транзакции нужно определять:

• is_relevant = 1, если транзакция создаёт или обновляет пользовательский user_pda;
• is_relevant = 0, если это транзакция истории, но она не меняет пользовательские PDA.

Для релевантных транзакций нужно дополнительно извлекать:

• affected_pda_address
• affected_login

Если транзакция затрагивает несколько пользовательских PDA, архитектура должна не запрещать хранить несколько связей, но на первом этапе можно исходить из одной пользовательской записи на одну транзакцию, если это соответствует текущему контракту.

---

Локальные таблицы

Модуль должен использовать три основные таблицы.

1. solana_sync_state

Одна строка состояния синхронизации.

Назначение:

• хранить текущий checkpoint истории;
• хранить время последней успешной актуализации;
• хранить технический статус синка.

Пример полей:

• id INTEGER PRIMARY KEY CHECK (id = 1)
• status TEXT NOT NULL
• ready INTEGER NOT NULL DEFAULT 0
• last_poll_at_ms INTEGER
• last_successful_poll_at_ms INTEGER
• last_seen_signature TEXT
• last_seen_slot INTEGER
• last_relevant_signature TEXT
• last_relevant_slot INTEGER
• last_error TEXT
• updated_at_ms INTEGER NOT NULL

2. solana_sync_tx_history

Append-only журнал всех просмотренных транзакций по users_economy_config_pda.

Назначение:

• хранить полную историю опроса;
• фиксировать, какие tx были релевантны;
• хранить связь tx -> пользовательский PDA / login;
• упрощать аудит и диагностику.

Пример полей:

• signature TEXT PRIMARY KEY
• slot INTEGER NOT NULL
• block_time INTEGER
• tx_kind TEXT NOT NULL
• is_relevant INTEGER NOT NULL
• affected_pda_address TEXT
• affected_login TEXT
• processed_at_ms INTEGER NOT NULL
• raw_summary_json TEXT NOT NULL

Индексы:

• по slot
• по is_relevant
• по affected_login
• по affected_pda_address

3. solana_user_pda_current

Текущее актуальное состояние каждого пользовательского PDA.

Назначение:

• быстрый lookup текущих данных пользователя;
• будущая интеграция с сервером;
• опорная таблица для поиска текущих ключей и полей PDA.

Пример полей:

• pda_address TEXT PRIMARY KEY
• login TEXT NOT NULL
• record_number INTEGER NOT NULL
• slot INTEGER NOT NULL
• last_tx_signature TEXT NOT NULL
• blockchain_name TEXT NOT NULL
• blockchain_key TEXT NOT NULL
• client_key TEXT NOT NULL
• paid_limit_bytes INTEGER NOT NULL
• used_bytes INTEGER NOT NULL
• last_block_number INTEGER NOT NULL
• last_block_hash TEXT
• arweave_tx_id TEXT
• is_server INTEGER NOT NULL DEFAULT 0
• server_address TEXT
• sync_servers_json TEXT NOT NULL DEFAULT '[]'
• access_servers_json TEXT NOT NULL DEFAULT '[]'
• sessions_json TEXT NOT NULL DEFAULT '[]'
• trusted_count INTEGER NOT NULL DEFAULT 0
• created_at_ms INTEGER NOT NULL
• updated_at_ms INTEGER NOT NULL
• raw_data_base64 TEXT NOT NULL
• first_seen_at_ms INTEGER NOT NULL
• last_synced_at_ms INTEGER NOT NULL

Индексы:

• уникальный индекс на login
• индекс на slot
• индекс на last_tx_signature

4. solana_user_pda_history

Append-only история всех версий пользовательских PDA.

Назначение:

• хранить все старые публичные ключи и прочие поля прошлых версий;
• позволять видеть, когда и какая версия записи была актуальна;
• позволять разбирать изменения пользователя во времени.

Пример полей:

• id INTEGER PRIMARY KEY
• tx_signature TEXT NOT NULL
• slot INTEGER NOT NULL
• block_time INTEGER
• pda_address TEXT NOT NULL
• login TEXT NOT NULL
• record_number INTEGER NOT NULL
• blockchain_name TEXT NOT NULL
• blockchain_key TEXT NOT NULL
• client_key TEXT NOT NULL
• paid_limit_bytes INTEGER NOT NULL
• used_bytes INTEGER NOT NULL
• last_block_number INTEGER NOT NULL
• last_block_hash TEXT
• arweave_tx_id TEXT
• is_server INTEGER NOT NULL DEFAULT 0
• server_address TEXT
• sync_servers_json TEXT NOT NULL DEFAULT '[]'
• access_servers_json TEXT NOT NULL DEFAULT '[]'
• sessions_json TEXT NOT NULL DEFAULT '[]'
• trusted_count INTEGER NOT NULL DEFAULT 0
• created_at_ms INTEGER NOT NULL
• updated_at_ms INTEGER NOT NULL
• raw_data_base64 TEXT NOT NULL
• saved_at_ms INTEGER NOT NULL

Индексы:

• уникальный индекс на (pda_address, record_number)
• индекс на login
• индекс на slot
• индекс на tx_signature

---

Зачем нужны и current, и history

Нужны обе таблицы:

• solana_user_pda_current хранит только последнюю актуальную версию и удобна для быстрых запросов;
• solana_user_pda_history хранит все версии и нужна для расследований и просмотра старых публичных ключей.

При обработке новой релевантной транзакции:

1. новая версия всегда добавляется в solana_user_pda_history;
2. актуальная строка в solana_user_pda_current вставляется или обновляется.

---

Что именно считается “историей пользователя”

История нужна не для секретных паролей, а для публичных данных PDA.

В частности, история должна позволять видеть старые значения:

• client_key
• blockchain_key
• sessions
• access_servers
• sync_servers
• server_address
• других публичных полей PDA

Секретные приватные ключи или настоящие пользовательские пароли этот модуль не хранит и хранить не должен.

---

Логирование

Модуль должен использовать нормальный logger, а не System.out.println.

Требования к логированию:

• совместимость с будущей интеграцией в общие логи сервера;
• явные уровни INFO, WARN, ERROR, DEBUG;
• короткие, но диагностичные сообщения;
• каждый важный переход состояния должен логироваться.

Что обязательно логировать:

• старт процесса;
• чтение конфига;
• вычисление users_economy_config_pda;
• старт websocket-подписки;
• успешную подписку;
• начало initial sync;
• окончание initial sync;
• вход в READY;
• periodic poll;
• число найденных сигнатур;
• число релевантных tx;
• число обновлённых PDA;
• реконнекты websocket;
• ошибки RPC/WS;
• переход в FAILED, если он будет.

---

Конфигурация

В конфиге должны остаться только обязательные для постоянной эксплуатации параметры:

SOLANA_RPC_URL=
SOLANA_WS_URL=
SOLANA_PROGRAM_ID=SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6

DATABASE_URL=jdbc:postgresql://127.0.0.1:5432/shine_server_db
PGUSER=shine_server
PGPASSWORD=
SYNC_POLL_INTERVAL_SECONDS=300

Дополнительно:

• SOLANA_COMMITMENT не нужен как параметр;
• commitment должен быть зафиксирован в коде как confirmed;
• HELIUS_API_KEY не нужен;
• SOLANA_NETWORK не нужен.

---

Поведение при ошибках

Ошибка periodic poll

Если periodic poll не удался:

• это логируется как WARN или ERROR;
• solana_sync_state.last_error обновляется;
• модуль не должен сразу завершаться, если reconnect/retry ещё возможны.

Ошибка initial sync

Если initial sync не удался:

• модуль не должен выставлять READY;
• отдельный процесс должен завершаться с ошибкой или оставаться в FAILED, в зависимости от выбранного runtime-режима;
• при встраивании в сервер основной startup должен считаться неуспешным.

Аварийный fallback

Даже если основная логика опирается на историю по users_economy_config_pda, аварийный full snapshot всех user_pda можно оставить как последний защитный fallback на случай повреждённого или неполного RPC-ответа.

Но это должен быть именно крайний защитный сценарий, а не штатный рабочий путь.

---

Почему хранить всю tx-историю полезно

Полный журнал solana_sync_tx_history нужен не только для самого синка, но и для эксплуатации:

• видно, что именно вернул RPC;
• видно, какие tx были признаны релевантными;
• видно, какие tx были проигнорированы и почему;
• можно поднимать старые кейсы без повторного запроса в Solana;
• упрощается аудит и отладка после инцидентов.

---

Что должно получиться в итоге

В результате модуль должен работать так:

1. стартует как отдельный Java-процесс;
2. подписывается на realtime-обновления shine_users;
3. делает начальную актуализацию через историю users_economy_config_pda;
4. входит в READY;
5. раз в 5 минут делает дополнительный audit истории;
6. хранит:
   • состояние синка;
   • полную историю просмотренных транзакций;
   • актуальное зеркало всех пользовательских PDA;
   • историю всех версий пользовательских PDA;
7. после будущего переноса в SHiNE-сервер может использоваться как блокирующий startup-модуль:
   • сначала синхронизируется Solana;
   • потом сервер продолжает запуск остальных подсистем.

---

Следующий шаг реализации

После утверждения этого документа модуль нужно доработать в коде:

1. упростить конфиг;
2. заменить текущее логирование на logger;
3. выделить lifecycle-сервис с awaitReady();
4. реализовать вычисление users_economy_config_pda;
5. реализовать polling истории по сигнатурам;
6. добавить новые SQLite-таблицы;
7. добавить запись в current и history;
8. добавить periodic guard раз в 5 минут;
9. сохранить отдельный main для запуска как процесса.