Storage
State commitment, historical queries, receipt retention, and backend configuration in Paxeer.
Overview
Paxeer storage separates active state commitment from historical state queries and receipt storage. Each has its own configuration and retention behavior. The implementation is under paxeer-network/storage/.
State Commitment
The state-commit layer under storage/state_db/sc/ includes MemIAVL, FlatKV, and a composite store that routes state operations. It participates in application commitment, snapshot import/export, and supported proof queries.
The default write mode is memiavl_only. Other named modes support staged migration to FlatKV. Select routing modes according to the existing data layout and the chain's migration plan.
# app.toml
[state-commit]
sc-enable = true
sc-write-mode = "memiavl_only"storage/config/sc_config.go, storage/config/write_mode.go, storage/state_db/sc/composite/store.go.Historical State Store
The state-store layer maintains versioned key/value data for historical queries. Configure imported data and retention for the historical range you need. Commitment proofs also require the corresponding commitment-store history.
# app.toml
[state-store]
ss-enable = true
ss-backend = "pebbledb"
ss-keep-recent = 100000The default backend is Pebble and the default retention is 100,000 versions. ss-keep-recent = 0 retains all available versions. The config also supports a separate EVM historical store through evm-ss-split; its data routing and missing-key behavior differ from the unsplit store.
storage/config/ss_config.go, storage/config/toml.go, storage/state_db/ss/.RocksDB Backend
The optional RocksDB backend uses user-defined timestamps and column families for versioned state. Build it from the Paxeer subtree:
make build-rocksdb
make install-rocksdbAfter installing the compatible binary, set ss-backend = "rocksdb" under [state-store]. When changing backends, import or restore data in the target backend's format.
Compare backends with the same revision, hardware, retained history, and request workload. Measure historical-query latency, iteration time, disk usage, and write throughput for the operations your application uses.
Makefile — build-rocksdb, install-rocksdb; storage/db_engine/rocksdb/mvcc/opts.go.Receipts and Blocks
# app.toml: root setting must precede section headers
min-retain-blocks = 100000
[receipt-store]
rs-backend = "pebbledb"The receipt configuration accepts pebbledb or its pebble alias. Set receipt retention with the root min-retain-blocks setting and historical state retention with ss-keep-recent.
--mode archive configures block and SS retention to zero, preserving imported history and subsequent state. Start with a dataset covering the historical range you plan to serve.
storage/config/receipt_config.go, node/params/config.go — setArchiveTypeAppConfig.Snapshots and Recovery
Application snapshots, commitment-store snapshots, and filesystem backups are distinct. Use the mechanism and directory layout matching your build. Stop a node before replacing its data, preserve validator last-sign state, and keep a compatible copy of the configuration and genesis.
Changelogs and write-ahead logs support storage replay and recovery. Follow the recovery procedure for the selected store, and preserve consensus signer state alongside the validator key.
storage/wal/, storage/state_db/sc/composite/, consensus/privval/file.go.Inspection Tools
The separate PaxDB command provides storage inspection and benchmark operations. Build or run it from the Paxeer subtree, using its help to select the correct database path and height:
go run ./storage/tools/cmd/paxdb --help
go run ./storage/tools/cmd/paxdb dump-iavl --help
go run ./storage/tools/cmd/paxdb dump-db --helpRun these inspection operations through paxdb. Use an offline copy when an operation needs exclusive database access.
storage/tools/cmd/paxdb/main.go, storage/tools/cmd/paxdb/operations/.