Crate dig_coinstore

Expand description

§dig-coinstore

Persistent global coin state database for the DIG Network L2 blockchain.

This crate manages the authoritative database of all spent and unspent coins across the entire blockchain using the coinset model (UTXO-like). It accepts validated blocks as input, applies their state transitions, and provides a rich query API for coin lookups by ID, puzzle hash, hint, parent, and height.

§Crate boundary

Input: Pre-validated BlockData (additions, removals, coinbase, hints)
Output: CoinRecords, CoinStates, state roots, Merkle proofs
Not in scope: CLVM execution, block production, networking, consensus

§Storage backends

Storage is feature-gated:

rocksdb-storage (default) — RocksDB with bloom filters and column families
lmdb-storage — LMDB with memory-mapped I/O
full-storage — Both backends enabled

§Module organization

Module	Responsibility	Requirement domain
`coin_store`	Primary public API struct	API-001
`config`	Configuration types and constants	API-003
`error`	Error enum	API-004
`types`	Domain types (CoinRecord, BlockData, etc.)	API-002, API-005..009
`block_apply`	Block application pipeline	BLK-001..014
`rollback`	Rollback / reorg recovery	RBK-001..007
`queries`	Coin state queries	QRY-001..011
`hints`	Hint store	HNT-001..006
`storage`	Backend trait + implementations	STO-001..008
`merkle`	Sparse Merkle tree + proofs	MRK-001..006
`cache`	In-memory caching (unspent set, LRU, counters)	PRF-001..003
`archive`	Tiered spent coin archival	PRF-005

§Spec reference

Master specification: docs/resources/SPEC.md Requirements: docs/requirements/IMPLEMENTATION_ORDER.md

Re-exports§

pub use config::default_storage_backend_for_features;
pub use config::CoinStoreConfig;
pub use config::StorageBackend;
pub use config::BLOOM_FILTER_BITS_PER_KEY;
pub use config::DEFAULT_LMDB_MAP_SIZE;
pub use config::DEFAULT_MAX_QUERY_RESULTS;
pub use config::DEFAULT_MAX_SNAPSHOTS;
pub use config::DEFAULT_ROCKSDB_MAX_OPEN_FILES;
pub use config::DEFAULT_ROCKSDB_WRITE_BUFFER_SIZE;
pub use error::CoinStoreError;
pub use types::ApplyBlockResult;
pub use types::BlockData;
pub use types::ChiaCoinRecord;
pub use types::CoinAddition;
pub use types::CoinId;
pub use types::CoinRecord;
pub use types::CoinStoreSnapshot;
pub use types::CoinStoreStats;
pub use types::PuzzleHash;
pub use types::RollbackResult;
pub use types::UnspentLineageInfo;
pub use storage::open_storage_backend;

Modules§

archive: Tiered spent coin archival (hot/archive/prune). See: docs/requirements/domains/performance/specs/PRF-005.md Tiered spent coin archival for dig-coinstore.
block_apply: Block application pipeline (Phase 1 validation + Phase 2 mutation). See: docs/requirements/domains/block_application/specs/ Block application pipeline for dig-coinstore.
cache: In-memory caching: unspent set, LRU cache, materialized counters. See: docs/requirements/domains/performance/specs/PRF-001..003.md In-memory caching layer for dig-coinstore.
coin_store: CoinStore struct — primary public API orchestration. See: docs/requirements/domains/crate_api/specs/API-001.md CoinStore — the primary public API struct for dig-coinstore.
config: Configuration types and constants. See: docs/requirements/domains/crate_api/specs/API-003.md Configuration types and constants for dig-coinstore.
error: Error types for all coinstore operations. See: docs/requirements/domains/crate_api/specs/API-004.md Error types for dig-coinstore.
hints: Hint store for puzzle hash hints on coins. See: docs/requirements/domains/hints/specs/ Hint store for puzzle hash hints on coins.
merkle: Sparse Merkle tree for state root computation and proofs. See: docs/requirements/domains/merkle/specs/ Sparse Merkle tree for state root computation.
queries: All query method implementations on CoinStore. See: docs/requirements/domains/queries/specs/ Query method implementations for dig-coinstore.
rollback: Rollback pipeline for chain reorganization recovery. See: docs/requirements/domains/rollback/specs/ Rollback pipeline for chain reorganization recovery.
storage: Storage backend abstraction (trait + RocksDB/LMDB implementations). Backend modules are feature-gated: rocksdb-storage, lmdb-storage. See: docs/requirements/domains/storage/specs/ Storage backend abstraction for dig-coinstore.
types: Domain types: CoinRecord, BlockData, CoinAddition, result structs, CoinStoreStats, CoinStoreSnapshot, UnspentLineageInfo, type aliases CoinId / PuzzleHash. See: docs/requirements/domains/crate_api/specs/API-002.md Domain types for dig-coinstore.

Structs§

Coin: The fundamental coin type in the Chia coinset model. CoinId = sha256(parent_coin_info || puzzle_hash || amount). Re-exported from dig-clvm (which re-exports from chia-protocol).
CoinState: Lightweight coin state for the sync protocol: coin + created_height + spent_height. Re-exported from dig-clvm (which re-exports from chia-protocol).
CoinStateFilters: Filters for batch coin state queries (include_spent, include_unspent, include_hinted, min_amount). Used by batch_coin_states_by_puzzle_hashes() (QRY-007). Not re-exported by dig-clvm, so imported directly from chia-protocol.

Type Aliases§

Bytes32: A 32-byte hash used for coin IDs, puzzle hashes, block hashes, state roots. Re-exported from dig-clvm (which re-exports from chia-protocol).