> For the complete documentation index, see [llms.txt](https://mars-protocol.gitbook.io/mars-protocol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mars-protocol.gitbook.io/mars-protocol/contracts-core/matoken.md).

# maToken

The maToken contract is a modified cw20 fork that is minted in representation of a deposited asset.

Each deposited asset has a corresponding instance of the maToken and accumulates interest in the way that they are redeemable for an ever-increasing amount of their underlying asset.

The Red Bank can do forced transfers/burns when user positions are being liquidated.

On each contract call that changes a balance, the maToken will call the incentives contract in order to manage MARS rewards.

## Links

* package (msgs and types): <https://github.com/mars-protocol/mars-core/blob/master/packages/mars-core/src/ma_token.rs>
* contract: <https://github.com/mars-protocol/mars-core/blob/master/contracts/mars-ma-token/src/contract.rs>
* schema: <https://github.com/mars-protocol/mars-core/tree/master/contracts/mars-ma-token/schema>

## Config

| Key                  | Type          | Description                 |
| -------------------- | ------------- | --------------------------- |
| `red_bank_address`   | CanonicalAddr | Red Bank contract address   |
| `incentives_address` | CanonicalAddr | Incentives contract address |

## InstantiateMsg

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, JsonSchema)]
pub struct InstantiateMsg {
    // cw20_base params
    pub name: String, 
    pub symbol: String, 
    pub decimals: u8, 
    pub initial_balances: Vec<Cw20Coin>, 
    pub mint: Option<MinterResponse>, 
    pub marketing: Option<InstantiateMarketingInfo>, 
    
    //custom_params
    pub init_hook: option<InitHook>, 
    pub red_bank_address: String, 
    pub incentives_address: String,  
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "name": "...", 
  "symbol": "...", 
  "decimals": 3, 
  "initial_balances": [
      ["terra..."], 
      ["terra..."] 
    ],
  "mint": {}, 
  "marketing": {},
  "init_hook": {
    "msg": 01001,
    "contract_addr": "terra...",
  }, 
  "red_bank_address": "terra...", 
  "incentives_address": "terra..."
}
```

{% endtab %}
{% endtabs %}

|                      |                                   |                                        |
| -------------------- | --------------------------------- | -------------------------------------- |
| `name`               | String                            | Name of maToken                        |
| `symbol`             | String                            | Token symbol                           |
| `decimals`           | u8                                | Decimals                               |
| `initial_balances`   | Vec\<Cw20Coin>                    | Initial balance                        |
| `mint`\*             | Option\<MinterResponse>           | Minter response                        |
| `marketing`\*        | Option\<InstantiateMarketingInfo> | Marketing Info                         |
| `init_hook`\*        | \<InitHook>                       | Hook called after token initialization |
| `red_bank_address`   | String                            | Red Bank contract address              |
| `incentives_address` | String                            | Incentives contract address            |

\* = optional

### `InitHook`

Hook to be called after token initialization.

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct InitHook {
    pub msg: Binary,
    pub contract_addr: String,
}
```

| Key             | Type   | Description      |
| --------------- | ------ | ---------------- |
| `msg`           | Binary | Binary message   |
| `contract_addr` | String | Contract address |

## ExecuteMsg

### `Transfer`

