store_qmdb/
lib.rs

1//! Store-backed bridge for Commonware authenticated storage proofs.
2//!
3//! The crate currently supports multiple Commonware authenticated backends:
4//! - ordered QMDB (`qmdb::any` and `qmdb::current::ordered`)
5//! - immutable (`qmdb::immutable`)
6//! - keyless (`qmdb::keyless`)
7//!
8//! Writers upload exact Commonware operations into the Exoware store, then publish an
9//! externally authoritative watermark once the uploaded prefix is complete.
10//!
11//! Uploads may still happen concurrently and out of order. Current batch-boundary
12//! state may also be uploaded ahead of publication. Only watermark publication is
13//! monotonic: publishing watermark `W` means the whole contiguous prefix
14//! `[0, W]` is available and may now be trusted by readers.
15//!
16//! Readers fence historical queries against that low watermark. Historical proofs
17//! use the global ops-MMR nodes stored by `Position`.
18//!
19//! Current ordered proofs use versioned current-state deltas:
20//! - bitmap chunk rows
21//! - grafted-node rows
22//!
23//! Those rows are versioned by uploaded batch boundary `Location`, not by the
24//! final published watermark. That is what preserves lower-boundary current
25//! proofs below a later published low watermark.
26
27mod auth;
28#[cfg(any(test, feature = "test-utils"))]
29mod boundary;
30pub(crate) mod codec;
31mod core;
32pub mod error;
33pub mod proof;
34pub mod prune;
35pub(crate) mod storage;
36
37mod immutable;
38mod keyless;
39mod ordered;
40mod unordered;
41
42pub use error::QmdbError;
43pub use immutable::ImmutableClient;
44pub use keyless::KeylessClient;
45pub use ordered::OrderedClient;
46pub use proof::{
47    AuthenticatedOperationRangeProof, CurrentOperationRangeProofResult, KeyValueProofResult,
48    MultiProofResult, OperationRangeProof, UnorderedOperationRangeProof,
49    VariantOperationRangeProof, VariantRoot,
50};
51pub use unordered::UnorderedClient;
52
53#[cfg(any(test, feature = "test-utils"))]
54pub use boundary::build_current_boundary_state;
55
56use commonware_cryptography::Digest;
57use commonware_storage::mmr::Location;
58
59/// Maximum encoded operation size for QMDB key and value payloads (u16 length on the wire).
60pub const MAX_OPERATION_SIZE: usize = u16::MAX as usize;
61
62/// QMDB proof/root variant supported by `exoware-qmdb`.
63#[derive(Clone, Copy, Debug, PartialEq, Eq)]
64pub enum QmdbVariant {
65    /// Historical `qmdb::any` root / proof over the uploaded ordered operation log.
66    Any,
67    /// Current-state `qmdb::current::ordered` root / proof at an uploaded batch boundary.
68    Current,
69}
70
71/// Historical value resolved for one logical key.
72#[derive(Clone, Debug, PartialEq, Eq)]
73pub struct VersionedValue<K, V> {
74    pub key: K,
75    pub location: Location,
76    pub value: Option<V>,
77}
78
79/// Metadata returned after uploading one batch of QMDB operations.
80#[derive(Clone, Copy, Debug, PartialEq, Eq)]
81pub struct UploadReceipt {
82    pub latest_location: Location,
83    pub operation_count: Location,
84    pub keyed_operation_count: u32,
85    pub writer_location_watermark: Option<Location>,
86    pub sequence_number: u64,
87}
88
89/// Current-state rows for one uploaded batch boundary.
90#[derive(Clone, Debug, PartialEq, Eq)]
91pub struct CurrentBoundaryState<D: Digest, const N: usize> {
92    pub root: D,
93    pub chunks: Vec<(u64, [u8; N])>,
94    pub grafted_nodes: Vec<(commonware_storage::mmr::Position, D)>,
95}
96
97// Keep test module inline since it tests the full integrated stack.
store_qmdb/lib.rs

store_qmdb/
lib.rs
