Snapshots

This guide provides technical instructions for engineers on using snapshots to rapidly bootstrap a Nexera node, bypassing the standard, time-consuming peer-to-peer initial sync process.

Available Snapshots

Snapshots are pre-synced copies of the Nexera chain data. The type of snapshot you use depends on your node's purpose.

Snapshot Type	Description	Use Case
Mainnet Snapshots	A copy of the Nexera main production network's chain data.	For any production node, including validators and RPC nodes, operating on the main Nexera network.
Testnet Snapshots	A copy of a specific Nexera test network's chain data (e.g., Sepolia, Holesky).	For development, testing applications, and running testnet validators without risking mainnet assets.
Archive Snapshots	A complete copy of the blockchain data, including the full state history for every block. These are extremely large (multiple terabytes).	Required for services that need to query historical states, such as block explorers and data analytics platforms.
Pruned Snapshots	A copy of the blockchain data with historical states older than a certain threshold removed (pruned). The node retains only recent state data.	The standard choice for most validators and RPC nodes, as it significantly reduces disk space requirements and is faster to import.

Using Snapshots

This section details the process of downloading, verifying, and importing a snapshot into your node client.

Download and Verification

Crucially, only download snapshots from official or highly trusted sources. Using a malicious snapshot can cause your node to sync to an invalid chain. Trusted sources typically include:

Official documentation from your execution client (e.g., Geth, Nethermind).
Community-vetted snapshot providers.

Always verify the integrity of the downloaded file using the checksum provided by the source.

# Example: Verifying a SHA256 checksum
sha256sum nexera-mainnet-snapshot.tar.gz
# Compare the output hash with the one provided by the source.

Installation Process

The general workflow for importing a snapshot is as follows:

Stop the Node Client: Ensure your execution client is not running.
sudo systemctl stop execution-client.service
Remove Old Data: Delete the existing chain data directory to prevent conflicts. This is a destructive action.
# Example for Geth. The path may vary. rm -rf /var/lib/geth/geth/chaindata
Download and Decompress: Download the snapshot file into the appropriate location and decompress it.
# Decompress a .tar.gz snapshot into the geth data directory tar -xzvf nexera-mainnet-snapshot.tar.gz -C /var/lib/geth/
Set Permissions: Ensure the client's user has ownership of the imported files.
# Example for a 'geth' user sudo chown -R geth:geth /var/lib/geth
Restart the Node Client: Start your client. It will begin syncing from the block height of the snapshot.
sudo systemctl start execution-client.service

Snapshot Formats

Snapshots are typically provided as compressed archives. Common formats include:

.tar.gz: A common archive format using Gzip compression.
.tar.zst: A modern format using Zstandard compression, often offering faster decompression speeds.
.car (Content Addressable aRchive): A format used by some clients for verifiable data transfer.

The decompression command will vary based on the format (tar -xzvf for .tar.gz, tar -I 'zstd -d' -xvf for .tar.zst).

Verification Procedures

After importing a snapshot and starting your node, perform these checks:

Monitor Logs: Check the node's logs for errors. The node should report that it is starting its sync from a high block number.
sudo journalctl -fu execution-client.service
Check Sync Status: Use an RPC call to check the node's sync status. The currentBlock should be close to the network's latest block.
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' http://localhost:8545
Verify Block Hash: Query the block hash at the snapshot's height and compare it against a trusted block explorer for the Nexera Network. This confirms you are on the canonical chain.

Troubleshooting Snapshot Issues

Decompression Errors / "Corrupt Snapshot": This almost always indicates an incomplete or corrupted download. Re-download the file and verify its checksum before attempting to decompress it again.
Permission Denied Errors: If the node fails to start with permission errors in the logs, it means the user running the client process does not have read/write access to the imported data directory. Run chown and chmod to fix ownership and permissions.
Client Compatibility Issues: A snapshot created by one client version may not be compatible with another. Always use snapshots intended for your specific client and version. Check the provider's release notes for compatibility information.
Node Fails to Find Peers: If the node starts but cannot find peers, the snapshot may be too old (stale). It can also indicate a networking or firewall issue preventing the node from connecting to the P2P network.