StexRatioSwapFeeModule.sol

This page documents the Public & External Functions for the Ratio Swap Fee Module contract in the Stake Exchange (STEX) AMM Architecture.

The Swap Fee Module is upgradable to any dynamic or static fee logic in STEX AMM because it is built as a Valantis Sovereign Pool. This page will cover a specific implantation of a ratio based dynamic fee implemented in the contract StexRatioSwapFeeModule.sol.

The Ratio Swap Fee Module only applies a fee for LST to Native Token swaps (token0 to token1)

Core Functionality

3. getSwapFeeInBips()

Purpose: Calculate dynamic swap fee

// Return dynamic swap fee for a swap
function getSwapFeeInBips(
        address _tokenIn,
        address, /*_tokenOut*/
        uint256 _amountIn,
        address, /*_user*/
        bytes memory /*_swapFeeModuleContext*/
    ) external view override returns (SwapFeeModuleData memory swapFeeModuleData) {

Parameters:

• _tokenIn: Input token address

• _amountIn: Trade amount

Reserve Ratio Overview

the fee uses the following variables to measure reserve ratio in the getSwapFeeInBips function:

1. amount0Total- LST reserves (token0) currently in the pool & LST reserves (token0) in the LST Unstaking Queue which will be returned to the pool, currently pending withdrawal back to Native Token (token1). This does not include token0 pending withdrawal which is marked for exited LPs.

2. amount1Total - Native Token reserves (token1) currently in the pool & Native Token reserves (token1) deposited in the integrated lending protocol.

3. amountIn - The LST (token0) that will be added to the pool as a result of the swap.

NOTE: LST reserves (token0) in the LST Unstaking Queue which will be returned to the pool is calculated as `total LST pending unstake` minus `LST pending unstake marked for exited LPs`.

amountToken0PendingUnstaking() - convertToToken0(amountToken1PendingLPWithdrawal())

The above functions are called from the Withdrawal Module

The reserve ratio is calculcated as:

$$\mathrm{\frac{amount0Total + amountIn}{amount1Total}}$$

Applied Fee

After calculating the post swap reserve ratio- a linear interpolation is applied.

A linear fee is applied when the reserve ratio exceeds a threshold (minThresholdRatioBips) and approaches a Maximum Fee when another threshold is hit (maxThresholdRatioBips). Minimum Fee is applied before minThresholdRatioBips is reached.

This bounds the applied fee between feeMinBips & feeMaxBips

Returns:

• feeInBips: Converted fee compatible with pool's swap formula

Setup Functions

1. setPool()

Purpose: Link to Valantis Sovereign Pool

// Sets the Sovereign Pool address
function setPool(address _pool) external onlyOwner

Parameters:

• _pool: Pool contract address

Checks:

• Can only be set once

• _pool cannot be zero address

Events:

• emit PoolSet(address pool)

2. setSwapFeeParams()

Purpose: Configure dynamic fee parameters

// Update AMM's dynamic swap fee parameters
function setSwapFeeParams(
        uint32 _minThresholdRatioBips,
        uint32 _maxThresholdRatioBips,
        uint32 _feeMinBips,
        uint32 _feeMaxBips
    ) external override onlyOwner { 

Fee parameters can be changed by owner at any time.

Parameters:

• _minThresholdRatioBips: Lower ratio bound (basis points)

• _maxThresholdRatioBips: Upper ratio bound

• _feeMinBips: Minimum fee when below lower bound

• _feeMaxBips: Maximum fee when above upper bound

Checks:

• Thresholds must be 0 < min < max ≤ 10,000

• Fees must be min ≤ max < 5,000

Events:

• emit SwapFeeParamsSet(min, max, feeMin, feeMax)

\