Storage Profiles

Shell-Chain nodes operate in one of three storage profiles: archive, full, and light. The profile controls how much chain history the node retains and what data it makes available to peers.

See also: Quickstart Guide · Testnet Operator Guide · JSON-RPC API Reference

Table of Contents

Profile Overview

Profile Description Use case
archive Retains all block bodies, witnesses, and state history forever Block explorers, auditors, historical queries
full Retains recent bodies and witnesses; prunes old ones after STARK proof Validators, full peers providing sync
light Retains only headers and recent state roots Wallets, light clients, resource-constrained nodes

Configuring the Profile

Set the profile via CLI flag or node.toml:

# CLI
shell-node --storage-profile archive
shell-node --storage-profile full
shell-node --storage-profile light

# node.toml
[storage]
profile = "full"

The node validates profile consistency with on-disk data at startup. If the stored data does not match the declared profile, startup is aborted with a diagnostic message.

Data Retention Per Profile

Field archive full light
Block headers ✅ All ✅ All ✅ All
Block bodies (tx lists) ✅ All ✅ Recent (until STARK proof) ❌ Pruned
PQ witnesses ✅ All ✅ Recent (witness_retention blocks) ❌ Pruned
World state (accounts) ✅ Full history ✅ Recent snapshots ✅ Recent only
STARK proofs ✅ Kept ✅ Kept ✅ Kept

full nodes prune block bodies and witnesses once a STARK proof for the batch has been received and verified. The witness_retention window (default: 128 blocks) gives light clients time to fetch witnesses before pruning.

P2P Capability Advertisement

Nodes advertise their storage profile to peers via the StorageCapability extension in the libp2p handshake. This lets peers know what data they can request:

When syncing, nodes prefer archive or full peers for body/witness downloads.

Switching Profiles

archive ↔ full: Safe to switch in either direction. The node will begin pruning (when moving to full) or stop pruning (when moving to archive) from the next block onward. Existing data on disk is not deleted retroactively.

full → light: Prunes all stored bodies and witnesses on next startup. This operation is irreversible — the data cannot be recovered without re-syncing from an archive peer.

light → full or archive: Requires re-syncing body/witness data from a full or archive peer. The node will automatically back-fill historical data during the initial sync phase.

RPC: shell_getStorageProfile

Query the current storage profile over JSON-RPC:

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getStorageProfile","params":[],"id":1}'

Response:

{
  "profile": "full",
  "body_retention": 0,
  "witness_retention": 128,
  "keep_recent": 0,
  "proof_replacement_grace": 0,
  "state_pruning_experimental": false
}
Field Type Description
profile string "archive", "full", or "light"
body_retention number Block body retention window (0 = unlimited for archive)
witness_retention number Witness retention in blocks
keep_recent number Additional recent-block grace period
proof_replacement_grace number Delay after proof before pruning
state_pruning_experimental boolean Whether experimental state pruning is active

Errors: -32003 if no storage profile is configured (node started without --storage-profile and no node.toml entry).

Added in shell-chain v0.18.0.