Module `sui::coin_registry`

Defines the system object for managing coin data in a central registry. This module provides a centralized way to store and manage metadata for all currencies in the Sui ecosystem, including their supply information, regulatory status, and metadata capabilities.

Struct CoinRegistry
Struct ExtraField
Struct CurrencyKey
Struct LegacyMetadataKey
Struct MetadataCap
Struct Borrow
Struct Currency
Struct CurrencyInitializer
Enum SupplyState
Enum RegulatedState
Enum MetadataCapState
Constants
Function new_currency
Function new_currency_with_otw
Function claim_metadata_cap
Function make_regulated
Function make_supply_fixed_init
Function make_supply_burn_only_init
Function make_supply_fixed
Function make_supply_burn_only
Function finalize
Function finalize_and_delete_metadata_cap
Function finalize_registration
Function delete_metadata_cap
Function burn
Function burn_balance
Function set_name
Function set_description
Function set_icon_url
Function set_treasury_cap_id
Function migrate_legacy_metadata
Function update_from_legacy_metadata
Function delete_migrated_legacy_metadata
Function migrate_regulated_state_by_metadata
Function migrate_regulated_state_by_cap
Function borrow_legacy_metadata
Function return_borrowed_legacy_metadata
Function decimals
Function name
Function symbol
Function description
Function icon_url
Function is_metadata_cap_claimed
Function is_metadata_cap_deleted
Function metadata_cap_id
Function treasury_cap_id
Function deny_cap_id
Function is_supply_fixed
Function is_supply_burn_only
Function is_regulated
Function total_supply
Function exists
Function is_migrated_from_legacy
Function to_legacy_metadata
Function create
Macro function finalize_impl
Macro function migrate_legacy_metadata_impl
Macro function is_ascii_printable

<pre><code>use <a href="../std/address.md#std_address">std::address</a>; use <a href="../std/ascii.md#std_ascii">std::ascii</a>; use <a href="../std/bcs.md#std_bcs">std::bcs</a>; use <a href="../std/internal.md#std_internal">std::internal</a>; use <a href="../std/option.md#std_option">std::option</a>; use <a href="../std/string.md#std_string">std::string</a>; use <a href="../std/type_name.md#std_type_name">std::type_name</a>; use <a href="../std/u128.md#std_u128">std::u128</a>; use <a href="../std/vector.md#std_vector">std::vector</a>; use <a href="../sui/accumulator.md#sui_accumulator">sui::accumulator</a>; use <a href="../sui/accumulator_settlement.md#sui_accumulator_settlement">sui::accumulator_settlement</a>; use <a href="../sui/address.md#sui_address">sui::address</a>; use <a href="../sui/bag.md#sui_bag">sui::bag</a>; use <a href="../sui/balance.md#sui_balance">sui::balance</a>; use <a href="../sui/bcs.md#sui_bcs">sui::bcs</a>; use <a href="../sui/coin.md#sui_coin">sui::coin</a>; use <a href="../sui/config.md#sui_config">sui::config</a>; use <a href="../sui/deny_list.md#sui_deny_list">sui::deny_list</a>; use <a href="../sui/derived_object.md#sui_derived_object">sui::derived_object</a>; use <a href="../sui/dynamic_field.md#sui_dynamic_field">sui::dynamic_field</a>; use <a href="../sui/dynamic_object_field.md#sui_dynamic_object_field">sui::dynamic_object_field</a>; use <a href="../sui/event.md#sui_event">sui::event</a>; use <a href="../sui/funds_accumulator.md#sui_funds_accumulator">sui::funds_accumulator</a>; use <a href="../sui/hash.md#sui_hash">sui::hash</a>; use <a href="../sui/hex.md#sui_hex">sui::hex</a>; use <a href="../sui/object.md#sui_object">sui::object</a>; use <a href="../sui/party.md#sui_party">sui::party</a>; use <a href="../sui/protocol_config.md#sui_protocol_config">sui::protocol_config</a>; use <a href="../sui/table.md#sui_table">sui::table</a>; use <a href="../sui/transfer.md#sui_transfer">sui::transfer</a>; use <a href="../sui/tx_context.md#sui_tx_context">sui::tx_context</a>; use <a href="../sui/types.md#sui_types">sui::types</a>; use <a href="../sui/url.md#sui_url">sui::url</a>; use <a href="../sui/vec_map.md#sui_vec_map">sui::vec_map</a>; use <a href="../sui/vec_set.md#sui_vec_set">sui::vec_set</a>; </code></pre>

Struct `CoinRegistry`

System object found at address <code>0xc</code> that stores coin data for all registered coin types. This is a shared object that acts as a central registry for coin metadata, supply information, and regulatory status.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a> has key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>id: <a href="../sui/object.md#sui_object_UID">sui::object::UID</a></code> </dt> <dd> </dd> </dl> </details>

Struct `ExtraField`

Store only object that enables more flexible coin data registration, allowing for additional fields to be added without changing the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> structure.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_ExtraField">ExtraField</a> has store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>0: <a href="../std/type_name.md#std_type_name_TypeName">std::type_name::TypeName</a></code> </dt> <dd> </dd> <dt> <code>1: vector<u8></code> </dt> <dd> </dd> </dl> </details>

Struct `CurrencyKey`

Key used to derive addresses when creating <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T></code> objects.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyKey">CurrencyKey</a><phantom T> has copy, drop, store </code></pre> <details> <summary>Fields</summary> <dl> </dl> </details>

Struct `LegacyMetadataKey`

Key used to store the legacy <code>CoinMetadata</code> for a <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a> has copy, drop, store </code></pre> <details> <summary>Fields</summary> <dl> </dl> </details>

Struct `MetadataCap`

Capability object that gates metadata (name, description, icon_url, symbol) changes in the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>. It can only be created (or claimed) once, and can be deleted to prevent changes to the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> metadata.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><phantom T> has key, store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>id: <a href="../sui/object.md#sui_object_UID">sui::object::UID</a></code> </dt> <dd> </dd> </dl> </details>

Struct `Borrow`

Potato callback for the legacy <code>CoinMetadata</code> borrowing.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a><phantom T> </code></pre> <details> <summary>Fields</summary> <dl> </dl> </details>

Struct `Currency`

