Mars Protocol
Search…
πŸŒ‡
Fields of Mars
The Fields of Mars contract contains a leveraged yield farming strategy utilizing contract-to-contract (C2C) lending from Mars Protocol.

Links

Config

ConfigBase

1
#[ruderive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct ConfigBase<T> {
3
pub primary_asset_info: AssetInfoBase<T>,
4
pub secondary_asset_info: AssetInfoBase<T>,
5
pub astro_token_info: AssetInfoBase<T>,
6
pub primary_pair: PairBase<T>,
7
pub astro_pair: PairBase<T>,
8
pub astro_generator: GeneratorBase<T>,
9
pub red_bank: RedBankBase<T>,
10
pub oracle: OracleBase<T>,
11
pub treasury: T,
12
pub governance: T,
13
pub operators: Vec<T>,
14
pub max_ltv: Decimal,
15
pub fee_rate: Decimal,
16
pub bonus_rate: Decimal
17
}
Copied!
Key
Type
Description
primary_asset_info
AssetInfoBase<T>
Info of the primary asset (deposit). Primary asset is the asset which the user takes an implicit long position on when utilizing Martian Field.
secondary_asset_info
AssetInfoBase<T>
Info of the secondary asset (borrow). Secondary asset is the asset which the user takes an implicit short position on when utilizing Martian Field.
astro_token_info
AssetInfoBase<T>
Info of the Astroport token, the staking reward that will be paid out by Astro generator.
primary_pair
PairBase<T>
Astroport pair consisting of the primary and secondary assets. The liquidity token of this pair will be staked/bonded in Astro generator to earn ASTRO and optionally a proxy token reward.
astro_pair
PairBase<T>
Astroport pair consisting of ASTRO token and the secondary asset. This pair is used for swapping ASTRO reward so that it can be reinvested.
astro_generator
GeneratorBase<T>
The Astro generator contract
red_bank
RedBankBase<T>
The Mars Protocol money market contract. We borrow the secondary asset here
oracle
OracleBase<T>
The Mars Protocol oracle contract. We read prices of the primary and secondary assets here
treasury
T
Account to receive fee payments
governance
T
Account who can update config
operators
Vec<T>
Accounts who can harvest
max_ltv
Decimal
Maximum loan-to-value ratio (LTV) above which a user can be liquidated
fee_rate
Decimal
Percentage of profit to be charged as performance fee
bonus_rate
Decimal
During liquidation, percentage of the user's asset to be awared to the liquidator as bonus

ConfigUnchecked / Config

1
pub type ConfigUnchecked = ConfigBase<String>;
2
pub type Config = ConfigBase<Addr>;
Copied!

InstantiateMsg

Rust
JSON
1
pub type InstantiateMsg = ConfigUnchecked;
Copied!
1
{
2
"config_unchecked"
3
}
Copied!

ExecuteMsg

UpdateConfig

Update data stored in config (only governance can call).
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum ExecuteMsg {
4
UpdateConfig {
5
new_config: ConfigUnchecked
6
}
7
}
Copied!
1
{
2
"update_config": {
3
"new_config": { ... } // object of `ConfigUnchecked` type
4
}
5
}
Copied!

UpdatePosition

Updates the sender's position by executing a list of actions. After the actions are executed, the contract executes three more callbacks: 1. Refund all unlocked assets to the user. 2. Assert the position's LTV is below the liquidation threshold. If not, throw an error and revert all previous actions. 3. Delete cached data in storage.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum ExecuteMsg {
4
UpdatePosition(Vec<Action>)
5
}
Copied!
1
{
2
"update_position": [
3
"deposit": { ... }, // object of `AssetUnchecked` type
4
"borrow": {
5
"amount": "123"
6
},
7
"repay": {
8
"amount": "123"
9
},
10
"bond": {
11
"slippage_tolerance": "0.01"
12
},
13
"unbond": {
14
"bond_units_to_reduce": "123"
15
},
16
"swap": {
17
"offer_amount": "123"
18
"max_spread": "0.01"
19
}
20
]
21
}
Copied!

Harvest

