ic_memory/
stable_cell.rs

1use crate::LedgerCommitStore;
2use ic_stable_structures::{Memory, Storable, storable::Bound};
3use serde::{Deserialize, Serialize};
4use std::borrow::Cow;
5use thiserror::Error;
6
7/// Stable-cell magic prefix written by `ic-stable-structures::Cell`.
8pub const STABLE_CELL_MAGIC: &[u8; 3] = b"SCL";
9/// Stable-cell layout version supported by this adapter.
10pub const STABLE_CELL_LAYOUT_VERSION: u8 = 1;
11/// Stable-cell header byte length.
12pub const STABLE_CELL_HEADER_SIZE: usize = 8;
13/// Byte offset where the stable-cell value payload starts.
14pub const STABLE_CELL_VALUE_OFFSET: u64 = 8;
15const WASM_PAGE_SIZE: u64 = 65_536;
16
17///
18/// StableCellLedgerRecord
19///
20/// `ic-stable-structures::Cell` record containing an `ic-memory` allocation
21/// ledger commit store.
22///
23/// This is a substrate adapter DTO. It owns no framework policy and does not
24/// open application allocations.
25///
26
27#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
28pub struct StableCellLedgerRecord {
29    store: LedgerCommitStore,
30}
31
32impl StableCellLedgerRecord {
33    /// Construct a record from a commit store.
34    #[must_use]
35    pub const fn new(store: LedgerCommitStore) -> Self {
36        Self { store }
37    }
38
39    /// Borrow the embedded commit store.
40    #[must_use]
41    pub const fn store(&self) -> &LedgerCommitStore {
42        &self.store
43    }
44
45    /// Mutably borrow the embedded commit store.
46    pub const fn store_mut(&mut self) -> &mut LedgerCommitStore {
47        &mut self.store
48    }
49
50    /// Consume this record and return the embedded commit store.
51    #[must_use]
52    pub fn into_store(self) -> LedgerCommitStore {
53        self.store
54    }
55}
56
57impl Storable for StableCellLedgerRecord {
58    const BOUND: Bound = Bound::Unbounded;
59
60    fn to_bytes(&self) -> Cow<'_, [u8]> {
61        Cow::Owned(serialize_record(self))
62    }
63
64    fn into_bytes(self) -> Vec<u8> {
65        serialize_record(&self)
66    }
67
68    fn from_bytes(bytes: Cow<'_, [u8]>) -> Self {
69        decode_stable_cell_ledger_record(&bytes).unwrap_or_else(|err| {
70            panic!("StableCellLedgerRecord deserialize failed: {err}");
71        })
72    }
73}
74
75///
76/// StableCellPayloadError
77///
78/// Stable-cell payload decode failure.
79#[derive(Clone, Debug, Eq, Error, PartialEq)]
80pub enum StableCellPayloadError {
81    /// Memory contents do not start with the stable-cell marker.
82    #[error("memory is not an ic-stable-structures Cell")]
83    NotStableCell,
84    /// Stable-cell format version is not supported.
85    #[error("unsupported stable-cell layout version {version}")]
86    UnsupportedVersion {
87        /// Observed stable-cell version.
88        version: u8,
89    },
90    /// Stable-cell header length does not fit inside the memory.
91    #[error("stable-cell payload length {value_len} exceeds available bytes {available_bytes}")]
92    InvalidLength {
93        /// Encoded value length.
94        value_len: u64,
95        /// Available payload bytes in memory.
96        available_bytes: u64,
97    },
98    /// Stable-cell length cannot be represented on the current host.
99    #[error("stable-cell payload length {value_len} cannot fit in usize")]
100    LengthOverflow {
101        /// Encoded value length.
102        value_len: u64,
103    },
104}
105
106///
107/// StableCellLedgerError
108///
109/// Stable-cell ledger record validation failure.
110#[derive(Debug, Error)]
111pub enum StableCellLedgerError {
112    /// Stable-cell envelope is corrupt or unsupported.
113    #[error(transparent)]
114    Payload(#[from] StableCellPayloadError),
115    /// Stable-cell value bytes are not a valid ledger record.
116    #[error("stable-cell ledger record decode failed")]
117    Record(#[source] serde_cbor::Error),
118}
119
120/// Decode the raw value payload from an `ic-stable-structures::Cell` memory.
121///
122/// This helper is intentionally narrow: it recognizes the physical stable-cell
123/// envelope and returns the value bytes. It does not deserialize those bytes or
124/// decide whether they represent a valid allocation ledger.
125pub fn decode_stable_cell_payload<M: Memory>(
126    memory: &M,
127) -> Result<Vec<u8>, StableCellPayloadError> {
128    let mut header = [0; STABLE_CELL_HEADER_SIZE];
129    memory.read(0, &mut header);
130    if &header[0..3] != STABLE_CELL_MAGIC {
131        return Err(StableCellPayloadError::NotStableCell);
132    }
133    if header[3] != STABLE_CELL_LAYOUT_VERSION {
134        return Err(StableCellPayloadError::UnsupportedVersion { version: header[3] });
135    }
136
137    let value_len = u64::from(u32::from_le_bytes([
138        header[4], header[5], header[6], header[7],
139    ]));
140    let available_bytes = memory.size().saturating_mul(WASM_PAGE_SIZE);
141    let payload_capacity = available_bytes.saturating_sub(STABLE_CELL_VALUE_OFFSET);
142    if value_len > payload_capacity {
143        return Err(StableCellPayloadError::InvalidLength {
144            value_len,
145            available_bytes: payload_capacity,
146        });
147    }
148    let value_len = usize::try_from(value_len)
149        .map_err(|_| StableCellPayloadError::LengthOverflow { value_len })?;
150
151    let mut bytes = vec![0; value_len];
152    memory.read(STABLE_CELL_VALUE_OFFSET, &mut bytes);
153    Ok(bytes)
154}
155
156/// Decode a `StableCellLedgerRecord` from stable-cell value bytes.
157///
158/// This decodes only the cell value payload, not the enclosing stable-cell
159/// header. Use [`decode_stable_cell_payload`] first when inspecting raw stable
160/// memory.
161pub fn decode_stable_cell_ledger_record(
162    bytes: &[u8],
163) -> Result<StableCellLedgerRecord, serde_cbor::Error> {
164    serde_cbor::from_slice(bytes)
165}
166
167/// Validate an existing stable-cell ledger record before opening it with
168/// `ic-stable-structures::Cell`.
169///
170/// `Cell::init` decodes the existing value through [`Storable::from_bytes`].
171/// That trait is panic-based, so the runtime preflights the raw memory with
172/// this fallible helper first. Empty memory is treated as uninitialized and is
173/// safe for `Cell::init` to create.
174pub fn validate_stable_cell_ledger_memory<M: Memory>(
175    memory: &M,
176) -> Result<(), StableCellLedgerError> {
177    if memory.size() == 0 {
178        return Ok(());
179    }
180
181    let payload = decode_stable_cell_payload(memory)?;
182    decode_stable_cell_ledger_record(&payload).map_err(StableCellLedgerError::Record)?;
183    Ok(())
184}
185
186fn serialize_record(record: &StableCellLedgerRecord) -> Vec<u8> {
187    serde_cbor::to_vec(record).unwrap_or_else(|err| {
188        panic!("StableCellLedgerRecord serialize failed: {err}");
189    })
190}
191
192#[cfg(test)]
193mod tests {
194    use super::*;
195    use ic_stable_structures::{Cell, VectorMemory};
196
197    #[test]
198    fn stable_cell_ledger_record_round_trips_through_cell() {
199        let memory = VectorMemory::default();
200        let record = StableCellLedgerRecord::default();
201        let cell = Cell::init(memory.clone(), record.clone());
202
203        assert_eq!(cell.get(), &record);
204        let payload = decode_stable_cell_payload(&memory).expect("decode stable cell payload");
205        let decoded = StableCellLedgerRecord::from_bytes(Cow::Owned(payload));
206        assert_eq!(decoded, record);
207    }
208
209    #[test]
210    fn stable_cell_payload_rejects_non_cell_memory() {
211        let memory = VectorMemory::default();
212        memory.grow(1);
213        memory.write(0, b"BAD");
214
215        assert_eq!(
216            decode_stable_cell_payload(&memory),
217            Err(StableCellPayloadError::NotStableCell)
218        );
219    }
220
221    #[test]
222    fn stable_cell_ledger_preflight_classifies_bad_record_without_panic() {
223        let memory = VectorMemory::default();
224        memory.grow(1);
225        memory.write(0, STABLE_CELL_MAGIC);
226        memory.write(3, &[STABLE_CELL_LAYOUT_VERSION]);
227        memory.write(4, &1_u32.to_le_bytes());
228        memory.write(STABLE_CELL_VALUE_OFFSET, &[0xff]);
229
230        let err =
231            validate_stable_cell_ledger_memory(&memory).expect_err("bad record must be classified");
232
233        assert!(matches!(err, StableCellLedgerError::Record(_)));
234    }
235}
ic_memory/stable_cell.rs

ic_memory/
stable_cell.rs
