# CW20 ## Introduction The **CW20 ADO** is a smart contract to initiate a [standard CW20 token](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md). CW20 is a specification for fungible tokens based on CosmWasm. The name and design is loosely based on Ethereum's ERC20 standard, but many changes have been made. **Ado\_type**: cw20 **Version: 2.1.0** ## InstantiateMsg {% hint style="warning" %} The symbol can only consist of letters and has to be between 3 and 12 characters. Decimals will indicate how divisible your token is. Having a decimal of 6 means you could have 0.000001 of your token. Showcasing the decimalized amounts is usually handled by the front-end interface that would take the amount of tokens and divide it by the number of decimals. This means that when you transfer or send tokens from this ADO directly, you would still use whole numbers. For example, if I want to transfer 5 full tokens to someone and I have 6 decimals for my token, I would be sending 5000000 tokens from this ADO. {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub struct InstantiateMsg { pub name: String, pub symbol: String, pub decimals: u8, pub initial_balances: Vec, pub mint: Option, pub marketing: Option, pub kernel_address: String, pub owner: Option } ``` {% endtab %} {% tab title="JSON" %} ```json { "name": "mytoken", "symbol":"MYT", "decimals": 6, "initial_balances":[ { "address":"andr1...", "amount":"500" } ... ], "mint":{ "minter":"andr1...", "cap": "1000000" }, "marketing":{ "project":"website-url", "description":"small project description", "marketing":"andr1...", "logo":{ "url": "https://example.com/logo.png" } }, "kernel_address":"andr1..." } ``` {% endtab %} {% endtabs %}
NameTypeDescription
nameStringThe name of the token.
symbolStringThe symbol of the token.
decimalsu8The number of decimals for the token.
initial_balancesVec<Cw20Coin>A vector containing a list of addresses and the amount of coin to initialize each.
mintOption<MinterResponse>Optional field to define a minter for the token and an optional cap for the total supply of tokens that can be minted. If not defined, additional tokens cannot be minted.
marketingOption<InstantiateMarketingInfo>Optional field to define the marketing information of the project.
kernel_addressStringContract address of the kernel contract to be used for AMP messaging. Kernel contract address can be found in our deployed contracts.
ownerOption<String>Optional address to specify as the owner of the ADO being created. Defaults to the sender if not specified.
#### Cw20Coin Struct used to initiate balances for addresses. Contains an address and the amount of tokens for that address. ```rust pub struct Cw20Coin { pub address: String, pub amount: Uint128, } ``` #### InstantiateMarketingInfo Struct used to store the marketing related data of the token. ```rust pub struct InstantiateMarketingInfo { pub project: Option, pub description: Option, pub marketing: Option, pub logo: Option, } ``` | Name | Type | | | ------------- | --------------- | ---------------------------------------------------------------------------------- | | `project` | Option\ | A URL pointing to the project behind this token. | | `description` | Option\ | A longer description of the token and it's utility. Designed for tooltips or such. | | `marketing` | Option\ | The address (if any) who can update this data structure. | | `logo` | Option\ | A link to the logo, or a comment that there is an on-chain logo stored. | #### Logo ```rust pub enum Logo { Url(String), Embedded(EmbeddedLogo), } ``` * **Url**: A reference to an externally hosted logo. Must be a valid HTTP or HTTPS URL. * **Embedded**: Logo content stored on the blockchain. Enforce maximum size of 5KB on all variants #### EmbeddedLogo ```rust pub enum EmbeddedLogo { Svg(Binary), Png(Binary), } ``` * **Svg**: Store the Logo as an SVG file. The content must conform to the specifications found [here](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics). * **Png:** Store the Logo as a PNG file. This will likely only support up to 64x64 or so within the 5KB limit. #### MinterResponse ```rust pub struct MinterResponse { pub minter: String, pub cap: Option, } ``` {% hint style="warning" %} The cap refers to the total supply. If it is not specified, then there is an unlimited cap. {% endhint %} | Name | Type | Description | | -------- | ---------------- | ------------------------------------------------------------------------- | | `minter` | String | The address to assign as a minter. | | `cap` | Option\ | A hard cap on total amount of CW20 tokens that can be minted by this ADO. | ## ExecuteMsg ### Mint Only with the "mint" extension. If authorized, creates amount new tokens and adds to the recipient balance. {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { Mint { recipient: String, amount: Uint128 } } ``` {% endtab %} {% tab title="JSON" %} ```json { "mint":{ "recipient":"andr1...", "amount": "100" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ----------- | ------- | ----------------------------------------- | | `recipient` | String | The address to receive the minted tokens. | | `amount` | Uint128 | The amount of tokens to mint. | ### Transfer Transfer is a base message to move tokens to another account without triggering actions. {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { Transfer { recipient: AndrAddr, amount: Uint128 } } ``` {% endtab %} {% tab title="JSON" %} ```json { "transfer":{ "recipient":"andr1...", "amount": "100" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------- | | `recipient` | [AndrAddr](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#andraddr) | The address to transfer the tokens to. | | `amount` | Uint128 | The amount of tokens to transfer. | ### Send Send is a base message to transfer tokens to a contract and trigger an action on the receiving contract. {% hint style="warning" %} The `amount` sent might be affected depending on the attached modules. The `msg` should be base64 encoded and not raw binary. This message is used when sending tokens to other ADOs that interact with CW20 tokens. In that case, the `msg` should be a CW20HookMsg that would be defined in the ADOs documentation page. {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { Send { contract: AndrAddr, amount: Uint128, msg: Binary, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "send":{ "contract":"andr1...", "amount":"100", "msg":"eyJzZW5kIjp7fX0=" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ---------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `contract` | [AndrAddr](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#andraddr) | The address of the receiving contract. | | `amount` | Uint128 | The amount to send. | | `msg` | Binary | A message to be sent to the receiving contract. | ### Burn Burn is a base message to destroy tokens forever {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { Burn { amount: Uint128, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "burn": { "amount": "100" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | -------- | ------- | -------------------------------- | | `amount` | Uint128 | The amount of coins to be burnt. | ### IncreaseAllowance Sets an `amount` of tokens from the owner that the specified `spender` can interact with. {% hint style="warning" %} A new Expiration will overwrite a previous one. {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { IncreaseAllowance { spender: String, amount: Uint128, expires: Option, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "increase_allowance":{ "spender":"andr1...", "amount":"1000" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | --------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `spender` | String | The address to receive the allowance. | | `amount` | Uint128 | The amount of tokens to give the spender access to. | | `expires` | Option<[Expiration](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#expiration)> | Optional Expiration for the allowance of the spender. | ### DecreaseAllowance Decreases the allowance set for the `spender` by the set `amount.` {% hint style="warning" %} The amount specified in `DecreaseAllowance` does not replace the old amount but is subtracted from it. If the result is 0 or less, then the spender no longer has an Allowance from the owner. If an `Expiration` is set, it will overwrite previously set Expiration {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { DecreaseAllowance { spender: String, amount: Uint128, expires: Option, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "decrease_allowance": { "spender":"andr1...", "amount":"100", "expires": { "at_height": "500" } } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | --------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `spender` | String | The address to have their allowance decreased. | | `amount` | Uint128 | The amount to decrease the allowance by. | | `expires` | Option<[Expiration](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#expiration)> | Optional expiration for the allowance of the spender. | ### TransferFrom Transfers the `amount` of tokens from the `owner` address to the `recipient.` {% hint style="warning" %} The `amount specified` cannot exceed the allowance of the address executing `TransferFrom.` {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { TransferFrom { owner: String, recipient: String, amount: Uint128, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "transfer_from":{ "owner":"andr1...", "recipient":"andr1...", "amount":"50" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ----------- | ------- | ------------------------------------------------------------- | | `owner` | String | The owner address that has the tokens to transfer. | | `recipient` | String | The address the receive the tokens. | | `amount` | Uint128 | The amount of tokens to send from the owner to the recipient. | ### SendFrom Sends the `amount` of tokens from the `owner` address to the `contract` address. Can use a msg to trigger an action on the receiving contract. {% hint style="warning" %} The `amount specified` cannot exceed the allowance of the address executing `TransferFrom.` The `msg` should be base64 encoded and not raw binary. {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg{ SendFrom { owner: String, contract: String, amount: Uint128, msg: Binary, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "send_from":{ "owner":"andr1...", "contract":"andr1...", "amount":"100", "msg": "eyJzZW5kIjp7fX0=" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ---------- | ------- | ------------------------------------------------------------ | | `owner` | String | The owner address that has the tokens to transfer. | | `contract` | String | The contract address to receive the tokens. | | `amount` | Uint128 | The amount of tokens to send from the owner to the contract. | | `msg` | Binary | A message to be sent to the receiving contract. | ### BurnFrom Burns a specified `amount` of tokens from the `owner` address **forever**. {% hint style="warning" %} The `amount specified` cannot exceed the allowance of the address executing `BurnFrom.` {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg{ BurnFrom { owner: String, amount: Uint128, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "burn_from":{ "owner":"andr1...", "amount": "100" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | -------- | ------- | -------------------------------- | | `owner` | String | The address to burn tokens from. | | `amount` | Uint128 | The amount of tokens to burn. | ### UpdateMarketing Updates the marketing information if instantiated. {% hint style="warning" %} Setting None/null for any of these will leave it unchanged {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { UpdateMarketing { project: Option, description: Option, marketing: Option, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "update_marketing":{ "project":"http...", "marketing":"andr1..." } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------- | --------------- | ---------------------------------------------------------------------------------- | | `project` | Option\ | A URL pointing to the project behind this token. | | `description` | Option\ | A longer description of the token and it's utility. Designed for tooltips or such. | | `marketing` | Option\ | The address (if any) who can update this data structure. | ### UploadLogo Uploads a Logo for the token. {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { UploadLogo(Logo), } ``` {% endtab %} {% tab title="JSON" %} ```json { "upload_logo":{ "url":"https://www..." } } ``` {% endtab %} {% endtabs %} Check [Logo](#logo). ### UpdateMinter Only with the "mintable" extension. The current minter may set a new minter. Setting the minter to None will remove the token's minter forever. {% hint style="warning" %} Only available to the current minter. {% endhint %} {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { UpdateMinter { new_minter: Option }, } ``` {% endtab %} {% tab title="JSON" %} ```json { "update_minter":{ "new_minter":"andr1..." } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------ | --------------- | ------------------------------------------------------------------------------------------ | | `new_minter` | Option\ | The address of the new minter. If not specified, then the token minter is removed forever. | ### Base Executes The rest of the execute messages can be found in the[ ADO Base](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/ado-base) section. ## QueryMsg ### Balance Queries the balance of a specific `address.` {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg { #[returns(cw20::BalanceResponse)] Balance { address:String, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "balance":{ "address":"andr1..." } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | --------- | ------ | ---------------------------------- | | `address` | String | The address to get the balance of. | #### BalanceResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct BalanceResponse { pub balance: Uint128, } ``` {% endtab %} {% tab title="JSON" %} ```json { "balance":"100" } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | --------- | ------- | ------------------------------------------------------------------ | | `balance` | Uint128 | The amount of tokens the specified `address` has in their balance. | ### TokenInfo Returns metadata on the contract. {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg { #[returns(cw20::TokenInfoResponse)] TokenInfo {} } ``` {% endtab %} {% tab title="JSON" %} ```json { "token_info":{} } ``` {% endtab %} {% endtabs %} #### TokenInfoResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct TokenInfoResponse { pub name: String, pub symbol: String, pub decimals: u8, pub total_supply: Uint128, } ``` {% endtab %} {% tab title="JSON" %} ```json { "name":"mytoken", "symbol":"MYT", "decimals": 6, "total_supply":"10000000" } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | -------------- | ------- | ------------------------------------- | | `name` | String | The name of the token. | | `symbol` | String | The symbol of the token. | | `decimals` | u8 | The number of decimals for the token. | | `total_supply` | Uint128 | The total amount of tokens. | ### Minter Returns who can mint and the hard cap on maximum tokens after minting {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { #[returns(cw20::MinterResponse)] Minter {} } ``` {% endtab %} {% tab title="JSON" %} ```json { "minter":{} } ``` {% endtab %} {% endtabs %} #### MinterResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct MinterResponse { pub minter: String, pub cap: Option, ``` {% endtab %} {% tab title="JSON" %} ```json { "minter":"andr1...", "cap":"1000000" } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | -------- | ---------------- | ------------------------------------------------------------------ | | `minter` | String | The address of the assigned minter. | | `cap` | Option\ | Cap is a hard cap on total supply that can be achieved by minting. | ### Allowance Returns the amount of tokens that the spender has from the owner's tokens and the expiration for the tokens. {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg { #[returns(cw20::AllowanceResponse)] Allowance { owner: String, spender: String } } ``` {% endtab %} {% tab title="JSON" %} ```json { "allowance": { "owner":"andr1...", "spender":"andr1..." } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | --------- | ------ | --------------------------------------- | | `owner` | String | The address of the owner of the tokens. | | `spender` | String | The address to check the allowance of. | #### AllowanceResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct AllowanceResponse { pub allowance: Uint128, pub expires: Expiration, } ``` {% endtab %} {% tab title="JSON" %} ```json { "allowance":"1000", "expires":{ "at_height":"500" } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ----------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `allowance` | Uint128 | The amount of tokens the spender has as allowance. | | `expires` | [Expiration](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#expiration) | The expiration for the tokens. | ### AllAllowanaces Returns all the allowances that the specified `owner` has given along with the information for each allowance. {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg{ #[returns(cw20::AllAllowancesResponse)] AllAllowances { owner: String, start_after: Option, limit: Option, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "all_allowances":{ "owner":"andr1...", "limit": 20, "start_after": 4 } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | | `owner` | String | The address of the owner that has given allowances. | | `start_after` | Option\ | An optional Id for which to start after, used for pagination. | | `limit` | Option\ | An optional limit to how many allowances are returned. Is set by default to 10. Can be set to reach a maximum of 30. | #### AllAllowanceResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct AllAllowancesResponse { pub allowances: Vec, } ``` {% endtab %} {% tab title="JSON" %} ```json { "allowances":[ { "spender":"andr1...", "allowance":"1000", "expires":{ "never":{} } }, { ... } ] } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------ | ------------------- | --------------------------------------------------------------- | | `allowances` | Vec\ | A vector containing each allowance and the related information. | #### AllowanceInfo ```rust pub struct AllowanceInfo { pub spender: String, pub allowance: Uint128, pub expires: Expiration } ``` | Name | Type | Description | | ----------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `spender` | String | The address that has an allowance. | | `allowance` | Uint128 | The amount of tokens in the allowance. | | `expires` | [Expiration](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/common-types#expiration) | The expiration for the allowance. | ### AllSpenderAllowances Returns all allowances this spender has been granted. Supports pagination. {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg { #[returns(cw20::AllSpenderAllowancesResponse)] AllSpenderAllowances { spender: String, start_after: Option, limit: Option, }, } ``` {% endtab %} {% tab title="JSON" %} ```json { "all_spender_allowances":{ "spender":"andr1..." } } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | | `spender` | String | The address we want to check the allowances for. | | `start_after` | Option\ | An optional Id for which to start after, used for pagination. | | `limit` | Option\ | An optional limit to how many allowances are returned. Is set by default to 10. Can be set to a maximum of 30. | ### AllAccounts Returns all the addresses that have a balance. {% tabs %} {% tab title="Rust" %} ```rust pub enum QueryMsg{ #[returns(cw20::AllAccountsResponse)] AllAccounts { start_after: Option, limit: Option, } } ``` {% endtab %} {% tab title="JSON" %} ```json { "all_accounts":{ "limit": 25 } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | | `start_after` | Option\ | An optional Id for which to start after, used for pagination. | | `limit` | Option\ | An optional limit to how many Accounts are returned. Is set by default to 10. Can be set to reach a maximum of 30. | #### AllAccountsResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct AllAccountsResponse { pub accounts: Vec, } ``` {% endtab %} {% tab title="JSON" %} ```json { "accounts":["andr1...","andr1...",...] } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ---------- | ------------ | ----------------------------------------------------- | | `accounts` | Vec\ | A vector containing the addresses that own the token. | ### MarketingInfo Returns the metadata of the marketing of the project. {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { #[returns(cw20::MarketingInfoResponse)] MarketingInfo {} } ``` {% endtab %} {% tab title="JSON" %} ```json { "marketing_info":{} } ``` {% endtab %} {% endtabs %} #### MarketingInfoResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct MarketingInfoResponse { pub project: Option, pub description: Option, pub logo: Option, pub marketing: Option, } ``` {% endtab %} {% tab title="JSON" %} ```json { "project":"http:...", "description":" This project ...", "marketing":"andr1..." } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ------------- | ----------------- | ---------------------------------------------------------------------------------- | | `project` | Option\ | A URL pointing to the project behind this token. | | `description` | Option\ | A longer description of the token and it's utility. Designed for tooltips or such. | | `logo` | Option\ | A link to the logo, or a comment there is an on-chain logo stored. | | `marketing` | Option\ | The address (if any) who can update this data structure. | ### DownloadLogo Downloads the embedded logo data (if stored on chain). Errors if no logo data stored for this contract. {% tabs %} {% tab title="Rust" %} ```rust pub enum ExecuteMsg { #[returns(cw20::DownloadLogoResponse)] DownloadLogo {} } ``` {% endtab %} {% tab title="JSON" %} ```json { "download_logo":{} } ``` {% endtab %} {% endtabs %} #### DownloadLogoResponse {% tabs %} {% tab title="Rust" %} ```rust pub struct DownloadLogoResponse { pub mime_type: String, pub data: Binary, } ``` {% endtab %} {% endtabs %} | Name | Type | Description | | ----------- | ------ | -------------------------- | | `mime_type` | String | The MIME type of the logo. | | `data` | Binary | The LOGO data. | ### Base Queries The rest of the query messages can be found in the[ ADO Base](https://docs.andromedaprotocol.io/andromeda/platform-and-framework/ado-base) section.