Claim staking reward and reinvest.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum ExecuteMsg {
4
Harvest {
5
max_spread: Option<Decimal>,
6
slippage_tolerance: Option<Decimal>
7
}
8
}
Copied!
1
{
2
"harvest": {
3
"max_spread": "0.01",
4
"slippage_tolerance": "0.01"
5
}
6
}
Copied!
Key
Type
Description
max_spread*
Decimal
Used for ASTRO >> secondary swap and balancing operations
slippage_tolerance*
Decimal
Used for providing primary + secondary liquidity
* = optional

Liquidate

Force close an underfunded position, repay all debts, and return all remaining funds to the position's owner. The liquidator is awarded a portion of the remaining funds.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum ExecuteMsg {
4
Liquidate {
5
user: String
6
}
7
}
Copied!
1
{
2
"liquidate": {
3
"user": "terra..."
4
}
5
}
Copied!
Key
Type
Description
user
String
Address to liquidate

Callback

Callbacks; only callable by the strategy itself.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum ExecuteMsg {
4
Callback(CallbackMsg)
5
}
Copied!
1
{
2
"callback": {
3
"provide_liquidity": {
4
"user_addr": "terra...",
5
"slippage_tolerance": "0.01"
6
},
7
"withdraw_liquidity": {
8
"user_addr": "terra..."
9
},
10
"bond": {
11
"user_addr": "terra..."
12
},
13
"unbond": {
14
"user_addr": "terra...",
15
"bond_units_to_reduce": "123"
16
},
17
"borrow": {
18
"user_addr": "terra...",
19
"borrow_amount": "10000"
20
},
21
"repay": {
22
"user_addr": "terra...",
23
"repay_amount": "10000"
24
},
25
"swap": {
26
"user_addr": "terra...",
27
"offer_asset_info": "terra...",
28
"offer_amount": "10000",
29
"max_spread": "0.01"
30
},
31
"balance": {
32
"max_spread": "0.01"
33
},
34
"cover": {
35
"user_addr": "terra..."
36
}
37
"refund": {
38
"user_addr": "terra...",
39
"recipient_addr": "terra...",
40
"percentage": "0.01"
41
},
42
"assert_health": {
43
"user_addr": "terra..."
44
},
45
"clear_bad_debt": {
46
"user_addr": "terra..."
47
},
48
"purge_storage": {
49
"user_addr": "terra..."
50
},
51
"snapshot": {
52
"user_addr": "terra..."
53
}
54
}
55
}
Copied!

QueryMsg

Config

Return strategy configurations.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
Config {}
5
}
Copied!
1
{
2
"config": {}
3
}
Copied!

State

Return the global state of the strategy.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
State {}
5
}
Copied!
1
{
2
"state": {}
3
}
Copied!

Positions

Enumerate all user positions.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
Positions {
5
start_after: Option<String>,
6
limit: Option<u32>
7
}
8
}
Copied!
1
{
2
"positions": {
3
"start_after": "terra...",
4
"limit": 10
5
}
6
}
Copied!
Key
Type
Description
start_after*
String
Used for pagination
limit*
u32
Used for pagination
* = optional

Postion

Return data on an individual user's position.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
Position {
5
user: String
6
}
7
}
Copied!
1
{
2
"position": {
3
"user": "terra..."
4
}
5
}
Copied!
Key
Type
Description
user
String
Address to return data on individual positions

Health

Query the health of a user's position: value of assets, debts, and LTV.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
Health {
5
user: String
6
}
7
}
Copied!
1
{
2
"health": {
3
"user": "terra..."
4
}
5
}
Copied!
Key
Type
Description
user
String
Address to get health for

Snapshot

Query the snapshot of a user's position. NOTE: Snapshot is a temporary functionality used for calculating the user's PnL, which is to be displayed on the frontend. Once the frontend team has built an off-chain indexing facility that can calculate PnL without the use of snapshots, this query function will be removed.
Rust
JSON
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum QueryMsg {
4
Snapshot {
5
user: String
6
}
7
}
Copied!
1
{
2
"snapshot": {
3
"user": "terra..."
4
}
5
}
Copied!
Key
Type
Description
user
String
Address to get snapshot for

