Stable Docs | Stable Architecture & Integration Guide

This guide covers various methods to synchronize your Stable node quickly using snapshots and state sync.

Sync methods overview

Method	Sync Time	Storage Required	Use Case
Pruned Snapshot	~10 min	< 5 GiB	Regular full nodes
Archive Snapshot	~1 hours	~500 GB	Archive nodes, block explorers

Official snapshots

Stable provides official snapshots updated daily (00:00 UTC).

Snapshot information

Mainnet
Testnet

Type	Compression	Size	URL	Update Frequency
Pruned	LZ4	< 5 GiB	Download	Daily
Archive	ZSTD	~300 GB	Download	Weekly

Using pruned snapshots

Pruned snapshots contain recent blockchain state (last 100-1000 blocks).

Step 1: set environment variable

# Set service name (default: stable)
export SERVICE_NAME=stable

Step 2: stop node service

# Stop the running node
sudo systemctl stop ${SERVICE_NAME}

# Verify it's stopped
sudo systemctl status ${SERVICE_NAME}

Step 3: backup current data (optional)

# Create backup directory
mkdir -p ~/stable-backup

# Backup current state (optional, requires significant space)
cp -r ~/.stabled/data ~/stable-backup/

Step 4: download and extract pruned snapshot

Mainnet
Testnet

# Install dependencies
sudo apt install -y wget zstd pv

# Create snapshot directory
mkdir -p ~/snapshot
cd ~/snapshot

# Download pruned snapshot with progress
wget -c https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/snapshots/snapshot.tar.lz4

# Remove old data
rm -rf ~/.stabled/data/*

# Extract snapshot with progress indicator
pv stable_pruned.tar.zst | zstd -d -c | tar -xf - -C ~/.stabled/

# Alternative extraction without pv
zstd -d stable_pruned.tar.zst -c | tar -xvf - -C ~/.stabled/

# Clean up
rm stable_pruned.tar.zst

# Install dependencies
sudo apt install -y wget lz4 pv

# Create snapshot directory
mkdir -p ~/snapshot
cd ~/snapshot

# Download pruned snapshot with progress
wget -c https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/snapshots/snapshot.tar.lz4

# Alternative: Download with resume support
curl -C - -o snapshot.tar.lz4 https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/snapshots/snapshot.tar.lz4

# Remove old data
rm -rf ~/.stabled/data/*

# Extract snapshot with progress indicator
pv snapshot.tar.lz4 | tar -I lz4 -xf - -C ~/.stabled/

# Alternative extraction without pv
tar -I lz4 -xvf snapshot.tar.lz4 -C ~/.stabled/

# Clean up
rm snapshot.tar.lz4

Step 5: restart node

# Start the node
sudo systemctl start ${SERVICE_NAME}

# Check status
sudo systemctl status ${SERVICE_NAME}

# Monitor logs
sudo journalctl -u stabled -f

Using archive snapshots

Archive snapshots contain complete blockchain history.

Step 1: prepare system

# Stop node
sudo systemctl stop ${SERVICE_NAME}

# Install dependencies
sudo apt install -y wget zstd pv

# Check available disk space (need 2x snapshot size)
df -h ~/.stabled

Step 2: download and extract archive snapshot

Mainnet
Testnet

# Create working directory
mkdir -p ~/snapshot
cd ~/snapshot

# Download archive snapshot
wget -c https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/snapshots/stable_archive.tar.zst

# Clear old data
rm -rf ~/.stabled/data/*

# Extract with high memory for better performance
pv stable_archive.tar.zst | zstd -d --long=31 --memory=2048MB -c - | tar -xf - -C ~/.stabled/

# Alternative: Standard extraction
zstd -d --long=31 stable_archive.tar.zst -c | tar -xvf - -C ~/.stabled/

# Clean up
rm stable_archive.tar.zst

# Create working directory
mkdir -p ~/snapshot
cd ~/snapshot

# Download archive snapshot
wget -c https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/snapshots/stable_archive.tar.zst

# Clear old data
rm -rf ~/.stabled/data/*

# Extract with high memory for better performance
pv archive.tar.zst | zstd -d --long=31 --memory=2048MB -c - | tar -xf - -C ~/.stabled/

# Alternative: Standard extraction
zstd -d --long=31 archive.tar.zst -c | tar -xvf - -C ~/.stabled/

# Clean up
rm archive.tar.zst

Step 3: start node

# Start service
sudo systemctl start ${SERVICE_NAME}

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

Creating your own snapshots

Manual snapshot creation

# Stop node
sudo systemctl stop ${SERVICE_NAME}

# Create snapshot archive
cd ~/.stabled
tar -cf - data/ | lz4 -9 > ~/stable-snapshot-$(date +%Y%m%d).tar.lz4

# Create checksum
sha256sum ~/stable-snapshot-*.tar.lz4 > checksums.txt

# Restart node
sudo systemctl start ${SERVICE_NAME}

Automated snapshot script

#!/bin/bash
# snapshot.sh - Automated snapshot creation

# Configuration
SNAPSHOT_DIR="/var/snapshots"
STABLED_HOME="$HOME/.stabled"
KEEP_DAYS=7

# Create snapshot directory
mkdir -p $SNAPSHOT_DIR

# Stop node
sudo systemctl stop ${SERVICE_NAME}

# Create snapshot
SNAPSHOT_NAME="stable-snapshot-$(date +%Y%m%d-%H%M%S).tar.lz4"
tar -cf - -C $STABLED_HOME data/ | lz4 -9 > $SNAPSHOT_DIR/$SNAPSHOT_NAME

# Generate metadata
cat > $SNAPSHOT_DIR/latest.json <<EOF
{
  "filename": "$SNAPSHOT_NAME",
  "height": "$(cat $STABLED_HOME/data/cs.wal/wal | grep height | tail -1 | awk '{print $2}' | tr -d ',')",
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "size": "$(du -h $SNAPSHOT_DIR/$SNAPSHOT_NAME | awk '{print $1}')",
  "checksum": "$(sha256sum $SNAPSHOT_DIR/$SNAPSHOT_NAME | awk '{print $1}')"
}
EOF

# Clean old snapshots
find $SNAPSHOT_DIR -name "stable-snapshot-*.tar.lz4" -mtime +$KEEP_DAYS -delete

# Restart node
sudo systemctl start ${SERVICE_NAME}

echo "Snapshot created: $SNAPSHOT_DIR/$SNAPSHOT_NAME"

Schedule automated snapshots

# Add to crontab (weekly on Sunday at 2 AM)
(crontab -l ; echo "0 2 * * 0 /usr/local/bin/snapshot.sh") | crontab -

Verification and troubleshooting

Verify snapshot integrity

# Check snapshot checksum
sha256sum -c checksums.txt

# Verify extraction
tar -I lz4 -tvf snapshot.tar.lz4 | head -20

# Test snapshot size
tar -I lz4 -tvf snapshot.tar.lz4 | wc -l

Common issues

Issue: snapshot extraction fails

# Check disk space
df -h

# Verify file integrity
lz4 -t snapshot.tar.lz4

# Try alternative extraction
lz4 -d snapshot.tar.lz4 snapshot.tar
tar -xvf snapshot.tar -C ~/.stabled/

Issue: node won’t start after snapshot

# Check permissions
ls -la ~/.stabled/data/

# Fix permissions
sudo chown -R $USER:$USER ~/.stabled/

# Verify genesis file
sha256sum ~/.stabled/config/genesis.json

# Reset and try again
stabled comet unsafe-reset-all
# Then restore snapshot

Issue: state sync fails

# Try different RPC servers
# Update config.toml with alternative RPCs

# Increase chunk fetchers
sed -i 's/chunk_fetchers = .*/chunk_fetchers = 8/' ~/.stabled/config/config.toml

