🔰Incentive

The incentive contract is responsible for distributing the flow rewards to the LPs. It is also responsible for managing the liquidity flows and positions. Incentive contracts allow any user to incentivize a pool. External users can then create positions to get rewards from flows by locking their LP tokens. Users will receive rewards for each active flow.

What is a flow?

So every incentive contract is able to have multiple flows. A flow is a stream of rewards that are distributed among users who lock their LP tokens. A flow has a start and end epoch, and a curve that determines how the rewards are distributed. A flow can be open, expanded and closed.

A flow is open when it is created, and users can add to their positions.

The flow can only be closed by the flow creator or the contract admin. When a flow is closed, the unclaimed rewards are returned to the creator.

The flow can be expanded indefinitely, but due to some limitations, the flow gets "reset" after a period of 180 epochs. When a flow gets reset, nothing changes for you as a flow creator in practice, as the flow continues to distribute rewards as usual. If you are a user however, you will need to claim your rewards within those 180 epochs (about 6 months), otherwise you will lose the rewards you were entitled to as they will become claimable by all the LP holders.

Instantiate

Instantiates an instance of the incentive contract

{
  "lp_asset": {
    "native_token": {
      "denom": "factory/migaloo1.../uLP"
    }
  },
  "fee_distributor_address": "migaloo1..."
}

Key	Type	Description
lp_asset	AssetInfo	Information about the LP asset
fee_distributor_address	String	Fee distributor contract address

ExecuteMsg

TakeGlobalWeightSnapshot

Makes a snapshot of the current global weight, at the current epoch. Used to accurately calculate the rewards share.

{
  "take_global_weight_snapshot": {}
}

OpenFlow

Opens a new liquidity flow.

{
  "open_flow": {
    "start_epoch": 123,
    "end_epoch": 123,
    "curve": "linear",
    "flow_asset": {
      "amount": "1000000",
      "native_token": {
        "denom": "uwhale"
      }
    },
    "flow_label": "my_alias"
  }
}

Key	Type	Description
start_epoch	Option<u64>	The epoch at which the flow should start. If unspecified, the flow will start at the current epoch.
end_epoch	Option<u64>	The epoch at which the flow should end. If unspecified, the flow will end in 14 epochs, or 2 weeks if the epoch is set to last a day.
curve	Option<Curve>	The type of distribution curve. If not set, the default curve will be Linear.
flow_asset	Asset	The asset to be distributed in this flow.
flow_label	Option<String>	If set, the label will be used to identify the flow, in addition to the flow_id.

Expand Flow

Expands an existing flow.

{
  "expand_flow": {
    "flow_identifier": {
      "label": "my_alias"
    },
    "end_epoch": 123,
    "flow_asset": {
      "amount": "1000000",
      "info": {
        "native_token": {
          "denom": "uwhale"
        }
      }
    }
  }
}

Key	Type	Description
flow_identifier	FlowIdentifier	The identifier of the flow to expand, whether an id or a label.
end_epoch	Option<u64>	The epoch at which the flow should end. If not set, the flow will be expanded a default value of 14 epochs.
flow_asset	Asset	The asset to expand this flow with.

CloseFlow

Closes an existing liquidity flow. Sender of the message must either be the contract admin or the creator of the flow.

Close Flow with a Flow ID

{
  "close_flow": {
    "flow_identifier": {
      "id": 123
    }
  }
}

Close Flow with a Flow Label

{
  "close_flow": {
    "flow_identifier": {
      "label": "my_alias"
    }
  }
}

Key	Type	Description
flow_identifier	FlowIdentifier	The identifier of the flow to close.

OpenPosition

Creates a new position to earn flow rewards.

{
  "open_position": {
    "amount": "1000000",
    "unbonding_duration": 123456789,
    "receiver": "juno1..."
  }
}

Key	Type	Description
amount	Uint128	The amount to add to the position.
unbonding_duration	u64	The amount of time (in seconds) before the LP tokens can be redeemed.
receiver	Option<String>	The receiver of the new position. This is mostly used for the frontend helper contract. If left empty, defaults to the message sender.

ExpandPosition

Expands an existing position to earn more flow rewards.

{
  "expand_position": {
    "amount": "1000000",
    "unbonding_duration": 123456789,
    "receiver": "migaloo1..."
  }
}

Key	Type	Description
amount	Uint128	The amount to add to the existing position.
unbonding_duration	u64	The unbond completion timestamp to identify the position to add to.
receiver	Option<String>	The receiver of the expanded position. This is mostly used for the frontend helper contract. If left empty, defaults to the message sender.

ClosePosition

Closes an existing position to stop earning flow rewards.

{
  "close_position": {
    "unbonding_duration": 123456789
  }
}

Key	Type	Description
unbonding_duration	u64	The unbonding duration of the position to close.

Withdraw

Withdraws the LP tokens from a closed position once the unbonding duration has passed.

{
  "withdraw": {}
}

Claim

Claims the flow rewards.

{
  "claim": {}
}

QueryMsg

Config

Retrieves the current contract configuration.

Query

{
  "config": {}
}

Response (ConfigResponse)

{
  "factory_address": "migaloo1...",
  "fee_distributor_address": "migaloo1...",
  "lp_asset": {
    "native_token": {
      "denom": "factory/migaloo1.../uLP"
    }
  }
}

Key	Type	Description
factory_address	Addr	The address of the incentive factory
fee_distributor_address	Addr	Fee distributor contract
lp_asset	AssetInfo	The LP token asset tied to the incentive contract

Flow

Retrieves a specific flow. If start_epoch and end_epoch are set, the asset_history and emitted_tokens will be filtered to only include epochs within the range. The maximum gap between the start_epoch and end_epoch is 100 epochs.