Structs

StateBase

Global state of the contract.
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct StateBase<T> {
3
pub total_bond_units: Uint128,
4
pub total_debt_units: Uint128,
5
pub pending_rewards: AssetListBase<T>
6
}
Copied!
Key
Type
Description
total_bond_units
Uint128
Total amount of bond units; used to calculate each user's share of bonded LP tokens
total_debt_units
Uint128
Total amount of debt units; used to calculate each user's share of the debt
pending_rewards
AssetListBase<T>
Reward tokens that can be reinvested in the next harvest

PositionBase

Info of individual users' positions.
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct StateBase<T> {
3
pub total_bond_units: Uint128,
4
pub total_debt_units: Uint128,
5
pub pending_rewards: AssetListBase<T>
6
}
Copied!
Key
Type
Description
total_bond_units
Uint128
Total amount of bond units; used to calculate each user's share of bonded LP tokens
total_debt_units
Uint128
Total amount of debt units; used to calculate each user's share of the debt
pending_rewards
AssetListBase<T>
Reward tokens that can be reinvested in the next harvest

Health

Info of individual users' health.
1
#[derive(Default, Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct Health {
3
pub bond_amount: Uint128,
4
pub bond_value: Uint128,
5
pub debt_amount: Uint128,
6
pub debt_value: Uint128,
7
pub ltv: Option<Decimal>
8
}
Copied!
Key
Type
Description
bond_amount
Uint128
Amount of primary pair liquidity tokens owned by this position
bond_value
Uint128
Value of the position's asset, measured in the short asset
debt_amount
Uint128
Amount of secondary assets owed by this position
debt_value
Uint
Value of the position's debt, measured in the short asset
ltv*
Decimal
The ratio of debt_value to bond_value; None if bond_value is zero
* = optional

Snapshot

Every time the user invokes update_position, we record a snaphot of the position. This snapshot does not have any impact on the contract's normal functioning. Rather it is used by the frontend to calculate PnL. Once we have the infrastructure for calculating PnL off-chain available, we will migrate the contract to delete this.
1
#[derive(Default, Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct Snapshot {
3
pub time: u64,
4
pub height: u64,
5
pub position: PositionUnchecked,
6
pub health: Health
7
}
Copied!
Key
Type
Description
time
u64
​
height
u64
​
position
​
Info of individual users' positions
health
​
Info of individual users' positions

PositionsResponseItem

1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
pub struct PositionsResponseItem {
3
pub user: String,
4
pub position: PositionUnchecked
5
}
Copied!
Key
Text
Text
user
String
​
position
​
​

Enums

Action

Defines a list of actions that users can perform on their positions.
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum Action {
4
Deposit(AssetUnchecked),
5
Borrow {
6
amount: Uint128
7
},
8
Repay {
9
amount: Uint128
10
},
11
Bond {
12
slippage_tolerance: Option<Decimal>
13
},
14
Unbond {
15
bond_units_to_reduce: Uint128
16
},
17
Swap {
18
offer_amount: Uint128,
19
max_spread: Option<Decimal>
20
}
21
}
Copied!
Function
Description
Keys/Types
Deposit
Deposit asset of specified type and amount
​
Borrow
Borrow secondary asset of specified amount from Red Bank
  • amount: Uint 128
Repay
Repay secondary asset of specified amount to Red Bank
  • amount: Uint 128
Bond
Provide all unlocked primary and secondary asset to Astroport pair, and bond the received liquidity tokens to the staking pool
  • slippage_tolerance* : Decimal
Unbond
Burn a specified amount bond units, unbond liquidity tokens of corresponding amount from the staking pool and withdraw liquidity
  • bond_units_to_reduce: Uint 128
Swap
Swap a specified amount of unlocked primary asset to the secondary asset
  • offer_amount : Uint128
  • max_spread* : Decimal
* = optional

CallbackMsg

