miden_protocol/account/component/storage/toml/
mod.rs

1use alloc::collections::BTreeMap;
2use alloc::string::{String, ToString};
3use alloc::vec::Vec;
4
5use miden_core::{Felt, Word};
6use semver::Version;
7use serde::de::Error as _;
8use serde::{Deserialize, Deserializer, Serialize, Serializer};
9
10use super::super::{
11    FeltSchema,
12    MapSlotSchema,
13    StorageSchema,
14    StorageSlotSchema,
15    StorageValueName,
16    ValueSlotSchema,
17    WordSchema,
18    WordValue,
19};
20use crate::account::StorageSlotName;
21use crate::account::component::storage::type_registry::SCHEMA_TYPE_REGISTRY;
22use crate::account::component::{AccountComponentMetadata, SchemaType};
23use crate::errors::ComponentMetadataError;
24
25mod init_storage_data;
26mod serde_impls;
27
28#[cfg(test)]
29mod tests;
30
31// ACCOUNT COMPONENT METADATA TOML FROM/TO
32// ================================================================================================
33
34#[derive(Debug, Deserialize)]
35#[serde(rename_all = "kebab-case", deny_unknown_fields)]
36struct RawAccountComponentMetadata {
37    name: String,
38    description: String,
39    version: Version,
40    #[serde(rename = "storage")]
41    #[serde(default)]
42    storage: RawStorageSchema,
43}
44
45impl AccountComponentMetadata {
46    /// Deserializes `toml_string` and validates the resulting [AccountComponentMetadata]
47    ///
48    /// # Errors
49    ///
50    /// - If deserialization fails
51    /// - If the schema specifies storage slots with duplicates.
52    /// - If the schema contains invalid slot definitions.
53    pub fn from_toml(toml_string: &str) -> Result<Self, ComponentMetadataError> {
54        let raw: RawAccountComponentMetadata = toml::from_str(toml_string)
55            .map_err(ComponentMetadataError::TomlDeserializationError)?;
56
57        if !raw.description.is_ascii() {
58            return Err(ComponentMetadataError::InvalidSchema(
59                "description must contain only ASCII characters".to_string(),
60            ));
61        }
62
63        let RawStorageSchema { slots } = raw.storage;
64        let mut fields = Vec::with_capacity(slots.len());
65
66        for slot in slots {
67            fields.push(slot.try_into_slot_schema()?);
68        }
69
70        let storage_schema = StorageSchema::new(fields)?;
71        Ok(Self::new(raw.name)
72            .with_description(raw.description)
73            .with_version(raw.version)
74            .with_storage_schema(storage_schema))
75    }
76
77    /// Serializes the account component metadata into a TOML string.
78    pub fn to_toml(&self) -> Result<String, ComponentMetadataError> {
79        let toml = toml::to_string(self).map_err(ComponentMetadataError::TomlSerializationError)?;
80        Ok(toml)
81    }
82}
83
84// ACCOUNT STORAGE SCHEMA SERIALIZATION
85// ================================================================================================
86
87/// Raw TOML storage schema:
88///
89/// - `[[storage.slots]]` for both value and map slots.
90///
91/// Slot kind is inferred by the shape of the `type` field:
92/// - `type = "..."` or `type = [ ... ]` => value slot
93/// - `type = { ... }` => map slot
94#[derive(Debug, Default, Deserialize, Serialize)]
95#[serde(rename_all = "kebab-case", deny_unknown_fields)]
96struct RawStorageSchema {
97    #[serde(default)]
98    slots: Vec<RawStorageSlotSchema>,
99}
100
101/// Storage slot type descriptor.
102///
103/// This field accepts either:
104/// - a type identifier (e.g. `"word"`, `"u16"`, `"miden::standards::auth::pub_key"`) for simple
105///   word slots,
106/// - an array of 4 [`FeltSchema`] descriptors for composite word slots, or
107/// - a table `{ key = ..., value = ... }` for map slots.
108#[derive(Debug, Clone, Deserialize, Serialize)]
109#[serde(untagged)]
110enum RawSlotType {
111    Word(RawWordType),
112    Map(RawMapType),
113}
114
115/// A word type descriptor.
116#[derive(Debug, Clone, Deserialize, Serialize)]
117#[serde(untagged)]
118enum RawWordType {
119    TypeIdentifier(SchemaType),
120    FeltSchemaArray(Vec<FeltSchema>),
121}
122
123/// A map type descriptor.
124#[derive(Debug, Clone, Deserialize, Serialize)]
125#[serde(rename_all = "kebab-case", deny_unknown_fields)]
126struct RawMapType {
127    key: RawWordType,
128    value: RawWordType,
129}
130
131// ACCOUNT STORAGE SCHEMA SERDE
132// ================================================================================================
133
134impl Serialize for StorageSchema {
135    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
136    where
137        S: Serializer,
138    {
139        let slots = self
140            .slots()
141            .iter()
142            .map(|(slot_name, schema)| RawStorageSlotSchema::from_slot(slot_name, schema))
143            .collect();
144
145        RawStorageSchema { slots }.serialize(serializer)
146    }
147}
148
149impl<'de> Deserialize<'de> for StorageSchema {
150    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
151    where
152        D: Deserializer<'de>,
153    {
154        // First, look at the raw representation
155        let raw = RawStorageSchema::deserialize(deserializer)?;
156        let mut fields = Vec::with_capacity(raw.slots.len());
157
158        for slot in raw.slots {
159            let (slot_name, schema) = slot.try_into_slot_schema().map_err(D::Error::custom)?;
160            fields.push((slot_name, schema));
161        }
162
163        StorageSchema::new(fields).map_err(D::Error::custom)
164    }
165}
166
167// ACCOUNT STORAGE SCHEMA SERDE HELPERS
168// ================================================================================================
169
170/// Raw storage slot schemas contain the raw representation that can get deserialized from TOML.
171/// Specifically, it expresses the different combination of fields that expose the different types
172/// of slots.
173#[derive(Debug, Deserialize, Serialize)]
174#[serde(rename_all = "kebab-case", deny_unknown_fields)]
175struct RawStorageSlotSchema {
176    /// The name of the storage slot, in `StorageSlotName` format (e.g.
177    /// `my_project::module::slot`).
178    name: String,
179    #[serde(default)]
180    description: Option<String>,
181    /// Slot type descriptor.
182    ///
183    /// - If `type = { ... }`, this is a map slot.
184    /// - If `type = [ ... ]`, this is a composite word slot whose schema is described by 4
185    ///   [`FeltSchema`] descriptors.
186    /// - Otherwise, if `type = "..."`, this is a simple word slot whose value is supplied at
187    ///   instantiation time unless `default-value` is set (or the type is `void`).
188    #[serde(rename = "type")]
189    r#type: RawSlotType,
190    /// The (overridable) default value for a simple word slot.
191    #[serde(default)]
192    default_value: Option<WordValue>,
193    /// Default map entries.
194    ///
195    /// These entries must be fully-specified values. If the map should be populated at
196    /// instantiation time, omit `default-values` and provide entries via init storage data.
197    #[serde(default)]
198    default_values: Option<Vec<RawMapEntrySchema>>,
199}
200
201#[derive(Debug, Deserialize, Serialize)]
202#[serde(deny_unknown_fields)]
203struct RawMapEntrySchema {
204    key: WordValue,
205    value: WordValue,
206}
207
208impl RawStorageSlotSchema {
209    // SERIALIZATION
210    // --------------------------------------------------------------------------------------------
211
212    fn from_slot(slot_name: &StorageSlotName, schema: &StorageSlotSchema) -> Self {
213        match schema {
214            StorageSlotSchema::Value(schema) => Self::from_value_slot(slot_name, schema),
215            StorageSlotSchema::Map(schema) => Self::from_map_slot(slot_name, schema),
216        }
217    }
218
219    fn from_value_slot(slot_name: &StorageSlotName, schema: &ValueSlotSchema) -> Self {
220        let word = schema.word();
221        let (r#type, default_value) = match word {
222            WordSchema::Simple { r#type, default_value } => (
223                RawSlotType::Word(RawWordType::TypeIdentifier(r#type.clone())),
224                default_value.map(|word| WordValue::from_word(r#type, word)),
225            ),
226            WordSchema::Composite { value } => {
227                (RawSlotType::Word(RawWordType::FeltSchemaArray(value.to_vec())), None)
228            },
229        };
230
231        Self {
232            name: slot_name.as_str().to_string(),
233            description: schema.description().cloned(),
234            r#type,
235            default_value,
236            default_values: None,
237        }
238    }
239
240    fn from_map_slot(slot_name: &StorageSlotName, schema: &MapSlotSchema) -> Self {
241        let default_values = schema.default_values().map(|default_values| {
242            default_values
243                .into_iter()
244                .map(|(key, value)| RawMapEntrySchema {
245                    key: WordValue::from_word(&schema.key_schema().word_type(), key),
246                    value: WordValue::from_word(&schema.value_schema().word_type(), value),
247                })
248                .collect()
249        });
250
251        let key_type = match schema.key_schema() {
252            WordSchema::Simple { r#type, .. } => RawWordType::TypeIdentifier(r#type.clone()),
253            WordSchema::Composite { value } => RawWordType::FeltSchemaArray(value.to_vec()),
254        };
255
256        let value_type = match schema.value_schema() {
257            WordSchema::Simple { r#type, .. } => RawWordType::TypeIdentifier(r#type.clone()),
258            WordSchema::Composite { value } => RawWordType::FeltSchemaArray(value.to_vec()),
259        };
260
261        Self {
262            name: slot_name.as_str().to_string(),
263            description: schema.description().cloned(),
264            r#type: RawSlotType::Map(RawMapType { key: key_type, value: value_type }),
265            default_value: None,
266            default_values,
267        }
268    }
269
270    // DESERIALIZATION
271    // --------------------------------------------------------------------------------------------
272
273    /// Converts the raw representation into a tuple of the storage slot name and its schema.
274    fn try_into_slot_schema(
275        self,
276    ) -> Result<(StorageSlotName, StorageSlotSchema), ComponentMetadataError> {
277        let RawStorageSlotSchema {
278            name,
279            description,
280            r#type,
281            default_value,
282            default_values,
283        } = self;
284
285        let slot_name_raw = name;
286        let slot_name = StorageSlotName::new(slot_name_raw.clone()).map_err(|err| {
287            ComponentMetadataError::InvalidSchema(format!(
288                "invalid storage slot name `{slot_name_raw}`: {err}"
289            ))
290        })?;
291
292        let description = description.filter(|d| !d.trim().is_empty());
293
294        let slot_prefix = StorageValueName::from_slot_name(&slot_name);
295
296        if default_value.is_some() && default_values.is_some() {
297            return Err(ComponentMetadataError::InvalidSchema(
298                "storage slot schema cannot define both `default-value` and `default-values`"
299                    .into(),
300            ));
301        }
302
303        match r#type {
304            RawSlotType::Map(map_type) => {
305                if default_value.is_some() {
306                    return Err(ComponentMetadataError::InvalidSchema(
307                        "map slots cannot define `default-value`".into(),
308                    ));
309                }
310
311                let RawMapType { key: key_type, value: value_type } = map_type;
312                let key_schema = Self::parse_word_schema(key_type, "`type.key`")?;
313                let value_schema = Self::parse_word_schema(value_type, "`type.value`")?;
314
315                let default_values = default_values
316                    .map(|entries| {
317                        Self::parse_default_map_entries(
318                            entries,
319                            &key_schema,
320                            &value_schema,
321                            &slot_prefix,
322                        )
323                    })
324                    .transpose()?;
325
326                Ok((
327                    slot_name,
328                    StorageSlotSchema::Map(MapSlotSchema::new(
329                        description,
330                        default_values,
331                        key_schema,
332                        value_schema,
333                    )),
334                ))
335            },
336
337            RawSlotType::Word(word_type) => {
338                if default_values.is_some() {
339                    return Err(ComponentMetadataError::InvalidSchema(
340                        "`default-values` can be specified only for map slots (use `type = { ... }`)"
341                            .into(),
342                    ));
343                }
344
345                match word_type {
346                    RawWordType::TypeIdentifier(r#type) => {
347                        if r#type.as_str() == "map" {
348                            return Err(ComponentMetadataError::InvalidSchema(
349                                "value slots cannot use `type = \"map\"`; use `type = { key = <key-type>, value = <value-type>}` instead"
350                                    .into(),
351                            ));
352                        }
353
354                        let word = default_value
355                            .as_ref()
356                            .map(|default_value| {
357                                default_value.try_parse_as_typed_word(
358                                    &r#type,
359                                    &slot_prefix,
360                                    "default value",
361                                )
362                            })
363                            .transpose()?;
364
365                        let word_schema = match word {
366                            Some(word) => WordSchema::new_simple_with_default(r#type, word),
367                            None => WordSchema::new_simple(r#type),
368                        };
369
370                        Ok((
371                            slot_name,
372                            StorageSlotSchema::Value(ValueSlotSchema::new(
373                                description,
374                                word_schema,
375                            )),
376                        ))
377                    },
378
379                    RawWordType::FeltSchemaArray(elements) => {
380                        if default_value.is_some() {
381                            return Err(ComponentMetadataError::InvalidSchema(
382                                "composite word slots cannot define `default-value`".into(),
383                            ));
384                        }
385
386                        let elements = Self::parse_felt_schema_array(elements, "word slot `type`")?;
387                        Ok((
388                            slot_name,
389                            StorageSlotSchema::Value(ValueSlotSchema::new(
390                                description,
391                                WordSchema::new_value(elements),
392                            )),
393                        ))
394                    },
395                }
396            },
397        }
398    }
399
400    fn parse_word_schema(
401        raw: RawWordType,
402        label: &str,
403    ) -> Result<WordSchema, ComponentMetadataError> {
404        match raw {
405            RawWordType::TypeIdentifier(r#type) => Ok(WordSchema::new_simple(r#type)),
406            RawWordType::FeltSchemaArray(elements) => {
407                let elements = Self::parse_felt_schema_array(elements, label)?;
408                Ok(WordSchema::new_value(elements))
409            },
410        }
411    }
412
413    fn parse_felt_schema_array(
414        elements: Vec<FeltSchema>,
415        label: &str,
416    ) -> Result<[FeltSchema; 4], ComponentMetadataError> {
417        if elements.len() != 4 {
418            return Err(ComponentMetadataError::InvalidSchema(format!(
419                "{label} must be an array of 4 elements, got {}",
420                elements.len()
421            )));
422        }
423        Ok(elements.try_into().expect("length is 4"))
424    }
425
426    fn parse_default_map_entries(
427        entries: Vec<RawMapEntrySchema>,
428        key_schema: &WordSchema,
429        value_schema: &WordSchema,
430        slot_prefix: &StorageValueName,
431    ) -> Result<BTreeMap<Word, Word>, ComponentMetadataError> {
432        let mut map = BTreeMap::new();
433
434        let parse = |schema: &WordSchema, raw: &WordValue, label: &str| {
435            super::schema::parse_storage_value_with_schema(schema, raw, slot_prefix).map_err(
436                |err| {
437                    ComponentMetadataError::InvalidSchema(format!("invalid map `{label}`: {err}"))
438                },
439            )
440        };
441
442        for (index, entry) in entries.into_iter().enumerate() {
443            let key_label = format!("default-values[{index}].key");
444            let value_label = format!("default-values[{index}].value");
445
446            let key = parse(key_schema, &entry.key, &key_label)?;
447            let value = parse(value_schema, &entry.value, &value_label)?;
448
449            if map.insert(key, value).is_some() {
450                return Err(ComponentMetadataError::InvalidSchema(format!(
451                    "map storage slot `default-values[{index}]` contains a duplicate key"
452                )));
453            }
454        }
455
456        Ok(map)
457    }
458}
459
460impl WordValue {
461    pub(super) fn try_parse_as_typed_word(
462        &self,
463        schema_type: &SchemaType,
464        slot_prefix: &StorageValueName,
465        label: &str,
466    ) -> Result<Word, ComponentMetadataError> {
467        let word = match self {
468            WordValue::FullyTyped(word) => *word,
469            WordValue::Atomic(value) => SCHEMA_TYPE_REGISTRY
470                .try_parse_word(schema_type, value)
471                .map_err(ComponentMetadataError::StorageValueParsingError)?,
472            WordValue::Elements(elements) => {
473                let felts = elements
474                    .iter()
475                    .map(|element| {
476                        SCHEMA_TYPE_REGISTRY.try_parse_felt(&SchemaType::native_felt(), element)
477                    })
478                    .collect::<Result<Vec<Felt>, _>>()
479                    .map_err(ComponentMetadataError::StorageValueParsingError)?;
480                let felts: [Felt; 4] = felts.try_into().expect("length is 4");
481                Word::from(felts)
482            },
483        };
484
485        WordSchema::new_simple(schema_type.clone()).validate_word_value(
486            slot_prefix,
487            label,
488            word,
489        )?;
490        Ok(word)
491    }
492
493    pub(super) fn from_word(schema_type: &SchemaType, word: Word) -> Self {
494        WordValue::Atomic(SCHEMA_TYPE_REGISTRY.display_word(schema_type, word).value().to_string())
495    }
496}
miden_protocol/account/component/storage/toml/mod.rs

miden_protocol/account/component/storage/toml/
mod.rs
