Skip the initial sync

Run this on EC2, not your laptop. Snapshots are only reachable through an Amazon S3 gateway VPC endpoint, so you download them from an EC2 instance in the same Region. A laptop or a browser won’t work.

1. 01

   Use an instance

   Run these steps on an EC2 instance in us-east-1, eu-west-1, or ap-northeast-1, running Amazon Linux 2023 or Ubuntu 24.04. Its VPC needs an S3 gateway endpoint, and its instance profile needs s3:GetObject and s3:ListBucket.

   • EC2 instance in an active Region
   • S3 gateway VPC endpoint
   • Instance profile with read access
   • Local NVMe or an EBS volume sized for the extracted snapshot

   Example instance profile policy

   jsonCopy

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject", "s3:ListBucket"],
         "Resource": [
           "arn:aws:s3:::blockchain-snapshots-us-east-1",
           "arn:aws:s3:::blockchain-snapshots-us-east-1/*",
           "arn:aws:s3:::blockchain-snapshots-eu-west-1",
           "arn:aws:s3:::blockchain-snapshots-eu-west-1/*",
           "arn:aws:s3:::blockchain-snapshots-ap-northeast-1",
           "arn:aws:s3:::blockchain-snapshots-ap-northeast-1/*"
         ]
       }
     ]
   }

   Scope the resources to the Region you use. Bucket names come from each Region’s catalog.

2. 02

   Get the tools and dependencies

   Clone the repository, then run setup once. Setup installs AWS CLI v2; Python 3 with boto3 and zstandard; zstd, tar, curl, and unzip; and mountpoint-s3 with FUSE when the instance supports them. Otherwise, downloads use S3 directly.

   Amazon Linux 2023 Ubuntu 24.04

   bashCopy

   sudo dnf install -y git
   cd ~ && git clone https://github.com/awslabs/blockchain-snapshots.git
   cd blockchain-snapshots/dist

   bashCopy

   sudo apt-get update && sudo apt-get install -y git
   cd ~ && git clone https://github.com/awslabs/blockchain-snapshots.git
   cd blockchain-snapshots/dist

   bash · run onceCopy

   ./snapshot.sh --setup

   Setup may prompt for sudo. Snapshot download commands don’t use sudo; run them as the account that should own the data. AWS Blockchain Node Runners uses bcuser.

3. 03

   Set up storage

   Extract to a dedicated directory on a volume with room for the full snapshot. Pick the one that matches your instance.

   Local NVMe EBS volume

   Join the instance’s NVMe drives into one volume at /data. Instance types like i4i or i8g are the fastest option.

   bashCopy

   sudo bash setup-storage.sh

   No RAID needed. If it’s an extra volume (here /dev/nvme1n1), format and mount it once. If you’re using the root volume, just make the directory.

   bashCopy

   sudo mkfs.xfs -f /dev/nvme1n1          # skip if already formatted
   sudo mkdir -p /data && sudo mount /dev/nvme1n1 /data
   sudo chown "$(id -u):$(id -g)" /data

   On EBS the extractor writes buffered automatically; on local NVMe it uses O_DIRECT. Either way the result is identical. Size the volume for the snapshot’s extracted size, not its download size.

4. 04

   Download a snapshot

   Pick a snapshot below and run its command from the dist folder. snapshot.sh resolves the latest catalog entry at execution time, checks storage, and selects the delivery method from catalog data. Each snapshot writes to its own folder under /data.

   bashCopy

   ./snapshot.sh --snapshot ethereum-mainnet-geth --out /data/ethereum-mainnet-geth

   For archive-set snapshots such as Solana, the files stay compressed because the node unpacks them itself. Start Agave with --snapshots pointing at that folder and --no-snapshot-fetch.