Contribute Snapshots

SnapsVault is a collaborative ecosystem welcoming new contributors to add snapshots for various networks and node configurations. Submissions are made through GitHub pull requests to the public registry.

How to Contribute a Snapshot

Contributing snapshots to SnapsVault involves two main steps:

1. Generate your snapshot metadata file that describes the snapshots you provide using our standardized format.
2. Submit your metadata via a GitHub pull request to the public SnapsVault repository, following the repository structure.

Step 1: Generate Snapshot Metadata

Every snapshot must be described in a valid JSON format. This metadata ensures users can verify the origin, integrity, and block range of your archive.

To generate snapshot metadata, you have two options:

• Option 1: Write your own script
• Option 2: Use our AutogenScript

Option 1: Write your own script

If you prefer, you can write your own script or tool to generate the JSON file, as long as it matches the required format. The URL provided under snapshots must point to a JSON file listing individual snapshots.

Script Requirements:

To keep your snapshots.json updated, you should run a scheduled script (e.g., depending on how often you update your snapshots). This script should:

1. Detect when a new snapshot file is available
2. Calculate and include all metadata described above
3. Push the structured data into the snapshots.json hosted on your server
4. Provide a list of the most recent snapshots you host

You can implement this script in any language. Here's an outline of what it must do:

- Monitor snapshot directory (e.g., /root/.snapshots)
- For each new archive:
  - Compute SHA256
  - Extract earliest/latest block heights from snapshot
  - Record creation time
  - Measure file size
  - Append structured data to snapshots.json
- Replace the old file with updated snapshots.json

Once you've validated the generated file, ensure that the snapshot archive is accessible, compressed efficiently (typically .tar.lz4), and contains all necessary files to bootstrap a node from the specified block height.

Option 2: Use our AutogenScript

To make contributing easier and consistent, we provide the AutogenScript that automates generating the required metadata JSON file. This script scans your snapshot archive directory, extracts necessary info like file URL, size, block heights, and SHA-256 checksums, then produces a properly formatted JSON file listing all snapshots you offer.

This script is ideal for:

• Node operators who maintain their own snapshot servers and want an automated way to generate metadata.
• Contributors who prefer a minimal setup using bash, curl, and standard Unix tools.
• Users looking for a quick way to integrate with SnapsVault without writing custom tooling.

We provide a helper script to generate it automatically from a local directory of .tar.lz4 archives:

curl -s https://github.com/denodes/snapsvault/scripts/autogen.py | python3

Example output:

[
  {
    "url": "https://example.com/snapshots/snapshot_12345.tar.lz4",
    "size": "5Gb",
    "creation_date": "2025-07-21T00:00:17Z",
    "earliest_block_height": "1000",
    "latest_block_height": "12345",
    "sha256sum": "df5b646912b04bf37e9adc7ba3bb451a19e8ac704349c5870c1661399d05df81"
  }
]

Metadata JSON Format

The JSON file should contain an array of snapshot entries. Each entry must have the following fields:

[
  {
    "url": "https://example.com/snapshots/snapshot_12345.tar.lz4",
    "size": "5Gb",
    "creation_date": "2025-07-21T00:00:17Z",
    "earliest_block_height": "1000",
    "latest_block_height": "12345",
    "sha256sum": "df5b646912b04bf37e9adc7ba3bb451a19e8ac704349c5870c1661399d05df81"
  }
]

Field breakdown:

• url: Direct download link to the snapshot archive.
• size: Archive size (e.g., 5Gb, 950Mb). Use consistent human-readable format.
• creation_date: Snapshot creation timestamp in ISO 8601 format (UTC), e.g., 2025-07-21T00:00:17Z.
• earliest_block_height: The lowest block height included in the snapshot.
• latest_block_height: The highest block height included in the snapshot.
• sha256sum: SHA-256 checksum of the archive file for validation.

Note: This format ensures all snapshots can be verified and compared programmatically by SnapsVault.

Step 2: Repository Structure and Submission

Once your snapshot metadata is properly generated and publicly hosted, the next step is to register your snapshots in the SnapsVault registry by submitting a pull request to the GitHub repository.

Here's what you need to do:

1. Fork the SnapsVault registry.
2. Locate the appropriate directory based on the network and chain ID (e.g., /chains/celestia/mocha-4/).
3. Add or update your contributor.json file in that directory using the structure shown above.
4. Commit your changes and open a pull request with a brief description of the snapshot source and update frequency.

The SnapsVault maintainers will review your submission, verify format and availability, and merge it into the public registry if all checks pass.

Repository Structure

Submit your snapshot contributions through pull requests to the SnapsVault registry. The repository organizes snapshots hierarchically under the /chains/ directory:

• Top-level directories represent networks (e.g., celestia, namada)
• Second-level directories represent chain IDs (e.g., mocha-4, firehouse)

For example, Celestia's Mocha-4 testnet snapshots would go here:

/chains/celestia/mocha-4/

Within each chain ID directory, create or update a contributor.json file containing:

• Your contributor details (name, contact info, etc.)
• A link to your hosted snapshot feed JSON (created in Step 1)

Contributor Metadata

This file contains information about your validator and the snapshots you provide. The snapshot metadata file (contributor.json) should follow the structure shown below.

{
  "contributor": {
    "name": "deNodes",
    "email": "hello@denodes.xyz",
    "discord": "bombermine",
    "telegram": "https://t.me/denodes",
    "x": "https://x.com/denodes_io",
    "description": "An institutional-grade staking provider delivering secure operations and superior performance for PoS networks",
    "website": "https://denodes.io",
    "identity": "C89053F92B77D8C0"
  },
  "snapshots": [
    {
      "snapshots": "https://airchains-varanasi.denodes.xyz/snapshots/snapshots.json",
      "period": "4h",
      "type": "pruned"
    }
  ]
}

Field Descriptions:

• name: Your organization or team name
• email: Contact email for inquiries
• discord: Your Discord handle (optional)
• telegram: Your Telegram username or group link
• x: Your X (Twitter) profile URL
• description: Brief description of your services (one line)
• website: Your organization's website
• identity: Validator/provider identity key (e.g., Keybase)
• snapshots: URL to your hosted snapshots.json file
• period: Update frequency (4h, 12h, 1d, etc.)
• type: Either archival (full history) or pruned (optimized size)

Final Checklist

Before submitting your pull request, verify:

• Your snapshots.json follows the correct format and contains valid data
• You can maintain snapshots consistently according to your stated update period
• Your file is in the correct location: /chains/{network}/{chain-id}/
• Your server uses HTTPS and has reliable uptime
• For indexed nodes, include tx_index = true in your config
• Outdated or unavailable snapshots may be removed from the registry

Thank you for helping us make node syncing faster and easier for everyone!