Snapshots

Snapshots are compressed backups of blockchain state that enable rapid node synchronization without replaying the entire blockchain history.

Overview

Aspect	Details
Purpose	Fast node bootstrapping and disaster recovery
Compression	lz4 (fast compression/decompression)
Cadence	Every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)
Retention	14 days
Provider	seed3 (archive node)

Snapshot Contents

Included

• data/ - Complete blockchain state database
• wasm/ - CosmWasm contract code cache (if exists)

Excluded (for security)

• config/ - Node-specific configuration files
• keyring/ - Validator keys and wallet data
• node_key.json - P2P node identity key
• priv_validator_key.json - Validator consensus signing key

!!! warning "Security Notice" Snapshots do NOT contain your validator keys or node configuration. You must configure these separately.

Available Snapshots

Sprintnet

Resource	URL
Latest Snapshot	https://snapshots.sprintnet.mononodes.xyz/latest.tar.lz4
Latest Checksum	https://snapshots.sprintnet.mononodes.xyz/latest.sha256
Latest Metadata	https://snapshots.sprintnet.mononodes.xyz/latest.json
Snapshot Index	https://snapshots.sprintnet.mononodes.xyz/index.json

Testnet

Coming soon

Mainnet

Coming soon

Using Snapshots

Prerequisites

# Install lz4 compression tool
# Ubuntu/Debian
sudo apt update && sudo apt install -y lz4

# macOS
brew install lz4

# RHEL/CentOS
sudo yum install -y lz4

Host-Native Restore

For nodes running monod directly on the host (systemd service):

# 1. Stop the node
sudo systemctl stop monod

# 2. Backup existing data (optional but recommended)
mv ~/.monod/data ~/.monod/data.backup.$(date +%Y%m%d_%H%M%S)

# 3. Download snapshot metadata to check freshness
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq .

# 4. Download snapshot and checksum
cd /tmp
curl -L -o snapshot.tar.lz4 https://snapshots.sprintnet.mononodes.xyz/latest.tar.lz4
curl -L -o snapshot.sha256 https://snapshots.sprintnet.mononodes.xyz/latest.sha256

# 5. Verify checksum
sha256sum -c snapshot.sha256
# Should output: snapshot.tar.lz4: OK

# 6. Extract snapshot
# Note: This extracts directly into ~/.monod
lz4 -dc snapshot.tar.lz4 | tar -xf - -C ~/.monod

# 7. Verify extraction
ls -lh ~/.monod/data
ls -lh ~/.monod/wasm  # if exists

# 8. Fix permissions (if needed)
chown -R $(whoami):$(whoami) ~/.monod/data
chown -R $(whoami):$(whoami) ~/.monod/wasm  # if exists

# 9. Start the node
sudo systemctl start monod

# 10. Verify sync status
sleep 10
curl -s http://localhost:26657/status | jq '.result.sync_info'

# 11. Monitor logs
sudo journalctl -u monod -f

Docker Restore

For nodes running in Docker containers:

# 1. Stop the container
docker stop monod

# 2. Backup existing data volume (optional but recommended)
docker run --rm -v monod-data:/source -v $(pwd):/backup \
  alpine tar czf /backup/monod-data-backup-$(date +%Y%m%d_%H%M%S).tar.gz -C /source .

# 3. Download snapshot metadata
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq .

# 4. Download snapshot and checksum
curl -L -o snapshot.tar.lz4 https://snapshots.sprintnet.mononodes.xyz/latest.tar.lz4
curl -L -o snapshot.sha256 https://snapshots.sprintnet.mononodes.xyz/latest.sha256

# 5. Verify checksum
sha256sum -c snapshot.sha256

# 6. Clear existing data volume
docker run --rm -v monod-data:/data alpine sh -c "rm -rf /data/data /data/wasm"

# 7. Extract snapshot into volume
docker run --rm -i -v monod-data:/data -v $(pwd):/snapshot \
  alpine sh -c "cd /data && lz4 -dc /snapshot/snapshot.tar.lz4 | tar -xf -"

# 8. Verify extraction
docker run --rm -v monod-data:/data alpine ls -lh /data/data
docker run --rm -v monod-data:/data alpine ls -lh /data/wasm  # if exists

# 9. Start the container
docker start monod

# 10. Verify sync status
sleep 10
docker exec monod curl -s http://localhost:26657/status | jq '.result.sync_info'

# 11. Monitor logs
docker logs -f monod

Snapshot Metadata

Each snapshot includes metadata in JSON format:

{
  "chain_id": "mono-sprint-1",
  "block_height": 123456,
  "timestamp": "2026-01-04T12:00:00Z",
  "size_bytes": 5368709120,
  "size_human": "5.0GiB",
  "compression": "lz4",
  "sha256": "abc123...",
  "filename": "snapshot_20260104_120000.tar.lz4",
  "includes": ["data/", "wasm/"],
  "excludes": ["config/", "keyring/", "node_key.json", "priv_validator_key.json"]
}

Checking Snapshot Freshness

