CW20 V1.0.0

Introduction

The CW20 ADO is a smart contract to initiate a standard CW20 token. 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

InstantiateMsg

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.

Rust

pub struct InstantiateMsg {
    pub name: String,
    pub symbol: String,
    pub decimals: u8,
    pub initial_balances: Vec<Cw20Coin>,
    pub mint: Option<MinterResponse>,
    pub marketing: Option<InstantiateMarketingInfo>,
    pub kernel_address: String,
    pub owner: Option<String>
    
}

JSON

{
 "name": "mytoken",
 "symbol":"MYT",
 "decimals": 6,
 "initial_balances":[
                {
              "address":"andr1...",
              "amount":"500"
          }
              ...
        ],
 "mint":{
       "minter":"andr1...",
       "cap": "1000000"
      },
  "kernel_address":"andr1..."

 }  

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.
initial_balances	Vec<Cw20Coin>	A vector containing a list of addresses and the amount of coin to initialize each.
mint	Option<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.
marketing	Option<InstantiateMarketingInfo>	Optional field to define the marketing information of the project.
kernel_address	String	Contract address of the kernel contract to be used for AMP messaging. Kernel contract address can be found in our deployed contracts.
owner	Option<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.

pub struct Cw20Coin {
    pub address: String,
    pub amount: Uint128,
}

InstantiateMarketingInfo

Struct used to store the marketing related data of the token.

pub struct InstantiateMarketingInfo {
    pub project: Option<String>,
    pub description: Option<String>,
    pub marketing: Option<String>,
    pub logo: Option<Logo>,
}

Name	Type
project	Option<String>	A URL pointing to the project behind this token.
description	Option<String>	A longer description of the token and it's utility. Designed for tooltips or such.
marketing	Option<String>	The address (if any) who can update this data structure.
logo	Option<Logo>	A link to the logo, or a comment that there is an on-chain logo stored.

Logo

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

pub enum EmbeddedLogo {
    Svg(Binary),
    Png(Binary),
}

• Svg: Store the Logo as an SVG file. The content must conform to the specifications found here.

• Png: Store the Logo as a PNG file. This will likely only support up to 64x64 or so within the 5KB limit.

MinterResponse

pub struct MinterResponse {
    pub minter: String,
    pub cap: Option<Uint128>,
}

The cap refers to the total supply. If it is not specified, then there is an unlimited cap.

Name	Type	Description
minter	String	The address to assign as a minter.
cap	Option<Uint128>	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.

Rust

 pub enum ExecuteMsg {
   Mint {
       recipient: String,
       amount: Uint128
        }
    }

JSON

{ 
 "mint":{
    "recipient":"andr1...",
    "amount": "100"
    }
 }

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.

Rust

pub enum ExecuteMsg { 
  Transfer { 
     recipient: AndrAddr,
     amount: Uint128 
    }
  }

JSON

{
 "transfer":{
      "recipient":"andr1...",
      "amount": "100"
      }
 }

Name	Type	Description
recipient	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.

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.

Rust

pub enum ExecuteMsg {
     Send {
        contract: AndrAddr,
        amount: Uint128,
        msg: Binary,
    }
 }

JSON

{
 "send":{
    "contract":"andr1...",
    "amount":"100",
    "msg":"eyJzZW5kIjp7fX0="
    }
 }

Name	Type	Description
contract	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

Rust

   pub enum ExecuteMsg {
      Burn {
        amount: Uint128,
    }
}

JSON

{
 "burn": {
     "amount": "100"
     }
 }

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.

A new Expiration will overwrite a previous one.

Rust

 pub enum ExecuteMsg {
 IncreaseAllowance {
        spender: String,
        amount: Uint128,
        expires: Option<Expiration>,
    }
  }

JSON

{
 "increase_allowance":{
     "spender":"andr1...",
     "amount":"1000"
     }
 }
     

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>	Optional Expiration for the allowance of the spender.

DecreaseAllowance

Decreases the allowance set for the spender by the set amount.

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

Rust

  pub enum ExecuteMsg {
  DecreaseAllowance {
        spender: String,
        amount: Uint128,
        expires: Option<Expiration>,
    }
  }

JSON

