Snapshot Examples
Worked investigation
Choose and execute the right mainnet recovery path
Use this investigation when an operator says “I need this node back online” and you need to decide whether the right path is optimized fast-rpc, standard RPC, or archival hot/cold recovery.
Pick the recovery class first, then run the smallest command sequence that matches that class.
01Decide whether the real need is optimized fast-rpc, standard RPC, or archival recovery.
02If the answer is archival, capture one exact snapshot block height first and keep reusing it.
03Run only the commands for that chosen path, instead of mixing optimized, standard, and archival steps together.
Goal
- Turn a vague recovery request into the right mainnet snapshot path and the minimum command sequence to get moving safely.
| Path or command | How we use it | Why we use it |
|---|---|---|
Mainnet optimized fast-rpc path | Choose it first when the goal is the fastest high-performance RPC recovery and the node can support the optimized profile | It is the preferred fast recovery path when archival retention is not required |
| Mainnet standard RPC path | Use it when the operator needs a simpler RPC recovery without the optimized profile | It gives a straightforward default recovery route into the normal nearcore data path |
| Latest archival block lookup | Fetch the latest archival snapshot height before archival recovery | Anchors the hot/cold downloads to a specific archival snapshot block |
| Archival hot-data command | Run it first and place the result on NVMe | Hot archival data must land on the fast storage tier to support the node correctly |
| Archival cold-data command | Run it after hot data and place it on the cold storage tier | Completes archival recovery without forcing all archival data onto the expensive hot tier |
What a useful answer should include
- which recovery path was chosen and why
- which critical env vars matter for the chosen path
- where data should land on disk
- whether the operator should stay in FastNear snapshot docs or move to general nearcore bootstrap docs
Mainnet archival recovery shell walkthrough
Use this when you have already decided that archival mainnet is the right path and now need the exact command sequence with one shared block anchor.
What you're doing
- Fetch the latest archival mainnet snapshot height once.
- Store it in
LATEST. - Reuse that exact block height for both the hot-data and cold-data downloads.
HOT_DATA_PATH=~/.near/data
COLD_DATA_PATH=/mnt/hdds/cold-data
LATEST="$(curl -s "https://snapshot.neardata.xyz/mainnet/archival/latest.txt")"
echo "Latest archival mainnet snapshot block: $LATEST"
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/fastnear/static/refs/heads/main/down_rclone_archival.sh \
| DATA_TYPE=hot-data DATA_PATH="$HOT_DATA_PATH" CHAIN_ID=mainnet BLOCK="$LATEST" bash
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/fastnear/static/refs/heads/main/down_rclone_archival.sh \
| DATA_TYPE=cold-data DATA_PATH="$COLD_DATA_PATH" CHAIN_ID=mainnet BLOCK="$LATEST" bashWhy this next step?
Hot and cold archival data need to come from the same snapshot cut. Reusing one captured LATEST value across both commands keeps the archival dataset internally consistent and makes later nearcore configuration much less surprising.
Common jobs
Bootstrap an optimized mainnet fast-rpc node
Start here
- Mainnet snapshots, specifically the optimized
fast-rpcpath.
Next page if needed
- Revisit the standard mainnet RPC path if the node cannot support the optimized profile.
Stop when
- You have the right
fast-rpccommand and environment variables for the target machine.
Switch when
- The real requirement is archival retention rather than fast sync.
Recover a standard RPC node to the default nearcore path
Start here
- Mainnet snapshots or Testnet snapshots, depending on network, and choose the standard RPC snapshot path for that environment.
Next page if needed
- Adjust
DATA_PATH,THREADS, or bandwidth settings only after the standard path is clear.
Stop when
- You can run the correct RPC recovery command with the expected data path.
Switch when
- The operator actually needs archival history or hot/cold data placement.
Bring up archival mainnet hot and cold data correctly
Start here
- Mainnet snapshots, archival section.
Next page if needed
- Fetch the latest archival snapshot height, then run separate hot-data and cold-data downloads with the correct paths.
Stop when
- The hot-data and cold-data plan is clear and the order of operations is correct.
Switch when
- The operator is really looking for general nearcore bootstrap guidance beyond FastNear snapshots.
Bootstrap testnet archival hot data
Start here
- Testnet snapshots, archival section.
Next page if needed
- Fetch the latest testnet archival snapshot height before the download step.
Stop when
- You have the right testnet archival hot-data command and block anchor.
Switch when
- The user is not doing infrastructure bootstrap and should be routed back to API or RPC docs.
Common mistakes
- Using snapshot docs when the task is really about reading chain data.
- Choosing archival recovery when a standard or optimized RPC path would do.
- Forgetting the hot/cold storage split for archival data.
- Jumping into commands before deciding the network and node goal.