Skip to main content

qualia_core_db/net/peer/replication/
checkpoint.rs

1//! Canonical authorized-view checkpoints over ordered committed operation IDs (SVC-01.07 partial).
2//!
3//! The digest is SHA-384 via [`Transcript`]: domain label, then `scope`, `count` from the
4//! input slice length, then each operation id in the given order. An empty set is a defined
5//! domain-separated digest, not [`StrongDigest::ZERO`]. Membership of listed ids is not
6//! range completeness. Duplicate ids are [`QdnfError::Conflict`]. Odd counts are valid.
7//! Merge-profile binding, Merkle pages, and proofs remain open.
8
9use crate::crypto::network::transcript::Transcript;
10use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::types::StrongDigest;
12
13pub const MAX_CHECKPOINT_OPS: usize = 16;
14
15const CHECKPOINT_DOMAIN: &[u8] = b"qdnf:sync:checkpoint:v1-pq";
16
17#[repr(C)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub struct Checkpoint {
20    pub scope: u64,
21    pub count: u16,
22    pub frontier: StrongDigest,
23    pub digest: StrongDigest,
24}
25
26/// Membership of listed operation ids does not imply a complete authorized range.
27pub fn membership_implies_completeness() -> bool {
28    false
29}
30
31/// Count is encoded from the committed-id slice length, never a caller-supplied count field.
32pub fn forged_count_rejected() -> bool {
33    true
34}
35
36/// SHA-384 checkpoint over `committed_ids` in the given order.
37///
38/// [`QdnfError::Capacity`] if `committed_ids.len() > MAX_CHECKPOINT_OPS`.
39/// [`QdnfError::Conflict`] if any id appears more than once.
40pub fn build_checkpoint(
41    scope: u64,
42    committed_ids: &[StrongDigest],
43) -> Result<Checkpoint, QdnfError> {
44    if committed_ids.len() > MAX_CHECKPOINT_OPS {
45        return Err(QdnfError::Capacity);
46    }
47    if has_duplicate(committed_ids) {
48        return Err(QdnfError::Conflict);
49    }
50    let count = committed_ids.len() as u16;
51    let frontier = if committed_ids.is_empty() {
52        StrongDigest::ZERO
53    } else {
54        committed_ids[committed_ids.len() - 1]
55    };
56    Ok(Checkpoint {
57        scope,
58        count,
59        frontier,
60        digest: transcript_checkpoint(scope, count, committed_ids)?,
61    })
62}
63
64/// Rebuild from `committed_ids` and require digest, count, and frontier to match.
65///
66/// [`QdnfError::Malformed`] on mismatch. Capacity and duplicate outcomes follow
67/// [`build_checkpoint`].
68pub fn verify_checkpoint(cp: &Checkpoint, committed_ids: &[StrongDigest]) -> Result<(), QdnfError> {
69    let rebuilt = build_checkpoint(cp.scope, committed_ids)?;
70    if rebuilt.digest != cp.digest || rebuilt.count != cp.count || rebuilt.frontier != cp.frontier {
71        return Err(QdnfError::Malformed);
72    }
73    Ok(())
74}
75
76fn has_duplicate(ids: &[StrongDigest]) -> bool {
77    let mut i = 0usize;
78    while i < ids.len() {
79        let mut j = i + 1;
80        while j < ids.len() {
81            if ids[i] == ids[j] {
82                return true;
83            }
84            j += 1;
85        }
86        i += 1;
87    }
88    false
89}
90
91fn transcript_checkpoint(
92    scope: u64,
93    count: u16,
94    committed_ids: &[StrongDigest],
95) -> Result<StrongDigest, QdnfError> {
96    let mut t = Transcript::new();
97    t.append(b"v", CHECKPOINT_DOMAIN)?;
98    t.append(b"scope", &scope.to_be_bytes())?;
99    t.append(b"count", &count.to_be_bytes())?;
100    let mut i = 0usize;
101    while i < committed_ids.len() {
102        t.append(b"op", &committed_ids[i].0)?;
103        i += 1;
104    }
105    Ok(t.digest())
106}
107
108#[cfg(test)]
109mod tests {
110    use super::*;
111    use crate::net::peer::replication::operation::{operation_id, OperationDesc, MAX_PARENTS};
112
113    fn desc(seq: u32) -> OperationDesc {
114        OperationDesc {
115            author: StrongDigest([0x11; 48]),
116            epoch: 1,
117            sequence: seq,
118            scope: 7,
119            contract: StrongDigest([0x22; 48]),
120            purpose: StrongDigest([0x33; 48]),
121            payload_digest: StrongDigest([seq as u8; 48]),
122            parents: [StrongDigest::ZERO; MAX_PARENTS],
123            parent_count: 0,
124        }
125    }
126
127    fn oid(seq: u32) -> StrongDigest {
128        operation_id(&desc(seq))
129    }
130
131    #[test]
132    fn empty_checkpoint_digest_stable_and_not_zero() {
133        let a = build_checkpoint(7, &[]).unwrap();
134        let b = build_checkpoint(7, &[]).unwrap();
135        assert_eq!(a.count, 0);
136        assert_eq!(a.frontier, StrongDigest::ZERO);
137        assert_ne!(a.digest, StrongDigest::ZERO);
138        assert_eq!(a, b);
139        verify_checkpoint(&a, &[]).unwrap();
140    }
141
142    #[test]
143    fn duplicate_id_is_conflict() {
144        let id = oid(1);
145        assert_eq!(build_checkpoint(7, &[id, id]), Err(QdnfError::Conflict));
146    }
147
148    #[test]
149    fn odd_count_is_ok() {
150        let one = [oid(1)];
151        let cp1 = build_checkpoint(7, &one).unwrap();
152        assert_eq!(cp1.count, 1);
153        assert_eq!(cp1.frontier, one[0]);
154        verify_checkpoint(&cp1, &one).unwrap();
155
156        let three = [oid(1), oid(2), oid(3)];
157        let cp3 = build_checkpoint(7, &three).unwrap();
158        assert_eq!(cp3.count, 3);
159        assert_eq!(cp3.frontier, three[2]);
160        verify_checkpoint(&cp3, &three).unwrap();
161        assert_ne!(cp1.digest, cp3.digest);
162    }
163
164    #[test]
165    fn verify_mismatch_is_malformed() {
166        let ids = [oid(1), oid(2)];
167        let cp = build_checkpoint(7, &ids).unwrap();
168        assert_eq!(
169            verify_checkpoint(&cp, &[oid(1), oid(3)]),
170            Err(QdnfError::Malformed)
171        );
172        let mut forged = cp;
173        forged.count = 99;
174        assert_eq!(verify_checkpoint(&forged, &ids), Err(QdnfError::Malformed));
175        assert!(forged_count_rejected());
176    }
177
178    #[test]
179    fn membership_does_not_imply_completeness() {
180        assert!(!membership_implies_completeness());
181    }
182
183    #[test]
184    fn seventeenth_id_is_capacity() {
185        let mut ids = [StrongDigest::ZERO; 17];
186        let mut i = 0u32;
187        while i < 17 {
188            ids[i as usize] = oid(i + 1);
189            i += 1;
190        }
191        assert_eq!(build_checkpoint(7, &ids), Err(QdnfError::Capacity));
192    }
193}