{
 "decrease_allowance": {
    "spender":"andr1...",
    "amount":"100",
    "expires": {
      "at_height": "500"
      }
   }
}

Name	Type	Description
spender	String	The address to have their allowance decreased.
amount	Uint128	The amount to decrease the allowance by.
expires	Option<Expiration>	Optional expiration for the allowance of the spender.

TransferFrom

Transfers the amount of tokens from the owner address to the recipient.

The amount specified cannot exceed the allowance of the address executing TransferFrom.

Rust

pub enum ExecuteMsg {
   TransferFrom {
        owner: String,
        recipient: String,
        amount: Uint128,
    }
  }

JSON

{
 "transfer_from":{
   "owner":"andr1...",
   "recipient":"andr1...",
   "amount":"50"
     }
 }
 

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.

The amount specified cannot exceed the allowance of the address executing TransferFrom.

The msg should be base64 encoded and not raw binary.

Rust

 pub enum ExecuteMsg{
    SendFrom {
        owner: String,
        contract: String,
        amount: Uint128,
        msg: Binary,
     }
  }

JSON

{
 "send_from":{
    "owner":"andr1...",
    "contract":"andr1...",
    "amount":"100",
    "msg": "eyJzZW5kIjp7fX0="
    }
 }

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.

The amount specified cannot exceed the allowance of the address executing BurnFrom.

Rust

pub enum ExecuteMsg{
 BurnFrom {
        owner: String,
        amount: Uint128,
    }
  }

JSON

{
 "burn_from":{
   "owner":"andr1...",
   "amount": "100"
     }
 }

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.

Setting None/null for any of these will leave it unchanged

Rust

pub enum ExecuteMsg {
UpdateMarketing {
        project: Option<String>,
        description: Option<String>,
        marketing: Option<String>,
    }
 }

JSON

{
 "update_marketing":{
  "project":"http...",
  "marketing":"andr1..."
    }
 }

Name	Type	Description
project	Option<String>	A URL pointing to the project behind this token.
description	Option<String>	A longer description of the token and it's utility. Designed for tooltips or such.
marketing	Option<String>	The address (if any) who can update this data structure.

UploadLogo

Uploads a Logo for the token.

Rust

pub enum ExecuteMsg {
    UploadLogo(Logo),
 }

JSON

{
"upload_logo":{
    "url":"https://www..."
    }
}

Check 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.

Only available to the current minter.

Rust

pub enum ExecuteMsg {   
     UpdateMinter {
           new_minter: Option<String> 
     },
}

JSON

{
"update_minter":{
    "new_minter":"andr1..."
    }
}

Name	Type	Description
new_minter	Option<String>	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 section.

QueryMsg

Balance

Queries the balance of a specific address.

Rust

pub enum QueryMsg {
   #[returns(cw20::BalanceResponse)]
   Balance {
    address:String,
     }
 }

JSON

{
"balance":{
    "address":"andr1..."
   }
 }
 

Name	Type	Description
address	String	The address to get the balance of.

BalanceResponse

Rust

 pub struct BalanceResponse {
    pub balance: Uint128,
}

JSON

{
"balance":"100"
}

Name	Type	Description
balance	Uint128	The amount of tokens the specified address has in their balance.

TokenInfo

Returns metadata on the contract.

Rust

pub enum QueryMsg {
    #[returns(cw20::TokenInfoResponse)]
    TokenInfo {}
}

JSON

{
"token_info":{}
}

TokenInfoResponse

Rust

pub struct TokenInfoResponse {
    pub name: String,
    pub symbol: String,
    pub decimals: u8,
    pub total_supply: Uint128,
}

JSON

{
"name":"mytoken",
"symbol":"MYT",
"decimals": 6,
"total_supply":"10000000"
}

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

Rust

pub enum ExecuteMsg {
    #[returns(cw20::MinterResponse)]
    Minter {}
}

JSON

{
"minter":{}
}

MinterResponse

Rust