Since CallbackMsg are always sent by the contract itself, we assume all types are already validated and don't do additional checks. E.g. user addresses are Addr instead of String.
1
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
2
#[serde(rename_all = "snake_case")]
3
pub enum CallbackMsg {
4
ProvideLiquidity {
5
user_addr: Option<Addr>,
6
slippage_tolerance: Option<Decimal>
7
},
8
WithdrawLiquidity {
9
user_addr: Addr
10
},
11
Bond {
12
user_addr: Option<Addr>
13
},
14
Unbond {
15
user_addr: Addr,
16
bond_units_to_reduce: Uint128
17
},
18
Borrow {
19
user_addr: Addr,
20
borrow_amount: Uint128
21
},
22
Repay{
23
user_addr: Addr,
24
repay_amount: Option<Uint128>
25
},
26
Swap {
27
user_addr: Option<Addr>,
28
offer_asset_info: AssetInfo,
29
offer_amount: Option<Uint128>,
30
max_spread: Option<Decimal>
31
},
32
Balance {
33
max_spread: Option<Decimal>
34
},
35
Cover {
36
user_addr: Addr
37
},
38
Refund {
39
user_addr: Addr,
40
recipient_addr: Addr,
41
percentage: Decimal
42
},
43
AssertHealth {
44
user_addr: Addr
45
},
46
ClearBadDebt {
47
user_addr: Addr
48
},
49
PurgeStorage {
50
user_addr: Addr
51
},
52
Snapshot {
53
user_addr: Addr
54
}
55
}
Copied!
Function
Description
Keys/Types
provide_liquidity
Provides unlocked primary & secondary assets to the AMM pool, receive share tokens; Reduce the user's unlocked primary & secondary asset amounts to zero; Increase the user's unlocked share token amount
  • user_addr* : String
  • slippage_tolerance* : Decimal
withdraw_liquidity
Burns the user's unlocked share tokens, receive primary & secondary assets; Reduce the user's unlocked share token amount to zero; Increase the user's unlocked primary & secondary asset amounts
  • user_addr: String
bond
Bonds share tokens to the staking contract; Reduce the user's unlocked share token amount to zero; Increase the user's bond units
  • user_addr* : String
unbond
Unbonds share tokens from the staking contract; Reduce the user's bond units; Increase the user's unlocked share token amount
  • user_addr: Addr
  • bond_units_to_reduce: Uint128
borrow
Borrows specified amount of secondary asset from Red Bank; Increase the user's debt units; Increase the user's unlocked secondary asset amount
  • user_addr: Addr
  • borrow_amount: Uint128
repay
Repays specified amount of secondary asset to Red Bank; Reduce the user's debt units; Reduce the user's unlocked secondary asset amount.
  • user_addr: String
  • repay_amount*: Uint128
swap
Swaps a specified amount of primary asset to secondary asset; Reduce the user's unlocked primary asset amount; Increase the user's unlocked secondary asset amount;
  • user_addr*: String
  • offer_asset_info: String
  • offer_amount*: Uint128
  • max_spread*: Decimal
balance
Swaps the primary and secondary assets currently held by the contract as pending rewards, such that the two assets have the same value and can be reinvested. Only used during the Harvest function call
max_spread*: Decimal
cover
Sells an appropriate amount of a user's unlocked primary asset, such that the user has enough unlocked secondary asset to fully pay off debt. Only used during the Liquidate function call
  • user_addr: String
refund
Sends a percentage of a user's unlocked primary & seoncdary asset to a recipient; default to the user if unspecified. Reduce the user's primary & secondary asset amounts
  • user_addr: String
  • recipient_addr: String
  • percentage: Decimal
assert_health
Calculates a user's current LTV. If below the maximum LTV, emits a position_updated event; if above the maximum LTV, throw an error
  • user_addr: String
clear_bad_debt
Check whether the user still has an outstanding debt. If no, do nothing. If yes, waive the debt from the user's position, and emit a bad_debt event
  • user_addr: String
purge_storage
Remove the user's position from contract storage if it is empty. Invoked at the end of update_position and liquidate callback chains
  • user_addr: String
snapshot
See the comment on struct Snapshot. This callback should be removed at some point after launch when our tx indexing infrastructure is ready
  • user_addr: String
* = optional