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 all block bodies; prunes eligible old witnesses after STARK proof Validators, full peers providing sync
light Pruned (Rolling): retains recent bodies, witnesses, and state roots Resource-constrained nodes participating in consensus

light is the CLI/config alias for the whitepaper’s Pruned (Rolling) profile. It is not a header-only light client; that client remains a future milestone. Storage profile and consensus role are separate choices.

Configuring the Profile

Set the profile via CLI flag or node.toml:

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

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

Load the file explicitly with shell-node run --config node.toml. Support for [storage].profile is available in unreleased node source builds; older binaries may silently ignore this section. Use the explicit CLI flag on those versions. An explicit --storage-profile overrides the TOML value, including --storage-profile full. With neither setting, the default is full. Invalid TOML profile values reject startup in the updated source build.

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 ✅ All (body_retention = 0) ✅ Recent 4,096 blocks
PQ witnesses ✅ All ✅ Recent (witness_retention blocks) ✅ Recent 64 blocks
World state (accounts) ✅ Full history ✅ Recent snapshots ✅ Recent only
STARK proofs ✅ Kept ✅ Kept ✅ Kept

full nodes retain transaction bodies indefinitely (body_retention = 0). Proof-based witness pruning does not remove those bodies: a block can report pruningStatus: "pruned" while its transaction bodies remain available. Witness pruning is subject to the retention window, verified proof coverage, and the proof replacement grace period.

Query shell_getStorageProfile for the running node’s effective windows. The current v0.27.3 testnet Full profile reports witness_retention = 256 and proof_replacement_grace = 128; these values are block counts.

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:

  • archive nodes: will serve historical bodies and witnesses
  • full nodes: retain historical bodies and serve witnesses within their retention window
  • light nodes: can serve retained bodies; older bodies become unavailable after pruning

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: Changes the retention policy to rolling windows: 4,096 blocks for bodies and 64 blocks for witnesses by default. It does not delete all bodies and witnesses at startup. Recent data remains subject to those windows, and witness pruning also requires verified proof coverage and the proof replacement grace period. Data actually pruned under the new policy requires re-syncing from a peer that still retains it to recover.

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": 256,
  "keep_recent": 0,
  "proof_replacement_grace": 128,
  "state_pruning_experimental": false
}
Field Type Description
profile string "archive", "full", or "pruned" (light in CLI/config)
body_retention number Block body retention window (0 = unlimited for archive and full)
witness_retention number Witness retention in blocks
keep_recent number Recent state-root retention target (0 retains all snapshots)
proof_replacement_grace number Delay after proof before pruning
state_pruning_experimental boolean Legacy compatibility flag; does not gate rolling state pruning

Rolling/light state pruning runs automatically when keep_recent is nonzero. With a nonzero consensus epoch length, it retains the last finalized epoch boundary and newer state so a restarted node can recover active authorities without applying pending Registry changes. This may exceed keep_recent; the preceding window becomes eligible for pruning after the next boundary is finalized. See consensus recovery.

When neither --storage-profile nor a storage profile in node.toml is specified, the standard node CLI uses full; this RPC returns its descriptor.

Errors: -32003 if the RPC handler has no storage-profile descriptor (for example, an integration that does not provide one). Omitting the CLI option and configuration entry does not cause this error.

Added in shell-chain v0.18.0.