# Liquidity Provider Distribution (LPD)

## Why LPD?

[Code design document](https://www.notion.so/sifchain/Liquidity-Provider-Distribution-Design-Document-external-4d864ac74f3c497388942707da832c74#136ee3995bfb400d9c6a0ac775af85da)

### Monetary Policy

LPD addresses three different problems. The first is the same problem addressed by other versions of Protocol Monetary Trading Policy (PMTP) like [Ratio Shifting PMTP](https://hackmd.io/vrCeYGvURZio4yWc-ChYzA).

Problem Statement:

- Premise: Through inflation, Rowan holders use a standard tool in the cryptocurrency monetary policy toolkit.
- Problem: Rowan holders seek alternative monetary policy options.
- Solution: Protocol Monetary Trade Policy is a viable alternative, using Sifchain’s liquidity to influence trade on its DEX.

We will refer to this feature as LPD, LPD monetary policy, or LPD PMTP in this document and will update other documents referring to PMTP to clarify that PMTP is a class of features rather than just one feature. We will refer to the original version of PMTP as Ratio Shifting, Ratio Shifting monetary policy, or Ratio Shifting PMTP.

### Burning Alternative

LPD also addresses user concerns about inflation and a desire to burn tokens.

Problem Statement:

- Premise: For a fixed liquid market cap and an increasing circulating supply, the value of each token decreases alongside inflation. As such, users of inflating currencies often call for a token burn to reduce circulating supply in the hopes of increasing the value of each token.
- Problem: Burn models require a cryptoeconomic value pump to acquire the tokens to burn, meaning they are quite limited in the amount of tokens they can remove from circulating supply.
- Solution: LPD removes tokens from the "effective circulating supply" without burning them, enabling it to have a more impactful effect on token value.

### Cover for Pool Ratio Adjustment

Finally, LPD can be used to maintain Rowan's purchasing power increases while Sifchain's pool ratios are adjusted in a way that would otherwise decrease Rowan's purchasing power.

Problem Statement:

- Premise: A Ratio Shifting monetary policy can change Sifchain's pool ratios to increase Rowan's purchasing power
- Problem: Moving those pools back to towards a 50:50 ratio would reduce Rowan's purchasing power, all else being equal
- Solution: LPD can be used to maintain Rowan's purchasing power (or even increase it) while a Ratio Shifting policy adjusted Sifchain's pool ratios back down to 50:50

## How Does LPD Work?

### Variable Definitions

#### Chain State
The chain state is the set of information from the consensus protocol. This is exogenous to the model of the liquidity pool in that blocks are validated without feedback loop that prevents the operation of the protocol. The variables specified below are the state of the chain necessary to be read by the LPD monetary policy.

| Variable Name | Descriptive Name | Description | Symbol |
|----|----|----|----|
| start_block_height | Start Block Height| First block of a given policy period| $h_S$ |
| final_block_height| Final Block Height | Last block of a given policy period| $h_F$ |
| current_block | Current Block | Current block | $h$ |

#### Governance Decision
The governance decision is a policy input message that broadcasts a specified $r_{gov}$ for a specified length of time $l_{policy}$, with a computable $r_{final}$ as the intentional end-state of the policy at the end of its effective life at $h_f$.

| Variable Name | Descriptive Name | Description | Symbol | Domain|
|----|----|----|----|----|
| epoch_length | Epoch Length | Number of blocks in an epoch | $l_{epoch}$ | $\mathcal{I} \geq 0$ |
| policy_length_in_epochs | Policy Length in Epochs | Number of epochs in the policy; the specific governance policy period resulting from one particular vote | $l_{policy}$ |$\mathcal{I} \geq 0$ |
| gov_rate | Governance Rate | Per-epoch (approximately daily) rate of purchasing power increase voted in by governance | $r_{gov}$ | [0,1]|
| final_compounded_rate | Final Compounded Rate | Overall rate of increase over the policy length| $r_{final}$|[0,1]|

**Assumption: epoch_length is a governance design, where there is the need for the consensus protocol to execute an epoch module.**

**final_compounded_rate is a metric of gov_rate and policy_length_in_epochs**

#### Liquidity Pool Module State
Receives LPD policy through governance decision, updating its parameters for $r_{gov}$ and $l_{policy}$. Combining this policy with the production of blocks from the protocol, allows for the computation of $r_{block}$ and $r_{running}$.

| Variable Name | Descriptive Name | Description | Symbol |
|----|----|----|----|
| block_rate | Block Rate| Incremental increase on a per block basis to reach ${final\_compounded\_rate}$ | $r_{block}$|
| running_rate | Running Rate| The purchasing power multiplier rate at a given block | $r_{running}$ |

#### Additional Details on these Variables:
The total duration of a policy is the span of blocks between $h_S$ and $h_F$

The duration of the policy can be divided into epochs which are sections of blocks of equal length. An obvious option for epochs would be one epoch per day. Of course, this would need to be measured against an average block duration as not all blocks have equal duration. For example, if blocks were approximately 5 seconds long then an epoch would be 17280 blocks, but because the blocks were not exactly 5 seconds long the epochs would not be exactly 1 day long.

The epochs are a user experience affordance to put governance reasoning about the effects of PMTP in intuitive units.

### Use $r_{gov}$ to Derive $r_{block}$

Let $r_{gov}$ be the per-epoch rate increase voted in by governance. Each epoch, the purchasing power of Rowan (treated as the $y$ token in Variable Definitions above) should increase by this percentage.

Let the final compounded rate, ${r_{final}}$, be defined as follows:
$${r_{final}} = (1 + r_{gov}) ^ {l_{policy}} - 1$$
Rowan should increase by this percentage between $h$ and $h_F$ (ie. across all epochs).

Now we compute $r_{block}$, which is the incremental increase on a per block basis (to reach $final\_compounded\_rate$):
$$r_{block} = (1 + r_{gov}) ^ {l_{policy}/({h_F-h_S})} - 1$$
$r_{block}$ function derivation can be found in Appendix 1 at the end of this document

**From this point onward we only focus on blocks.**

Given a block rate calculated at the initial governance decision, there is no further role for the epoch rate or to keep track of epochs. The block rate is not recalculated again after the initial goverance decision.

### Use $r_{block}$ to Derive $r_{running}$

Let $r_{running}$ be the running rate that is compounded over time (at any particular block). Similarly

$$r_{running} = (1+r_{block})^i-1$$
where
$$ i = h - h_S $$

**Note:** $r_{running}$ in LPD is an interesting stat but is not necessary for calculations in this feature

#### Similarities and Differences with Ratio Shifting PMTP

The content above is almost identical to the [Variable Definitions of Ratio Shifting PMTP](https://hackmd.io/vrCeYGvURZio4yWc-ChYzA?both#Variable-Definitions). The protocol makes an adjustment to the liquidity pool module state on a per-block basis to modify Rowan's purchasing power. With LPD, we are NOT modifying the swap formula (as is done in Ratio Shifting). Instead, $r_{gov}$ here refers to the rate at which Rowan is removed from a liquidity pool and returned to a liquidity provider. As such, $r_{gov}$ and $r_{final}$ are found within the range of [0,1] for LPD whereas they are found within [-1,1] for Ratio Shifting.

As previously mentioned, it is possible to run LPD and Ratio Shifting at the same time where they'd have additive effects on Rowan's purchasing power.

### Computational and Financial Effect of LPD

On a per-block basis, LPD removes $r_{block}$ Rowan from all LP positions and returns it to LPs. Consider the image below:


Note that the LP's non-Rowan liquidity remains in the pools. This means Sifchain's TVL stays constant despite these liquidity removals and the purchasing power of Rowan increases commensurately.

Sifchain's swap fee formula remains unaffected by LPD; the reason Rowan's purchasing power increases is simply that there are fewer Rowan tokens in the pool relative to the same amount of external tokens.

With both LPD and Ratio Shifting, the increase to Rowan's purchasing power is jeopardized by excessive removal of Sifchain's external (non-Rowan) liquidity. Therefore, they belong deployed alongside some version of [DEX Liquidity Protection](https://hackmd.io/3MCsy4EqSaeNvstUL6hDKg?view)
### Policy Definition
Let the LPD policy be: $\mathbb{B}$, with an associated amount policy Rowan tokens of $X_{\mathbb{B}}$. $\mathbb{B}$ is parameterized by a start time ($t_i$), an end time ($t_f$), and a block rate ($r_{block}$), which is the desired LPD rate. For any $\mathbb{B}$, there is: $t_i(\mathbb{B})$ is the start time, $t_f(\mathbb{B})$ is the end time, and $r_{block}(\mathbb{B})$ is the block rate.

Given $block(t)$ as the number of blocks from the start of the LPD period until timestep $t$, swap formulae being dependent on the pool depths $X, Y$ yields the generalized form that is both time and path dependent:

$$
r_{running}^\mathbb{B}(t) = (1+r_{block}(\mathbb{B}))^{block(t) - t_i(\mathbb{B})} - 1
$$

To analyze metrics across different LPD decisions, define the metrics using $\mathcal{\mathbb{B}}$, the set of LPD decisions that occur during the interval $[t, t')$.
$$
\mathcal{\mathbb{B}}(t, t') = \{\mathbb{B} | \exists t\in [t, t'] s.t.\ t\in [t_i(\mathbb{B}), t_f(\mathbb{B})) \}
$$
The current state of the liquidity in the pool must be considered.

$$X_{\mathbb{B}} = \mathbb{B}(X, Y, r_{block}(\mathbb{B}))$$
$r_{block}(\mathbb{B})$ is the rate of tokens distributed on a per block basis through this policy.
$r_{block}(\mathbb{B})$ would be expected to be constant over this policy.
Distribution comes from only the Rowan side of the pool ($X$). The simplest version of this would be:

$$X_{\mathbb{B}} = X \cdot r_{block}(\mathbb{B})$$
This would result in a linear decrease in $X$ tokens in the pool.
$X$ cannot be known during this policy because $X$ is subject to AMM activity (swapping and add/removes).
The problem with using $X$ as a multiplier would create a greater outflow due to liquidity adds, possibly disincentiving adds during the policy.
The problem with using $X$ as a static amount at the start of the policy is that $X$ would change due to AMM activity and therefore would not be reactive to large shifts in the pool. Using $X$ would work for accounting for the change in token states, keeping the same value distributed due to swapping activity, it would not handle change in liquidity.
$TVL$ may be a normalizing factor in this mechanism.
Value is the better base to apply a rate against.
with an associated expected shift in the pool at the end of LPD period $T$:
$$
\Delta_{w_X}(X_T^\mathbb{B}, X_T, Y_T^\mathbb{B}, Y_T) \\
\Delta_{w_Y}(X_T^\mathbb{B}, X_T, Y_T^\mathbb{B}, Y_T)
$$
### Pool State Update
As currently written, the liquid assets would be leaving the pool. Liabilities could be used instead.
If opting to drain liquidity directly at every block:
$$X_A^+ = X_A - X_{\mathbb{B}}$$
If utilizing claims, conditioned on the LP holder choosing to claim at that block, $D$ :
$$X_A^+ = X_A - \sum_{c=i}^{c=n}{c^i}, \forall c \in D$$
where some $c \in \mathcal{C}$ has chosen to claim at that block and $c \subset R$.

Unclaimed receipts can be thought of as liabilities on X, so in effect increasing the debt on that side of the pool, if the LP holder chooses not to claim at that block:
$$X_L^+ = X_L + \sum_{c=i}^{c=n}{c^i},\forall c \notin D$$
where some $c \in \mathcal{C}$ has chosen not to claim at that block and $c \subset R$.

### Distribution
LPD tokens are distributed based on the shares in the pool and the corresponding distribution of LP position holders.

LPD tokens could be instantiated by receipts that would be claimable by LP holders when they are substantial enough with respect to transaction fees.
The claimable receipts are distributed according to the policy and LP holder's shares:
$$ r^i = X_{\mathbb{B}} \cdot \frac{s^i}{S}$$

The tokens are issued upon claiming to the LP holder's wallet outside of their position:
$$ agent_x^i = agent_x^i + c^i $$

## Implementation Detail
If LPD is too computational to run every block, it can be optimized. For example, it can be run every n blocks on all pools or once every block on only a subset of pools such that after n blocks all pools have been adjusted.