Full Node Snapshots

If you were following the run Citrea full node guide, you've probably seen the optional step and came here. Think of this as the last step before running your own node. This step is optional and aimed at people who want to reduce syncing time.

Syncing a full node from the genesis block can take a long time since Citrea state tends to grow quickly due to its two-second block time.

Instead of waiting for your node to sync from scratch, you can visit Citrea Snapshots. There you will find full node snapshots of different Citrea networks. Pick your network to see the available snapshots.

Snapshots are usually created once every three days. When you use these snapshots, you only need to sync a few days of blocks instead of syncing from genesis.

Downloading Snapshots

These snapshots can be very large in size, which is why it is not recommended to use a browser for downloading. Here's why:

• No reliable resume support - Most browsers can technically resume, but it's unreliable. If the connection drops mid-download or the browser crashes, you're often starting from zero.

• Memory overhead - Browsers keep download metadata in memory. Long downloads can cause memory bloat, and if the browser crashes, you lose your progress.

• Poor timeout handling - Browsers give up too easily on stalled connections.

This is where command line tools come in. You can use any of the following tools to download these snapshots. Click copy url next to the snapshot you want to download, open the terminal, and follow the steps for the tool of your choice:

First, create a directory for your downloads and navigate into it:

mkdir ~/citrea-snapshot && cd ~/citrea-snapshot

wget

wget -c <URL>

The -c flag enables resuming. Optionally, you can add --timeout=60 --tries=0 for infinite retries on flaky connections.

aria2c

aria2c -x 16 -s 16 -k 100M -c --max-tries=0 --retry-wait=10 <URL>

• -x 16: 16 connections per server

• -s 16: split into 16 segments

• -k 100M: minimum split size

• -c: continue/resume

• --max-tries=0: Infinite retries

• --retry-wait=10: Retry 10 seconds after failing

rclone

rclone copyurl "<URL>" ~/citrea-snapshot --progress

Rclone resumes automatically. Optionally, use --multi-thread-streams=16 to split a single file download across multiple streams, which may speed up your download.

Extracting

The snapshots are tar files. To extract them, use the tar command:

tar -xvf <snapshot_file>.tar

No need for the compression flag as the database is not compressed, just packaged.

Using the Snapshot to Run a Node

After extracting the snapshot, you should see a folder named full-node. Copy the absolute path to that folder.

To run the node with the snapshot:

Using Config Files

Go to your rollup_config.toml and under [storage], update the path variable with the path to your snapshot folder.

Using Environment Variables

Update your STORAGE_PATH environment variable with the snapshot path:

export STORAGE_PATH=<path_to_your_snapshot_folder>

Now you can return to the run Citrea full node guide and start running your node.

Using Docker Compose

If you're running Citrea using Docker Compose, you can use snapshots by mounting the extracted snapshot directory as a volume.

After downloading and extracting your snapshot, modify the docker-compose.yml to mount the snapshot folder directly. Replace the named volume with a bind mount pointing to your extracted snapshot:

services:
  citrea-full-node:
    # ... other configuration remains the same
    volumes:
      - /path/to/your/full-node:/mnt/task/citrea-db

For example, if you extracted the snapshot to ~/citrea-snapshot/full-node:

volumes:
  - ~/citrea-snapshot/full-node:/mnt/task/citrea-db

Make sure the snapshot folder has the correct permissions for Docker to read and write. You may need to run chmod -R 755 ~/citrea-snapshot/full-node if you encounter permission errors.

Then start your node with:

docker compose -f docker-compose.yml up