> 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/incentives.md).

# Incentives

The Incentives contract manages MARS incentives for maToken holders (depositors).

## Links

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

## Config

| Key                        | Type          | Description                                                   |
| -------------------------- | ------------- | ------------------------------------------------------------- |
| `owner`                    | CanonicalAddr | Contract owner                                                |
| `address_provider_address` | String        | Address provider returns addresses for all protocol contracts |

## InstantiateMsg

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

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct InstantiateMsg {
    pub owner: String, 
    pub address_provider_address: String,
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "owner": "terra...", 
  "address_provider_address": "...", 
}
```

{% endtab %}
{% endtabs %}

| Key                        | Type   | Description                                                   |
| -------------------------- | ------ | ------------------------------------------------------------- |
| `owner`                    | String | Contract owner                                                |
| `address_provider_address` | String | Address provider returns addresses for all protocol contracts |

## ExecuteMsg

### `UpdateConfig`

Updates contract config. Only callable by owner.

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

```rust
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Config {
        owner: Option<String>,
        address_provider_address: Option<String>
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "config": {
    "owner": "terra...",
    "address_provider_address": "terra..."
  }
}
```

{% endtab %}
{% endtabs %}

| Key                          | Type   | Description              |
| ---------------------------- | ------ | ------------------------ |
| `owner`\*                    | String | Owner contract address   |
| `address_provider_address`\* | String | Address Provider address |

\* = optional

### `SetAssetIncentive`

Sets emission per second for an asset to holders of its maToken.

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

```rust
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    SetAssetIncentive {
        ma_token_address: String,
        emission_per_second: Uint128,
    }
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "set_asset_incentive": {
    "ma_token_address": "terra...",
    "emission_per_second": 
  }
}
```

{% endtab %}
{% endtabs %}

| Key                   | Type    | Description                                                                           |
| --------------------- | ------- | ------------------------------------------------------------------------------------- |
| `ma_token_address`    | String  | maToken address associated with the incentives                                        |
| `emission_per_second` | Uint128 | How many MARS will be assigned per second to be distributed among all maToken holders |

### `BalanceChange`

Handle balance change updating user and asset rewards. Sent from an external contract, triggered on user balance changes. Will return an empty response if no incentive is applied for the asset.&#x20;

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

```rust
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    BalanceChange {
        user_address: Addr,
        user_balance_before: Uint128,
        total_supply_before: Uint128    
    } 
}
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "balance_change": {
    "user_address": "terra...",
    "user_balance_before":, 
    "total_supply_before":
  }
}
```

{% endtab %}
{% endtabs %}

| Key                   | Type    | Description                                                                                                 |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `user_address`        | String  | User address. Address is trusted as it must be validated by the maToken contract before calling this method |
| `user_balance_before` | Uint128 | User maToken balance up to the instant before the change                                                    |
| `total_supply_before` | Uint128 | Total maToken supply up to the instant before the change                                                    |

### `ClaimRewards`

Claim rewards. MARS rewards accrued by the user will be staked into xMARS before being sent.

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

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "claim_rewards": {}
}
```

{% endtab %}
{% endtabs %}

### `ExecuteCosmosMsg`

Execute Cosmos msg (only callable by owner).

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

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "execute_cosmos_msg": {}
}
```

{% endtab %}
{% endtabs %}

## QueryMsg

### `Config`

Query contract config.

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

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "config": {}
}
```

{% endtab %}
{% endtabs %}

### `AssetIncentive`

Query info about asset incentive for a given maToken.

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

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "asset_incentive": {
    "ma_token_address": "terra..."
  }
}
```

{% endtab %}
{% endtabs %}

| Key                | Type   | Description              |
| ------------------ | ------ | ------------------------ |
| `ma_token_address` | String | maToken contract address |

### `UserUnclaimedRewards`

Query user current unclaimed rewards.

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

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "user_unclaimed_rewards": {
    "user_address": "terra..."
  }
}
```

{% endtab %}
{% endtabs %}

| Key            | Type   | Description                             |
| -------------- | ------ | --------------------------------------- |
| `user_address` | String | User address to query unclaimed rewards |

## Structs

### `AssetIncentive`

Incentive Metadata for a given incentive.

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct AssetIncentive {
    pub emission_per_second: Uint128,
    pub index: Decimal,
    pub last_updated: u64,
}
```

| Key                   | Type    | Description                                                                       |
| --------------------- | ------- | --------------------------------------------------------------------------------- |
| `emission_per_second` | Uint128 | How much MARS per second is emitted to be then distributed to all maToken holders |
| `index`               | Decimal | Total MARS assigned for distribution since the start of the incentive             |
| `last_updated`        | u64     | Last time (in seconds) index was updated                                          |

### `AssetIncentiveResponse`

Response to `AssetIncentive` query.

```rust
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct AssetIncentiveResponse {
    pub asset_incentive: Option<AssetIncentive>,
}
```