iotexproject / iotexproject/iotex-bootstrap
Docs: add checksum verification to snapshot download instructions
- Dominant language
- Shell
- Stars
- 97
- Forks
- 43
- Avg merge
- 1h 7m
- Merged PRs (30d)
- 2
Description
### Problem
The snapshot download steps in the README ([core](https://t.iotex.me/mainnet-data-snapshot-core-latest), [gateway](https://t.iotex.me/mainnet-data-snapshot-gateway-latest)) 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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.