Metadata (#19)

* add metadata extension with tests

* fix clippy

contracts/token/fungible/src/extensions/metadata/mod.rs

@@ -0,0 +1,4 @@
+mod storage;
+pub use self::storage::*;
+
+mod test;

contracts/token/fungible/src/extensions/metadata/storage.rs

@@ -0,0 +1,70 @@
+use soroban_sdk::{contracttype, symbol_short, unwrap::UnwrapOptimized, Env, String, Symbol};
+
+use crate::storage::{INSTANCE_EXTEND_AMOUNT, INSTANCE_TTL_THRESHOLD};
+
+/// Storage key that maps to [`Metadata`]
+pub const METADATA_KEY: Symbol = symbol_short!("METADATA");
+
+/// Storage container for token metadata
+#[contracttype]
+pub struct Metadata {
+    pub decimals: u32,
+    pub name: String,
+    pub symbol: String,
+}
+
+/// Returns the token metadata such as decimals, name and symbol.
+///
+/// # Arguments
+///
+/// * `e` - Access to the Soroban environment.
+pub fn get_metadata(e: &Env) -> Metadata {
+    e.storage().instance().get(&METADATA_KEY).unwrap_optimized()
+}
+
+/// Returns the token decimals.
+///
+/// # Arguments
+///
+/// * `e` - Access to the Soroban environment.
+pub fn decimals(e: &Env) -> u32 {
+    get_metadata(e).decimals
+}
+
+/// Returns the token name.
+///
+/// # Arguments
+///
+/// * `e` - Access to the Soroban environment.
+pub fn name(e: &Env) -> String {
+    get_metadata(e).name
+}
+
+/// Returns the token symbol.
+///
+/// # Arguments
+///
+/// * `e` - Access to the Soroban environment.
+pub fn symbol(e: &Env) -> String {
+    get_metadata(e).symbol
+}
+
+/// Sets the token metadata such as decimals, name and symbol.
+///
+/// # Arguments
+///
+/// * `e` - Access to the Soroban environment.
+/// * `decimals` - The number of decimals.
+/// * `name` - The name of the token.
+/// * `symbol` - The symbol of the token.
+///
+/// # Notes
+///
+/// **IMPORTANT**: This function lacks authorization controls. You want to
+/// invoke it most likely from a constructor or from another function with
+/// admin-only authorization.
+pub fn set_metadata(e: &Env, decimals: u32, name: String, symbol: String) {
+    let metadata = Metadata { decimals, name, symbol };
+    e.storage().instance().extend_ttl(INSTANCE_TTL_THRESHOLD, INSTANCE_EXTEND_AMOUNT);
+    e.storage().instance().set(&METADATA_KEY, &metadata);
+}

contracts/token/fungible/src/extensions/metadata/test.rs

@@ -0,0 +1,53 @@
+#![cfg(test)]
+
+use soroban_sdk::{contract, Env, String};
+
+use crate::extensions::metadata::{decimals, name, set_metadata, symbol};
+
+#[contract]
+struct MockContract;
+
+#[test]
+fn set_and_get_metadata() {
+    let e = Env::default();
+    let address = e.register(MockContract, ());
+
+    e.as_contract(&address, || {
+        let test_decimals: u32 = 7;
+        let test_name = String::from_str(&e, "Test Token");
+        let test_symbol = String::from_str(&e, "TEST");
+
+        set_metadata(&e, test_decimals, test_name.clone(), test_symbol.clone());
+
+        assert_eq!(decimals(&e), test_decimals);
+        assert_eq!(name(&e), test_name);
+        assert_eq!(symbol(&e), test_symbol);
+    });
+}
+
+#[test]
+#[should_panic]
+fn get_unset_metadata() {
+    let e = Env::default();
+    let address = e.register(MockContract, ());
+
+    e.as_contract(&address, || {
+        decimals(&e);
+    });
+}
+
+#[test]
+fn metadata_update() {
+    let e = Env::default();
+    let address = e.register(MockContract, ());
+
+    e.as_contract(&address, || {
+        set_metadata(&e, 6, String::from_str(&e, "Initial Name"), String::from_str(&e, "INI"));
+
+        set_metadata(&e, 8, String::from_str(&e, "Updated Name"), String::from_str(&e, "UPD"));
+
+        assert_eq!(decimals(&e), 8);
+        assert_eq!(name(&e), String::from_str(&e, "Updated Name"));
+        assert_eq!(symbol(&e), String::from_str(&e, "UPD"));
+    });
+}

contracts/token/fungible/src/extensions/mod.rs

@@ -1,2 +1,3 @@
 pub mod burnable;
+pub mod metadata;
 pub mod mintable;

contracts/token/fungible/src/fungible.rs

@@ -148,8 +148,8 @@ pub trait FungibleToken {
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::metadata::decimals()`] function from
-    /// the `metadata` module when implementing this function.
+    /// We recommend using the [`crate::metadata::decimals()`]
+    /// function from the `metadata` module when implementing this function.
     fn decimals(e: &Env) -> u32;
 
     /// Returns the name for this token.
@@ -160,8 +160,8 @@ pub trait FungibleToken {
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::metadata::name()`] function from
-    /// the `metadata` module when implementing this function.
+    /// We recommend using the [`crate::metadata::name()`] function
+    /// from the `metadata` module when implementing this function.
     fn name(e: &Env) -> String;
 
     /// Returns the symbol for this token.
@@ -172,8 +172,8 @@ pub trait FungibleToken {
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::metadata::symbol()`] function from
-    /// the `metadata` module when implementing this function.
+    /// We recommend using the [`crate::metadata::symbol()`]
+    /// function from the `metadata` module when implementing this function.
     fn symbol(e: &Env) -> String;
 }
 

contracts/token/fungible/src/lib.rs

@@ -62,4 +62,6 @@ pub mod extensions;
 pub mod fungible;
 pub mod storage;
 
+pub use extensions::metadata;
+
 mod test;

contracts/token/fungible/test_snapshots/extensions/burnable/test/burn_with_allowance_works.1.json

@@ -188,7 +188,7 @@
             },
             "ext": "v0"
           },
-          4095
+          518400
         ]
       ],
       [
@@ -236,7 +236,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ],
       [
@@ -323,7 +323,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ]
     ]

contracts/token/fungible/test_snapshots/extensions/burnable/test/burn_with_insufficient_allowance_panics.1.json

@@ -160,7 +160,7 @@
             },
             "ext": "v0"
           },
-          4095
+          518400
         ]
       ],
       [
@@ -192,7 +192,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ],
       [
@@ -279,7 +279,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ]
     ]

contracts/token/fungible/test_snapshots/extensions/burnable/test/burn_with_insufficient_balance_panics.1.json

@@ -61,7 +61,7 @@
             },
             "ext": "v0"
           },
-          4095
+          518400
         ]
       ],
       [
@@ -93,7 +93,40 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
+        ]
+      ],
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+            "key": {
+              "ledger_key_nonce": {
+                "nonce": 801925984706572462
+              }
+            },
+            "durability": "temporary"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+                "key": {
+                  "ledger_key_nonce": {
+                    "nonce": 801925984706572462
+                  }
+                },
+                "durability": "temporary",
+                "val": "void"
+              }
+            },
+            "ext": "v0"
+          },
+          6311999
         ]
       ],
       [
@@ -114,7 +147,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ]
     ]

contracts/token/fungible/test_snapshots/extensions/burnable/test/burn_with_no_allowance_panics.1.json

@@ -61,7 +61,7 @@
             },
             "ext": "v0"
           },
-          4095
+          518400
         ]
       ],
       [
@@ -93,7 +93,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ],
       [
@@ -147,7 +147,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ]
     ]

contracts/token/fungible/test_snapshots/extensions/burnable/test/burn_works.1.json

@@ -5,7 +5,21 @@
   },
   "auth": [
     [],
-    []
+    [
+      [
+        "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+        {
+          "function": {
+            "contract_fn": {
+              "contract_address": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+              "function_name": "",
+              "args": []
+            }
+          },
+          "sub_invocations": []
+        }
+      ]
+    ]
   ],
   "ledger": {
     "protocol_version": 22,
@@ -62,7 +76,7 @@
             },
             "ext": "v0"
           },
-          4095
+          518400
         ]
       ],
       [
@@ -110,7 +124,40 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
+        ]
+      ],
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+            "key": {
+              "ledger_key_nonce": {
+                "nonce": 801925984706572462
+              }
+            },
+            "durability": "temporary"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+                "key": {
+                  "ledger_key_nonce": {
+                    "nonce": 801925984706572462
+                  }
+                },
+                "durability": "temporary",
+                "val": "void"
+              }
+            },
+            "ext": "v0"
+          },
+          6311999
         ]
       ],
       [
@@ -131,7 +178,7 @@
             },
             "ext": "v0"
           },
-          4095
+          120960
         ]
       ]
     ]