refactor: Implement component schemas

CHANGELOG.md

@@ -27,6 +27,7 @@
 - [BREAKING] Made `AccountProcedureIndexMap` construction infallible ([#2163](https://github.com/0xMiden/miden-base/pull/2163)).
 - [BREAKING] Renamed `tracked_procedure_roots_slot` to `trigger_procedure_roots_slot` in ACL auth components for naming consistency ([#2166](https://github.com/0xMiden/miden-base/pull/2166)).
 - [BREAKING] Refactored `AccountStorageDelta` to use a new `StorageSlotDelta` type ([#2182](https://github.com/0xMiden/miden-base/pull/2182)).
+- [BREAKING] Refactored account component templates into `AccountStorageSchema` ([#2193](https://github.com/0xMiden/miden-base/pull/2193)).
 
 ## 0.12.4 (2025-11-26)
 

crates/miden-lib/src/account/faucets/network_fungible.rs

@@ -214,7 +214,7 @@ impl From<NetworkFungibleFaucet> for AccountComponent {
             Felt::ZERO,
         ]);
 
-        // Convert AccountId to Word representation for storage
+        // Convert AccountId into its Word encoding for storage.
         let owner_account_id_word: Word = [
             Felt::new(0),
             Felt::new(0),

crates/miden-objects/src/account/component/metadata/mod.rs

@@ -0,0 +1,213 @@
+use alloc::collections::{BTreeMap, BTreeSet};
+use alloc::string::{String, ToString};
+use core::str::FromStr;
+
+use miden_core::utils::{ByteReader, ByteWriter, Deserializable, Serializable};
+use miden_mast_package::{Package, SectionId};
+use miden_processor::DeserializationError;
+use semver::Version;
+
+use super::{AccountStorageSchema, AccountType, SchemaRequirement, StorageValueName};
+use crate::AccountError;
+
+// ACCOUNT COMPONENT METADATA
+// ================================================================================================
+
+/// Represents the full component metadata configuration.
+///
+/// An account component metadata describes the component alongside its storage layout.
+/// The storage layout can declare typed values which must be provided at instantiation time via
+/// [InitStorageData](`super::storage::InitStorageData`). These can appear either at the slot level
+/// (a singular word slot) or inside composed words as typed fields.
+///
+/// When the `std` feature is enabled, this struct allows for serialization and deserialization to
+/// and from a TOML file.
+///
+/// # Guarantees
+///
+/// - The metadata's storage schema does not contain duplicate slot names.
+/// - The schema cannot contain protocol-reserved slot names.
+/// - Each init-time value name uniquely identifies a single value. The expected init-time metadata
+///   can be retrieved with [AccountComponentMetadata::schema_requirements()], which returns a map
+///   from keys to [SchemaRequirement] (which indicates the expected value type and optional
+///   defaults).
+///
+/// # Example
+///
+/// ```
+/// use std::collections::BTreeSet;
+///
+/// use miden_objects::account::StorageSlotName;
+/// use miden_objects::account::component::{
+///     AccountComponentMetadata,
+///     AccountStorageSchema,
+///     FeltSchema,
+///     InitStorageData,
+///     SchemaTypeId,
+///     StorageSlotSchema,
+///     StorageValueName,
+///     ValueSlotSchema,
+///     WordSchema,
+/// };
+/// use semver::Version;
+///
+/// let slot_name = StorageSlotName::new("demo::test_value")?;
+///
+/// let word = WordSchema::new_value([
+///     FeltSchema::new_void(),
+///     FeltSchema::new_void(),
+///     FeltSchema::new_void(),
+///     FeltSchema::new_typed(SchemaTypeId::native_felt(), "foo"),
+/// ]);
+///
+/// let storage_schema = AccountStorageSchema::new([(
+///     slot_name.clone(),
+///     StorageSlotSchema::Value(ValueSlotSchema::new(Some("demo slot".into()), word)),
+/// )])?;
+///
+/// let metadata = AccountComponentMetadata::new(
+///     "test name".into(),
+///     "description of the component".into(),
+///     Version::parse("0.1.0")?,
+///     BTreeSet::new(),
+///     storage_schema,
+/// );
+///
+/// // Init value keys are derived from slot name: `demo::test_value.foo`.
+/// let init_storage_data = InitStorageData::new(
+///     [(StorageValueName::from_slot_name(&slot_name).with_suffix("foo")?, "300".into())],
+///     [],
+/// );
+///
+/// let storage_slots = metadata.storage_schema().build_storage_slots(&init_storage_data)?;
+/// assert_eq!(storage_slots.len(), 1);
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "std", derive(serde::Deserialize, serde::Serialize))]
+#[cfg_attr(feature = "std", serde(rename_all = "kebab-case"))]
+pub struct AccountComponentMetadata {
+    /// The human-readable name of the component.
+    name: String,
+
+    /// A brief description of what this component is and how it works.
+    description: String,
+
+    /// The version of the component using semantic versioning.
+    /// This can be used to track and manage component upgrades.
+    version: Version,
+
+    /// A set of supported target account types for this component.
+    supported_types: BTreeSet<AccountType>,
+
+    /// Storage schema defining the component's storage layout, defaults, and init-supplied values.
+    #[cfg_attr(feature = "std", serde(rename = "storage"))]
+    storage_schema: AccountStorageSchema,
+}
+
+impl AccountComponentMetadata {
+    /// Create a new [AccountComponentMetadata].
+    pub fn new(
+        name: String,
+        description: String,
+        version: Version,
+        targets: BTreeSet<AccountType>,
+        storage_schema: AccountStorageSchema,
+    ) -> Self {
+        Self {
+            name,
+            description,
+            version,
+            supported_types: targets,
+            storage_schema,
+        }
+    }
+
+    /// Returns the init-time values's requirements for this schema.
+    ///
+    /// These values are used for initializing storage slot values or storage map entries. For a
+    /// full example, refer to the docs for [AccountComponentMetadata].
+    ///
+    /// Types for returned init values are inferred based on their location in the storage layout.
+    pub fn schema_requirements(&self) -> BTreeMap<StorageValueName, SchemaRequirement> {
+        self.storage_schema.schema_requirements().expect("storage schema is validated")
+    }
+
+    /// Returns the name of the account component.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Returns the description of the account component.
+    pub fn description(&self) -> &str {
+        &self.description
+    }
+
+    /// Returns the semantic version of the account component.
+    pub fn version(&self) -> &Version {
+        &self.version
+    }
+
+    /// Returns the account types supported by the component.
+    pub fn supported_types(&self) -> &BTreeSet<AccountType> {
+        &self.supported_types
+    }
+
+    /// Returns the storage schema of the component.
+    pub fn storage_schema(&self) -> &AccountStorageSchema {
+        &self.storage_schema
+    }
+}
+
+impl TryFrom<&Package> for AccountComponentMetadata {
+    type Error = AccountError;
+
+    fn try_from(package: &Package) -> Result<Self, Self::Error> {
+        package
+            .sections
+            .iter()
+            .find_map(|section| {
+                (section.id == SectionId::ACCOUNT_COMPONENT_METADATA).then(|| {
+                    AccountComponentMetadata::read_from_bytes(&section.data).map_err(|err| {
+                        AccountError::other_with_source(
+                            "failed to deserialize account component metadata",
+                            err,
+                        )
+                    })
+                })
+            })
+            .transpose()?
+            .ok_or_else(|| {
+                AccountError::other(
+                    "package does not contain account component metadata section - packages without explicit metadata may be intended for other purposes (e.g., note scripts, transaction scripts)",
+                )
+            })
+    }
+}
+
+// SERIALIZATION
+// ================================================================================================
+
+impl Serializable for AccountComponentMetadata {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.name.write_into(target);
+        self.description.write_into(target);
+        self.version.to_string().write_into(target);
+        self.supported_types.write_into(target);
+        self.storage_schema.write_into(target);
+    }
+}
+
+impl Deserializable for AccountComponentMetadata {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        Ok(Self {
+            name: String::read_from(source)?,
+            description: String::read_from(source)?,
+            version: semver::Version::from_str(&String::read_from(source)?).map_err(
+                |err: semver::Error| DeserializationError::InvalidValue(err.to_string()),
+            )?,
+            supported_types: BTreeSet::<AccountType>::read_from(source)?,
+            storage_schema: AccountStorageSchema::read_from(source)?,
+        })
+    }
+}

crates/miden-objects/src/account/component/mod.rs

@@ -1,9 +1,14 @@
 use alloc::collections::BTreeSet;
 use alloc::vec::Vec;
 
-// TODO(named_slots): Refactor templates.
-// mod template;
-// pub use template::*;
+use miden_mast_package::{MastArtifact, Package};
+
+mod metadata;
+pub use metadata::*;
+
+pub mod storage;
+pub use storage::*;
+
 mod code;
 pub use code::AccountComponentCode;
 
@@ -69,7 +74,6 @@ impl AccountComponent {
         })
     }
 
-    /*
     /// Creates an [`AccountComponent`] from a [`Package`] using [`InitStorageData`].
     ///
     /// This method provides type safety by leveraging the component's metadata to validate
@@ -104,8 +108,7 @@ impl AccountComponent {
         };
 
         let component_code = AccountComponentCode::from(library);
-
-        AccountComponent::from_library(&component_code, &metadata, init_storage_data)
+        Self::from_library(&component_code, &metadata, init_storage_data)
     }
 
     /// Creates an [`AccountComponent`] from an [`AccountComponentCode`] and
@@ -134,18 +137,16 @@ impl AccountComponent {
         account_component_metadata: &AccountComponentMetadata,
         init_storage_data: &InitStorageData,
     ) -> Result<Self, AccountError> {
-        let mut storage_slots = vec![];
-        for storage_entry in account_component_metadata.storage_entries() {
-            let entry_storage_slots = storage_entry
-                .try_build_storage_slots(init_storage_data)
-                .map_err(AccountError::AccountComponentTemplateInstantiationError)?;
-            storage_slots.extend(entry_storage_slots);
-        }
+        let storage_slots = account_component_metadata
+            .storage_schema()
+            .build_storage_slots(init_storage_data)
+            .map_err(|err| {
+                AccountError::other_with_source("failed to instantiate account component", err)
+            })?;
 
         Ok(AccountComponent::new(library.clone(), storage_slots)?
             .with_supported_types(account_component_metadata.supported_types().clone()))
     }
-    */
 
     // ACCESSORS
     // --------------------------------------------------------------------------------------------
@@ -241,8 +242,6 @@ impl From<AccountComponent> for AccountComponentCode {
     }
 }
 
-// TODO(named_slots): Reactivate tests once template is refactored.
-/*
 #[cfg(test)]
 mod tests {
     use alloc::collections::BTreeSet;
@@ -268,9 +267,8 @@ mod tests {
             "A test component".to_string(),
             Version::new(1, 0, 0),
             BTreeSet::from_iter([AccountType::RegularAccountImmutableCode]),
-            vec![],
-        )
-        .unwrap();
+            AccountStorageSchema::default(),
+        );
 
         let metadata_bytes = metadata.to_bytes();
         let package_with_metadata = Package {
@@ -326,9 +324,8 @@ mod tests {
                 AccountType::RegularAccountImmutableCode,
                 AccountType::RegularAccountUpdatableCode,
             ]),
-            vec![],
-        )
-        .unwrap();
+            AccountStorageSchema::default(),
+        );
 
         // Test with empty init data - this tests the complete workflow:
         // Library + Metadata -> AccountComponent
@@ -358,4 +355,3 @@ mod tests {
         assert!(error_msg.contains("package does not contain account component metadata"));
     }
 }
-*/