Query

{
  "flow": {
    "flow_identifier": {
      "id": 123
    },
    "start_epoch": 1500,
    "end_epoch": 1600
  }
}

Key	Type	Description
flow_identifier	FlowIdentifier	The id of the flow to find.
start_epoch	Option<u64>	If set, filters the asset_history and emitted_tokens to only include epochs from start_epoch
end_epoch	Option<u64>	If set, filters the asset_history and emitted_tokens to only include epochs until end_epoch

Response (FlowResponse)

{
  "flow": {
    "flow_id": 1,
    "flow_label": "my_alias",
    "flow_creator": "migaloo1...",
    "flow_asset": {
      "info": {
        "native_token": {
          "denom": "uwhale"
        }
      },
      "amount": "10000000"
    },
    "claimed_amount": "500000000",
    "curve": "linear",
    "start_epoch": 100,
    "end_epoch": 200,
    "emitted_tokens": {
      "1": "10000000",
      "2": "20000000"
    },
    "asset_history": {
      "1": [
        "5000000",
        100
      ],
      "2": [
        "6000000",
        150
      ]
    }
  }
}

Key	Type	Description
flow	Option<Flow>	The flow that was searched for

Flows

Retrieves the current flows. If start_epoch and end_epoch are set, the asset_history and emitted_tokens will be filtered to only include epochs within the range. The maximum gap between the start_epoch and end_epoch is 100 epochs.

Query

{
  "flows": {
    "start_epoch": 1500,
    "end_epoch": 1600
  }
}

Key	Type	Description
start_epoch	Option<u64>	If set, filters the asset_history and emitted_tokens to only include epochs from start_epoch
end_epoch	Option<u64>	If set, filters the asset_history and emitted_tokens to only include epochs until end_epoch

Response (FlowsResponse)

{
  "flows": [
    {
      "flow_id": 1,
      "flow_label": "my_alias",
      "flow_creator": "migaloo1...",
      "flow_asset": {
        "info": {
          "native_token": {
            "denom": "uwhale"
          }
        },
        "amount": "10000000"
      },
      "claimed_amount": "500000000",
      "curve": "linear",
      "start_epoch": 100,
      "end_epoch": 200,
      "emitted_tokens": {
        "1": "10000000",
        "2": "20000000"
      },
      "asset_history": {
        "1": [
          "5000000",
          100
        ],
        "2": [
          "6000000",
          150
        ]
      }
    },
    {
      "flow_id": 2,
      "flow_label": "another_alias",
      "flow_creator": "migaloo1...",
      "flow_asset": {
        "info": {
          "native_token": {
            "denom": "uwhale"
          }
        },
        "amount": "10000000"
      },
      "claimed_amount": "500000000",
      "curve": "linear",
      "start_epoch": 100,
      "end_epoch": 200,
      "emitted_tokens": {
        "1": "10000000",
        "2": "20000000",
        "3": "30000000"
      },
      "asset_history": {
        "1": [
          "5000000",
          100
        ],
        "2": [
          "6000000",
          150
        ]
      }
    }
  ]
}

Key	Type	Description
flows	Vec	The current flows

Positions

Retrieves the positions for an address.

Query

{
  "positions": {
    "address": "migaloo1..."
  }
}

Key	Type	Description
address	String	The address to query.

Response (PositionsResponse)

{
  "timestamp": 123456789,
  "positions": [
    {
      "open_position": {
        "amount": "1000000000",
        "unbonding_duration": 3600,
        "weight": "500000000"
      }
    },
    {
      "closed_position": {
        "amount": "5000",
        "unbonding_duration": 86400,
        "weight": "500000000"
      }
    }
  ]
}

Key	Type	Description
timestamp	u64	The current time of the blockchain
positions	Vec<QueryPosition>	All the positions a user has

Rewards

Retrieves the rewards for an address.

Query

{
  "rewards": {
    "address": "juno1..."
  }
}

Key	Type	Description
address	String	The address to query.

Response (RewardsResponse)

{
  "rewards": [
    {
      "amount": "10000000",
      "info": {
        "native_token": {
          "denom": "uwhale"
        }
      }
    },
    {
      "amount": "500000",
      "info": {
        "token": {
          "contract_addr": "migaloo1..."
        }
      }
    }
  ]
}

Key	Type	Description
rewards	Vec<Asset>	The rewards that is available to a user if they executed the claim function at this point

GlobalWeight

Retrieves the global weight for an epoch.

Query

{
  "global_weight": {
    "epoch_id": 123
  }
}

Key	Type	Description
epoch_id	u64	The epoch to get the global weight for.

Response (GlobalWeightResponse)

{
  "global_weight": "1000000000",
  "epoch_id": 123456
}

Key	Type	Description
global_weight	Uint128	The global weight of the incentive contract for the given epoch
epoch_id	u64	Epoch id for which the global weight is calculated

CurrentEpochRewardsShare

Retrieves the rewards share of an address for the current epoch.

Query

{
  "current_epoch_rewards_share": {
    "address": "migaloo1..."
  }
}

Key	Type	Description
address	String	The address to query.

Response (RewardsShareResponse)

{
  "address": "migaloo1...",
  "global_weight": "1000000",
  "address_weight": "500000",
  "share": "0.5",
  "epoch_id": 123456
}

Key	Type	Description
address	Addr	The address the rewards were retrieved for
global_weight	Uint128	The global weight of the incentive contract for the given epoch
address_weight	Uint128	The weight of the address
share	Decimal256	The rewards share of the address
epoch_id	u64	The epoch which the rewards were computed for