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,20 @@ 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`.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the key is not a valid metadata key format.
+    pub fn entry(
+        key: &str,
+        val: impl Into<MetadataValue>,
+    ) -> Result<(MetadataKey, Self), MetadataKeyError> {
+        let metadata_key = MetadataKey::parse(key)?;
+        Ok((metadata_key, val.into()))
     }
 }
 
@@ -76,3 +89,21 @@ 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").unwrap();
+        assert_eq!(entry.0.as_str(), "icrc1:name");
+        assert_eq!(entry.1, MetadataValue::Text("My Token".to_string()));
+    }
+
+    #[test]
+    fn test_metadata_value_entry_invalid_key() {
+        let result = MetadataValue::entry("invalid_no_colon", "value");
+        assert!(result.is_err());
+    }
+}