[coin.move] CoinMetadata getter functions (MystenLabs#6911)

- Currently, `CoinMetadata` can be accessed for off-chain consumption, however there is a class of use-cases where we would like to consume the metadata fields (decimals, name, symbol, etc.) on-chain. For example, a protocol might want to perform checks on the metadata corresponding to a `CoinType` on-chain, e.g. check that `decimals==8`. Currently this is impossible because the metadata fields are opaque. The following getters allow inspection of `CoinMetadata` fields.
nitingujarathi · Dec 23, 2022 · 3d57ffd · 3d57ffd
1 parent 150aed8
commit 3d57ffd
Show file tree

Hide file tree

Showing 4 changed files with 174 additions and 7 deletions.
diff --git a/crates/sui-config/tests/snapshots/snapshot_tests__empty_genesis_snapshot_matches.snap b/crates/sui-config/tests/snapshots/snapshot_tests__empty_genesis_snapshot_matches.snap
diff --git a/crates/sui-cost/tests/snapshots/empirical_transaction_cost__good_snapshot-2.snap b/crates/sui-cost/tests/snapshots/empirical_transaction_cost__good_snapshot-2.snap
@@ -4,13 +4,13 @@ expression: common_costs_estimate
 ---
 {
   "MergeCoin": {
-    "computation_cost": 6511,
-    "storage_cost": 9318,
+    "computation_cost": 6534,
+    "storage_cost": 9353,
     "storage_rebate": 0
   },
   "Publish": {
-    "computation_cost": 7303,
-    "storage_cost": 10423,
+    "computation_cost": 7326,
+    "storage_cost": 10457,
     "storage_rebate": 0
   },
   "SharedCounterAssertValue": {
@@ -29,8 +29,8 @@ expression: common_costs_estimate
     "storage_rebate": 0
   },
   "SplitCoin": {
-    "computation_cost": 6489,
-    "storage_cost": 9286,
+    "computation_cost": 6512,
+    "storage_cost": 9320,
     "storage_rebate": 0
   },
   "TransferPortionSuiCoin": {

diff --git a/crates/sui-framework/docs/coin.md b/crates/sui-framework/docs/coin.md
@@ -39,6 +39,11 @@ tokens and coins. <code><a href="coin.md#0x2_coin_Coin">Coin</a></code> can be d
 -  [Function `update_symbol`](#0x2_coin_update_symbol)
 -  [Function `update_description`](#0x2_coin_update_description)
 -  [Function `update_icon_url`](#0x2_coin_update_icon_url)
+-  [Function `get_decimals`](#0x2_coin_get_decimals)
+-  [Function `get_name`](#0x2_coin_get_name)
+-  [Function `get_symbol`](#0x2_coin_get_symbol)
+-  [Function `get_description`](#0x2_coin_get_description)
+-  [Function `get_icon_url`](#0x2_coin_get_icon_url)
 
 
 <pre><code><b>use</b> <a href="">0x1::ascii</a>;
@@ -1127,4 +1132,134 @@ Update the url of the coin in <code><a href="coin.md#0x2_coin_CoinMetadata">Coin
 
 
 
+</details>
+
+<a name="0x2_coin_get_decimals"></a>
+
+## Function `get_decimals`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_decimals">get_decimals</a>&lt;T&gt;(metadata: &<a href="coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;): u8
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_decimals">get_decimals</a>&lt;T&gt;(
+    metadata: &<a href="coin.md#0x2_coin_CoinMetadata">CoinMetadata</a>&lt;T&gt;
+): u8 {
+    metadata.decimals
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x2_coin_get_name"></a>
+
+## Function `get_name`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_name">get_name</a>&lt;T&gt;(metadata: &<a href="coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;): <a href="_String">string::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_name">get_name</a>&lt;T&gt;(
+    metadata: &<a href="coin.md#0x2_coin_CoinMetadata">CoinMetadata</a>&lt;T&gt;
+): <a href="_String">string::String</a> {
+    metadata.name
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x2_coin_get_symbol"></a>
+
+## Function `get_symbol`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_symbol">get_symbol</a>&lt;T&gt;(metadata: &<a href="coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;): <a href="_String">ascii::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_symbol">get_symbol</a>&lt;T&gt;(
+    metadata: &<a href="coin.md#0x2_coin_CoinMetadata">CoinMetadata</a>&lt;T&gt;
+): <a href="_String">ascii::String</a> {
+    metadata.symbol
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x2_coin_get_description"></a>
+
+## Function `get_description`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_description">get_description</a>&lt;T&gt;(metadata: &<a href="coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;): <a href="_String">string::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_description">get_description</a>&lt;T&gt;(
+    metadata: &<a href="coin.md#0x2_coin_CoinMetadata">CoinMetadata</a>&lt;T&gt;
+): <a href="_String">string::String</a> {
+    metadata.description
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x2_coin_get_icon_url"></a>
+
+## Function `get_icon_url`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_icon_url">get_icon_url</a>&lt;T&gt;(metadata: &<a href="coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;): <a href="_Option">option::Option</a>&lt;<a href="url.md#0x2_url_Url">url::Url</a>&gt;
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="coin.md#0x2_coin_get_icon_url">get_icon_url</a>&lt;T&gt;(
+    metadata: &<a href="coin.md#0x2_coin_CoinMetadata">CoinMetadata</a>&lt;T&gt;
+): Option&lt;Url&gt; {
+    metadata.icon_url
+}
+</code></pre>
+
+
+
 </details>
diff --git a/crates/sui-framework/sources/coin.move b/crates/sui-framework/sources/coin.move
@@ -392,6 +392,38 @@ module sui::coin {
         metadata.icon_url = option::some(url::new_unsafe(url));
     }
 
+    // === Get coin metadata fields for on-chain consumption ===
+
+    public fun get_decimals<T>(
+        metadata: &CoinMetadata<T>
+    ): u8 {
+        metadata.decimals
+    }
+
+    public fun get_name<T>(
+        metadata: &CoinMetadata<T>
+    ): string::String {
+        metadata.name
+    }
+
+    public fun get_symbol<T>(
+        metadata: &CoinMetadata<T>
+    ): ascii::String {
+        metadata.symbol
+    }
+
+    public fun get_description<T>(
+        metadata: &CoinMetadata<T>
+    ): string::String {
+        metadata.description
+    }
+
+    public fun get_icon_url<T>(
+        metadata: &CoinMetadata<T>
+    ): Option<Url> {
+        metadata.icon_url
+    }
+
     // === Test-only code ===
 
     #[test_only]