Currency stores metadata such as name, symbol, decimals, icon_url and description, as well as supply states (optional) and regulatory status.

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><phantom T> has key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>id: <a href="../sui/object.md#sui_object_UID">sui::object::UID</a></code> </dt> <dd> </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: u8</code> </dt> <dd> Number of decimal places the coin uses for display purposes. </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: <a href="../std/string.md#std_string_String">std::string::String</a></code> </dt> <dd> Human-readable name for the coin. </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: <a href="../std/string.md#std_string_String">std::string::String</a></code> </dt> <dd> Short symbol/ticker for the coin. </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: <a href="../std/string.md#std_string_String">std::string::String</a></code> </dt> <dd> Detailed description of the coin. </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: <a href="../std/string.md#std_string_String">std::string::String</a></code> </dt> <dd> URL for the coin's icon/logo. </dd> <dt> <code>supply: <a href="../std/option.md#std_option_Option">std::option::Option</a><<a href="../sui/coin_registry.md#sui_coin_registry_SupplyState">sui::coin_registry::SupplyState</a><T>></code> </dt> <dd> Current supply state of the coin (fixed supply or unknown) Note: We're using <code>Option</code> because <code><a href="../sui/coin_registry.md#sui_coin_registry_SupplyState">SupplyState</a></code> does not have drop, meaning we cannot swap out its value at a later state. </dd> <dt> <code>regulated: <a href="../sui/coin_registry.md#sui_coin_registry_RegulatedState">sui::coin_registry::RegulatedState</a></code> </dt> <dd> Regulatory status of the coin (regulated with deny cap or unknown) </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>: <a href="../std/option.md#std_option_Option">std::option::Option</a><<a href="../sui/object.md#sui_object_ID">sui::object::ID</a>></code> </dt> <dd> ID of the treasury cap for this coin type, if registered. </dd> <dt> <code><a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>: <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCapState">sui::coin_registry::MetadataCapState</a></code> </dt> <dd> ID of the metadata capability for this coin type, if claimed. </dd> <dt> <code>extra_fields: <a href="../sui/vec_map.md#sui_vec_map_VecMap">sui::vec_map::VecMap</a><<a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_ExtraField">sui::coin_registry::ExtraField</a>></code> </dt> <dd> Additional fields for extensibility. </dd> </dl> </details>

Struct `CurrencyInitializer`

Hot potato wrapper to enforce registration after "new_currency" data creation. Destroyed in the <code><a href="../sui/coin_registry.md#sui_coin_registry_finalize">finalize</a></code> call and either transferred to the <code><a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a></code> (in case of an OTW registration) or shared directly (for dynamically created currencies).

<pre><code>public struct <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><phantom T> </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>currency: <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T></code> </dt> <dd> </dd> <dt> <code>extra_fields: <a href="../sui/bag.md#sui_bag_Bag">sui::bag::Bag</a></code> </dt> <dd> </dd> <dt> <code>is_otw: bool</code> </dt> <dd> </dd> </dl> </details>

Enum `SupplyState`

Supply state marks the type of Currency Supply, which can be

Fixed: no minting or burning;
BurnOnly: no minting, burning is allowed;
Unknown: flexible (supply is controlled by its <code>TreasuryCap</code>);

<pre><code>public enum <a href="../sui/coin_registry.md#sui_coin_registry_SupplyState">SupplyState</a><phantom T> has store </code></pre> <details> <summary>Variants</summary> <dl> <dt> Variant <code>Fixed</code> </dt> <dd> Coin has a fixed supply with the given Supply object. </dd> <dl> <dt> <code>0: <a href="../sui/balance.md#sui_balance_Supply">sui::balance::Supply</a><T></code> </dt> <dd> </dd> </dl> <dt> Variant <code>BurnOnly</code> </dt> <dd> Coin has a supply that can ONLY decrease. </dd> <dl> <dt> <code>0: <a href="../sui/balance.md#sui_balance_Supply">sui::balance::Supply</a><T></code> </dt> <dd> </dd> </dl> <dt> Variant <code>Unknown</code> </dt> <dd> Supply information is not yet known or registered. </dd> </dl> </details>

Enum `RegulatedState`

Regulated state of a coin type.

Regulated: <code>DenyCap</code> exists or a <code>RegulatedCoinMetadata</code> used to mark currency as regulated;
Unregulated: the currency was created without deny list;
Unknown: the regulatory status is unknown.

<pre><code>public enum <a href="../sui/coin_registry.md#sui_coin_registry_RegulatedState">RegulatedState</a> has copy, drop, store </code></pre> <details> <summary>Variants</summary> <dl> <dt> Variant <code>Regulated</code> </dt> <dd> Coin is regulated with a deny cap for address restrictions. <code>allow_global_pause</code> is <code>None</code> if the information is unknown (has not been migrated from <code>DenyCapV2</code>). </dd> <dl> <dt> <code>cap: <a href="../sui/object.md#sui_object_ID">sui::object::ID</a></code> </dt> <dd> </dd> </dl> <dl> <dt> <code>allow_global_pause: <a href="../std/option.md#std_option_Option">std::option::Option</a><bool></code> </dt> <dd> </dd> </dl> <dl> <dt> <code>variant: u8</code> </dt> <dd> </dd> </dl> <dt> Variant <code>Unregulated</code> </dt> <dd> The coin has been created without deny list. </dd> <dt> Variant <code>Unknown</code> </dt> <dd> Regulatory status is unknown. Result of a legacy migration for that coin (from <code><a href="../sui/coin.md#sui_coin">coin</a>.move</code> constructors) </dd> </dl> </details>

Enum `MetadataCapState`

State of the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> for a single <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public enum <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCapState">MetadataCapState</a> has copy, drop, store </code></pre> <details> <summary>Variants</summary> <dl> <dt> Variant <code>Claimed</code> </dt> <dd> The metadata cap has been claimed. </dd> <dl> <dt> <code>0: <a href="../sui/object.md#sui_object_ID">sui::object::ID</a></code> </dt> <dd> </dd> </dl> <dt> Variant <code>Unclaimed</code> </dt> <dd> The metadata cap has not been claimed. </dd> <dt> Variant <code>Deleted</code> </dt> <dd> The metadata cap has been claimed and then deleted. </dd> </dl> </details>

Constants

Metadata cap already claimed

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EMetadataCapAlreadyClaimed">EMetadataCapAlreadyClaimed</a>: vector<u8> = b"Metadata cap already claimed"; </code></pre>

Only the system address can create the registry

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ENotSystemAddress">ENotSystemAddress</a>: vector<u8> = b"Only the system can <a href="../sui/coin_registry.md#sui_coin_registry_create">create</a> the registry."; </code></pre>

Currency for this coin type already exists

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ECurrencyAlreadyExists">ECurrencyAlreadyExists</a>: vector<u8> = b"<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a> for this <a href="../sui/coin.md#sui_coin">coin</a> type already <a href="../sui/coin_registry.md#sui_coin_registry_exists">exists</a>."; </code></pre>

