[deny list v2] Added doc comments for sui::coin::deny_list_v2_* APIs (

#18571) ## Description - Added doc comments ## Test plan - 👀 --- ## Release notes Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required. For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates. - [ ] Protocol: - [ ] Nodes (Validators and Full nodes): - [ ] Indexer: - [ ] JSON-RPC: - [ ] GraphQL: - [ ] CLI: - [ ] Rust SDK: --------- Co-authored-by: ronny-mysten <[email protected]>
MystenLabs · Jul 10, 2024 · 1af538a · 1af538a
1 parent a62575f
commit 1af538a
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 0 deletions.
diff --git a/crates/sui-framework/docs/sui-framework/coin.md b/crates/sui-framework/docs/sui-framework/coin.md
@@ -253,6 +253,11 @@ coins of type <code>T</code>. Transferable
 
 ## Resource `DenyCapV2`
 
+Capability allowing the bearer to deny addresses from using the currency's coins--
+immediately preventing those addresses from interacting with the coin as an input to a
+transaction and at the start of the next preventing them from receiving the coin.
+If <code>allow_global_pause</code> is true, the bearer can enable a global pause that behaves as if
+all addresses were added to the deny list.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">DenyCapV2</a>&lt;T&gt; <b>has</b> store, key
@@ -882,6 +887,14 @@ type, ensuring that there's only one <code><a href="../sui-framework/coin.md#0x2
 
 ## Function `create_regulated_currency_v2`
 
+This creates a new currency, via <code>create_currency</code>, but with an extra capability that
+allows for specific addresses to have their coins frozen. When an address is added to the
+deny list, it is immediately unable to interact with the currency's coin as input objects.
+Additionally at the start of the next epoch, they will be unable to receive the currency's
+coin.
+The <code>allow_global_pause</code> flag enables an additional API that will cause all addresses to be
+be denied. Note however, that this doesn't affect per-address entries of the deny list and
+will not change the result of the "contains" APIs.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_create_regulated_currency_v2">create_regulated_currency_v2</a>&lt;T: drop&gt;(witness: T, decimals: u8, symbol: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;u8&gt;, name: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;u8&gt;, description: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;u8&gt;, icon_url: <a href="../move-stdlib/option.md#0x1_option_Option">option::Option</a>&lt;<a href="../sui-framework/url.md#0x2_url_Url">url::Url</a>&gt;, allow_global_pause: bool, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>): (<a href="../sui-framework/coin.md#0x2_coin_TreasuryCap">coin::TreasuryCap</a>&lt;T&gt;, <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;, <a href="../sui-framework/coin.md#0x2_coin_CoinMetadata">coin::CoinMetadata</a>&lt;T&gt;)
@@ -933,6 +946,9 @@ type, ensuring that there's only one <code><a href="../sui-framework/coin.md#0x2
 
 ## Function `migrate_regulated_currency_to_v2`
 
+Given the <code><a href="../sui-framework/coin.md#0x2_coin_DenyCap">DenyCap</a></code> for a regulated currency, migrate it to the new <code><a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">DenyCapV2</a></code> type.
+All entries in the deny list will be migrated to the new format.
+See <code>create_regulated_currency_v2</code> for details on the new v2 of the deny list.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_migrate_regulated_currency_to_v2">migrate_regulated_currency_to_v2</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<b>mut</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, cap: <a href="../sui-framework/coin.md#0x2_coin_DenyCap">coin::DenyCap</a>&lt;T&gt;, allow_global_pause: bool, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>): <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;
@@ -1057,6 +1073,9 @@ accordingly.
 
 ## Function `deny_list_v2_add`
 
+Adds the given address to the deny list, preventing it from interacting with the specified
+coin type as an input to a transaction. Additionally at the start of the next epoch, the
+address will be unable to receive objects of this coin type.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_add">deny_list_v2_add</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<b>mut</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, _deny_cap: &<b>mut</b> <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;, addr: <b>address</b>, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -1087,6 +1106,9 @@ accordingly.
 
 ## Function `deny_list_v2_remove`
 
+Removes an address from the deny list. Similar to <code>deny_list_v2_add</code>, the effect for input
+objects will be immediate, but the effect for receiving objects will be delayed until the
+next epoch.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_remove">deny_list_v2_remove</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<b>mut</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, _deny_cap: &<b>mut</b> <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;, addr: <b>address</b>, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -1117,6 +1139,8 @@ accordingly.
 
 ## Function `deny_list_v2_contains_current_epoch`
 
+Check if the deny list contains the given address for the current epoch. Denied addresses
+in the current epoch will be unable to receive objects of this coin type.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_contains_current_epoch">deny_list_v2_contains_current_epoch</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, addr: <b>address</b>, ctx: &<a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>): bool
@@ -1146,6 +1170,9 @@ accordingly.
 
 ## Function `deny_list_v2_contains_next_epoch`
 
+Check if the deny list contains the given address for the next epoch. Denied addresses in
+the next epoch will immediately be unable to use objects of this coin type as inputs. At the
+start of the next epoch, the address will be unable to receive objects of this coin type.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_contains_next_epoch">deny_list_v2_contains_next_epoch</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, addr: <b>address</b>): bool
@@ -1174,6 +1201,9 @@ accordingly.
 
 ## Function `deny_list_v2_enable_global_pause`
 
+Enable the global pause for the given coin type. This will immediately prevent all addresses
+from using objects of this coin type as inputs. At the start of the next epoch, all
+addresses will be unable to receive objects of this coin type.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_enable_global_pause">deny_list_v2_enable_global_pause</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<b>mut</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, deny_cap: &<b>mut</b> <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -1204,6 +1234,9 @@ accordingly.
 
 ## Function `deny_list_v2_disable_global_pause`
 
+Disable the global pause for the given coin type. This will immediately allow all addresses
+to resume using objects of this coin type as inputs. However, receiving objects of this coin
+type will still be paused until the start of the next epoch.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_disable_global_pause">deny_list_v2_disable_global_pause</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<b>mut</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, deny_cap: &<b>mut</b> <a href="../sui-framework/coin.md#0x2_coin_DenyCapV2">coin::DenyCapV2</a>&lt;T&gt;, ctx: &<b>mut</b> <a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -1234,6 +1267,7 @@ accordingly.
 
 ## Function `deny_list_v2_is_global_pause_enabled_current_epoch`
 
+Check if the global pause is enabled for the given coin type in the current epoch.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_is_global_pause_enabled_current_epoch">deny_list_v2_is_global_pause_enabled_current_epoch</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>, ctx: &<a href="../sui-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>): bool
@@ -1262,6 +1296,7 @@ accordingly.
 
 ## Function `deny_list_v2_is_global_pause_enabled_next_epoch`
 
