Coreum Fungible Token

This document specifies assetft module, which allows public users of the blockchain to create fungible tokens on Coreum blockchain.

Concepts

In this section we will provide the detailed behavior of fungible token creation and management.

Here is the list of functionalities provided by this module, we will examine each of them separately.

  • Issue
  • Mint
  • Burn
  • Freeze
  • Global Freeze
  • Whitelist
  • IBC transfers
  • Block smart contracts
  • Clawback
  • Transferring admin
  • Clear admin
  • Extension

Interaction with bank module, introducing wbank module

Coreum uses native Cosmos SDK bank module which is responsible for tracking fungible token creation and balances of each account. But this module does not allow any public to create a fungible token, mint/burn it, and also does not allow for other features such as freezing and whitelisting. To work around this issue we have wrapped the bank module into the wbank module.

In wbank module we wrap all the send related methods of the bank module and intercept them with BeforeSend and BeforeInputOutput functions provided by assetft module. This allows assetft module to inject custom logic into interceptor functions and reject some transaction if whitelisting or freezing criteria are not met, or apply other features such as BurnRate.

This structure allows to reuse the code provided by Cosmos SDK, and also reuse the infrastructure that the community provides (e.g. explorers and wallets). But it also leads to the fact that some of the information regarding fungible tokens will exist in the assetft module and some in the bank module. For example, if you want to query for frozen balances of a fungible token, you need to query the assetft module but if you want to get the total supply, you must query the bank module.

In a nutshell, assetft module interacts with wbank which in turn wraps the original bank module.

Token Interactions

Issue

Coreum provides a decentralized platform which allows everyone to tokenize their assets. Although the functionality of fungible token creation and minting is present in the original bank module of Cosmos SDK, it is not exposed to end users, and it is only possible to create new fungible tokens via either the governance or IBC. The Issue method described here, makes it possible for everyone to create a fungible token and manage its supply. When the admin (issuer of the token) issues a token, they specify the initial total supply which will be delivered to the admin account address.

All the information provided at the time of issuance is immutable and cannot be changed later.

Denom naming, Symbol and Precision

The way that denom is created is that the user provides a name for their subunit, and the denom for the token, which is the main identifier of the token, will be created by joining the subunit and the issuer address separated with a dash (subunit-address). The user also provides the symbol and precision which will only be used for display purposes and will be stored in the bank module's metadata field.

For example to represent Bitcoin on Coreum, one could choose satoshi as subunit, BTC as Symbol and 8 as precision. It means that if the issuer address is core1tr3w86yesnj8f290l6ve02cqhae8x4ze0nk0a8 then the denom will be satoshi-core1tr3w86yesnj8f290l6ve02cqhae8x4ze0nk0a8 and since we have chosen BTC as symbol and 8 as precision, it will follow that (1 BTC = 10^8 satoshi-devcore1tr3w86yesnj8f290l6ve02cqhae8x4ze0nk0a8)

Transferring admin

Each token has an issuer, whose address is a part of the denom forever. The initial admin of the token is the issuer, but the admin role can be transferred to another account. Then, all the privileges of the previous admin will be transferred to the new admin, such as the ability to mint tokens if minting is enabled. The specific privileges and features will be discussed in the next section.

Clear admin

Tokens can also lose their admin forever by clearing admin. Then, no one will have any more privilege than others.

Token Features

When issuing a token, the admin must decide which features are enabled on the token. For example if minting feature is enabled then it will allow the admin to mint further tokens on top of the initial supply, otherwise no new tokens can be minted. Here is a list of all the features that can be enabled on the token. Each of these features affects how the token will behave and a detailed description will be provided in the dedicated section for each feature.

  • minting
  • burning
  • freezing
  • whitelisting
  • ibc
  • block smart contracts
  • clawback
  • Transferring admin
  • Clear Admin
  • extension

Burn Rate

The admin has the option to provide BurnRate when issuing a new token. This value is a number between 0 and 1, and if it is above zero, in every transfer, some additional tokens will be burnt on top of the transferred value, from the senders address. The tokens to be burnt are calculated by multiplying the TransferAmount by burn rate, and rounding it up to an integer value.

If IBC feature is enabled for the token then the burn rate is applied to outgoing IBC transfers.

Burn rate is never applied if smart contract is the sender.

Send Commission Rate

Exactly same as the Burn Rate, but the calculated value will be transferred to the admin account addressed instead of being burnt.

If IBC feature is enabled for the token then the send commission rate is applied to outgoing IBC transfers.

Send commission rate is never applied if smart contract is the sender.

Issuance Fee

Whenever a user wants to issue a fungible token, they have to pay some extra money as issuance fee, which is calculated on top of tx execution fee and will be burnt. The amount of the issuance fee is controlled by governance.

Mint

If the minting feature is enabled, then admin of the token can submit a Mint transaction to add more tokens to the total supply. All the minted tokens will be transferred to the admin account address.

Burn

The admin of the token can burn the tokens that they hold. If the burning feature is enabled, then every holder of the token can burn the tokens they hold.

Freeze/Unfreeze

If the freezing feature is enabled on a token, then the admin of the token can freeze an account up to an amount. The frozen amount can be more than what the user currently holds, an works even if the user holds zero. The user can only send the tokens that they hold in excess of the frozen amount. For example if the admin freezes 1000 ABC tokens on account Y and this account holds 800, then they cannot move any of their tokens, but if the account receives 400 extra ABC tokens, their total balance will become 1200 and then can only spend 200 of it, since 1000 is Frozen.