Attempt to set the deny list state permissionlessly while it has already been set.

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EDenyListStateAlreadySet">EDenyListStateAlreadySet</a>: vector<u8> = b"Cannot set the deny list state as it has already been set."; </code></pre>

Attempt to update <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> with legacy metadata after the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> has been claimed. Updates are only allowed if the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> has not yet been claimed or deleted.

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ECannotUpdateManagedMetadata">ECannotUpdateManagedMetadata</a>: vector<u8> = b"Cannot update metadata whose `<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a>` has already been claimed"; </code></pre>

Attempt to set the symbol to a non-ASCII printable character

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EInvalidSymbol">EInvalidSymbol</a>: vector<u8> = b"Symbol has to be ASCII printable"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EDenyCapAlreadyCreated">EDenyCapAlreadyCreated</a>: vector<u8> = b"Cannot claim the deny cap twice"; </code></pre>

Attempt to migrate legacy metadata for a <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> that already exists.

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ECurrencyAlreadyRegistered">ECurrencyAlreadyRegistered</a>: vector<u8> = b"<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a> already registered"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EEmptySupply">EEmptySupply</a>: vector<u8> = b"Supply cannot be empty"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ESupplyNotBurnOnly">ESupplyNotBurnOnly</a>: vector<u8> = b"Cannot <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a> on a non <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a>-only supply"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EInvariantViolation">EInvariantViolation</a>: vector<u8> = b"Code invariant violation"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EDeletionNotSupported">EDeletionNotSupported</a>: vector<u8> = b"Deleting legacy metadata is not supported"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_ENotOneTimeWitness">ENotOneTimeWitness</a>: vector<u8> = b"Type is expected to be OTW"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EBorrowLegacyMetadata">EBorrowLegacyMetadata</a>: vector<u8> = b"Cannot <a href="../sui/borrow.md#sui_borrow">borrow</a> legacy metadata for migrated currency"; </code></pre>

<pre><code>#[error] const <a href="../sui/coin_registry.md#sui_coin_registry_EDuplicateBorrow">EDuplicateBorrow</a>: vector<u8> = b"Attempt to return duplicate borrowed CoinMetadata"; </code></pre>

Incremental identifier for regulated coin versions in the deny list. We start from <code>0</code> in the new system, which aligns with the state of <code>DenyCapV2</code>.

<pre><code>const <a href="../sui/coin_registry.md#sui_coin_registry_REGULATED_COIN_VERSION">REGULATED_COIN_VERSION</a>: u8 = 0; </code></pre>

Marker used in metadata to indicate that the currency is not migrated.

<pre><code>const <a href="../sui/coin_registry.md#sui_coin_registry_NEW_CURRENCY_MARKER">NEW_CURRENCY_MARKER</a>: vector<u8> = vector[105, 115, 95, 110, 101, 119, 95, 99, 117, 114, 114, 101, 110, 99, 121]; </code></pre>

Function `new_currency`

Creates a new currency.

Note: This constructor has no long term difference from <code><a href="../sui/coin_registry.md#sui_coin_registry_new_currency_with_otw">new_currency_with_otw</a></code>. This can be called from the module that defines <code>T</code> any time after it has been published.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_new_currency">new_currency</a><T: key>(registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">sui::coin_registry::CoinRegistry</a>, <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: u8, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_new_currency">new_currency</a><T: /* internal */ key>( registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>, <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: u8, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: String, ctx: &mut TxContext, ): (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, TreasuryCap<T>) { assert!(!registry.<a href="../sui/coin_registry.md#sui_coin_registry_exists">exists</a><T>(), <a href="../sui/coin_registry.md#sui_coin_registry_ECurrencyAlreadyExists">ECurrencyAlreadyExists</a>); assert!(<a href="../sui/coin_registry.md#sui_coin_registry_is_ascii_printable">is_ascii_printable</a>!(&<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>), <a href="../sui/coin_registry.md#sui_coin_registry_EInvalidSymbol">EInvalidSymbol</a>); let treasury_cap = <a href="../sui/coin.md#sui_coin_new_treasury_cap">coin::new_treasury_cap</a>(ctx); let currency = <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T> { id: <a href="../sui/derived_object.md#sui_derived_object_claim">derived_object::claim</a>(&mut registry.id, <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyKey">CurrencyKey</a><T>()), <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>, supply: option::some(SupplyState::Unknown), regulated: RegulatedState::Unregulated, <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>: option::some(<a href="../sui/object.md#sui_object_id">object::id</a>(&treasury_cap)), <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>: MetadataCapState::Unclaimed, extra_fields: <a href="../sui/vec_map.md#sui_vec_map_empty">vec_map::empty</a>(), }; (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a> { currency, is_otw: false, extra_fields: <a href="../sui/bag.md#sui_bag_new">bag::new</a>(ctx) }, treasury_cap) } </code></pre> </details>

Function `new_currency_with_otw`

Creates a new currency with using an OTW as proof of uniqueness.

This is a two-step operation:

<code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> is constructed in the <code>init</code> function and sent to the <code><a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a></code>;
<code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> is promoted to a shared object in the <code><a href="../sui/coin_registry.md#sui_coin_registry_finalize_registration">finalize_registration</a></code> call;

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_new_currency_with_otw">new_currency_with_otw</a><T: drop>(otw: T, <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: u8, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: <a href="../std/string.md#std_string_String">std::string::String</a>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_new_currency_with_otw">new_currency_with_otw</a><T: drop>( otw: T, <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: u8, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: String, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: String, ctx: &mut TxContext, ): (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, TreasuryCap<T>) { assert!(<a href="../sui/types.md#sui_types_is_one_time_witness">sui::types::is_one_time_witness</a>(&otw), <a href="../sui/coin_registry.md#sui_coin_registry_ENotOneTimeWitness">ENotOneTimeWitness</a>); assert!(<a href="../sui/coin_registry.md#sui_coin_registry_is_ascii_printable">is_ascii_printable</a>!(&<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>), <a href="../sui/coin_registry.md#sui_coin_registry_EInvalidSymbol">EInvalidSymbol</a>); let treasury_cap = <a href="../sui/coin.md#sui_coin_new_treasury_cap">coin::new_treasury_cap</a>(ctx); let currency = <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T> { id: <a href="../sui/object.md#sui_object_new">object::new</a>(ctx), <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>, supply: option::some(SupplyState::Unknown), regulated: RegulatedState::Unregulated, <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>: option::some(<a href="../sui/object.md#sui_object_id">object::id</a>(&treasury_cap)), <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>: MetadataCapState::Unclaimed, extra_fields: <a href="../sui/vec_map.md#sui_vec_map_empty">vec_map::empty</a>(), }; (<a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a> { currency, is_otw: true, extra_fields: <a href="../sui/bag.md#sui_bag_new">bag::new</a>(ctx) }, treasury_cap) } </code></pre> </details>

