Плагин snapshot

Плагин snapshot обеспечивает почти мгновенный запуск узла путём сериализации и восстановления полного состояния блокчейна в виде JSON-файла снапшота. Вместо реплея миллионов блоков из block log узел может загрузить заранее подготовленный снапшот и начать синхронизацию с этой точки через P2P.

---

Включение

plugin = snapshot

Или из командной строки:

vizd --plugin snapshot

---

Справочник конфигурации

Параметры только командной строки

Параметр	Тип	Описание
--snapshot <path>	string	Загрузить состояние из файла снапшота (DLT-режим). Пропускает импорт, если shared_memory.bin уже существует; переименовывает файл в .used после успешного импорта.
--snapshot-auto-latest	bool	Автоматически найти последний снапшот в snapshot-dir по номеру блока в имени файла. Игнорируется, если задан --snapshot.
--replay-from-snapshot	bool	Восстановление после сбоя: импортировать снапшот, затем воспроизвести dlt_block_log для достижения последнего доступного состояния. Всегда очищает разделяемую память; не переименовывает снапшот.
--auto-recover-from-snapshot	bool (по умолчанию: true)	Автоматическое восстановление при обнаружении повреждения разделяемой памяти. Закрывает БД, находит последний снапшот, очищает разделяемую память, импортирует и реплеит — без перезапуска.
--create-snapshot <path>	string	Создать снапшот из текущего состояния БД, затем завершить работу.
--sync-snapshot-from-trusted-peer	bool (по умолчанию: false)	Загрузить и применить снапшот от доверенных пиров при пустом состоянии. Требует явного включения.

Параметры конфигурационного файла

Параметр	Тип	По умолчанию	Описание
snapshot-at-block	uint32	0	Создать снапшот при достижении этого номера блока
snapshot-every-n-blocks	uint32	0	Создавать снапшот каждые N блоков (0 = отключено)
snapshot-dir	string	""	Каталог для автоматически генерируемых файлов снапшотов
snapshot-max-age-days	uint32	90	Удалять снапшоты старше N дней (0 = отключено)
allow-snapshot-serving	bool	false	Включить раздачу снапшотов по TCP другим узлам
allow-snapshot-serving-only-trusted	bool	false	Ограничить раздачу только доверенными пирами
snapshot-serve-endpoint	string	0.0.0.0:8092	TCP-адрес для раздачи снапшотов
trusted-snapshot-peer	string (multi)	—	Доверенный пир для синхронизации снапшотов (IP:port). Повторяемый.
dlt-block-log-max-blocks	uint32	100000	Количество последних блоков в скользящем DLT block log (плагин chain)

---

Создание снапшотов

Метод 1: Разовый (узел останавливается и завершает работу)

vizd --create-snapshot /data/snapshots/viz-snapshot.json --plugin snapshot

Узел открывает существующую БД, при необходимости выполняет реплей, создаёт снапшот и завершает работу до активации P2P.

Метод 2: В определённом блоке (без простоя)

plugin = snapshot
snapshot-at-block = 5000000
snapshot-dir = /data/snapshots

Когда применяется блок 5 000 000, снапшот записывается в /data/snapshots/snapshot-block-5000000.json в фоновом потоке — обработка блоков приостанавливается лишь на короткое время.

Метод 3: Периодические автоматические снапшоты (рекомендуется)

plugin = snapshot
snapshot-every-n-blocks = 100000
snapshot-dir = /data/snapshots

Снапшоты создаются каждые 100 000 блоков (~3,5 суток). Во время синхронизации снапшоты пропускаются — они срабатывают только на живых блоках.

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

Интервал	Блоков	Приблизительное время
Частый	10 000	~8 часов
Ежедневный	28 800	~24 часа
Еженедельный	100 000	~3,5 суток
Редкий	1 000 000	~35 суток

Ротация снапшотов

Старые снапшоты автоматически удаляются после создания каждого нового снапшота, если они старше snapshot-max-age-days (по умолчанию 90). Для отключения:

snapshot-max-age-days = 0

---

Загрузка из снапшота (DLT-режим)

vizd --snapshot /path/to/snapshot.json --plugin snapshot

Что происходит при загрузке:

1. Плагин snapshot регистрирует callback загрузки в плагине chain.
2. Плагин chain проверяет: если shared_memory.bin уже существует → пропускает импорт (защита от дублирования). Если файл снапшота не найден → пропускает импорт.
3. БД открывается через open_from_snapshot() — разделяемая память очищается, chainbase инициализируется.
4. Снапшот валидируется (версия формата, chain ID, контрольная сумма SHA-256) и все 32 типа объектов импортируются.
5. Файл снапшота переименовывается в .used.
6. LIB продвигается до head_block_num, чтобы P2P-синопсис начинался с head снапшота.
7. Fork-БД инициализируется head-блоком снапшота.
8. P2P начинает синхронизацию с LIB + 1.

Защита от дублирования при перезапуске

Сценарий перезапуска	Действие
1-й запуск (нет shared_memory, файл существует)	Импортирует снапшот, переименовывает в .used
Перезапуск (shared_memory существует)	Пропускает импорт
Перезапуск (shared_memory удалена, файл .used)	Пропускает импорт
Принудительный повторный импорт	--resync-blockchain + новый файл снапшота

Флаг --snapshot безопасно оставлять в командной строке постоянно.

---

Скользящий DLT block log

При работе в DLT-режиме (загружено из снапшота) основной block_log пуст. Отдельный скользящий DLT block log (dlt_block_log) хранит последние необратимые блоки.