# View latest snapshot metadata
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq .

# Check block height
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq -r '.block_height'

# Check timestamp
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq -r '.timestamp'

# Compare with current chain height
SNAPSHOT_HEIGHT=$(curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq -r '.block_height')
CURRENT_HEIGHT=$(curl -s https://rpc.sprintnet.mononodes.xyz/status | jq -r '.result.sync_info.latest_block_height')
echo "Snapshot height: $SNAPSHOT_HEIGHT"
echo "Current height: $CURRENT_HEIGHT"
echo "Blocks behind: $(($CURRENT_HEIGHT - $SNAPSHOT_HEIGHT))"

Historical Snapshots

View all available snapshots:

curl -s https://snapshots.sprintnet.mononodes.xyz/index.json | jq .

Download a specific snapshot by filename:

# List available snapshots
curl -s https://snapshots.sprintnet.mononodes.xyz/index.json | jq -r '.snapshots[].filename'

# Download specific snapshot
curl -L -o snapshot.tar.lz4 \
  https://snapshots.sprintnet.mononodes.xyz/snapshot_20260104_060000.tar.lz4

Verification

Checksum Verification

Always verify checksums before extracting:

# Download checksum file
curl -L -o snapshot.sha256 https://snapshots.sprintnet.mononodes.xyz/latest.sha256

# Verify
sha256sum -c snapshot.sha256

# Manual verification
EXPECTED=$(cat snapshot.sha256 | cut -d' ' -f1)
ACTUAL=$(sha256sum snapshot.tar.lz4 | cut -d' ' -f1)

if [ "$EXPECTED" = "$ACTUAL" ]; then
  echo "Checksum verified successfully"
else
  echo "ERROR: Checksum mismatch!"
  exit 1
fi

Post-Restore Verification

After restoring from snapshot:

# 1. Check node is running
sudo systemctl status monod
# or for Docker:
docker ps | grep monod

# 2. Check sync status
curl -s http://localhost:26657/status | jq '.result.sync_info'
# Look for:
# - catching_up: should be true initially
# - latest_block_height: should be increasing

# 3. Monitor logs for errors
sudo journalctl -u monod -f
# or for Docker:
docker logs -f monod

# 4. Verify database integrity
# Node should not panic on startup
# Check logs for "committed state" messages

# 5. Wait for sync to complete
# catching_up will become false when synced
while true; do
  catching_up=$(curl -s http://localhost:26657/status | jq -r '.result.sync_info.catching_up')
  height=$(curl -s http://localhost:26657/status | jq -r '.result.sync_info.latest_block_height')
  echo "Height: $height, Catching up: $catching_up"
  if [ "$catching_up" = "false" ]; then
    echo "Node is synced!"
    break
  fi
  sleep 10
done

Troubleshooting

Checksum Verification Fails

# Re-download the snapshot
rm snapshot.tar.lz4
curl -L -o snapshot.tar.lz4 https://snapshots.sprintnet.mononodes.xyz/latest.tar.lz4

# Verify again
sha256sum -c snapshot.sha256

Extraction Fails

# Check lz4 is installed
which lz4

# Test decompression separately
lz4 -t snapshot.tar.lz4

# Try alternative extraction method
lz4 -d snapshot.tar.lz4 snapshot.tar
tar -xf snapshot.tar -C ~/.monod

Node Won't Start After Restore

# Check logs for specific error
sudo journalctl -u monod -n 100 --no-pager

# Common issues:

# 1. Missing genesis.json
# Ensure genesis.json is in ~/.monod/config/
curl -L -o ~/.monod/config/genesis.json \
  https://raw.githubusercontent.com/monolythium/mono-core-peers/prod/networks/sprintnet/genesis.json

# 2. Permission issues
chown -R $(whoami):$(whoami) ~/.monod

# 3. Corrupted database
# Delete data and try snapshot again
rm -rf ~/.monod/data
# Re-extract snapshot...

# 4. Wrong chain-id in config
# Edit ~/.monod/config/app.toml and client.toml
# Ensure chain-id matches genesis

Sync Progress Stalled

# Check peer connections
curl -s http://localhost:26657/net_info | jq '.result.n_peers'

# Should have multiple peers (>3)
# If not, check seeds/peers in config.toml

# Verify peers in config
grep -E "^(seeds|persistent_peers)" ~/.monod/config/config.toml

# Update with known good peers
# See: https://github.com/monolythium/mono-core-peers/blob/prod/networks/sprintnet/peers.json

Disk Space Issues

# Check available space
df -h ~/.monod

# Snapshot size estimate
curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq -r '.size_human'

# Free up space before downloading
# Remove old backups
rm -rf ~/.monod/data.backup.*

# Or download snapshot to different location
SNAPSHOT_DIR=/mnt/large-disk
cd $SNAPSHOT_DIR
curl -L -o snapshot.tar.lz4 https://snapshots.sprintnet.mononodes.xyz/latest.tar.lz4
lz4 -dc snapshot.tar.lz4 | tar -xf - -C ~/.monod

Snapshot vs State Sync

Feature	Snapshot	State Sync
Method	Download compressed archive	Sync from peers via P2P
Speed	Fastest (depends on bandwidth)	Fast (depends on network)
Trust	Single provider	Multiple validators
Freshness	Up to 6 hours old	Live state
Bandwidth	One large download	Continuous peer sync
Best For	Initial sync, disaster recovery	Regular syncing, lower trust requirements

Choose snapshots when:

• You need the fastest possible sync
• You trust the snapshot provider
• You have good download bandwidth
• You're setting up a new node
• You're recovering from data corruption

Choose state sync when:

• You prefer decentralized trust model
• Snapshot download is slow/unavailable
• You want the most recent state
• See State Sync for details

Advanced: Creating Your Own Snapshots

For operators who want to maintain their own snapshot archives:

Prerequisites

# Install dependencies
sudo apt install -y lz4 jq rsync

# Clone snapshot scripts
git clone https://github.com/monolythium/mono-core-peers.git
cd mono-core-peers/snapshots

Manual Snapshot

# Stop node
sudo systemctl stop monod

# Create snapshot
cd /var/www/snapshots
tar -cf - -C ~/.monod data wasm 2>/dev/null | lz4 -9 > snapshot-$(date +%Y%m%d_%H%M%S).tar.lz4

# Calculate checksum
sha256sum snapshot-*.tar.lz4 > snapshot-*.sha256

# Start node
sudo systemctl start monod

Automated Snapshots

# Install snapshot service
cd /path/to/mono-core-peers/snapshots
sudo ./install-snapshot-service.sh

# Verify installation
sudo systemctl status monod-snapshot.timer

# View next scheduled run
systemctl list-timers monod-snapshot.timer

# Manual trigger (for testing)
sudo systemctl start monod-snapshot.service
sudo journalctl -u monod-snapshot.service -f

For full automation setup, see /Users/nayiemwillems/workspace/monolythium/mono-core-peers/snapshots/README.md

Best Practices

For Snapshot Users

1. Always verify checksums - Never skip this step
2. Check snapshot freshness - Review metadata before downloading
3. Backup before restore - Keep your old data just in case
4. Monitor after restore - Watch logs for the first hour
5. Verify sync completion - Ensure node fully catches up

For Snapshot Providers

1. Consistent schedule - Users rely on regular updates
2. Provide checksums - Essential for security
3. Document contents - Be clear about what's included/excluded
4. Monitor service health - Set up alerts for failures
5. Maintain retention - Keep reasonable history (14 days recommended)

Security Considerations

1. Never include keys - Snapshots should not contain:

   • Validator private keys
   • Node identity keys
   • Keyring data

2. Verify source - Only use snapshots from:

   • Official infrastructure
   • Trusted validators
   • Known community providers

3. Check chain-id - Ensure snapshot matches your target network

4. Validate genesis - After restore, verify genesis.json hash matches official

FAQ

How often are snapshots created?

Every 6 hours at 00:00, 06:00, 12:00, and 18:00 UTC.

How long are snapshots kept?

14 days of rolling retention.

Can I use a snapshot from a different network?

No. Snapshots are network-specific. Sprintnet snapshots only work for Sprintnet.

Will a snapshot restore my validator keys?

No. Validator keys are intentionally excluded for security. You must configure keys separately.

What if the snapshot is corrupted during download?

The checksum verification will fail. Re-download the snapshot.

Can validators use snapshots?

Yes, especially for initial setup. Ensure the node is fully synced and tested before activating as a validator.

How much disk space do I need?

Check the snapshot metadata for exact size. Generally, you need:

• Snapshot download size (compressed)
• 2-3x snapshot size for extraction and operation
• Example: 5GB snapshot needs ~15GB free space

What's the difference between archive and pruned snapshots?

Currently, all snapshots are from an archive node (full history). Pruned snapshots may be added in the future.

Can I download a snapshot from a specific time?

Yes, use the index.json to find historical snapshots (up to 14 days back).

What if I'm behind a slow connection?

Consider using a download manager that supports resume (like wget with -c flag or aria2c).

Related Documentation

• State Sync - Alternative sync method
• Join Network - Complete setup guide
• Seed Deployment - Seed node setup
• Docker - Container-based deployment

Support

If you encounter issues with snapshots:

1. Check this troubleshooting section
2. Review logs: sudo journalctl -u monod -n 200
3. Verify snapshot metadata and checksums
4. Check network connectivity and disk space
5. Reach out to the community for help

Snapshot Service Health

Check snapshot service status:

# Check if latest snapshot is recent
SNAPSHOT_TIME=$(curl -s https://snapshots.sprintnet.mononodes.xyz/latest.json | jq -r '.timestamp')
echo "Latest snapshot: $SNAPSHOT_TIME"

# Check snapshot service health (requires SSH access)
ssh -i ~/.ssh/claude_vps_key claude@77.42.42.64 'sudo systemctl status monod-snapshot.timer'