SHiNE-server/docs/Archive/README.md

SHiNE Archive Publisher — документация

Эта папка — актуальная точка входа для механизма серверной архивации SHiNE в Arweave с фиксацией archive head в Solana User PDA.

Если задачу выполняет другая нейронка/агент, читать документы нужно в таком порядке:

1. 01_PROTOCOL_v1.0.md — бинарный формат SHINE-ARCHIVE, big-block references, UserBlockchainChunk, подписи, PDA block 100, crash-safety.
2. 02_IMPLEMENTATION_MAP.md — как спецификация разложена по Java/Rust/JS/SQL файлам текущего проекта.
3. 03_DEPLOY_TEST_SERVER.md — полный порядок установки на тестовый сервер, включая обязательный апгрейд shine_users, конфиг, ключи, сборку и запуск.
4. 04_TEST_AND_OPERATIONS.md — что проверять до полуночи, после полуночи и при сбоях.
5. 05_PATCH_CONTENTS_AND_REMOVALS.md — какие файлы содержит пакет и какие legacy test-free-avatar файлы нужно удалить при наложении ZIP поверх старого исходника.
6. 07_ARCHIVE_IMPORT_AND_VIEWER.md — whitelist доверенных publisher-ов, импорт archive chain, индекс последнего chunk, UI и Blockchain-Viewer.html.
7. archive-publisher.example.properties — пример конфигурации publisher + importer.

Коротко

• Архиватор по умолчанию выключен: archive.publish.enabled=false.
• При включении создаёт новый snapshot один раз в сутки в заданное локальное время, по умолчанию 00:00.
• При первом успешном запуске, когда архивных курсоров ещё нет, в первый big block попадает всё локально известное состояние всех blockchain, начиная с source block 0.
• Далее публикуется только дельта.
• Один blockchain_name в одном big block представлен максимум одним UserBlockchainChunk; внутри него лежат все новые raw SHiNE records этой цепочки.
• В конце chunk одна ссылка на предыдущий chunk этой же blockchain. Если blockchain в текущем big block отсутствует, её cursor/head не меняется.
• Готовый файл сначала существует локально как <login>.<00001>.<dd.MM.yy>.tmp.SHiNE-archive. После успешной загрузки в Arweave он переименовывается в <login>.<00001>.<dd.MM.yy>.<REAL_ARWEAVE_TX_ID>.SHiNE-archive и остаётся локально.
• После Arweave confirmations обычным update_user_pda обновляется PDA block type 100: archive_tx_id[32] + archive_hash[32].
• Cursor commit выполняется только после Solana finalized.

Важно перед тестом

Изменён формат/парсер shine_users. Нельзя просто заменить серверный JAR и включить archive publisher, если целевая Solana-программа shine_users ещё не обновлена кодом из этого пакета. Сначала обновить программу на нужном кластере, затем сервер.

Импорт архивов других серверов

Импорт по умолчанию также выключен. Настройка:

archive.import.allowedPublishers=

Пустой список означает: не доверять архивам ни одного внешнего сервера. Для разрешения перечислить логины через запятую. Подробности — 07_ARCHIVE_IMPORT_AND_VIEWER.md.

Текущая схема БД: v23. v22 добавила publisher, v23 добавляет локальные archive_imported/archive_last_imported_tx_id, trusted importer и универсальный archive_blockchain_location.