ic_memory/ledger/
payload.rs

1const LEDGER_PAYLOAD_MAGIC: &[u8; 8] = b"ICMEMLED";
2const LEDGER_PAYLOAD_FORMAT_MARKER: &[u8; 4] = b"ICMF";
3/// Current durable ledger payload format version.
4pub const LEDGER_PAYLOAD_FORMAT_VERSION: u32 = 1;
5use crate::constants::LEDGER_PAYLOAD_HEADER_LEN;
6
7///
8/// LedgerPayloadEnvelope
9///
10/// Logical ledger payload envelope embedded inside one physically committed
11/// generation. This layer is decoded after physical dual-slot recovery selects
12/// a committed generation and before any allocation-ledger DTO is decoded.
13///
14/// This is an advanced protocol byte wrapper, not an authority token. Decoding
15/// an envelope only classifies the logical payload; authority is established
16/// later when [`crate::LedgerCommitStore`] routes the payload, checks
17/// the current ledger format, validates committed ledger integrity, and returns
18/// [`crate::RecoveredLedger`].
19#[derive(Clone, Debug, Eq, PartialEq)]
20pub struct LedgerPayloadEnvelope {
21    payload: Vec<u8>,
22}
23
24impl LedgerPayloadEnvelope {
25    /// Wrap a current logical ledger payload.
26    #[must_use]
27    pub const fn current(payload: Vec<u8>) -> Self {
28        Self { payload }
29    }
30
31    /// Manually encode the logical payload envelope.
32    ///
33    /// # Panics
34    ///
35    /// Panics if the payload exceeds the current ledger byte ceiling. Use
36    /// `try_encode` for typed errors.
37    #[must_use]
38    pub fn encode(&self) -> Vec<u8> {
39        self.try_encode()
40            .expect("payload exceeds the ledger byte ceiling")
41    }
42
43    /// Try to encode the logical payload envelope.
44    pub fn try_encode(&self) -> Result<Vec<u8>, LedgerPayloadEnvelopeError> {
45        if self.payload.len() > crate::constants::MAX_LEDGER_BYTES {
46            return Err(LedgerPayloadEnvelopeError::PayloadTooLarge {
47                len: self.payload.len() as u64,
48            });
49        }
50        // The byte ceiling bounds both the total usize length and the u64 header.
51        let total_len = LEDGER_PAYLOAD_HEADER_LEN + self.payload.len();
52        let payload_len = self.payload.len() as u64;
53
54        let mut bytes = Vec::with_capacity(total_len);
55        bytes.extend_from_slice(LEDGER_PAYLOAD_MAGIC);
56        bytes.extend_from_slice(LEDGER_PAYLOAD_FORMAT_MARKER);
57        bytes.extend_from_slice(&LEDGER_PAYLOAD_FORMAT_VERSION.to_le_bytes());
58        bytes.extend_from_slice(&payload_len.to_le_bytes());
59        bytes.extend_from_slice(&self.payload);
60        Ok(bytes)
61    }
62
63    /// Manually decode the logical payload envelope.
64    pub fn decode(bytes: &[u8]) -> Result<Self, LedgerPayloadEnvelopeError> {
65        Ok(Self {
66            payload: Self::decode_payload(bytes)?.to_vec(),
67        })
68    }
69
70    // Recovery already owns the committed bytes. Validate the same envelope
71    // without copying its bounded payload before logical ledger decoding.
72    pub(super) fn decode_payload(bytes: &[u8]) -> Result<&[u8], LedgerPayloadEnvelopeError> {
73        let Some(magic) = bytes.get(0..8).and_then(|bytes| bytes.try_into().ok()) else {
74            return Err(LedgerPayloadEnvelopeError::Truncated {
75                actual: bytes.len(),
76                minimum: LEDGER_PAYLOAD_HEADER_LEN,
77            });
78        };
79        if &magic != LEDGER_PAYLOAD_MAGIC {
80            return Err(LedgerPayloadEnvelopeError::BadMagic { found: magic });
81        }
82
83        let Some(format_marker) = bytes.get(8..12).and_then(|bytes| bytes.try_into().ok()) else {
84            return Err(LedgerPayloadEnvelopeError::Truncated {
85                actual: bytes.len(),
86                minimum: LEDGER_PAYLOAD_HEADER_LEN,
87            });
88        };
89        if &format_marker != LEDGER_PAYLOAD_FORMAT_MARKER {
90            return Err(LedgerPayloadEnvelopeError::UnsupportedFormat {
91                marker: format_marker,
92                version: None,
93            });
94        }
95
96        let Some(format_version) = bytes.get(12..16).and_then(|bytes| bytes.try_into().ok()) else {
97            return Err(LedgerPayloadEnvelopeError::Truncated {
98                actual: bytes.len(),
99                minimum: LEDGER_PAYLOAD_HEADER_LEN,
100            });
101        };
102        let format_version = u32::from_le_bytes(format_version);
103        if format_version != LEDGER_PAYLOAD_FORMAT_VERSION {
104            return Err(LedgerPayloadEnvelopeError::UnsupportedFormat {
105                marker: format_marker,
106                version: Some(format_version),
107            });
108        }
109
110        let Some(payload_len) = bytes.get(16..24).and_then(|bytes| bytes.try_into().ok()) else {
111            return Err(LedgerPayloadEnvelopeError::Truncated {
112                actual: bytes.len(),
113                minimum: LEDGER_PAYLOAD_HEADER_LEN,
114            });
115        };
116        let payload_len = u64::from_le_bytes(payload_len);
117        let payload_len = usize::try_from(payload_len)
118            .map_err(|_| LedgerPayloadEnvelopeError::PayloadTooLarge { len: payload_len })?;
119        if payload_len > crate::constants::MAX_LEDGER_BYTES {
120            return Err(LedgerPayloadEnvelopeError::PayloadTooLarge {
121                len: payload_len as u64,
122            });
123        }
124        let expected_len = LEDGER_PAYLOAD_HEADER_LEN + payload_len;
125        if bytes.len() != expected_len {
126            return Err(LedgerPayloadEnvelopeError::LengthMismatch {
127                declared: payload_len,
128                actual: bytes.len().saturating_sub(LEDGER_PAYLOAD_HEADER_LEN),
129            });
130        }
131
132        Ok(&bytes[LEDGER_PAYLOAD_HEADER_LEN..])
133    }
134
135    /// Borrow the logical ledger payload bytes.
136    #[must_use]
137    pub fn payload(&self) -> &[u8] {
138        &self.payload
139    }
140}
141
142///
143/// LedgerPayloadEnvelopeError
144///
145/// Logical payload envelope could not be classified before ledger decode.
146///
147
148#[non_exhaustive]
149#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
150pub enum LedgerPayloadEnvelopeError {
151    /// Not enough bytes for an envelope header.
152    #[error("ledger payload envelope is truncated: {actual} bytes, need at least {minimum}")]
153    Truncated {
154        /// Bytes present.
155        actual: usize,
156        /// Minimum bytes required.
157        minimum: usize,
158    },
159    /// Magic bytes do not identify an `ic-memory` ledger payload.
160    #[error("ledger payload envelope has bad magic {found:?}")]
161    BadMagic {
162        /// Magic bytes found.
163        found: [u8; 8],
164    },
165    /// The payload belongs to the `ic-memory` ledger family but does not carry
166    /// the current format discriminator.
167    #[error("unsupported ic-memory ledger payload format (marker={marker:?}, version={version:?})")]
168    UnsupportedFormat {
169        /// Format marker found after the ledger-family magic.
170        marker: [u8; 4],
171        /// Format version when the current marker was present.
172        version: Option<u32>,
173    },
174    /// Payload length exceeds the ledger byte ceiling or cannot fit in this
175    /// platform's address space.
176    #[error("ledger payload envelope length {len} is too large")]
177    PayloadTooLarge {
178        /// Declared payload length.
179        len: u64,
180    },
181    /// Declared payload length does not match the bytes present.
182    #[error("ledger payload envelope declared {declared} payload bytes but contained {actual}")]
183    LengthMismatch {
184        /// Declared payload length.
185        declared: usize,
186        /// Actual payload length.
187        actual: usize,
188    },
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194
195    #[test]
196    fn oversized_payload_is_rejected_before_encoding() {
197        let len = crate::constants::MAX_LEDGER_BYTES + 1;
198        assert_eq!(
199            LedgerPayloadEnvelope::current(vec![0; len]).try_encode(),
200            Err(LedgerPayloadEnvelopeError::PayloadTooLarge { len: len as u64 })
201        );
202    }
203
204    #[test]
205    fn malformed_lengths_are_classified_before_payload_copy() {
206        let mut bytes = LedgerPayloadEnvelope::current(Vec::new()).encode();
207        for len in 0..LEDGER_PAYLOAD_HEADER_LEN {
208            assert_eq!(
209                LedgerPayloadEnvelope::decode(&bytes[..len]),
210                Err(LedgerPayloadEnvelopeError::Truncated {
211                    actual: len,
212                    minimum: LEDGER_PAYLOAD_HEADER_LEN,
213                })
214            );
215        }
216        for len in [crate::constants::MAX_LEDGER_BYTES as u64 + 1, u64::MAX] {
217            bytes[16..24].copy_from_slice(&len.to_le_bytes());
218            assert_eq!(
219                LedgerPayloadEnvelope::decode(&bytes),
220                Err(LedgerPayloadEnvelopeError::PayloadTooLarge { len })
221            );
222        }
223        bytes[16..24].copy_from_slice(&1_u64.to_le_bytes());
224        assert_eq!(
225            LedgerPayloadEnvelope::decode(&bytes),
226            Err(LedgerPayloadEnvelopeError::LengthMismatch {
227                declared: 1,
228                actual: 0,
229            })
230        );
231        bytes[16..24].copy_from_slice(&0_u64.to_le_bytes());
232        bytes.push(42);
233        assert_eq!(
234            LedgerPayloadEnvelope::decode(&bytes),
235            Err(LedgerPayloadEnvelopeError::LengthMismatch {
236                declared: 0,
237                actual: 1,
238            })
239        );
240    }
241
242    #[test]
243    fn borrowed_payload_decode_shares_storage_through_the_byte_ceiling() {
244        for len in [0, 3, crate::constants::MAX_LEDGER_BYTES] {
245            let bytes = LedgerPayloadEnvelope::current(vec![42; len])
246                .try_encode()
247                .expect("bounded envelope");
248            let payload = LedgerPayloadEnvelope::decode_payload(&bytes).expect("valid envelope");
249
250            assert_eq!(payload.len(), len);
251            assert_eq!(
252                payload.as_ptr(),
253                bytes[LEDGER_PAYLOAD_HEADER_LEN..].as_ptr()
254            );
255            assert!(payload.iter().all(|byte| *byte == 42));
256        }
257    }
258}
ic_memory/ledger/payload.rs

ic_memory/ledger/
payload.rs
