Skip to main content

hyprstream_ledger/
journal.rs

1//! Journal, checkpoint, and outbox types + the checkpoint signing seam (plan
2//! §2a, §2d, §2e).
3//!
4//! Scope note: the hash-chained journal *data model* and the checkpoint
5//! *commitments* live here so the [`crate::LedgerBackend`] trait is complete and
6//! MemLedger is a true oracle. The RocksDB-persisted journal, group commit, and
7//! the standalone `hyprstream ledger verify` offline tool are later work items
8//! (1.2/1.3/1.10); this module builds only the in-memory reference.
9
10use serde::{Deserialize, Serialize};
11
12use crate::engine::Op;
13use crate::errors::LedgerError;
14use crate::types::{Account, Did, PendingReservation, TransferId, TransferResult};
15
16/// Domain-separation tag for checkpoint signatures (plan §2d).
17pub const CHECKPOINT_DOMAIN: &[u8] = b"hs-ledger-checkpoint-v1";
18
19/// One committed operation in the hash chain. `prev_hash` links it to the prior
20/// entry; the *outcome* is in the chain too (plan §2a step 3), so tampering with
21/// a result breaks the chain.
22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
23pub struct JournalEntry {
24    /// Monotonic sequence, starting at 1.
25    pub seq: u64,
26    /// Hash of entry `seq - 1` (`[0u8; 32]` for the genesis entry).
27    pub prev_hash: [u8; 32],
28    /// Logical commit timestamp.
29    pub ts: u64,
30    /// The op that was applied.
31    pub op: Op,
32    /// The recorded result (`Ok` summary or the deterministic error).
33    pub result: Result<TransferResult, LedgerError>,
34}
35
36impl JournalEntry {
37    /// The blake3-256 hash of this entry's canonical encoding. Used as the next
38    /// entry's `prev_hash` and as the checkpoint `head_hash`.
39    pub fn hash(&self) -> Result<[u8; 32], LedgerError> {
40        let mut hasher = blake3::Hasher::new();
41        hasher.update(b"hs-ledger-journal-entry-v1");
42        cbor_into(&mut hasher, self)?;
43        Ok(*hasher.finalize().as_bytes())
44    }
45}
46
47/// The head of the hash chain — the constant-size commitment the backend keeps
48/// in memory and (for RocksLedger) at `CF(meta)/"head"`.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
50pub struct ChainHead {
51    /// Sequence of the last committed entry (`0` when empty).
52    pub seq: u64,
53    /// Hash of the last committed entry (`[0u8; 32]` when empty).
54    pub head_hash: [u8; 32],
55}
56
57/// Ordered position of an outbox item.
58#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
59pub struct OutboxSeq(pub u64);
60
61/// What a proof-plane item evidences (plan §2e). The ledger crate only *stages*
62/// these; the service layer drains and emits them to the PDS.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
64pub enum OutboxKind {
65    /// A dual-signed usage receipt for a posted spend/issue.
66    Receipt,
67    /// A signed checkpoint to publish.
68    Checkpoint,
69}
70
71/// A committed-but-unemitted proof-plane item, staged transactionally with the
72/// ledger commit (the outbox pattern) and drained by
73/// [`crate::LedgerBackend::outbox_peek`] / `outbox_ack`.
74#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
75pub struct OutboxItem {
76    /// Ordered position.
77    pub seq: OutboxSeq,
78    /// The kind of proof this item carries.
79    pub kind: OutboxKind,
80    /// The transfer this evidences (for receipts).
81    pub transfer_id: Option<TransferId>,
82    /// The journal sequence of the commit that produced it.
83    pub journal_seq: u64,
84}
85
86/// The injection seam for checkpoint signing (mirrors `mac::audit::AuditSigner`).
87///
88/// PLAN DECISION 8: the seam exists for **key/policy injection**, not
89/// optionality. The production impl (service layer) wraps
90/// `hyprstream_crypto::cose_sign::sign_composite` and is policy-aware
91/// (Hybrid/Classical); tests supply a deterministic signer. `hyprstream-crypto`
92/// is an unconditional dependency — a build that cannot sign checkpoints must not
93/// exist.
94pub trait CheckpointSigner {
95    /// Sign the domain-separated signing input (see [`checkpoint_signing_input`]).
96    fn sign(&self, signing_input: &[u8]) -> Result<Vec<u8>, LedgerError>;
97    /// The signing identity (the cell ledger's service DID).
98    fn ledger_id(&self) -> &Did;
99}
100
101/// A periodic, PQC-hybrid-signed commitment to ledger state (plan §2d). It is the
102/// anchorable object and the settlement reference. Per-commit chaining is cheap
103/// and unsigned; only checkpoints carry a signature.
104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
105pub struct SignedCheckpoint {
106    /// The cell ledger's service identity.
107    pub ledger_id: Did,
108    /// Journal head at checkpoint time.
109    pub seq: u64,
110    /// Hash of journal entry `seq`.
111    pub head_hash: [u8; 32],
112    /// Merkle-style root over all accounts sorted by id (plan §2d).
113    pub balances_root: [u8; 32],
114    /// Root over open reservations sorted by id.
115    pub pending_root: [u8; 32],
116    /// Logical commit time of the checkpoint.
117    pub ts: u64,
118    /// Hash of the previous checkpoint (checkpoints chain too).
119    pub prev_checkpoint_hash: [u8; 32],
120    /// COSE composite signature over [`checkpoint_signing_input`].
121    pub sig: Vec<u8>,
122}
123
124impl SignedCheckpoint {
125    /// A digest over the whole (signed) checkpoint — the value the next
126    /// checkpoint chains to via `prev_checkpoint_hash`, and the object an OTS
127    /// anchor attests (plan §2h).
128    pub fn digest(&self) -> Result<[u8; 32], LedgerError> {
129        let mut h = blake3::Hasher::new();
130        h.update(b"hs-ledger-checkpoint-digest-v1");
131        cbor_into(&mut h, self)?;
132        Ok(*h.finalize().as_bytes())
133    }
134
135    /// The bytes the signature covers (everything except `sig`).
136    pub fn signing_input(&self) -> Result<Vec<u8>, LedgerError> {
137        let content = CheckpointContent {
138            ledger_id: &self.ledger_id,
139            seq: self.seq,
140            head_hash: self.head_hash,
141            balances_root: self.balances_root,
142            pending_root: self.pending_root,
143            ts: self.ts,
144            prev_checkpoint_hash: self.prev_checkpoint_hash,
145        };
146        content.signing_input()
147    }
148}
149
150/// The signable content of a checkpoint (the `sig`-free projection).
151#[derive(Serialize)]
152pub struct CheckpointContent<'a> {
153    /// See [`SignedCheckpoint::ledger_id`].
154    pub ledger_id: &'a Did,
155    /// See [`SignedCheckpoint::seq`].
156    pub seq: u64,
157    /// See [`SignedCheckpoint::head_hash`].
158    pub head_hash: [u8; 32],
159    /// See [`SignedCheckpoint::balances_root`].
160    pub balances_root: [u8; 32],
161    /// See [`SignedCheckpoint::pending_root`].
162    pub pending_root: [u8; 32],
163    /// See [`SignedCheckpoint::ts`].
164    pub ts: u64,
165    /// See [`SignedCheckpoint::prev_checkpoint_hash`].
166    pub prev_checkpoint_hash: [u8; 32],
167}
168
169impl CheckpointContent<'_> {
170    /// Domain-separated signing input: a content hash prefixed by the domain tag
171    /// (the `mac::audit::audit_signing_input` shape — sign the hash, not the raw
172    /// bytes, so the signature is independent of the canonical-bytes choice).
173    pub fn signing_input(&self) -> Result<Vec<u8>, LedgerError> {
174        let mut hasher = blake3::Hasher::new();
175        cbor_into(&mut hasher, self)?;
176        Ok(checkpoint_signing_input(hasher.finalize().as_bytes()))
177    }
178}
179
180/// Assemble the domain-separated signing input from a 32-byte content hash.
181pub fn checkpoint_signing_input(content_hash: &[u8; 32]) -> Vec<u8> {
182    let mut v = Vec::with_capacity(CHECKPOINT_DOMAIN.len() + 32);
183    v.extend_from_slice(CHECKPOINT_DOMAIN);
184    v.extend_from_slice(content_hash);
185    v
186}
187
188/// Verify a checkpoint's composite signature against the ledger DID's key
189/// material, delegating to `hyprstream_crypto::cose_sign::verify_composite`.
190///
191/// This is the load-bearing use of the unconditional `hyprstream-crypto`
192/// dependency: checkpoint signatures gate anchoring, settlement, and dispute
193/// evidence, so the verification primitive belongs in the ledger crate. Full
194/// journal replay + multi-checkpoint verification (`verify.rs` / the CLI) is a
195/// later work item; this verifies a single checkpoint's signature.
196pub fn verify_checkpoint_signature(
197    cp: &SignedCheckpoint,
198    ed_vk: &ed25519_dalek::VerifyingKey,
199    pq_vk: Option<&hyprstream_crypto::pq::MlDsaVerifyingKey>,
200    require_pq: bool,
201) -> Result<(), LedgerError> {
202    let input = cp.signing_input()?;
203    hyprstream_crypto::cose_sign::verify_composite(&cp.sig, ed_vk, pq_vk, &input, &[], require_pq)
204        .map(|_| ())
205        .map_err(|e| LedgerError::Internal(format!("checkpoint signature invalid: {e}")))
206}
207
208/// Root over accounts sorted by id: `blake3(concat(blake3(id || cbor(account))))`.
209/// A deterministic commitment (not a sparse-Merkle proof system — sufficient for
210/// the drift/equivalence properties; a full accumulator can replace it later
211/// without changing the trait).
212pub fn balances_root<'a>(
213    accounts: impl Iterator<Item = &'a Account>,
214) -> Result<[u8; 32], LedgerError> {
215    let mut sorted: Vec<&Account> = accounts.collect();
216    sorted.sort_by_key(|a| a.id.0);
217    let mut root = blake3::Hasher::new();
218    root.update(b"hs-ledger-balances-root-v1");
219    for a in sorted {
220        let mut leaf = blake3::Hasher::new();
221        leaf.update(&a.id.0.to_be_bytes());
222        cbor_into(&mut leaf, a)?;
223        root.update(leaf.finalize().as_bytes());
224    }
225    Ok(*root.finalize().as_bytes())
226}
227
228/// Root over open (`Pending`) reservations sorted by id.
229pub fn pending_root<'a>(
230    reservations: impl Iterator<Item = &'a PendingReservation>,
231) -> Result<[u8; 32], LedgerError> {
232    let mut sorted: Vec<&PendingReservation> = reservations
233        .filter(|r| r.state == crate::types::PendingState::Pending)
234        .collect();
235    sorted.sort_by_key(|r| r.transfer.id.0);
236    let mut root = blake3::Hasher::new();
237    root.update(b"hs-ledger-pending-root-v1");
238    for r in sorted {
239        let mut leaf = blake3::Hasher::new();
240        leaf.update(&r.transfer.id.0.to_be_bytes());
241        cbor_into(&mut leaf, r)?;
242        root.update(leaf.finalize().as_bytes());
243    }
244    Ok(*root.finalize().as_bytes())
245}
246
247/// What one `tick` did (plan §2b.4 sweep + scheduled checkpoint).
248#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
249pub struct TickReport {
250    /// How many reservations the sweep expired.
251    pub expired: usize,
252    /// The sequence at which a checkpoint was cut, if any.
253    pub checkpointed: Option<u64>,
254}
255
256/// Serialize `value` as CBOR directly into a `Write` (a blake3 hasher), mapping
257/// the (practically unreachable) serializer error to a fail-closed
258/// [`LedgerError::Internal`] rather than unwrapping.
259fn cbor_into<W: std::io::Write, T: serde::Serialize>(
260    w: &mut W,
261    value: &T,
262) -> Result<(), LedgerError> {
263    ciborium::into_writer(value, w)
264        .map_err(|e| LedgerError::Internal(format!("cbor encoding failed: {e}")))
265}
266
267#[cfg(test)]
268#[allow(clippy::unwrap_used, clippy::expect_used)]
269mod tests {
270    use super::*;
271    use hyprstream_crypto::cose_sign::sign_composite;
272    use hyprstream_crypto::pq::{ml_dsa_sk_from_seed, ml_dsa_sk_to_vk_bytes, ml_dsa_vk_from_bytes};
273
274    /// End-to-end proof that the unconditional `hyprstream-crypto` dependency is
275    /// load-bearing: a checkpoint signed with the hybrid composite (EdDSA +
276    /// ML-DSA-65) verifies, and tampering with a committed field breaks it.
277    #[test]
278    fn checkpoint_hybrid_signature_roundtrips_and_detects_tamper() {
279        let ed_sk = ed25519_dalek::SigningKey::from_bytes(&[7u8; 32]);
280        let ed_vk = ed_sk.verifying_key();
281        let pq_sk = ml_dsa_sk_from_seed(&[9u8; 32]);
282        let pq_vk = ml_dsa_vk_from_bytes(&ml_dsa_sk_to_vk_bytes(&pq_sk)).unwrap();
283
284        let content = CheckpointContent {
285            ledger_id: &Did("did:web:cell.test".to_owned()),
286            seq: 42,
287            head_hash: [1u8; 32],
288            balances_root: [2u8; 32],
289            pending_root: [3u8; 32],
290            ts: 1000,
291            prev_checkpoint_hash: [0u8; 32],
292        };
293        let input = content.signing_input().unwrap();
294        let sig = sign_composite(&ed_sk, Some(&pq_sk), &input, &[]).unwrap();
295
296        let mut cp = SignedCheckpoint {
297            ledger_id: Did("did:web:cell.test".to_owned()),
298            seq: 42,
299            head_hash: [1u8; 32],
300            balances_root: [2u8; 32],
301            pending_root: [3u8; 32],
302            ts: 1000,
303            prev_checkpoint_hash: [0u8; 32],
304            sig,
305        };
306
307        // Valid signature verifies (fail-closed require_pq = true).
308        verify_checkpoint_signature(&cp, &ed_vk, Some(&pq_vk), true).unwrap();
309
310        // Tampering with a committed field changes the signing input ⇒ rejected.
311        cp.balances_root = [0xFFu8; 32];
312        assert!(verify_checkpoint_signature(&cp, &ed_vk, Some(&pq_vk), true).is_err());
313    }
314}