+Check if the global pause is enabled for the given coin type in the next epoch.
 
 
 <pre><code><b>public</b> <b>fun</b> <a href="../sui-framework/coin.md#0x2_coin_deny_list_v2_is_global_pause_enabled_next_epoch">deny_list_v2_is_global_pause_enabled_next_epoch</a>&lt;T&gt;(<a href="../sui-framework/deny_list.md#0x2_deny_list">deny_list</a>: &<a href="../sui-framework/deny_list.md#0x2_deny_list_DenyList">deny_list::DenyList</a>): bool

diff --git a/crates/sui-framework/docs/sui-framework/deny_list.md b/crates/sui-framework/docs/sui-framework/deny_list.md
@@ -91,6 +91,8 @@ A shared object that stores the addresses that are blocked for a given core type
 
 ## Struct `ConfigWriteCap`
 
+The capability used to write to the deny list config. Ensures that the Configs for the
+DenyList are modified only by this module.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_ConfigWriteCap">ConfigWriteCap</a> <b>has</b> drop
@@ -118,6 +120,8 @@ A shared object that stores the addresses that are blocked for a given core type
 
 ## Struct `ConfigKey`
 
+The dynamic object field key used to store the <code>Config</code> for a given type, essentially a
+<code>(per_type_index, per_type_key)</code> pair.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_ConfigKey">ConfigKey</a> <b>has</b> <b>copy</b>, drop, store
@@ -151,6 +155,7 @@ A shared object that stores the addresses that are blocked for a given core type
 
 ## Struct `AddressKey`
 
