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}