# Clear and retry
stabled comet unsafe-reset-all --keep-addr-book

Performance optimization

Download optimization

# Use aria2 for parallel downloads
aria2c -x 16 -s 16 https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/snapshots/snapshot.tar.lz4

# Use wget with compression
wget --header="Accept-Encoding: gzip" -c URL

# Resume interrupted downloads
curl -C - -o snapshot.tar.lz4 URL

Extraction optimization

# Use parallel extraction
pigz -d -c snapshot.tar.gz | tar -xf - -C ~/.stabled/

# Monitor extraction progress
pv snapshot.tar.lz4 | tar -I lz4 -xf - -C ~/.stabled/

# Use more memory for zstd
zstd -d --long=31 --memory=4096MB archive.tar.zst

Best practices

Always backup validator keys before replacing data
Verify checksums before extracting snapshots
Monitor disk space during extraction (need 2x snapshot size)
Use official snapshots when possible
Test snapshots in non-production environment first
Schedule regular snapshots for your archive nodes
Document snapshot sources for audit trail

Next steps

Configure your node for optimal performance
Set up monitoring to track sync progress
Review troubleshooting for common issues

​Sync methods overview

​Official snapshots

​Snapshot information

​Using pruned snapshots

​Step 1: set environment variable

​Step 2: stop node service

​Step 3: backup current data (optional)

​Step 4: download and extract pruned snapshot

​Step 5: restart node

​Using archive snapshots

​Step 1: prepare system

​Step 2: download and extract archive snapshot

​Step 3: start node

​Creating your own snapshots

​Manual snapshot creation

​Automated snapshot script

​Schedule automated snapshots

​Verification and troubleshooting

​Verify snapshot integrity

​Common issues

​Issue: snapshot extraction fails

​Issue: node won’t start after snapshot

​Issue: state sync fails

​Performance optimization

​Download optimization

​Extraction optimization

​Best practices

​Next steps