+The setting key used to store the deny list for a given address in the <code>Config</code>.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_AddressKey">AddressKey</a> <b>has</b> <b>copy</b>, drop, store
@@ -178,6 +183,7 @@ A shared object that stores the addresses that are blocked for a given core type
 
 ## Struct `GlobalPauseKey`
 
+The setting key used to store the global pause setting in the <code>Config</code>.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_GlobalPauseKey">GlobalPauseKey</a> <b>has</b> <b>copy</b>, drop, store
@@ -205,6 +211,8 @@ A shared object that stores the addresses that are blocked for a given core type
 
 ## Struct `PerTypeConfigCreated`
 
+The event emitted when a new <code>Config</code> is created for a given type. This can be useful for
+tracking the <code>ID</code> of a type's <code>Config</code> object.
 
 
 <pre><code><b>struct</b> <a href="../sui-framework/deny_list.md#0x2_deny_list_PerTypeConfigCreated">PerTypeConfigCreated</a> <b>has</b> <b>copy</b>, drop, store

diff --git a/crates/sui-framework/packages/sui-framework/sources/coin.move b/crates/sui-framework/packages/sui-framework/sources/coin.move
@@ -77,6 +77,11 @@ module sui::coin {
         total_supply: Supply<T>
     }
 
+    /// Capability allowing the bearer to deny addresses from using the currency's coins--
+    /// immediately preventing those addresses from interacting with the coin as an input to a
+    /// transaction and at the start of the next preventing them from receiving the coin.
+    /// If `allow_global_pause` is true, the bearer can enable a global pause that behaves as if
+    /// all addresses were added to the deny list.
     public struct DenyCapV2<phantom T> has key, store {
         id: UID,
         allow_global_pause: bool,
@@ -236,6 +241,14 @@ module sui::coin {
         )
     }
 