Here is the description of behavior of the freezing feature:

  • The admin can freeze an account up to a specific amount if the freezing feature is enabled.
  • The admin can increase the frozen amount by submitting a new freeze transaction on top of already frozen account. The frozen amount of the account will be increased by the new value.
  • The admin can unfreeze a portion of the frozen amount on an account.
  • The admin cannot freeze their own account
  • The user can only send their tokens in excess of the frozen amount.
  • The user can receive tokens regardless of frozen limitation.
  • The user cannot burn the frozen amount if both freezing and burning is enabled.
  • Frozen amount cannot be a negative value, it means that amount present in unfreeze transaction cannot be bigger than the current frozen amount
  • If either or both of BurnRate and SendCommissionRate are set above zero, then after transfer has taken place and those rates are applied, the sender's balance must not go below the frozen amount. Otherwise the transaction will fail.

Same rules apply to sending tokens over IBC transfer protocol if IBC is enabled for the token.

Global Freeze/Unfreeze

If the freezing feature is enabled on a token, then the admin of the token can globally freeze that token, which means that nobody except the admin can send that token. In other words, only the admin will be able to send to other accounts. The admin can also globally unfreeze and remove this limitation.

If IBC is enabled for the token and token is globally frozen then only the admin can send them over IBC transfer protocol.

Whitelist

If the whitelisting feature is enabled, then every account that wishes to receive this token, must first be whitelisted by the admin, otherwise they will not be able to receive that token. This feature allows the admin to set whitelisted limit on any account, and then that account will be able to receive tokens only up to the whitelisted limit. If someone tries to send tokens to an account which will result in the whitelisted amount to be exceeded, the transaction will fail.

Here is the description of behavior of the whitelisting feature:

  • The admin can set whitelisted limit on any account except their own.
  • The admin can set whitelisted amount higher or lower than what the user currently holds.
  • The admin account is whitelisted to infinity by default and cannot be modified.
  • The user can receive tokens as long as their total balance, after the transaction execution, will not be higher than their whitelisted amount

Same rules apply to receiving tokens over IBC transfer protocol if IBC is enabled for the token.

Unlimited freezing and whitelisting

When admin wants to freeze or whitelist account, the exact amount to whitelist or freeze must be provided. We don't support separate message types which might be used to freeze or whitelist unlimited amounts.

If admin needs that functionality, here is the procedure for achieving this goal:

  1. Check what the total supply of the token is
  2. Whitelist or freeze amount greater than or equal to that total supply.

Keep in mind that admin must plan for eventual total supply changes caused by minting.

IBC

When token is created, admin decides if users may send and receive it over IBC transfer protocol. If IBC feature is disabled token can never leave the Coreum chain.

Block Smart Contracts

When token is created, admin decides if users may send it to smart contracts or not. If this feature is enabled, then the token can only be sent to regular user addresses. It's important to point out that this doesn't mean that the token cannot be issued from a smart contract. If the token with this feature enabled is issued from a smart contract, it can be sent back to this contract, but it cannot be sent to any other smart contract.

Clawback

If the clawback feature is enabled on a token, then the admin of the token can confiscate up to the amount an account holds. The clawback amount cannot be more than what the user currently holds.

Here is the description of behavior of the clawback feature:

  • The admin can clawback up to the amount an account holds if the clawback feature is enabled.
  • The admin cannot clawback from their own account
  • The admin cannot clawback from module accounts

Same rules apply to sending tokens over IBC transfer protocol if IBC is enabled for the token.

Disclaimer: if the admin claws back from the escrow address, then it will break the IBC. admins should not do this if they want the IBC to work for their token.

Transferring admin

Each token has an issuer, whose address is a part of the denom forever. The initial admin of the token is the issuer, but the admin role can be transferred to another account. Then, all the privileges of the previous admin will be transferred to the new admin, such as the ability to mint tokens if minting is enabled. The specific privileges and features will be discussed in the next section.

Clearing admin

Tokens can also lose their admin forever by clearing admin. Then, no one will have any more privilege than others.

Extension

Extension is a powerful feature which lets the admin override some functionalities of the token by attaching a smart contract to the token that can administrate it. When a bank transfer is initiated, the smart contract account receives the amount plus any commission or burn amount if they should be applied, then it is called via a sudo call with the information related to the bank transfer and the context information. The smart contract then can decide to do whatever it decides with the transfer which may include overriding of some behaviors for the features explained before. The sudo call is received in the pub fn sudo(deps: DepsMut<CoreumQueries>, env: Env, msg: SudoMsg) entry point of the smart contract and the message would be a ExtensionTransfer which is defined as follows.

#[cw_serde]
pub enum SudoMsg {
    ExtensionTransfer {
        recipient: String,
        sender: String,
        transfer_amount: Uint128,
        commission_amount: Uint128,
        burn_amount: Uint128,
        context: TransferContext,
    },
}

#[cw_serde]
pub struct TransferContext {
    sender_is_smart_contract: bool,
    recipient_is_smart_contract: bool,
    ibc_purpose: IBCPurpose,
}

The fields are:

  • recipient: the account which receives the amount
  • sender: the account which sends the amount
  • transfer_amount: the amount to be sent
  • commission_amount: the amount to be sent times the commission rate of the token (if it is set)
  • burn_amount: the amount to be sent times the burn rate of the token (if it is set)
  • context: contextual information regarding the transfer which includes:
  • sender_is_smart_contract: indicated whether the transfer is instantiated from a smart contract
  • recipient_is_smart_contract: indicated whether the transfer is going to be received by a smart contract
  • ibc_purpose: if it is an ibc transfer, indicates whether it's an outgoing, incoming, acknowledged or timed-out transfer

Note: The extension feature is not compatible with ibc and block smart contract feature. It will error out if you try to enable those features at the same time.

previous
Modules Overview
next
Non-Fungible Tokens