feat(icrc-ledger-types): add MetadataKey type

packages/icrc-ledger-agent/src/lib.rs

@@ -18,7 +18,8 @@ use icrc_ledger_types::icrc3::archive::{ArchivedRange, QueryBlockArchiveFn};
 use icrc_ledger_types::icrc3::blocks::ICRC3DataCertificate;
 use icrc_ledger_types::icrc3::blocks::{GetBlocksRequest, GetBlocksResponse};
 use icrc_ledger_types::{
-    icrc::generic_metadata_value::MetadataValue as Value, icrc3::blocks::BlockRange,
+    icrc::generic_metadata_value::MetadataValue as Value, icrc::metadata_key::MetadataKey,
+    icrc3::blocks::BlockRange,
 };
 
 #[derive(Debug)]
@@ -126,15 +127,18 @@ impl Icrc1Agent {
     }
 
     /// Returns the list of metadata entries for this ledger
-    pub async fn metadata(&self, mode: CallMode) -> Result<Vec<(String, Value)>, Icrc1AgentError> {
+    pub async fn metadata(
+        &self,
+        mode: CallMode,
+    ) -> Result<Vec<(MetadataKey, Value)>, Icrc1AgentError> {
         Ok(match mode {
             CallMode::Query => Decode!(
                 &self.query("icrc1_metadata", &Encode!()?).await?,
-                Vec<(String, Value)>
+                Vec<(MetadataKey, Value)>
             )?,
             CallMode::Update => Decode!(
                 &self.update("icrc1_metadata", &Encode!()?).await?,
-                Vec<(String, Value)>
+                Vec<(MetadataKey, Value)>
             )?,
         })
     }

packages/icrc-ledger-client/src/lib.rs

@@ -3,6 +3,7 @@ use candid::Principal;
 use candid::types::number::Nat;
 use candid::utils::{ArgumentDecoder, ArgumentEncoder};
 use icrc_ledger_types::icrc::generic_metadata_value::MetadataValue as Value;
+use icrc_ledger_types::icrc::metadata_key::MetadataKey;
 use icrc_ledger_types::icrc1::account::Account;
 use icrc_ledger_types::icrc1::transfer::{BlockIndex, TransferArg, TransferError};
 use icrc_ledger_types::icrc2::approve::{ApproveArgs, ApproveError};
@@ -55,7 +56,7 @@ impl<R: Runtime> ICRC1Client<R> {
             .map(untuple)
     }
 
-    pub async fn metadata(&self) -> Result<Vec<(String, Value)>, (i32, String)> {
+    pub async fn metadata(&self) -> Result<Vec<(MetadataKey, Value)>, (i32, String)> {
         self.runtime
             .call(self.ledger_canister_id, "icrc1_metadata", ())
             .await

packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs

@@ -2,6 +2,8 @@ use candid::{CandidType, Deserialize, Int, Nat};
 use serde::Serialize;
 use serde_bytes::ByteBuf;
 
+pub use crate::icrc::metadata_key::{MetadataKey, MetadataKeyError};
+
 /// Variant type for the `icrc1_metadata` endpoint values. The corresponding metadata keys are
 /// arbitrary Unicode strings and must follow the pattern `<namespace>:<key>`, where `<namespace>`
 /// is a string not containing colons. The namespace `icrc1` is reserved for keys defined in the
@@ -17,9 +19,18 @@ pub enum MetadataValue {
 }
 
 impl MetadataValue {
-    /// Create a `(String, MetadataValue)` tuple for use in metadata maps.
-    pub fn entry(key: impl ToString, val: impl Into<MetadataValue>) -> (String, Self) {
-        (key.to_string(), val.into())
+    /// Create a `(MetadataKey, MetadataValue)` tuple for use in metadata maps.
+    ///
+    /// The key must be a valid metadata key in the format `<namespace>:<key>`.
+    /// This is typically used with the predefined constants like `MetadataKey::ICRC1_NAME`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the key is not a valid metadata key format.
+    pub fn entry(key: &str, val: impl Into<MetadataValue>) -> (MetadataKey, Self) {
+        let metadata_key =
+            MetadataKey::parse(key).unwrap_or_else(|e| panic!("invalid metadata key '{key}': {e}"));
+        (metadata_key, val.into())
     }
 }
 
@@ -76,3 +87,15 @@ impl<'a> From<&'a [u8]> for MetadataValue {
         MetadataValue::Blob(ByteBuf::from(bytes.to_vec()))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_metadata_value_entry() {
+        let entry = MetadataValue::entry(MetadataKey::ICRC1_NAME, "My Token");
+        assert_eq!(entry.0.as_str(), "icrc1:name");
+        assert_eq!(entry.1, MetadataValue::Text("My Token".to_string()));
+    }
+}

packages/icrc-ledger-types/src/icrc/metadata_key.rs

@@ -0,0 +1,268 @@
+//! Metadata key types for ICRC-1 ledger metadata.
+
+use candid::{CandidType, Deserialize};
+use serde::Serialize;
+use std::fmt;
+
+/// Error type for invalid metadata key format.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum MetadataKeyError {
+    /// The key does not contain a colon separator.
+    MissingColon,
+    /// The namespace (part before the first colon) contains a colon.
+    ColonInNamespace,
+    /// The namespace is empty.
+    EmptyNamespace,
+    /// The key part (after the colon) is empty.
+    EmptyKey,
+}
+
+impl fmt::Display for MetadataKeyError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            MetadataKeyError::MissingColon => {
+                write!(f, "metadata key must contain a colon separator")
+            }
+            MetadataKeyError::ColonInNamespace => {
+                write!(f, "namespace must not contain colons")
+            }
+            MetadataKeyError::EmptyNamespace => {
+                write!(f, "namespace must not be empty")
+            }
+            MetadataKeyError::EmptyKey => {
+                write!(f, "key part must not be empty")
+            }
+        }
+    }
+}
+
+impl std::error::Error for MetadataKeyError {}
+
+/// A validated metadata key following the ICRC-1 standard format `<namespace>:<key>`.
+///
+/// Metadata keys are arbitrary Unicode strings that must follow the pattern `<namespace>:<key>`,
+/// where `<namespace>` is a string not containing colons. The namespace `icrc1` is reserved
+/// for keys defined in the ICRC-1 standard.
+///
+/// For more information, see the
+/// [documentation of Metadata in the ICRC-1 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1#metadata).
+///
+/// # Examples
+///
+/// ```
+/// use icrc_ledger_types::icrc::metadata_key::MetadataKey;
+///
+/// // Valid keys
+/// let key = MetadataKey::new("icrc1", "name").unwrap();
+/// assert_eq!(key.namespace(), "icrc1");
+/// assert_eq!(key.key(), "name");
+/// assert_eq!(key.as_str(), "icrc1:name");
+///
+/// // Parse from string
+/// let key = MetadataKey::parse("myapp:decimals").unwrap();
+/// assert_eq!(key.namespace(), "myapp");
+/// assert_eq!(key.key(), "decimals");
+/// ```
+#[derive(
+    CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash,
+)]
+pub struct MetadataKey(String);
+
+impl MetadataKey {
+    // ==================== ICRC-1 Standard Keys ====================
+
+    /// The name of the token.
+    /// When present, should be the same as the result of the icrc1_name query call.
+    pub const ICRC1_NAME: &'static str = "icrc1:name";
+
+    /// The token currency code (see ISO-4217).
+    /// When present, should be the same as the result of the icrc1_symbol query call.
+    pub const ICRC1_SYMBOL: &'static str = "icrc1:symbol";
+
+    /// The number of decimals the token uses. For example, 8 means to divide the token amount by 108 to get its user representation.
+    /// When present, should be the same as the result of the icrc1_decimals query call.
+    pub const ICRC1_DECIMALS: &'static str = "icrc1:decimals";
+
+    /// The default transfer fee.
+    /// When present, should be the same as the result of the icrc1_fee query call.
+    pub const ICRC1_FEE: &'static str = "icrc1:fee";
+
+    /// The URL of the token logo. The value can contain the actual image if it's a Data URL.
+    pub const ICRC1_LOGO: &'static str = "icrc1:logo";
+
+    /// The maximum length of a memo in bytes.
+    pub const ICRC1_MAX_MEMO_LENGTH: &'static str = "icrc1:max_memo_length";
+
+    // ==================== ICRC-103 Keys ====================
+
+    /// Whether allowance data is public or not.
+    pub const ICRC103_PUBLIC_ALLOWANCES: &'static str = "icrc103:public_allowances";
+
+    /// The maximum number of allowances the ledger will return in response to a query.
+    pub const ICRC103_MAX_TAKE_VALUE: &'static str = "icrc103:max_take_value";
+
+    // ==================== ICRC-106 Keys ====================
+
+    /// The textual representation of the principal of the associated index canister.
+    pub const ICRC106_INDEX_PRINCIPAL: &'static str = "icrc106:index_principal";
+
+    /// Creates a new metadata key from namespace and key parts.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The namespace is empty
+    /// - The namespace contains a colon
+    /// - The key is empty
+    pub fn new(namespace: &str, key: &str) -> Result<Self, MetadataKeyError> {
+        if namespace.is_empty() {
+            return Err(MetadataKeyError::EmptyNamespace);
+        }
+        if namespace.contains(':') {
+            return Err(MetadataKeyError::ColonInNamespace);
+        }
+        if key.is_empty() {
+            return Err(MetadataKeyError::EmptyKey);
+        }
+        Ok(Self(format!("{namespace}:{key}")))
+    }
+
+    /// Parses a metadata key from a string in the format `<namespace>:<key>`.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the string does not follow the required format.
+    pub fn parse(s: &str) -> Result<Self, MetadataKeyError> {
+        let colon_pos = s.find(':').ok_or(MetadataKeyError::MissingColon)?;
+        let namespace = &s[..colon_pos];
+        let key = &s[colon_pos + 1..];
+
+        if namespace.is_empty() {
+            return Err(MetadataKeyError::EmptyNamespace);
+        }
+        if key.is_empty() {
+            return Err(MetadataKeyError::EmptyKey);
+        }
+        Ok(Self(s.to_string()))
+    }
+
+    /// Returns the namespace part of the key.
+    pub fn namespace(&self) -> &str {
+        self.0
+            .find(':')
+            .map(|pos| &self.0[..pos])
+            .expect("BUG: MetadataKey should always contain a colon")
+    }
+
+    /// Returns the key part (after the namespace).
+    pub fn key(&self) -> &str {
+        self.0
+            .find(':')
+            .map(|pos| &self.0[pos + 1..])
+            .expect("BUG: MetadataKey should always contain a colon")
+    }
+
+    /// Returns the full key as a string slice.
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for MetadataKey {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl AsRef<str> for MetadataKey {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl From<MetadataKey> for String {
+    fn from(key: MetadataKey) -> Self {
+        key.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_metadata_key_new() {
+        let key = MetadataKey::new("icrc1", "name").unwrap();
+        assert_eq!(key.namespace(), "icrc1");
+        assert_eq!(key.key(), "name");
+        assert_eq!(key.as_str(), "icrc1:name");
+    }
+
+    #[test]
+    fn test_metadata_key_parse() {
+        let key = MetadataKey::parse("myapp:decimals").unwrap();
+        assert_eq!(key.namespace(), "myapp");
+        assert_eq!(key.key(), "decimals");
+    }
+
+    #[test]
+    fn test_metadata_key_with_colons_in_value() {
+        // Key part can contain colons
+        let key = MetadataKey::parse("myapp:some:complex:key").unwrap();
+        assert_eq!(key.namespace(), "myapp");
+        assert_eq!(key.key(), "some:complex:key");
+    }
+
+    #[test]
+    fn test_metadata_key_empty_namespace() {
+        assert_eq!(
+            MetadataKey::new("", "name"),
+            Err(MetadataKeyError::EmptyNamespace)
+        );
+        assert_eq!(
+            MetadataKey::parse(":name"),
+            Err(MetadataKeyError::EmptyNamespace)
+        );
+    }
+
+    #[test]
+    fn test_metadata_key_empty_key() {
+        assert_eq!(
+            MetadataKey::new("icrc1", ""),
+            Err(MetadataKeyError::EmptyKey)
+        );
+        assert_eq!(
+            MetadataKey::parse("icrc1:"),
+            Err(MetadataKeyError::EmptyKey)
+        );
+    }
+
+    #[test]
+    fn test_metadata_key_missing_colon() {
+        assert_eq!(
+            MetadataKey::parse("nonamespace"),
+            Err(MetadataKeyError::MissingColon)
+        );
+    }
+
+    #[test]
+    fn test_metadata_key_colon_in_namespace() {
+        assert_eq!(
+            MetadataKey::new("bad:namespace", "key"),
+            Err(MetadataKeyError::ColonInNamespace)
+        );
+    }
+
+    #[test]
+    fn test_metadata_key_display() {
+        let key = MetadataKey::new("icrc1", "symbol").unwrap();
+        assert_eq!(format!("{}", key), "icrc1:symbol");
+    }
+
+    #[test]
+    fn test_metadata_key_into_string() {
+        let key = MetadataKey::new("icrc1", "decimals").unwrap();
+        let s: String = key.into();
+        assert_eq!(s, "icrc1:decimals");
+    }
+}

packages/icrc-ledger-types/src/icrc/mod.rs

@@ -3,3 +3,4 @@
 pub mod generic_metadata_value;
 pub mod generic_value;
 pub mod generic_value_predicate;
+pub mod metadata_key;

rs/ethereum/ledger-suite-orchestrator/src/scheduler/mod.rs

@@ -907,6 +907,7 @@ fn icrc1_ledger_init_arg(
 ) -> LedgerInitArgs {
     use ic_icrc1_ledger::FeatureFlags as LedgerFeatureFlags;
     use icrc_ledger_types::icrc::generic_metadata_value::MetadataValue as LedgerMetadataValue;
+    use icrc_ledger_types::icrc::metadata_key::MetadataKey;
     use icrc_ledger_types::icrc1::account::Account as LedgerAccount;
 
     const LEDGER_FEE_SUBACCOUNT: [u8; 32] = [
@@ -928,7 +929,7 @@ fn icrc1_ledger_init_arg(
         token_name: ledger_init_arg.token_name,
         token_symbol: ledger_init_arg.token_symbol,
         metadata: vec![(
-            "icrc1:logo".to_string(),
+            MetadataKey::parse(MetadataKey::ICRC1_LOGO).unwrap(),
             LedgerMetadataValue::from(ledger_init_arg.token_logo),
         )],
         archive_options: icrc1_archive_options(