RFC: Multi Flow v1.1.0

Author

Brendan Sanderson

Summary

Modify the cap reserves functionality in Multi Flow to have two separate caps:
1. A cap on the maximum change in exchange rate between any two tokens in the Pump
2. A cap on the maximum change in support of LP Tokens in a Well
This allows the Multi Flow Pump to independently control the maximum change in total tokens in a Well and the exchange rate between them.
Move all constants to Pump Data to allow customizability between Wells.

Motivation

When the BEAN:3CRV liquidity was migrated to BEAN:ETH, it took a significant time (~14 hours) for the Multi Flow capped reserves to catch up to the real balances (see EBIP-9). During this time, the ratio between the capped reserves did not change as they both increased by the max percent each Season. This introduced a problem where the exchange rates in Multi Flow Pump may not reflect the actual exchange rates in the pool. Multi Flow Pump needs a way to change the exchange rates even when the magnitude of the increase of reserves is capped.

Currently Multi Flow Pump's constants are stored in the Pump. However, different types of Wells (e.g., A Well with Stablecoins) may want to use different constants. Currently, this requires deploying different Pumps for each. By moving the constants to Pump Data, it will allow each Well to chose its own constants while using the same Pump.

Design Specification

Given Constants:

\begin{bmatrix}
0 & \delta_{01} & \cdots & \delta_{0n} \\
\vdots & \vdots & \vdots & \vdots \\
\delta_{n0} & \delta_{n1} & \cdots & 0
\end{bmatrix}

where $\delta_{ij}$ is the maximum % increase in exchange rate of exchanging $j$ for $i$.

$\phi+$, $\phi-$ be the maximum % increase and decrease in k
$l$ be the timestamp that the Pump was last updated
$t$ be the current timestamp
$b$ be the block time in seconds
$w$ be the Well Data
$n$ be the number of tokens in the pool

Given Functions

calcLpTokenSupply - Gets the LP token supply given a list of reserves.
calcReserveAtRatioSwap - Calculates the $j$th reserve such that $\prod_{i | i != j}^n \frac{d x_j}{d xi} = \prod{i | i != j}^n \frac{r_j}{r_i}$ where $r$ is a list of input exchange ratios.
calcLPTokenUnderlying - Calculates the amount of each reserve token underlying a given amount of LP tokens.
calcRate - Calculates the exchange rate of exchange $j$ for $i$.

Given Variables:

$[x{0,t}, \cdots, x{n-1,t}]$
$[x{0,l}^{last}, \cdots, x{n-1,l}^{last}]$

Solve For:

$[x{0,t}^{last}, \cdots, x{n-1,t}^{last}]$

Step 1: Cap Change of Magnitude

Let:

k^{last}_l = \text{calcLpTokenSupply}([x_{0,l}^{last}, \cdots, x_{n-1,l}^{last}], w)

k_t = \text{calcLpTokenSupply}([x_{0,t}, \cdots, x_{n-1,t}], w)

k_t^{max} = k^{last}_l(1 - \phi_+)^{\frac{t-l}{b}}

k_t^{min} = k^{last}_l(1 - \phi_-)^{\frac{t-l}{b}}

[x_{0,t}^{cap}, \cdots, x_{n-1,t}^{cap}] = \begin{cases}
\text{calcLPTokenUnderlying}(k_t^{max}, [x_{0,t}, \cdots, x_{n-1,t}], k_t, w) & k_t > k_t^{max} \\
\text{calcLPTokenUnderlying}(k_t^{min}, [x_{0,t}, \cdots, x_{n-1,t}], k_t, w) & k_t < k_t^{min} \\
[x_{0,t}, \cdots, x_{n-1,t}] & \text{otherwise}
\end{cases}

Step 2: Cap Change of Rates

For each unique set of 2 tokens in the Well (order doesn’t matter):

Let $(i, j)$ be defined such that $x{i,t}^{cap} > x{j,t}^{cap}$

Let:

r_{ij, l}^{last} = \text{calcRate}(x_{i,l}^{last}, x_{j,l}^{last}, i, j)

r_{ij,t}^{max} = r_{ij,l}^{last}(1 + \delta_{ij})^{\frac{t-l}{b}}

