Skip to content

Docs: add checksum verification to snapshot download instructions #330

Description

@envestcc

Problem

The snapshot download steps in the README (core, gateway) provide no way for users to verify the integrity of the downloaded archive. Snapshots are large (the mainnet gateway archive is ~48 GB), so interrupted or truncated downloads are common.

When the archive is truncated, extraction fails with errors that don't make the root cause obvious:

gzip: stdin: unexpected end of file
tar: Unexpected EOF in archive
tar: Error is not recoverable: exiting now

A user recently reported exactly this. On investigation the snapshot on the server was fully intact — the failure was a truncated download on the user's side. Without a published checksum (or even an expected file size), users can't tell a corrupt download apart from a corrupt snapshot, and end up re-downloading blindly or filing false bug reports.

Suggestion

  1. Publish a checksum (e.g. SHA256SUMS) alongside each snapshot at t.iotex.me / storage.iotex.io.

  2. Add a verification step to the README snapshot section, e.g.:

    curl -L -C - -o $IOTEX_HOME/data.tar.gz https://t.iotex.me/mainnet-data-snapshot-core-latest
    curl -L -o $IOTEX_HOME/data.tar.gz.sha256 https://t.iotex.me/mainnet-data-snapshot-core-latest.sha256
    sha256sum -c $IOTEX_HOME/data.tar.gz.sha256
    
  3. At minimum, document the expected file size so users can sanity-check (the current mainnet gateway archive is 48598308441 bytes), and recommend gunzip -t before extracting.

This would make download failures self-diagnosable and cut down on confusion.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions