Skip to main content

Filecoin Validated Snapshot

Background​

We provide chaindata snapshots of Mainnet and Calibnet to the Filecoin community. The service exports Forest snapshots, validates them, and uploads them to R2.

These snapshots include messages and state-trees but do not include message receipts.

🔎 Validation runs forest-tool snapshot validate --check-network <chain> --check-links 5 --check-stateroots 5 against every snapshot before upload; the sidecars below are additionally checked with forest-tool snapshot validate-extended.

Since Forest v0.35.0 each latest snapshot is published alongside two optional sidecar files — an augmented CAR carrying message receipts and events, and a tipset-lookup CAR. They are separate downloads, shown with an Enriched badge in the listing, and never replace the base snapshot.

🕒 Publish cadence​

Per network, measured from the archive listings:

KindCadenceTypical age of the newest file
latest (F3)every 240 epochs (~2h)up to ~3h
diffevery 3000 epochs (~25h)up to ~2 days
liteevery 30000 epochs (~10.4 days)up to ~11 days

🌐 Snapshot Endpoints​

/latest/<network>/ answers with a 302 to the immutable /archive/<bucket>/<key> URL of the current snapshot, so a download started before a rotation keeps working. Every listing also accepts ?format=json (with limit and offset).

Snapshot Content​

Each snapshot includes the following data:

End height: 		  Recent Block
Message start height: Recent block - 2000 blocks
State start height:	  Current block - 2000 blocks

Hosts for Snapshot Generation​

Both hosts belong to the forest_archives inventory group and run the same pipeline:

  • fil-prod-ovh-forest-mainnet-snapshots: 🔄 continuous snapshot creation for Mainnet
  • fil-prod-ovh-forest-calibnet-archive: 🔄 continuous snapshot creation for Calibnet

Each host runs a Forest node and a set of long-running Docker Compose jobs — compute-state, build-snapshots-latest, build-snapshots-historic, validate-snapshots, upload-snapshots — coordinated over RabbitMQ. They are services with restart: on-failure, deployed by the chainsafe.general.forest_snapshots Ansible role.

⚙️ Manual Intervention​

There is no on-demand trigger: the build jobs run continuously and pick up each cycle on their own. To intervene, work on the host directly:

docker compose ps
docker compose logs --tail=200 build-snapshots-latest upload-snapshots
docker compose restart build-snapshots-latest

A build that appears stuck is usually a wedged Forest export — check forest-cli snapshot export-status and stale .tmp files in the snapshots directory.

📈 Monitoring​

  • Dashboard: Filecoin-Snapshot in Grafana (uid adoa3l225p4hsf), fed by a textfile exporter the Ansible role installs on both hosts.
  • Alert runbook: docs/runbooks/filecoin-alerts.md in infrastructure-general.
  • External probe: the filecoin-snapshot-check synthetic check, which verifies that /latest/ resolves, that the snapshot is downloadable, that the listing is not empty, and that recent snapshots carry a checksum.

R2 Storage Buckets​

ChainSafe uses R2 storage for organizing and managing snapshot data:

  1. forest-archive bucket:
    Contains snapshot diffs and lite versions for both Mainnet and Calibnet.

  2. infra-team-filecoin-archive bucket:
    Hosts the legacy snapshots for the past 14 days for both Mainnet and Calibnet.

  3. forest-snapshots-v2 bucket: Hosts the latest F3 snapshots for the past 14 days for both Mainnet and Calibnet.

  4. forbidden-snapshot bucket: Stores snapshots that encountered errors during processing.

  5. backup-filecoin-archive bucket: Maintains backup snapshots of the Mainnet archive node.

The public listing at forest-archive.chainsafe.dev is a Cloudflare Worker (filecoin-snapshot-listing) mapping each bucket to a /list/ path.

Architecture Diagram​

The link to the snapshot generation workflow is available here.