r_{ij,t}^{min} = r_{ij,l}^{last}(1 - \frac{1}{1+\delta_{ji}})^{\frac{t-l}{b}}

\textbf{R}_{max} = \begin{cases} 
[r^{max}_{ij,t}, 1] & i =0 \\
[1, r^{max}_{ij,t}] & otherwise
\end{cases}

\textbf{R}_{min} = \begin{cases} 
[r^{min}_{ij,t}, 1] & i =0 \\
[1, r^{min}_{ij,t}] & otherwise
\end{cases}

x^{\text{last}}_{i,t} = \begin{cases} \text{calcReserveAtRatioSwap}([x_{i,t}^{cap}, x_{j,t}^{cap}], i, \mathbf{R}^{max}, w)  & \frac{x_{i,t}^{cap}}{x_{j,t}^{cap}} > r_{ij,t}^{max} \\ 
\text{calcReserveAtRatioSwap}([x_{i,t}^{cap}, x_{j,t}^{cap}], i, \mathbf{R}^{min}, w) & \frac{x_{j,t}^{cap}}{x_{i,t}^{cap}} < r_{ij,t}^{min} \\
x_{i,t}^{cap} & \text{otherwise}
\\\end{cases}

x^{\text{last}}_{j,t} = \begin{cases} \text{calcReserveAtRatioSwap}([x_{i,t}^{cap}, x_{j,t}^{cap}], j, \mathbf{R}^{max}, w)  & \frac{x_{i,t}^{cap}}{x_{j,t}^{cap}} > r_{ij,t}^{max} \\ 
\text{calcReserveAtRatioSwap}([x_{i,t}^{cap}, x_{j,t}^{cap}], j, \mathbf{R}^{min}, w) & \frac{x_{j,t}^{cap}}{x_{i,t}^{cap}} < r_{ij,t}^{min} \\
x_{j,t}^{cap} & \text{otherwise}
\\\end{cases}

Technical Specification

Well Function Interface Augmentation:

1. Create a new interface `IMultiFlowPump.sol`

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.20;

import {IWellFunction} from "src/interfaces/IWellFunction.sol";

/**
 * @title IMultiFlowPumpWellFunction
 * @dev A Well Function must implement IMultiFlowPumpWellFunction to be supported by
 * the Multi Flow Pump.
 */
interface IMultiFlowPumpWellFunction is IWellFunction {
    /**
     * @notice Calculates the `j` reserve such that `π_{i | i != j} (d reserves_j / d reserves_i) = π_{i | i != j}(ratios_j / ratios_i)`.
     * assumes that reserve_j is being swapped for other reserves in the Well.
     * @dev used by Beanstalk to calculate the deltaB every Season
     * @param reserves The reserves of the Well
     * @param j The index of the reserve to solve for
     * @param ratios The ratios of reserves to solve for
     * @param data Well function data provided on every call
     * @return reserve The resulting reserve at the jth index
     */
    function calcReserveAtRatioSwap(
        uint256[] calldata reserves,
        uint256 j,
        uint256[] calldata ratios,
        bytes calldata data
    ) external view returns (uint256 reserve);

    /**
     * @notice Calculates the rate at which j can be exchanged for i.
     * @param reserves The reserves of the Well
     * @param i The index of the token for which the output is being calculated
     * @param j The index of the token for which 1 token is being exchanged
     * @param data Well function data provided on every call
     * @return rate The rate at which j can be exchanged for i
     */
    function calcRate(
        uint256[] calldata reserves,
        uint256 i,
        uint256 j,
        bytes calldata data
    ) external view returns (uint256 rate);
}

IBeanstalkWellFunction should now extend IMultiFlowPumpWellFunction

2. Implement `IMultiFlowPump` in `ConstantProduct2`

The only function that needs to be added is calcRate. calcRate should return the output of reserves[i] / reserves[j].

MultiFlowPump Modification:

1. Remove existing constants

LOG_MAX_INCREASE
LOG_MAX_DECREASE
ALPHA

2. Add new constants as Pump Data

Add constants:
- ALPHA
- MAX_LP_TOKENS_INCREASE
- MAX_LP_TOKENS_DECREASE
- MAX_PERCENT_PRICE_CHANGE

BeanstalkFarms / Basin