Skip to main content

ratify_protocol/v2/
checkpoint_ack.rs

1//! Independent checkpoint acknowledgement wire form (SPEC-v2 §7.8). Mirrors
2//! Go `checkpoint_ack_v2.go`; the struct itself is declared in Go
3//! `release_v2.go`.
4
5use base64::{engine::general_purpose::STANDARD, Engine as _};
6
7use super::crypto::lower_hex;
8use super::errors::{plain, Classify, V2Error, V2ErrorClass, V2Result};
9use super::json::{canonical, obj, parse_wire, CJ};
10use super::limits::{
11    check_v2_wire_size, valid_v2_timestamp, MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2,
12};
13use super::wire::MAX_SAFE;
14
15/// An independent checkpoint's acknowledgement of one receipt-log entry.
16#[derive(Debug, Clone, PartialEq, Eq, Default)]
17pub struct V2CheckpointAcknowledgement {
18    pub log_id: String,
19    pub sequence: i64,
20    pub entry_hash: Vec<u8>,
21    pub timestamp: i64,
22}
23
24const CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS: &[&str] =
25    &["entry_hash", "log_id", "sequence", "timestamp"];
26
27fn validate_v2_checkpoint_acknowledgement(ack: &V2CheckpointAcknowledgement) -> V2Result<()> {
28    if ack.log_id.len() != 32
29        || !lower_hex(&ack.log_id)
30        || ack.sequence < 1
31        || ack.sequence > MAX_SAFE
32        || ack.entry_hash.len() != 48
33        || !valid_v2_timestamp(ack.timestamp)
34    {
35        return plain(
36            "wire v2: checkpoint acknowledgement log_id, sequence, entry_hash, or timestamp is invalid",
37        );
38    }
39    Ok(())
40}
41
42/// The canonical JSON wire form of an independent checkpoint
43/// acknowledgement: `{"entry_hash":<base64 of 48 bytes>,"log_id":<32
44/// lowercase hex>,"sequence":<integer>,"timestamp":<integer>}` (class
45/// `malformed` on failure).
46pub fn encode_v2_checkpoint_acknowledgement(
47    ack: &V2CheckpointAcknowledgement,
48) -> V2Result<Vec<u8>> {
49    validate_v2_checkpoint_acknowledgement(ack).classify(V2ErrorClass::Malformed)?;
50    canonical(&CJ::obj(vec![
51        ("entry_hash", CJ::Str(STANDARD.encode(&ack.entry_hash))),
52        ("log_id", CJ::s(&ack.log_id)),
53        ("sequence", CJ::Int(ack.sequence)),
54        ("timestamp", CJ::Int(ack.timestamp)),
55    ]))
56    .classify(V2ErrorClass::Malformed)
57}
58
59/// Strictly decode the acknowledgement wire form; only the canonical
60/// encoding is accepted (class `malformed` on failure).
61pub fn decode_v2_checkpoint_acknowledgement(data: &[u8]) -> V2Result<V2CheckpointAcknowledgement> {
62    (|| {
63        check_v2_wire_size(
64            data,
65            "checkpoint acknowledgement",
66            "MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2",
67            MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2,
68        )?;
69        let root = parse_wire(data, &["entry_hash"], &[])?;
70        let o = obj(&root)?;
71        o.require(CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS, &[])?;
72        o.only(CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS)?;
73        let entry_hash_text = o.str("entry_hash")?;
74        let log_id = o.str("log_id")?;
75        let sequence = o.i64("sequence")?;
76        let timestamp = o.i64("timestamp")?;
77        let entry_hash = STANDARD
78            .decode(&entry_hash_text)
79            .ok()
80            .filter(|h| STANDARD.encode(h) == entry_hash_text)
81            .ok_or_else(|| {
82                V2Error::plain(
83                    "wire v2: checkpoint acknowledgement entry_hash is not canonical base64",
84                )
85            })?;
86        let ack = V2CheckpointAcknowledgement {
87            log_id,
88            sequence,
89            entry_hash,
90            timestamp,
91        };
92        let canonical_bytes = encode_v2_checkpoint_acknowledgement(&ack)?;
93        if canonical_bytes != data {
94            return plain("wire v2: checkpoint acknowledgement is not canonically encoded");
95        }
96        Ok(ack)
97    })()
98    .classify(V2ErrorClass::Malformed)
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    fn ack() -> V2CheckpointAcknowledgement {
106        V2CheckpointAcknowledgement {
107            log_id: "0123456789abcdef0123456789abcdef".into(),
108            sequence: 7,
109            entry_hash: vec![0xab; 48],
110            timestamp: 1_800_000_000,
111        }
112    }
113
114    #[test]
115    fn round_trip_is_canonical_only() {
116        let wire = encode_v2_checkpoint_acknowledgement(&ack()).expect("encode");
117        assert_eq!(
118            String::from_utf8(wire.clone()).expect("utf8"),
119            format!(
120                "{{\"entry_hash\":\"{}\",\"log_id\":\"0123456789abcdef0123456789abcdef\",\"sequence\":7,\"timestamp\":1800000000}}",
121                STANDARD.encode([0xab; 48])
122            )
123        );
124        assert_eq!(
125            decode_v2_checkpoint_acknowledgement(&wire).expect("decode"),
126            ack()
127        );
128        let spaced = String::from_utf8(wire.clone())
129            .expect("utf8")
130            .replace(",", ", ");
131        let reordered = String::from_utf8(wire).expect("utf8").replace(
132            "\"sequence\":7,\"timestamp\":1800000000",
133            "\"timestamp\":1800000000,\"sequence\":7",
134        );
135        for bad in [spaced, reordered, "{}".into(), "null".into()] {
136            let e =
137                decode_v2_checkpoint_acknowledgement(bad.as_bytes()).expect_err("non-canonical");
138            assert_eq!(e.class, V2ErrorClass::Malformed);
139        }
140        for mutate in [
141            |a: &mut V2CheckpointAcknowledgement| {
142                a.log_id = "0123456789ABCDEF0123456789abcdef".into()
143            },
144            |a: &mut V2CheckpointAcknowledgement| a.sequence = 0,
145            |a: &mut V2CheckpointAcknowledgement| a.entry_hash.pop().map(|_| ()).unwrap_or(()),
146            |a: &mut V2CheckpointAcknowledgement| a.timestamp = -1,
147        ] {
148            let mut a = ack();
149            mutate(&mut a);
150            assert_eq!(
151                encode_v2_checkpoint_acknowledgement(&a)
152                    .expect_err("invalid")
153                    .class,
154                V2ErrorClass::Malformed
155            );
156        }
157    }
158
159    #[test]
160    fn size_limit_is_checked_before_parsing() {
161        let wire = encode_v2_checkpoint_acknowledgement(&ack()).expect("encode");
162        // At the limit: the size gate passes and the canonical check rejects
163        // the padding; at limit + 1 the size gate itself rejects.
164        let mut at_limit = wire.clone();
165        at_limit.resize(MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2, b' ');
166        let e = decode_v2_checkpoint_acknowledgement(&at_limit).expect_err("padded");
167        assert!(
168            !e.message
169                .contains("MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2"),
170            "{}",
171            e.message
172        );
173        let mut over = wire;
174        over.resize(MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2 + 1, b' ');
175        let e = decode_v2_checkpoint_acknowledgement(&over).expect_err("limit+1");
176        assert_eq!(e.class, V2ErrorClass::Malformed);
177        assert!(
178            e.message
179                .contains("MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2"),
180            "{}",
181            e.message
182        );
183    }
184}