# Liquidity Incentive

The `x/liquidityincentive` module incentivizes liquidity providers by distributing rewards based on their contributions to liquidity pools. It uses an epoch-based reward system and a gauge voting mechanism to allocate rewards dynamically. This module ensures sustainable liquidity provisioning while allowing users to participate in governance through gauge voting.

See the [Bribes](/learn/sunrise/liquidity-incentive/bribes.md) for more information on the bribe feature.

## Key Features

1. **Epoch-Based Reward Distribution**:
   * Rewards are distributed at the end of each epoch.
   * Lazy accounting minimizes computational overhead by calculating rewards only when claimed.
2. **Gauge Voting**:
   * Users can vote on which liquidity pools should receive incentives.
   * Voting power is determined by **`vRISE`** tokens (non-transferable staking tokens).
3. **Lazy Accounting for Rewards**:
   * Rewards are tracked using accumulators and distributed only when users claim them.
   * This reduces the computational load on the network.
4. **Dynamic Incentive Allocation**:
   * Incentives are allocated based on pool weights (gauges) determined through voting.

## **Core Concepts**

### Epochs

> **Note:** The following section covers advanced topics intended for experienced users or developers.

* Two epochs exist concurrently:
  1. **Past Epoch**: The epoch that has ended.
  2. **Current Epoch**: The ongoing epoch.
* Each epoch has the following parameters:
  * **`id`**: The unique epoch ID.
  * **`start_block`**: The block where the epoch begins.
  * **`start_time`**: The Unix time where the epoch begins.
  * **`end_block`**: The block where the epoch ends.
  * **`gauges`**: A list of gauges (pool weights) for incentive distribution.

### Gauge

> **Note:** The following section covers advanced topics intended for experienced users or developers.

* A gauge represents a specific liquidity pool's weight in reward allocation.
* Parameters:
  * **`pool_id`**: The ID of the liquidity pool.
  * **`voting_power`**: The voting power allocated to this pool.

### Lazy Accounting

* Rewards are not distributed immediately but are calculated when claimed.
* Formula for calculating rewards:

$$
\text{ClaimAmount}*{ij} = \frac{\text{PositionUnclaimedAccumulation}*{ij}}{\text{PoolUnclaimedAccumulation}*{i}} \times \text{PoolUnclaimed}*{i}
$$

## Workflow

{% @mermaid/diagram content="graph TD
A{User A}-->|Provide Liquidity|B((Pool B))
A-->|Register a Bribe|C((Gauge for Pool B))
D{Users}-->|Vote|C
C-.->|Distribute the Bribe|D
C-.->|Allocate more vRISE|B
B-.->|Distribute vRISE incentives|A" %}

### BeginBlocker

1. Transfers a portion of inflation rewards from the Fee Collector account to the **`x/liquidityincentive`** module account.
2. Rewards are converted to **`vRISE`** tokens (non-transferable staking tokens).
3. Rewards are accumulated in each pool's fee accumulator.

### MsgClaimRewards (`x/liquiditypool`)

* Users claim rewards by interacting with their positions in liquidity pools.

> **Note:**\
> The rewards discussed here are specifically **Gauge Voting rewards, allocated according to your vRISE voting power**.\
> These are distinct from standard LP rewards.\
> You claim Gauge Voting rewards by participating in Gauge Voting with your vRISE, which determines your share of the rewards for each pool per epoch.

## Sequence Diagram: Reward Distribution

> **Note:** The following section covers advanced topics intended for experienced users or developers.

{% @mermaid/diagram content="sequenceDiagram
participant User as Liquidity Provider
participant LiquidityPool as x/liquiditypool Module
participant IncentiveModule as x/liquidityincentive Module
participant Distribution as x/distribution Module

```
User->>LiquidityPool: Provide Liquidity
LiquidityPool->>IncentiveModule: Track Position Accumulation
IncentiveModule->>Distribution: Transfer Inflation Rewards
User->>IncentiveModule: Claim Rewards
IncentiveModule->>User: Calculate and Distribute Rewards" %}
```

## Parameters

| Parameter              | Default | Units  | Description                                         |
| ---------------------- | ------- | ------ | --------------------------------------------------- |
| epoch\_blocks          | 4,320   | blocks | Number of blocks per epoch (approximately 12 days)  |
| staking\_reward\_ratio | 0.50    | ratio  | Ratio of vRISE allocated to staking (50%)           |
| bribe\_claim\_epochs   | 5       | epochs | Number of epochs during which bribes can be claimed |

### Parameter Details

1. **epoch\_blocks**
   * Defines the length of each epoch in blocks
   * Default value is approximately 12 days (`DefaultParams().BlocksPerYear/365*12`)
   * Controls epoch start and end, determining reward distribution timing
2. **staking\_reward\_ratio**
   * Ratio of newly minted vRISE tokens allocated to staking rewards
   * Default value is 50% (`math.LegacyNewDecWithPrec(50, 2)`)
   * Remaining 50% is used for liquidity incentives
3. **bribe\_claim\_epochs**
   * Defines the period during which bribes can be claimed in epochs
   * Default value is 5 epochs
   * Bribes cannot be claimed after this period expires

These parameters can be updated through governance. Parameter changes can significantly impact system behavior and should be carefully considered.

## Messages

The module provides various message types:

* MsgUpdateParams: Update module parameters (governance operation)
* MsgStartNewEpoch: Start a new epoch
* MsgVoteGauge: Vote on pool weights for reward distribution
* MsgRegisterBribe: Register a bribe for a specific pool and epoch
* MsgClaimBribes: Claim accumulated bribes

## Queries

The module provides various query endpoints:

* Params: Query module parameters
* Epoch: Get details of a specific epoch
* Epochs: List all epochs
* Vote: Get voting information for a specific address
* Votes: List all votes
* Bribe: Get details of a specific bribe
* Bribes: List all bribes with optional filters
* BribeAllocation: Get bribe allocation for a specific address, epoch, and pool
* BribeAllocations: List all bribe allocations with optional filters
* TallyResult: Get the tally result for the next epoch

See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/liquidityincentive) for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sunriselayer.io/learn/sunrise/liquidity-incentive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.