Transfer is a base message to move tokens to another account. Requires to be finalized by the money market.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Transfer {
        recipient: String, 
        amount: Uint128
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "transfer": {
    "recipient": "terra...",
    "amount": 10000000,
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type    | Description                          |
| ----------- | ------- | ------------------------------------ |
| `recipient` | String  | Recipient address receiving transfer |
| `amount`    | Uint128 | Amount being transfered              |
|             |         |                                      |

### `TransferOnLiquidation`

A forced transfer is called by the money market when an account is being liquidated.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    TransferOnLiquidation {
        sender: String, 
        recipient: String, 
        amount: Uint128
    }  
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "transfer_on_liquidation": {
    "sender": "terra...",
    "recipient": "terra...",
    "amount": 10000000,
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type    | Description                            |
| ----------- | ------- | -------------------------------------- |
| `sender`    | String  | Sender address                         |
| `recipient` | String  | Recipient address                      |
| `amount`    | Uint128 | Amount being transfered by liquidation |

### `Burn`

Burns tokens from user. Only money market can call this. Used when a user is being liquidated.&#x20;

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Burn {
        user: String, 
        amount: Uint128   
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "burn": {
    "user": "terra...",
    "amount": 10000000,
  }
}
```

{% endtab %}
{% endtabs %}

| Key      | Type    | Description              |
| -------- | ------- | ------------------------ |
| `user`   | String  | User address             |
| `amount` | Uint128 | Amount of tokens to burn |

### `Send`

Send is a base message to transfer tokens to a contract and trigger an action on the receiving contract.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Send {
        contract: String, 
        amount: Uint128,
        msg: Binary
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "send": {
    "contract": "terra...",
    "amount": 10000000,
    "msg": 01001
  }
}
```

{% endtab %}
{% endtabs %}

| Key        | Type    | Description      |
| ---------- | ------- | ---------------- |
| `contract` | String  | Contract address |
| `amount`   | Uint128 | Amount           |
| `msg`      | Binary  | Binary message   |

### `Mint`

Only with the "mintable" extension. If authorized, creates amount new tokens and adds to the recipient balance.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Mint {
        recipient: String,
        amount: Uint128
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "mint": {
    "recipient": "terra...",
    "amount": 10000000,
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type    | Description       |
| ----------- | ------- | ----------------- |
| `recipient` | String  | Recipient address |
| `amount`    | Uint128 | Amount to add     |

### `IncreaseAllowance`

Only with "approval" extension. Allows spender to access an additional amount tokens from the owner's (env.sender) account. If expires is Some(), overwrites current allowance expiration with this one.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    IncreaseAllowance {
        spender: String, 
        amount: Uint128,
        expires: Option<Expiration>
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "increase_allowance": {
    "spender": "terra...",
    "amount": 10000000,
    "expires": {}
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type                | Description     |
| ----------- | ------------------- | --------------- |
| `spender`   | String              | Spender address |
| `amount`    | Uint128             | Amount          |
| `expires`\* | Option\<Expiration> | Expiration      |

\* = optional

### `DecreaseAllowance`

Only with "approval" extension. Lowers the spender's access of tokens from the owner's (`env.sender`) account by amount. If expires is `Some()`, overwrites current allowance expiration with this one.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    DecreaseAllowance {
        spender: String,
        amount: Uint128,
        expires: Option<Expiration>
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "decrease_allowance": {
    "spender": "terra...",
    "amount": 10000000,
    "expires": {}
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type                | Description     |
| ----------- | ------------------- | --------------- |
| `spender`   | String              | Spender address |
| `amount`    | Uint128             | Amount          |
| `expires`\* | Option\<Expiration> | Expiration      |

\* = optional

### `TransferFrom`

Only with "approval" extension. Transfers amount tokens from owner -> recipient if `env.sender` has sufficient pre-approval.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    TransferFrom {
        owner: String,
        recipient: String,
        amount: Uint128
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "transfer_from": {
    "owner": "terra...",
    "recipient": "terra...",
    "amount": 10000000
  }
}
```

{% endtab %}
{% endtabs %}

| Key         | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| `owner`     | String  | Owner address                |
| `recipient` | String  | Recipient address            |
| `amount`    | Uint128 | Amount of tokens to transfer |

### `SendFrom`

Only with "approval" extension. Sends amount tokens from owner -> contract if `info.sender` has sufficient pre-approval.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    SendFrom {
        owner: String,
        contract: String,
        amount: Uint128, 
        msg: Binary
    } 
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "send_from": {
    "owner": "terra...",
    "contract": "terra...",
    "amount": 10000000, 
    "msg": 01001
  }
}
```

{% endtab %}
{% endtabs %}

| Key        | Type    | Description              |
| ---------- | ------- | ------------------------ |
| `owner`    | String  | Owner address            |
| `contract` | String  | Contract address         |
| `amount`   | Uint128 | Amount of tokens to send |
| `msg`      | Binary  | Binary message           |

### `UpdateMarketing`

Only with the "marketing" extension. If authorized, updates marketing metadata. Setting None/null for any of these will leave it unchanged. Setting `Some("")` will clear this field on the contract storage.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    UpdateMarketing {
        project: Option<String>,
        description: Option<String>,
        marketing: Option<String>
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "update_marketing": {
    "project": "...",
    "description": "...",
    "marketing": "..."
  }
}
```

{% endtab %}
{% endtabs %}

| Key             | Type   | Description                                                                       |
| --------------- | ------ | --------------------------------------------------------------------------------- |
| `project`\*     | String | A URL pointing to the project behind this token                                   |
| `description`\* | String | A longer description of the token and it's utility. Designed for tooltips or such |
| `marketing`\*   | String | The address (if any) who can update this data structure                           |

\* = optional

### `UploadLogo`

If set as the "marketing" role on the contract, upload a new URL, SVG, or PNG for the token`.`

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    UploadLogo(Logo)
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "upload_logo": "logo.png"
}
```

{% endtab %}
{% endtabs %}

## QueryMsg

### `Balance`

Returns the current balance of the given address, 0 if unset.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    address: String
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "balance": {
    "address": "terra..." 
  }
}
```

{% endtab %}
{% endtabs %}

| Key       | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| `address` | String | Address to return current balance from |

### `BalanceAndTotalSupply`

Returns both balance (0 if unset) and total supply. Used by incentives contract when computing unclaimed rewards.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    BalanceAndTotalSupply {
        address: String
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "balance_and_total_supply": {
    "address": "terra..." 
  }
}
```

{% endtab %}
{% endtabs %}

| Key       | Type   | Description      |
| --------- | ------ | ---------------- |
| `address` | String | Address to query |

### `TokenInfo`

Returns metadata on the contract - name, decimals, supply, etc.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    TokenInfo {}
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "token_info": {}
}
```

{% endtab %}
{% endtabs %}

### `Minter`

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Minter {}
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "minter": {}
}
```

{% endtab %}
{% endtabs %}

### `Allowance`

Only with "allowance" extension. Returns how much spender can use from owner account, 0 if unset.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Allowance {
        owner: String,
        spender: String
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "allowance": {
    "owner": "terra...",
    "spender": "...",
  }
}
```

{% endtab %}
{% endtabs %}

| Key       | Type   | Description     |
| --------- | ------ | --------------- |
| `owner`   | String | Owner address   |
| `spender` | String | Spender address |

### `AllAllowances`

Only with "enumerable" extension (and "allowances"). Returns all allowances this owner has approved. Supports pagination.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    AllAllowances {
        owner: String,
        start_after: Option<String>,
        limit: Option<u32>
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "all_allowances": {
    "owner": "terra...",
    "start_after": "terra...",
    "limit": 100,
  }
}
```

{% endtab %}
{% endtabs %}

| Key             | Type   | Description            |
| --------------- | ------ | ---------------------- |
| `owner`         | String | Owner address          |
| `start_after`\* | String | Address to start after |
| `limit`\*       | u32    | Limit to query         |

\* = optional

### `AllAccounts`

Only with "enumerable" extension. Returns all accounts that have balances. Supports pagination.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    start_after: Option<String>,
    limit: Option<u32>
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "all_accounts": {
    "start_after": "terra...",
    "limit": 100,
  }
}
```

{% endtab %}
{% endtabs %}

| Key             | Type   | Description            |
| --------------- | ------ | ---------------------- |
| `start_after`\* | String | Address to start after |
| `limit`\*       | u32    | Limit                  |

\* = optional

### `MarketingInfo`

Only with "marketing" extension. Returns more metadata on the contract to display in the client: description, logo, project url, etc.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    MarketingInfo {}
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "marketing_info": {}
}
```

{% endtab %}
{% endtabs %}

### `DownloadLogo`

Only with "marketing" extension. Downloads the embedded logo data (if stored on-chain). Errors if no logo data is stored for this contract.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    DownloadLogo {}
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "download_logo": {}
}
```

{% endtab %}
{% endtabs %}

### `UnderlyingAssetBalance`

Returns the underlying asset amount for given address.

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    UnderlyingAssetBalance {
        address: String
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "underlying_asset_balance": {
    "address": "terra..."
  }
}
```

{% endtab %}
{% endtabs %}

| Key       | Type   | Description                               |
| --------- | ------ | ----------------------------------------- |
| `address` | String | Address to return underlying asset amount |

## Structs

### `BalanceAndTotalSupplyResponse`

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct BalanceAndTotalSupplyResponse {
    pub balance: Uint128,
    pub total_supply: Uint128,
}
```

| Key            | Type    | Description  |
| -------------- | ------- | ------------ |
| `balance`      | Uint128 | Balance      |
| `total_supply` | Uint128 | Total supply |