• Позволяет раздавать блоки через P2P (пиры могут запрашивать недавние блоки для разрешения форков).
• Позволяет выполнять API-вызовы типа get_block для недавних блоков.
• Хранится в dlt_block_log.log и dlt_block_log.index в каталоге данных блокчейна.
• Скользящее окно: когда лог превышает dlt-block-log-max-blocks, старые блоки усекаются с начала.

dlt-block-log-max-blocks = 100000

---

Восстановление после сбоя: --replay-from-snapshot

Когда shared_memory.bin повреждён после некорректного завершения, используйте этот режим:

# Явно указать путь к снапшоту
vizd --replay-from-snapshot --snapshot /data/snapshots/snapshot-block-79273800.vizjson --plugin snapshot

# Автоматически найти последний снапшот
vizd --replay-from-snapshot --snapshot-auto-latest --plugin snapshot

Шаги восстановления:

1. Очищает shared_memory.bin (всегда — предполагается повреждение).
2. Импортирует состояние из снапшота.
3. Реплеит блоки dlt_block_log за head снапшота.
4. Возобновляет P2P-синхронизацию от реплеенного head.

Аспект	--snapshot	--replay-from-snapshot
Проверка разделяемой памяти	Пропускает если существует	Всегда очищает
Переименование снапшота	Переименовывает в .used	Не переименовывает
Реплей DLT block log	Нет	Да
Применение	Первоначальная загрузка	Восстановление после сбоя

---

Автоматическое восстановление: --auto-recover-from-snapshot

Включено по умолчанию (true). При обнаружении повреждения разделяемой памяти в процессе обработки или генерации блоков узел:

1. Закрывает БД.
2. Находит последний снапшот в snapshot-dir.
3. Очищает разделяемую память, импортирует снапшот, реплеит dlt_block_log.
4. Возобновляет P2P-синхронизацию — без перезапуска.

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

• plugin = snapshot должен быть включён.
• В snapshot-dir должны существовать снапшоты.

Для отключения (например, для отладки):

vizd --no-auto-recover-from-snapshot

---

P2P-синхронизация снапшотов

Узлы могут загружать снапшоты напрямую от доверенных пиров по TCP.

Конфигурация сервера

plugin = snapshot
allow-snapshot-serving = true
snapshot-serve-endpoint = 0.0.0.0:8092
snapshot-every-n-blocks = 28800
snapshot-dir = /data/viz-snapshots

Конфигурация клиента

trusted-snapshot-peer = seed1.viz.world:8092
trusted-snapshot-peer = seed2.viz.world:8092
trusted-snapshot-peer = seed3.viz.world:8092
sync-snapshot-from-trusted-peer = true

Клиент подключается к каждому доверенному пиру, выбирает тот, у которого наибольший номер блока, загружает снапшот частями по 1 МБ, проверяет контрольную сумму SHA-256 и импортирует его.

Меры безопасности: максимальный размер снапшота 2 ГБ, список доверенных пиров, ограничение скорости, 60-секундный дедлайн соединения, потоковая проверка контрольной суммы.

---

Формат файла снапшота

{
  "header": {
    "version": 1,
    "chain_id": "...",
    "snapshot_block_num": 12345678,
    "snapshot_block_id": "...",
    "snapshot_block_time": "2025-01-01T00:00:00",
    "last_irreversible_block_num": 12345660,
    "payload_checksum": "sha256...",
    "object_counts": { "account": 50000, ... }
  },
  "state": {
    "dynamic_global_property": [ ... ],
    "account": [ ... ],
    ...
  }
}

Включённые типы объектов (32 всего)

Критические (11): dynamic_global_property, witness_schedule, hardfork_property, account, account_authority, validator, witness_vote, block_summary, content, content_vote, block_post_validation

Важные (15): transaction, vesting_delegation, vesting_delegation_expiration, fix_vesting_delegation, withdraw_vesting_route, escrow, proposal, required_approval, committee_request, committee_vote, invite, award_shares_expire, paid_subscription, paid_subscribe, witness_penalty_expire

Опциональные (5): content_type, account_metadata, master_authority_history, account_recovery_request, change_recovery_account_request

---

Рекомендуемая продакшен-конфигурация

plugin = snapshot

# Создавать снапшот каждые ~24 часа
snapshot-every-n-blocks = 28800
snapshot-dir = /data/viz-snapshots

# Автоматически удалять снапшоты старше 90 дней
snapshot-max-age-days = 90

# DLT rolling block log: хранить последние 100k блоков
dlt-block-log-max-blocks = 100000

shared-file-size = 4G
plugin = p2p
p2p-seed-node = seed1.viz.world:2001

---

Краткий справочник Docker

Задача	Команда
Запуск с периодическими снапшотами	Добавить snapshot-every-n-blocks в конфиг, перезапустить контейнер
Разовый снапшот	VIZD_EXTRA_OPTS="--create-snapshot /var/lib/vizd/snapshots/snap.json --plugin snapshot"
Загрузка из снапшота	VIZD_EXTRA_OPTS="--snapshot /var/lib/vizd/snapshots/snap.json --plugin snapshot"
Восстановление после сбоя	VIZD_EXTRA_OPTS="--replay-from-snapshot --snapshot-auto-latest --plugin snapshot"
Авто-восстановление (по умолчанию)	Включено по умолчанию; убедитесь, что plugin = snapshot и snapshot-every-n-blocks заданы

---

См. также: Плагин chain, Разделяемая память, Block log, Сценарии синхронизации P2P.