🔰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..."
}

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"
  }
}

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"
        }
      }
    }
  }
}

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"
    }
  }
}

OpenPosition

Creates a new position to earn flow rewards.

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

ExpandPosition

Expands an existing position to earn more flow rewards.

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

ClosePosition

Closes an existing position to stop earning flow rewards.

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

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"
    }
  }
}

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
  }
}

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
      ]
    }
  }
}

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
  }
}

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
        ]
      }
    }
  ]
}

Positions

Retrieves the positions for an address.

Query

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

Response (PositionsResponse)

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

Rewards

Retrieves the rewards for an address.

Query

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

Response (RewardsResponse)

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

GlobalWeight

Retrieves the global weight for an epoch.

Query

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

Response (GlobalWeightResponse)

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

CurrentEpochRewardsShare

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

Query

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

Response (RewardsShareResponse)

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