Function `claim_metadata_cap`

Claim a <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> for a coin type. Only allowed from the owner of <code>TreasuryCap</code>, and only once.

Aborts if the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> has already been claimed. Deleted <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> cannot be reclaimed.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_claim_metadata_cap">claim_metadata_cap</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, _: &<a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_claim_metadata_cap">claim_metadata_cap</a><T>( currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, _: &TreasuryCap<T>, ctx: &mut TxContext, ): <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T> { assert!(!currency.<a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_claimed">is_metadata_cap_claimed</a>(), <a href="../sui/coin_registry.md#sui_coin_registry_EMetadataCapAlreadyClaimed">EMetadataCapAlreadyClaimed</a>); let id = <a href="../sui/object.md#sui_object_new">object::new</a>(ctx); currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a> = MetadataCapState::Claimed(id.to_inner()); <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a> { id } } </code></pre> </details>

Function `make_regulated`

Allows converting a currency, on init, to regulated, which creates a <code>DenyCapV2</code> object, and a denylist entry. Sets regulated state to <code>Regulated</code>.

This action is irreversible.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_regulated">make_regulated</a><T>(init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, allow_global_pause: bool, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): <a href="../sui/coin.md#sui_coin_DenyCapV2">sui::coin::DenyCapV2</a><T> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_regulated">make_regulated</a><T>( init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, allow_global_pause: bool, ctx: &mut TxContext, ): DenyCapV2<T> { assert!(init.currency.regulated == RegulatedState::Unregulated, <a href="../sui/coin_registry.md#sui_coin_registry_EDenyCapAlreadyCreated">EDenyCapAlreadyCreated</a>); let deny_cap = <a href="../sui/coin.md#sui_coin_new_deny_cap_v2">coin::new_deny_cap_v2</a><T>(allow_global_pause, ctx); init.currency.regulated = RegulatedState::Regulated { cap: <a href="../sui/object.md#sui_object_id">object::id</a>(&deny_cap), allow_global_pause: option::some(allow_global_pause), variant: <a href="../sui/coin_registry.md#sui_coin_registry_REGULATED_COIN_VERSION">REGULATED_COIN_VERSION</a>, }; deny_cap } </code></pre> </details>

Function `make_supply_fixed_init`

Initializer function to make the supply fixed. Aborts if Supply is <code>0</code> to enforce minting during initialization.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_fixed_init">make_supply_fixed_init</a><T>(init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, cap: <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_fixed_init">make_supply_fixed_init</a><T>(init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, cap: TreasuryCap<T>) { assert!(cap.<a href="../sui/coin_registry.md#sui_coin_registry_total_supply">total_supply</a>() > 0, <a href="../sui/coin_registry.md#sui_coin_registry_EEmptySupply">EEmptySupply</a>); init.currency.<a href="../sui/coin_registry.md#sui_coin_registry_make_supply_fixed">make_supply_fixed</a>(cap) } </code></pre> </details>

Function `make_supply_burn_only_init`

Initializer function to make the supply burn-only. Aborts if Supply is <code>0</code> to enforce minting during initialization.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_burn_only_init">make_supply_burn_only_init</a><T>(init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, cap: <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_burn_only_init">make_supply_burn_only_init</a><T>(init: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, cap: TreasuryCap<T>) { assert!(cap.<a href="../sui/coin_registry.md#sui_coin_registry_total_supply">total_supply</a>() > 0, <a href="../sui/coin_registry.md#sui_coin_registry_EEmptySupply">EEmptySupply</a>); init.currency.<a href="../sui/coin_registry.md#sui_coin_registry_make_supply_burn_only">make_supply_burn_only</a>(cap) } </code></pre> </details>

Function `make_supply_fixed`

Freeze the supply by destroying the <code>TreasuryCap</code> and storing it in the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_fixed">make_supply_fixed</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, cap: <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_fixed">make_supply_fixed</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, cap: TreasuryCap<T>) { match (currency.supply.swap(SupplyState::Fixed(cap.into_supply()))) { // Impossible: We cannot fix a supply or make a supply <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a>-only twice. SupplyState::Fixed(_supply) | SupplyState::BurnOnly(_supply) => abort <a href="../sui/coin_registry.md#sui_coin_registry_EInvariantViolation">EInvariantViolation</a>, // We replaced "unknown" with fixed supply. SupplyState::Unknown => (), }; } </code></pre> </details>

Function `make_supply_burn_only`

Make the supply <code>BurnOnly</code> by giving up the <code>TreasuryCap</code>, and allowing burning of Coins through the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_burn_only">make_supply_burn_only</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, cap: <a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_make_supply_burn_only">make_supply_burn_only</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, cap: TreasuryCap<T>) { match (currency.supply.swap(SupplyState::BurnOnly(cap.into_supply()))) { // Impossible: We cannot fix a supply or make a supply <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a>-only twice. SupplyState::Fixed(_supply) | SupplyState::BurnOnly(_supply) => abort <a href="../sui/coin_registry.md#sui_coin_registry_EInvariantViolation">EInvariantViolation</a>, // We replaced "unknown" with frozen supply. SupplyState::Unknown => (), }; } </code></pre> </details>

Function `finalize`

Finalize the coin initialization, returning <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code>

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize">finalize</a><T>(builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize">finalize</a><T>(builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, ctx: &mut TxContext): <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T> { let is_otw = builder.is_otw; let (currency, metadata_cap) = <a href="../sui/coin_registry.md#sui_coin_registry_finalize_impl">finalize_impl</a>!(builder, ctx); // Either share directly (`<a href="../sui/coin_registry.md#sui_coin_registry_new_currency">new_currency</a>` scenario), or <a href="../sui/transfer.md#sui_transfer">transfer</a> as TTO to `<a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>`. if (is_otw) <a href="../sui/transfer.md#sui_transfer_transfer">transfer::transfer</a>(currency, <a href="../sui/object.md#sui_object_sui_coin_registry_address">object::sui_coin_registry_address</a>()) else <a href="../sui/transfer.md#sui_transfer_share_object">transfer::share_object</a>(currency); metadata_cap } </code></pre> </details>

Function `finalize_and_delete_metadata_cap`

Does the same as <code><a href="../sui/coin_registry.md#sui_coin_registry_finalize">finalize</a></code>, but also deletes the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> after finalization.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_and_delete_metadata_cap">finalize_and_delete_metadata_cap</a><T>(builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><T>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_and_delete_metadata_cap">finalize_and_delete_metadata_cap</a><T>( builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><T>, ctx: &mut TxContext, ) { let is_otw = builder.is_otw; let (mut currency, metadata_cap) = <a href="../sui/coin_registry.md#sui_coin_registry_finalize_impl">finalize_impl</a>!(builder, ctx); currency.<a href="../sui/coin_registry.md#sui_coin_registry_delete_metadata_cap">delete_metadata_cap</a>(metadata_cap); // Either share directly (`<a href="../sui/coin_registry.md#sui_coin_registry_new_currency">new_currency</a>` scenario), or <a href="../sui/transfer.md#sui_transfer">transfer</a> as TTO to `<a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>`. if (is_otw) <a href="../sui/transfer.md#sui_transfer_transfer">transfer::transfer</a>(currency, <a href="../sui/object.md#sui_object_sui_coin_registry_address">object::sui_coin_registry_address</a>()) else <a href="../sui/transfer.md#sui_transfer_share_object">transfer::share_object</a>(currency); } </code></pre> </details>

Function `finalize_registration`

The second step in the "otw" initialization of coin metadata, that takes in the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T></code> that was transferred from init, and transforms it in to a "derived address" shared object.

Can be performed by anyone.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_registration">finalize_registration</a><T>(registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">sui::coin_registry::CoinRegistry</a>, currency: <a href="../sui/transfer.md#sui_transfer_Receiving">sui::transfer::Receiving</a><<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>>, _ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_registration">finalize_registration</a><T>( registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>, currency: Receiving<<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>>, _ctx: &mut TxContext, ) { // 1. Consume <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a> // 2. Re-<a href="../sui/coin_registry.md#sui_coin_registry_create">create</a> it with a "derived" address. let <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a> { id, <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>, supply, regulated, <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>, <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>, extra_fields, } = <a href="../sui/transfer.md#sui_transfer_receive">transfer::receive</a>(&mut registry.id, currency); id.delete(); // Now, <a href="../sui/coin_registry.md#sui_coin_registry_create">create</a> the derived version of the <a href="../sui/coin.md#sui_coin">coin</a> currency. <a href="../sui/transfer.md#sui_transfer_share_object">transfer::share_object</a>(<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a> { id: <a href="../sui/derived_object.md#sui_derived_object_claim">derived_object::claim</a>(&mut registry.id, <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyKey">CurrencyKey</a><T>()), <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>, supply, regulated, <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>, <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>, extra_fields, }) } </code></pre> </details>

Function `delete_metadata_cap`

Delete the metadata cap making further updates of <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> metadata impossible. This action is IRREVERSIBLE, and the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> can no longer be claimed.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_delete_metadata_cap">delete_metadata_cap</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, cap: <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_delete_metadata_cap">delete_metadata_cap</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, cap: <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T>) { let <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a> { id } = cap; currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a> = MetadataCapState::Deleted; id.delete(); } </code></pre> </details>

Function `burn`

Burn the <code>Coin</code> if the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> has a <code>BurnOnly</code> supply state.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, <a href="../sui/coin.md#sui_coin">coin</a>: <a href="../sui/coin.md#sui_coin_Coin">sui::coin::Coin</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_burn">burn</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, <a href="../sui/coin.md#sui_coin">coin</a>: Coin<T>) { currency.<a href="../sui/coin_registry.md#sui_coin_registry_burn_balance">burn_balance</a>(<a href="../sui/coin.md#sui_coin">coin</a>.into_balance()); } </code></pre> </details>

Function `burn_balance`

Burn the <code>Balance</code> if the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> has a <code>BurnOnly</code> supply state.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_burn_balance">burn_balance</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, <a href="../sui/balance.md#sui_balance">balance</a>: <a href="../sui/balance.md#sui_balance_Balance">sui::balance::Balance</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_burn_balance">burn_balance</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, <a href="../sui/balance.md#sui_balance">balance</a>: Balance<T>) { assert!(currency.<a href="../sui/coin_registry.md#sui_coin_registry_is_supply_burn_only">is_supply_burn_only</a>(), <a href="../sui/coin_registry.md#sui_coin_registry_ESupplyNotBurnOnly">ESupplyNotBurnOnly</a>); match (currency.supply.borrow_mut()) { SupplyState::BurnOnly(supply) => { supply.decrease_supply(<a href="../sui/balance.md#sui_balance">balance</a>); }, _ => abort <a href="../sui/coin_registry.md#sui_coin_registry_EInvariantViolation">EInvariantViolation</a>, // unreachable } } </code></pre> </details>

Function `set_name`

Update the name of the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_name">set_name</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: <a href="../std/string.md#std_string_String">std::string::String</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_name">set_name</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: String) { currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a> = <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>; } </code></pre> </details>

Function `set_description`

Update the description of the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_description">set_description</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: <a href="../std/string.md#std_string_String">std::string::String</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_description">set_description</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: String) { currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a> = <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>; } </code></pre> </details>

Function `set_icon_url`

Update the icon URL of the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_icon_url">set_icon_url</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: <a href="../std/string.md#std_string_String">std::string::String</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_icon_url">set_icon_url</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, _: &<a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: String) { currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a> = <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>; } </code></pre> </details>

Function `set_treasury_cap_id`

Register the treasury cap ID for a migrated <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>. All currencies created with <code><a href="../sui/coin_registry.md#sui_coin_registry_new_currency">new_currency</a></code> or <code><a href="../sui/coin_registry.md#sui_coin_registry_new_currency_with_otw">new_currency_with_otw</a></code> have their treasury cap ID set during initialization.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_treasury_cap_id">set_treasury_cap_id</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, cap: &<a href="../sui/coin.md#sui_coin_TreasuryCap">sui::coin::TreasuryCap</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_set_treasury_cap_id">set_treasury_cap_id</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, cap: &TreasuryCap<T>) { currency.<a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>.fill(<a href="../sui/object.md#sui_object_id">object::id</a>(cap)); } </code></pre> </details>

Function `migrate_legacy_metadata`

Register <code>CoinMetadata</code> in the <code><a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a></code>. This can happen only once, if the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> did not exist yet. Further updates are possible through <code><a href="../sui/coin_registry.md#sui_coin_registry_update_from_legacy_metadata">update_from_legacy_metadata</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_legacy_metadata">migrate_legacy_metadata</a><T>(registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">sui::coin_registry::CoinRegistry</a>, legacy: &<a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T>, _ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_legacy_metadata">migrate_legacy_metadata</a><T>( registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>, legacy: &CoinMetadata<T>, _ctx: &mut TxContext, ) { let currency = <a href="../sui/coin_registry.md#sui_coin_registry_migrate_legacy_metadata_impl">migrate_legacy_metadata_impl</a>!(registry, legacy); <a href="../sui/transfer.md#sui_transfer_share_object">transfer::share_object</a>(currency); } </code></pre> </details>

Function `update_from_legacy_metadata`

Update <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> from <code>CoinMetadata</code> if the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> is not claimed. After the <code><a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a></code> is claimed, updates can only be made through <code>set_*</code> functions.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_update_from_legacy_metadata">update_from_legacy_metadata</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, legacy: &<a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_update_from_legacy_metadata">update_from_legacy_metadata</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, legacy: &CoinMetadata<T>) { assert!(!currency.<a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_claimed">is_metadata_cap_claimed</a>(), <a href="../sui/coin_registry.md#sui_coin_registry_ECannotUpdateManagedMetadata">ECannotUpdateManagedMetadata</a>); currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a> = legacy.get_name(); currency.<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a> = legacy.get_symbol().to_string(); currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a> = legacy.get_description(); currency.<a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a> = legacy.get_decimals(); currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a> = legacy.get_icon_url().map!(|<a href="../sui/url.md#sui_url">url</a>| <a href="../sui/url.md#sui_url">url</a>.inner_url().to_string()).destroy_or!(b"".to_string()); } </code></pre> </details>

Function `delete_migrated_legacy_metadata`

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_delete_migrated_legacy_metadata">delete_migrated_legacy_metadata</a><T>(_: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, _: <a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_delete_migrated_legacy_metadata">delete_migrated_legacy_metadata</a><T>(_: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, _: CoinMetadata<T>) { abort <a href="../sui/coin_registry.md#sui_coin_registry_EDeletionNotSupported">EDeletionNotSupported</a> } </code></pre> </details>

Function `migrate_regulated_state_by_metadata`

Allow migrating the regulated state by access to <code>RegulatedCoinMetadata</code> frozen object. This is a permissionless operation which can be performed only once.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_regulated_state_by_metadata">migrate_regulated_state_by_metadata</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, metadata: &<a href="../sui/coin.md#sui_coin_RegulatedCoinMetadata">sui::coin::RegulatedCoinMetadata</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_regulated_state_by_metadata">migrate_regulated_state_by_metadata</a><T>( currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, metadata: &RegulatedCoinMetadata<T>, ) { // Only allow if this hasn't been migrated before. assert!(currency.regulated == RegulatedState::Unknown, <a href="../sui/coin_registry.md#sui_coin_registry_EDenyListStateAlreadySet">EDenyListStateAlreadySet</a>); currency.regulated = RegulatedState::Regulated { cap: metadata.<a href="../sui/coin_registry.md#sui_coin_registry_deny_cap_id">deny_cap_id</a>(), allow_global_pause: option::none(), variant: <a href="../sui/coin_registry.md#sui_coin_registry_REGULATED_COIN_VERSION">REGULATED_COIN_VERSION</a>, }; } </code></pre> </details>

Function `migrate_regulated_state_by_cap`

Mark regulated state by showing the <code>DenyCapV2</code> object for the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_regulated_state_by_cap">migrate_regulated_state_by_cap</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, cap: &<a href="../sui/coin.md#sui_coin_DenyCapV2">sui::coin::DenyCapV2</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_regulated_state_by_cap">migrate_regulated_state_by_cap</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, cap: &DenyCapV2<T>) { currency.regulated = RegulatedState::Regulated { cap: <a href="../sui/object.md#sui_object_id">object::id</a>(cap), allow_global_pause: option::some(cap.allow_global_pause()), variant: <a href="../sui/coin_registry.md#sui_coin_registry_REGULATED_COIN_VERSION">REGULATED_COIN_VERSION</a>, }; } </code></pre> </details>

Function `borrow_legacy_metadata`

Borrow the legacy <code>CoinMetadata</code> from a new <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>. To preserve the <code>ID</code> of the legacy <code>CoinMetadata</code>, we create it on request and then store it as a dynamic field for future borrows.

<code><a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a><T></code> ensures that the <code>CoinMetadata</code> is returned in the same transaction.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_borrow_legacy_metadata">borrow_legacy_metadata</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): (<a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T>, <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">sui::coin_registry::Borrow</a><T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_borrow_legacy_metadata">borrow_legacy_metadata</a><T>( currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, ctx: &mut TxContext, ): (CoinMetadata<T>, <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a><T>) { assert!(!currency.<a href="../sui/coin_registry.md#sui_coin_registry_is_migrated_from_legacy">is_migrated_from_legacy</a>(), <a href="../sui/coin_registry.md#sui_coin_registry_EBorrowLegacyMetadata">EBorrowLegacyMetadata</a>); if (!df::exists_(&currency.id, <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a>())) { let legacy = currency.<a href="../sui/coin_registry.md#sui_coin_registry_to_legacy_metadata">to_legacy_metadata</a>(ctx); df::add(&mut currency.id, <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a>(), legacy); }; let mut legacy: CoinMetadata<T> = df::remove(&mut currency.id, <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a>()); legacy.update_coin_metadata( currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>.to_ascii(), currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>.to_ascii(), ); (legacy, <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a> {}) } </code></pre> </details>

Function `return_borrowed_legacy_metadata`

Return the borrowed <code>CoinMetadata</code> and the <code><a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a></code> potato to the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

Note to self: Borrow requirement prevents deletion through this method.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_return_borrowed_legacy_metadata">return_borrowed_legacy_metadata</a><T>(currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, legacy: <a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T>, <a href="../sui/borrow.md#sui_borrow">borrow</a>: <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">sui::coin_registry::Borrow</a><T>, _ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_return_borrowed_legacy_metadata">return_borrowed_legacy_metadata</a><T>( currency: &mut <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, mut legacy: CoinMetadata<T>, <a href="../sui/borrow.md#sui_borrow">borrow</a>: <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a><T>, _ctx: &mut TxContext, ) { assert!(!df::exists_(&currency.id, <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a>()), <a href="../sui/coin_registry.md#sui_coin_registry_EDuplicateBorrow">EDuplicateBorrow</a>); let <a href="../sui/coin_registry.md#sui_coin_registry_Borrow">Borrow</a> {} = <a href="../sui/borrow.md#sui_borrow">borrow</a>; // Always store up to date value. legacy.update_coin_metadata( currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>.to_ascii(), currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>.to_ascii(), ); df::add(&mut currency.id, <a href="../sui/coin_registry.md#sui_coin_registry_LegacyMetadataKey">LegacyMetadataKey</a>(), legacy); } </code></pre> </details>

Function `decimals`

Get the number of decimal places for the coin type.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): u8 </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): u8 { currency.<a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a> } </code></pre> </details>

Function `name`

Get the human-readable name of the coin.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/string.md#std_string_String">std::string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): String { currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a> } </code></pre> </details>

Function `symbol`

Get the symbol/ticker of the coin.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/string.md#std_string_String">std::string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): String { currency.<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a> } </code></pre> </details>

Function `description`

Get the description of the coin.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/string.md#std_string_String">std::string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): String { currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a> } </code></pre> </details>

Function `icon_url`

Get the icon URL for the coin.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/string.md#std_string_String">std::string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): String { currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a> } </code></pre> </details>

Function `is_metadata_cap_claimed`

Check if the metadata capability has been claimed for this <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> type.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_claimed">is_metadata_cap_claimed</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_claimed">is_metadata_cap_claimed</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { match (currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>) { MetadataCapState::Claimed(_) | MetadataCapState::Deleted => true, _ => false, } } </code></pre> </details>

Function `is_metadata_cap_deleted`

Check if the metadata capability has been deleted for this <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> type.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_deleted">is_metadata_cap_deleted</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_metadata_cap_deleted">is_metadata_cap_deleted</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { match (currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>) { MetadataCapState::Deleted => true, _ => false, } } </code></pre> </details>

Function `metadata_cap_id`

Get the metadata cap ID, or none if it has not been claimed.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/option.md#std_option_Option">std::option::Option</a><<a href="../sui/object.md#sui_object_ID">sui::object::ID</a>> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): Option<ID> { match (currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>) { MetadataCapState::Claimed(id) => option::some(id), _ => option::none(), } } </code></pre> </details>

Function `treasury_cap_id`

Get the treasury cap ID for this coin type, if registered.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/option.md#std_option_Option">std::option::Option</a><<a href="../sui/object.md#sui_object_ID">sui::object::ID</a>> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): Option<ID> { currency.<a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a> } </code></pre> </details>

Function `deny_cap_id`

Get the deny cap ID for this coin type, if it's a regulated coin. Returns <code>None</code> if:

The <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> is not regulated;
The <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code> is migrated from legacy, and its regulated state has not been set;

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_deny_cap_id">deny_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/option.md#std_option_Option">std::option::Option</a><<a href="../sui/object.md#sui_object_ID">sui::object::ID</a>> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_deny_cap_id">deny_cap_id</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): Option<ID> { match (currency.regulated) { RegulatedState::Regulated { cap, .. } => option::some(cap), RegulatedState::Unregulated | RegulatedState::Unknown => option::none(), } } </code></pre> </details>

Function `is_supply_fixed`

Check if the supply is fixed.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_supply_fixed">is_supply_fixed</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_supply_fixed">is_supply_fixed</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { match (currency.supply.<a href="../sui/borrow.md#sui_borrow">borrow</a>()) { SupplyState::Fixed(_) => true, _ => false, } } </code></pre> </details>

Function `is_supply_burn_only`

Check if the supply is burn-only.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_supply_burn_only">is_supply_burn_only</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_supply_burn_only">is_supply_burn_only</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { match (currency.supply.<a href="../sui/borrow.md#sui_borrow">borrow</a>()) { SupplyState::BurnOnly(_) => true, _ => false, } } </code></pre> </details>

Function `is_regulated`

Check if the currency is regulated.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_regulated">is_regulated</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_is_regulated">is_regulated</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { match (currency.regulated) { RegulatedState::Regulated { .. } => true, _ => false, } } </code></pre> </details>

Function `total_supply`

Get the total supply for the <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T></code> if the Supply is in fixed or burn-only state. Returns <code>None</code> if the SupplyState is Unknown.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_total_supply">total_supply</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): <a href="../std/option.md#std_option_Option">std::option::Option</a><u64> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_total_supply">total_supply</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): Option<u64> { match (currency.supply.<a href="../sui/borrow.md#sui_borrow">borrow</a>()) { SupplyState::Fixed(supply) => option::some(supply.value()), SupplyState::BurnOnly(supply) => option::some(supply.value()), SupplyState::Unknown => option::none(), } } </code></pre> </details>

Function `exists`

Check if coin data exists for the given type T in the registry.

<pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_exists">exists</a><T>(registry: &<a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">sui::coin_registry::CoinRegistry</a>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="../sui/coin_registry.md#sui_coin_registry_exists">exists</a><T>(registry: &<a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>): bool { <a href="../sui/derived_object.md#sui_derived_object_exists">derived_object::exists</a>(&registry.id, <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyKey">CurrencyKey</a><T>()) } </code></pre> </details>

Function `is_migrated_from_legacy`

Whether the currency is migrated from legacy.

<pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_is_migrated_from_legacy">is_migrated_from_legacy</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_is_migrated_from_legacy">is_migrated_from_legacy</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>): bool { !currency.extra_fields.contains(&<a href="../sui/coin_registry.md#sui_coin_registry_NEW_CURRENCY_MARKER">NEW_CURRENCY_MARKER</a>.to_string()) } </code></pre> </details>

Function `to_legacy_metadata`

Create a new legacy <code>CoinMetadata</code> from a <code><a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a></code>.

<pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_to_legacy_metadata">to_legacy_metadata</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><T>, ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): <a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><T> </code></pre> <details> <summary>Implementation</summary> <pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_to_legacy_metadata">to_legacy_metadata</a><T>(currency: &<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><T>, ctx: &mut TxContext): CoinMetadata<T> { <a href="../sui/coin.md#sui_coin_new_coin_metadata">coin::new_coin_metadata</a>( currency.<a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>.to_ascii(), currency.<a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>, currency.<a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>.to_ascii(), ctx, ) } </code></pre> </details>

Function `create`

Create and share the singleton <code><a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a></code> -- this function is called exactly once, during the upgrade epoch. Only the system address (0x0) can create the registry.

<pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_create">create</a>(ctx: &<a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>fun <a href="../sui/coin_registry.md#sui_coin_registry_create">create</a>(ctx: &TxContext) { assert!(ctx.sender() == @0x0, <a href="../sui/coin_registry.md#sui_coin_registry_ENotSystemAddress">ENotSystemAddress</a>); <a href="../sui/transfer.md#sui_transfer_share_object">transfer::share_object</a>(<a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a> { id: <a href="../sui/object.md#sui_object_sui_coin_registry_object_id">object::sui_coin_registry_object_id</a>(), }); } </code></pre> </details>

Macro function `finalize_impl`

Internal macro to keep implementation between build and test modes.

<pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_impl">finalize_impl</a><$T>($builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">sui::coin_registry::CurrencyInitializer</a><$T>, $ctx: &mut <a href="../sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): (<a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><$T>, <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">sui::coin_registry::MetadataCap</a><$T>) </code></pre> <details> <summary>Implementation</summary> <pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_finalize_impl">finalize_impl</a><$T>( $builder: <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a><$T>, $ctx: &mut TxContext, ): (<a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><$T>, <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><$T>) { let <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyInitializer">CurrencyInitializer</a> { mut currency, extra_fields, is_otw: _ } = $builder; extra_fields.destroy_empty(); let id = <a href="../sui/object.md#sui_object_new">object::new</a>($ctx); currency.<a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a> = MetadataCapState::Claimed(id.to_inner()); // Mark the currency as new, so in the future we can support borrowing of the // legacy metadata. currency .extra_fields .insert( <a href="../sui/coin_registry.md#sui_coin_registry_NEW_CURRENCY_MARKER">NEW_CURRENCY_MARKER</a>.to_string(), <a href="../sui/coin_registry.md#sui_coin_registry_ExtraField">ExtraField</a>(type_name::with_original_ids<bool>(), <a href="../sui/coin_registry.md#sui_coin_registry_NEW_CURRENCY_MARKER">NEW_CURRENCY_MARKER</a>), ); (currency, <a href="../sui/coin_registry.md#sui_coin_registry_MetadataCap">MetadataCap</a><$T> { id }) } </code></pre> </details>

Macro function `migrate_legacy_metadata_impl`

Internal macro to keep implementation between build and test modes.

<pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_legacy_metadata_impl">migrate_legacy_metadata_impl</a><$T>($registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">sui::coin_registry::CoinRegistry</a>, $legacy: &<a href="../sui/coin.md#sui_coin_CoinMetadata">sui::coin::CoinMetadata</a><$T>): <a href="../sui/coin_registry.md#sui_coin_registry_Currency">sui::coin_registry::Currency</a><$T> </code></pre> <details> <summary>Implementation</summary> <pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_migrate_legacy_metadata_impl">migrate_legacy_metadata_impl</a><$T>( $registry: &mut <a href="../sui/coin_registry.md#sui_coin_registry_CoinRegistry">CoinRegistry</a>, $legacy: &CoinMetadata<$T>, ): <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><$T> { let registry = $registry; let legacy = $legacy; assert!(!registry.<a href="../sui/coin_registry.md#sui_coin_registry_exists">exists</a><$T>(), <a href="../sui/coin_registry.md#sui_coin_registry_ECurrencyAlreadyRegistered">ECurrencyAlreadyRegistered</a>); assert!(<a href="../sui/coin_registry.md#sui_coin_registry_is_ascii_printable">is_ascii_printable</a>!(&legacy.get_symbol().to_string()), <a href="../sui/coin_registry.md#sui_coin_registry_EInvalidSymbol">EInvalidSymbol</a>); <a href="../sui/coin_registry.md#sui_coin_registry_Currency">Currency</a><$T> { id: <a href="../sui/derived_object.md#sui_derived_object_claim">derived_object::claim</a>(&mut registry.id, <a href="../sui/coin_registry.md#sui_coin_registry_CurrencyKey">CurrencyKey</a><$T>()), <a href="../sui/coin_registry.md#sui_coin_registry_decimals">decimals</a>: legacy.get_decimals(), <a href="../sui/coin_registry.md#sui_coin_registry_name">name</a>: legacy.get_name(), <a href="../sui/coin_registry.md#sui_coin_registry_symbol">symbol</a>: legacy.get_symbol().to_string(), <a href="../sui/coin_registry.md#sui_coin_registry_description">description</a>: legacy.get_description(), <a href="../sui/coin_registry.md#sui_coin_registry_icon_url">icon_url</a>: legacy .get_icon_url() .map!(|<a href="../sui/url.md#sui_url">url</a>| <a href="../sui/url.md#sui_url">url</a>.inner_url().to_string()) .destroy_or!(b"".to_string()), supply: option::some(SupplyState::Unknown), regulated: RegulatedState::Unknown, <a href="../sui/coin_registry.md#sui_coin_registry_treasury_cap_id">treasury_cap_id</a>: option::none(), <a href="../sui/coin_registry.md#sui_coin_registry_metadata_cap_id">metadata_cap_id</a>: MetadataCapState::Unclaimed, extra_fields: <a href="../sui/vec_map.md#sui_vec_map_empty">vec_map::empty</a>(), } } </code></pre> </details>

Macro function `is_ascii_printable`

Nit: consider adding this function to <code><a href="../std/string.md#std_string">std::string</a></code> in the future.

<pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_is_ascii_printable">is_ascii_printable</a>($s: &<a href="../std/string.md#std_string_String">std::string::String</a>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>macro fun <a href="../sui/coin_registry.md#sui_coin_registry_is_ascii_printable">is_ascii_printable</a>($s: &String): bool { let s = $s; s.as_bytes().all!(|b| ascii::is_printable_char(*b)) } </code></pre> </details>

Struct CoinRegistry

Struct ExtraField

Struct CurrencyKey

Struct LegacyMetadataKey

Struct MetadataCap

Struct Borrow

Struct Currency

Struct CurrencyInitializer

Enum SupplyState

Enum RegulatedState

Enum MetadataCapState

Constants

Function new_currency

Function new_currency_with_otw

Function claim_metadata_cap

Function make_regulated

Function make_supply_fixed_init

Function make_supply_burn_only_init

Function make_supply_fixed

Function make_supply_burn_only

Function finalize

Function finalize_and_delete_metadata_cap

Function finalize_registration

Function delete_metadata_cap

Function burn

Function burn_balance

Function set_name

Function set_description

Function set_icon_url

Function set_treasury_cap_id

Function migrate_legacy_metadata

Function update_from_legacy_metadata

Function delete_migrated_legacy_metadata

Function migrate_regulated_state_by_metadata

Function migrate_regulated_state_by_cap

Function borrow_legacy_metadata

Function return_borrowed_legacy_metadata

Function decimals

Function name

Function symbol

Function description

Function icon_url

Function is_metadata_cap_claimed

Function is_metadata_cap_deleted

Function metadata_cap_id

Function treasury_cap_id

Function deny_cap_id

Function is_supply_fixed

Function is_supply_burn_only

Function is_regulated

Function total_supply

Function exists

Function is_migrated_from_legacy

Function to_legacy_metadata

Function create

Macro function finalize_impl

Macro function migrate_legacy_metadata_impl

Macro function is_ascii_printable