+    /// This creates a new currency, via `create_currency`, but with an extra capability that
+    /// allows for specific addresses to have their coins frozen. When an address is added to the
+    /// deny list, it is immediately unable to interact with the currency's coin as input objects.
+    /// Additionally at the start of the next epoch, they will be unable to receive the currency's
+    /// coin.
+    /// The `allow_global_pause` flag enables an additional API that will cause all addresses to be
+    /// be denied. Note however, that this doesn't affect per-address entries of the deny list and
+    /// will not change the result of the "contains" APIs.
     public fun create_regulated_currency_v2<T: drop>(
         witness: T,
         decimals: u8,
@@ -267,6 +280,9 @@ module sui::coin {
         (treasury_cap, deny_cap, metadata)
     }
 
+    /// Given the `DenyCap` for a regulated currency, migrate it to the new `DenyCapV2` type.
+    /// All entries in the deny list will be migrated to the new format.
+    /// See `create_regulated_currency_v2` for details on the new v2 of the deny list.
     public fun migrate_regulated_currency_to_v2<T>(
         deny_list: &mut DenyList,
         cap: DenyCap<T>,
@@ -311,6 +327,9 @@ module sui::coin {
         cap.total_supply.decrease_supply(balance)
     }
 
+    /// Adds the given address to the deny list, preventing it from interacting with the specified
+    /// coin type as an input to a transaction. Additionally at the start of the next epoch, the
+    /// address will be unable to receive objects of this coin type.
     public fun deny_list_v2_add<T>(
         deny_list: &mut DenyList,
         _deny_cap: &mut DenyCapV2<T>,
@@ -321,6 +340,9 @@ module sui::coin {
         deny_list.v2_add(DENY_LIST_COIN_INDEX, ty, addr, ctx)
     }
 
+    /// Removes an address from the deny list. Similar to `deny_list_v2_add`, the effect for input
+    /// objects will be immediate, but the effect for receiving objects will be delayed until the
+    /// next epoch.
     public fun deny_list_v2_remove<T>(
         deny_list: &mut DenyList,
         _deny_cap: &mut DenyCapV2<T>,
@@ -331,6 +353,8 @@ module sui::coin {
         deny_list.v2_remove(DENY_LIST_COIN_INDEX, ty, addr, ctx)
     }
 
+    /// Check if the deny list contains the given address for the current epoch. Denied addresses
+    /// in the current epoch will be unable to receive objects of this coin type.
     public fun deny_list_v2_contains_current_epoch<T>(
         deny_list: &DenyList,
         addr: address,
@@ -340,6 +364,9 @@ module sui::coin {
         deny_list.v2_contains_current_epoch(DENY_LIST_COIN_INDEX, ty, addr, ctx)
     }
 
+    /// Check if the deny list contains the given address for the next epoch. Denied addresses in
+    /// the next epoch will immediately be unable to use objects of this coin type as inputs. At the
+    /// start of the next epoch, the address will be unable to receive objects of this coin type.
     public fun deny_list_v2_contains_next_epoch<T>(
         deny_list: &DenyList,
         addr: address,
@@ -348,6 +375,9 @@ module sui::coin {
         deny_list.v2_contains_next_epoch(DENY_LIST_COIN_INDEX, ty, addr)
     }
 
+    /// Enable the global pause for the given coin type. This will immediately prevent all addresses
+    /// from using objects of this coin type as inputs. At the start of the next epoch, all
+    /// addresses will be unable to receive objects of this coin type.
     #[allow(unused_mut_parameter)]
     public fun deny_list_v2_enable_global_pause<T>(
         deny_list: &mut DenyList,
@@ -359,6 +389,9 @@ module sui::coin {
         deny_list.v2_enable_global_pause(DENY_LIST_COIN_INDEX, ty, ctx)
     }
 
+    /// Disable the global pause for the given coin type. This will immediately allow all addresses
+    /// to resume using objects of this coin type as inputs. However, receiving objects of this coin
+    /// type will still be paused until the start of the next epoch.
     #[allow(unused_mut_parameter)]
     public fun deny_list_v2_disable_global_pause<T>(
         deny_list: &mut DenyList,
@@ -370,6 +403,7 @@ module sui::coin {
         deny_list.v2_disable_global_pause(DENY_LIST_COIN_INDEX, ty, ctx)
     }
 
+    /// Check if the global pause is enabled for the given coin type in the current epoch.
     public fun deny_list_v2_is_global_pause_enabled_current_epoch<T>(
         deny_list: &DenyList,
         ctx: &TxContext,
@@ -378,6 +412,7 @@ module sui::coin {
         deny_list.v2_is_global_pause_enabled_current_epoch(DENY_LIST_COIN_INDEX, ty, ctx)
     }
 
+    /// Check if the global pause is enabled for the given coin type in the next epoch.
     public fun deny_list_v2_is_global_pause_enabled_next_epoch<T>(
         deny_list: &DenyList,
     ): bool {

diff --git a/crates/sui-framework/packages/sui-framework/sources/deny_list.move b/crates/sui-framework/packages/sui-framework/sources/deny_list.move
@@ -55,17 +55,25 @@ module sui::deny_list {
 
     // === V2 ===
 
+    /// The capability used to write to the deny list config. Ensures that the Configs for the
+    /// DenyList are modified only by this module.
     public struct ConfigWriteCap() has drop;
 
+    /// The dynamic object field key used to store the `Config` for a given type, essentially a
+    /// `(per_type_index, per_type_key)` pair.
     public struct ConfigKey has copy, drop, store {
         per_type_index: u64,
         per_type_key: vector<u8>,
     }
 
+    /// The setting key used to store the deny list for a given address in the `Config`.
     public struct AddressKey(address) has copy, drop, store;
 
+    /// The setting key used to store the global pause setting in the `Config`.
     public struct GlobalPauseKey() has copy, drop, store;
 
+    /// The event emitted when a new `Config` is created for a given type. This can be useful for
+    /// tracking the `ID` of a type's `Config` object.
     public struct PerTypeConfigCreated has copy, drop, store {
         key: ConfigKey,
         config_id: ID,