pub struct MinterResponse {
    pub minter: String,
    pub cap: Option<Uint128>,

JSON

{
"minter":"andr1...",
"cap":"1000000"
}

Name	Type	Description
minter	String	The address of the assigned minter.
cap	Option<Uint128>	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.

Rust

pub enum QueryMsg {
  #[returns(cw20::AllowanceResponse)]
  Allowance {
  owner: String,
  spender: String 
   }
 }

JSON

{
"allowance": {
   "owner":"andr1...",
   "spender":"andr1..."
   }
}

Name	Type	Description
owner	String	The address of the owner of the tokens.
spender	String	The address to check the allowance of.

AllowanceResponse

Rust

pub struct AllowanceResponse {
    pub allowance: Uint128,
    pub expires: Expiration,
}

JSON

{
"allowance":"1000",
"expires":{
  "at_height":"500"
    }
}   

Name	Type	Description
allowance	Uint128	The amount of tokens the spender has as allowance.
expires	Expiration	The expiration for the tokens.

AllAllowanaces

Returns all the allowances that the specified owner has given along with the information for each allowance.

Rust

  pub enum QueryMsg{
    #[returns(cw20::AllAllowancesResponse)]
  AllAllowances {
        owner: String,
        start_after: Option<String>,
        limit: Option<u32>,
      }
   }

JSON

{
"all_allowances":{
  "owner":"andr1...",
  "limit": 20,
  "start_after": 4
    }
}

Name	Type	Description
owner	String	The address of the owner that has given allowances.
start_after	Option<String>	An optional Id for which to start after, used for pagination.
limit	Option<u32>	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

Rust

pub struct AllAllowancesResponse {
    pub allowances: Vec<AllowanceInfo>,
}

JSON

{
"allowances":[
     { 
        "spender":"andr1...",
        "allowance":"1000",
        "expires":{
              "never":{}
              }
           },
           {
           ...
           }
        ]
  }   

Name	Type	Description
allowances	Vec<AllowanceInfo>	A vector containing each allowance and the related information.

AllowanceInfo

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	The expiration for the allowance.

AllSpenderAllowances

Returns all allowances this spender has been granted. Supports pagination.

Rust

pub enum QueryMsg {
  #[returns(cw20::AllSpenderAllowancesResponse)]
  AllSpenderAllowances {
        spender: String,
        start_after: Option<String>,
        limit: Option<u32>,
    },
  }

JSON

{
"all_spender_allowances":{
    "spender":"andr1..."
    }
}

Name	Type	Description
spender	String	The address we want to check the allowances for.
start_after	Option<String>	An optional Id for which to start after, used for pagination.
limit	Option<u32>	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.

Rust

pub enum QueryMsg{
    #[returns(cw20::AllAccountsResponse)]
    AllAccounts {
        start_after: Option<String>,
        limit: Option<u32>,
    }
  }

JSON

{
"all_accounts":{
    "limit": 25
}

Name	Type	Description
start_after	Option<String>	An optional Id for which to start after, used for pagination.
limit	Option<u32>	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

Rust

pub struct AllAccountsResponse {
    pub accounts: Vec<String>,
}

JSON

{
"accounts":["andr1...","andr1...",...]
}

Name	Type	Description
accounts	Vec<String>	A vector containing the addresses that own the token.

MarketingInfo

Returns the metadata of the marketing of the project.

Rust

pub enum ExecuteMsg {
  #[returns(cw20::MarketingInfoResponse)]
  MarketingInfo {}
 }

JSON

{
"marketing_info":{}
}

MarketingInfoResponse

Rust

pub struct MarketingInfoResponse {
    pub project: Option<String>,
    pub description: Option<String>,
    pub logo: Option<LogoInfo>,
    pub marketing: Option<Addr>,
}

JSON

{
"project":"http:...",
"description":" This project ...",
"marketing":"andr1..."
}

Name	Type	Description
project	Option<String>	A URL pointing to the project behind this token.
description	Option<String>	A longer description of the token and it's utility. Designed for tooltips or such.
logo	Option<LogoInfo>	A link to the logo, or a comment there is an on-chain logo stored.
marketing	Option<Addr>	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.

Rust

pub enum ExecuteMsg {
    #[returns(cw20::DownloadLogoResponse)]
    DownloadLogo {}
  }

JSON

{
"download_logo":{}
}

DownloadLogoResponse

Rust

pub struct DownloadLogoResponse {
    pub mime_type: String,
    pub data: Binary,
}

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 section.