dig-coinstore 0.1.0

DIG L2 global coin state database — persistent UTXO store with Merkle proofs, hint indexing, and rollback support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

//! # 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:** `CoinRecord`s, `CoinState`s, 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`
//!
//! See also:
//! - Chia CoinStore: `chia/full_node/coin_store.py`
//! - Chia HintStore: `chia/full_node/hint_store.py`

// ─────────────────────────────────────────────────────────────────────────────
// Re-exports: Chia ecosystem types (STR-005)
// ─────────────────────────────────────────────────────────────────────────────
// These re-exports ensure consumers of dig-coinstore can access core Chia types
// without adding direct dependencies on chia-protocol or dig-clvm.
//
// The dependency chain is:
//   chia-protocol  →  dig-clvm  →  dig-coinstore  →  consumers
//       (defines)    (re-exports)   (re-exports)
//
// Requirement: STR-005
// Spec: docs/requirements/domains/crate_structure/specs/STR-005.md

/// 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`).
pub use dig_clvm::Coin;

/// 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`).
pub use dig_clvm::Bytes32;

/// Lightweight coin state for the sync protocol: coin + created_height + spent_height.
/// Re-exported from `dig-clvm` (which re-exports from `chia-protocol`).
pub use dig_clvm::CoinState;

/// 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.
pub use chia_protocol::CoinStateFilters;

// STO-007: at least one storage backend feature must be enabled so `rocksdb` / `heed` stay optional
// dependencies and backend modules are never half-linked. Without this, `cargo build --no-default-features`
// would compile an unusable crate (no `RocksDbBackend` / `LmdbBackend` symbols).
//
// Spec: docs/requirements/domains/storage/specs/STO-007.md — "Compile-Time Validation"
#[cfg(not(any(feature = "rocksdb-storage", feature = "lmdb-storage")))]
compile_error!(
    "dig-coinstore: enable at least one storage backend Cargo feature: \
     `rocksdb-storage` and/or `lmdb-storage`, or `full-storage` for both. \
     The default package features include `rocksdb-storage`."
);

// ─────────────────────────────────────────────────────────────────────────────
// Top-level modules
// ─────────────────────────────────────────────────────────────────────────────
// Each module corresponds to one or more requirement domains in
// docs/requirements/domains/. The module hierarchy is defined by STR-002.

/// CoinStore struct — primary public API orchestration.
/// See: docs/requirements/domains/crate_api/specs/API-001.md
pub mod coin_store;

/// Configuration types and constants.
/// See: docs/requirements/domains/crate_api/specs/API-003.md
pub mod config;

// API-003: expose config surface at crate root (see also `storage::StorageBackend` trait).
pub use config::{
    default_storage_backend_for_features, CoinStoreConfig, StorageBackend,
    BLOOM_FILTER_BITS_PER_KEY, DEFAULT_LMDB_MAP_SIZE, DEFAULT_MAX_QUERY_RESULTS,
    DEFAULT_MAX_SNAPSHOTS, DEFAULT_ROCKSDB_MAX_OPEN_FILES, DEFAULT_ROCKSDB_WRITE_BUFFER_SIZE,
};

/// Error types for all coinstore operations.
/// See: docs/requirements/domains/crate_api/specs/API-004.md
pub mod error;

pub use error::CoinStoreError;

/// Domain types: CoinRecord, BlockData, CoinAddition, result structs, [`CoinStoreStats`], [`CoinStoreSnapshot`],
/// [`UnspentLineageInfo`], type aliases [`CoinId`] / [`PuzzleHash`].
/// See: docs/requirements/domains/crate_api/specs/API-002.md
pub mod types;

// Wire-shaped coin row for interop (see `types` module doc: mirrors upstream `CoinRecord` until
// `chia-protocol` in the `dig-clvm` graph exposes it; then replace with `pub use chia_protocol::CoinRecord as ChiaCoinRecord`).
pub use types::{
    ApplyBlockResult, BlockData, ChiaCoinRecord, CoinAddition, CoinId, CoinRecord,
    CoinStoreSnapshot, CoinStoreStats, PuzzleHash, RollbackResult, UnspentLineageInfo,
};

/// Block application pipeline (Phase 1 validation + Phase 2 mutation).
/// See: docs/requirements/domains/block_application/specs/
pub mod block_apply;

/// Rollback pipeline for chain reorganization recovery.
/// See: docs/requirements/domains/rollback/specs/
pub mod rollback;

/// All query method implementations on CoinStore.
/// See: docs/requirements/domains/queries/specs/
pub mod queries;

/// Hint store for puzzle hash hints on coins.
/// See: docs/requirements/domains/hints/specs/
pub mod hints;

/// Tiered spent coin archival (hot/archive/prune).
/// See: docs/requirements/domains/performance/specs/PRF-005.md
pub mod archive;

// ─────────────────────────────────────────────────────────────────────────────
// Subdirectory modules
// ─────────────────────────────────────────────────────────────────────────────

/// Storage backend abstraction (trait + RocksDB/LMDB implementations).
/// Backend modules are feature-gated: `rocksdb-storage`, `lmdb-storage`.
/// See: docs/requirements/domains/storage/specs/
pub mod storage;

/// Open a concrete [`storage::StorageBackend`] for the engine in [`config::CoinStoreConfig::backend`].
///
/// **STO-007:** runtime factory when one or both backends are compiled (`full-storage`); callers that only need
/// the KV layer (not [`coin_store::CoinStore`]) use this entry point. See [`storage::open_storage_backend`].
pub use storage::open_storage_backend;

/// Sparse Merkle tree for state root computation and proofs.
/// See: docs/requirements/domains/merkle/specs/
pub mod merkle;

/// In-memory caching: unspent set, LRU cache, materialized counters.
/// See: docs/requirements/domains/performance/specs/PRF-001..003.md
pub mod cache;