STEXAMM.sol

This page documents the Public & External Functions for the Liquidity Module contract in the Valantis Sovereign Pool Architecture for Stake Exchange (STEX) AMM.

This contract is critical for interfacing with pool reserves

• Liquidity Providers Deposit and Withdraw directly from STEXAMM.sol

• The Sovereign Pool sources the exchange rate between token0 & token1 using the getLiquidityQuote() function implemented in STEXAMM.sol

• The Withdrawal Module uses functions in STEXAMM.sol to interface with pool reserves

  • supplyToken1Reserves() to supply Native Token (token1) pool reserves to an integrated borrow-lending market.

  • unstakeToken0Reserves() to send LST (token0) pool reserves to the integrated LST Protocol Withdrawal Queue.

STEXAMM.sol is the central contract coordinating the use of pool reserves.

Core Functions: Deposit, Withdrawal, Swap

1. deposit()

Purpose: Mint LP tokens by depositing Native Token (token1)

// Deposit liquidity into `pool` and mint LP tokens
function deposit(uint256 _amount, uint256 _minShares, uint256 _deadline, address _recipient)   external  returns (uint256 shares)

Note: Deposits are one-sided, only in Native Token (token1); LP tokens represent a share of all pool reserves.

Note: This function accepts the wrapped version of the Native Token. For LP deposits of unwrapped Native Token- Deposit Wrapper depositFromNative() helper function must be used.

Note: ownercan pause this function.

Parameters:

• _amount: Native Token amount to deposit

• _minShares: Minimum LP shares to receive

• _deadline: Transaction validity timestamp

• _recipient: LP shares recipient

Key Mechanics:

• First deposit mints MINIMUM_LIQUIDITY to address(0)

• Calculates shares using geometric mean formula

• Transfers Native Token (token1) from sender via DepositWrapper

Events:

• emit Deposit(address indexed sender, address indexed recipient, uint256 amount1, uint256 shares)

2. withdraw()

Purpose: Redeem LP shares for underlying assets

// Withdraw liquidity from `pool` and burn LP tokens
function withdraw(
        uint256 _shares,
        uint256 _amount0Min,
        uint256 _amount1Min,
        uint256 _deadline,
        address _recipient,
        bool _unwrapToNativeToken,
        bool _isInstantWithdrawal
    ) external override nonReentrant returns (uint256 amount0, uint256 amount1)

Parameters:

• _shares: LP tokens to burn

• _amount0Min: Minimum token0 to receive

• _amount1Min: Minimum token1 to receive

• _deadline: Deadline for txns

• _recipient: Assets recipient

• _unwrapToNativeToken: Boolean to receive as native token (relevant if token1 is wrapped)

• _isInstantWithdrawal: Boolean to swap the LPs share of LST (token0) for Native Token (token1) with internal swap; outputting only Native Token (token1) while paying a fee.

Flow:

• Calculates pro-rata share of reserves

• If _isInstantWithdrawal is True:

  • Process instant withdrawal pro-rata for Native Token shares (token1):

    • Transfer pool reserve Native Token shares to the recipient

    • Withdrawal lending protocol Native Token shares via the Withdrawal Module and transfer to the recipient

  • Process instant withdrawal modeled as a swap() for LST shares (token0):

    • Combine pro-rata shares of LST (token0) pool reserves & pro-rata shares of LST (token0) in withdrawal queue

    • Simulate a swap of the combined LST (token0) shares using getAmountOut() and transfer the output Native Token (token1) to the recipient

• If _isInstantWithdrawal is False:

  • Process instant withdrawal pro-rata for Native Token shares (token1) as above

  • Process delayed withdrawal pro-rata for LST shares (token0):

    • Send pro-rata shares of LST pool reserves (token0) to the Withdrawal Queue for unstaking.

    • Create an LPWithdrawalRequest for the claim of pro-rata shares of LST (token0) pool reserves just sent to the Withdrawal Queue & pro-rata shares of LST (token0) that was in the Withdrawal Queue before withdraw() was called; claimable by recipient when mature.

Events:

• emit Withdraw(msg.sender, _recipient, amount0, amount1, _shares)

3. getLiquidityQuote()

Purpose: Provide a Swap Quote for the true rate of LST and Native Token

// Called by the Sovereign Pool
function getLiquidityQuote(
        ALMLiquidityQuoteInput memory _almLiquidityQuoteInput,
        bytes calldata, /*_externalContext*/
        bytes calldata /*_verifierData*/
    ) external view override returns (ALMLiquidityQuote memory quote)

For further documentation on the getLiquidityQuote function's role in Sovereign Pool check Liquidity Module Docs

Parameters:

• _almLiquidityQuoteInput: Swap direction and amounts

Returns:

• quote.amountInFilled: Actual input amount

• quote.amountOut: Output amount

Note:

• getLiquidityQuote() calls the `StHYPEWithdrawalModule` functions `convertToToken0` or `convertToToken1` in order to obtain the ground truth exchange rate between LST and token1.

• ownercan pause this function, effectively pausing swaps.

• This function will revert when STEX AMM's reentrancy guard is active.

Pause Functions

1. pause()

Purpose: Pause deposit and getLiquidityQuote

Checks:

• Only callable by owner

2. unpause()

Purpose: Unpause deposit and getLiquidityQuote

Checks:

• Only callable by owner

Set Up Functions: Swap Fee Module, Withdrawal Module, & Manager Fees

The following functions are used for initial set up of the pool and future mutability.

Swap Fee Module

The STEXAMM Liquidity Module as listed as the Sovereign Pool Pool Manager allowing us to enable access controls and STEX specific logic for functions like Swap Fee Module upgrades.

1. proposeSwapFeeModule()

Purpose: Initiate fee module upgrade proposal

// Propose a change to Swap Fee Module with specific timelock before upgrade
function proposeSwapFeeModule(address _swapFeeModule, uint256 _timelockDelay) external override onlyOwner

Parameters:

• _swapFeeModule: the address of new module

• _timelockDelay: the timelock in seconds before the upgrade can be executed

Checks:

• Only callable by owner

• New Swap Fee Module cannot be zero address

• No active Swap Fee Module upgrade proposals

• Proposed timelock within 3-7 days

Events:

• emit SwapFeeModuleProposed(_swapFeeModule, block.timestamp + _timelockDelay)

2. cancelSwapFeeModuleProposal()

Purpose: Delete proposal to set swap fee

// Cancels swap fee proposal
function cancelSwapFeeModuleProposal() external override onlyOwner

Checks:

• Only callable by owner

Events:

• emit SwapFeeModuleProposalCancelled()

3. setProposedSwapFeeModule()

Purpose: Execute fee module upgrade if the active proposal has become eligible

// Sets the proposed Swap Fee Module after timelock
function setProposedSwapFeeModule() external override onlyOwner

Checks:

• Only callable by owner

• Proposal exists and timelock expired

• New module is contract

Events:

• emit SwapFeeModuleSet(proposal.swapFeeModule)

Withdrawal Module

The Withdrawal Module is upgradable under a 7 day timelock. This is a critical function as the withdrawal module is able to move pool reserves to potentially arbitrary contracts.

4. proposeWithdrawalModule()

Purpose: Initiate withdrawal module upgrade proposal under 7 day timelock

// Propose an update to Withdrawal Module under a 7 days timelock
function proposeWithdrawalModule(address withdrawalModule_) external override onlyOwner

Parameter:

• withdrawalModule_: address of the new withdrawal module being proposed

Checks:

• Only callable by owner

• New Withdrawal Module cannot be zero address

• No active Withdrawal Module upgrade proposals

Flow:

• sets the withdrawalModuleProposal variable to a struct containing the proposal data

Events:

• emit WithdrawalModuleProposed(withdrawalModule_, block.timestamp + 7 days)

5. cancelWithdrawalModuleProposal()

Purpose: Cancel a withdrawal module upgrade proposal

// Cancel a proposed Withdrawal Module upgrade before it is executed
function cancelWithdrawalModuleProposal() external override onlyOwner

Checks:

• Only callable by owner

Flow:

• deletes withdrawalModuleProposal data

Events:

• emit WithdrawalModuleProposalCancelled()

6. setProposedWithdrawalModule()

Purpose: Initiate fee module upgrade proposal under 7 day timelock

// Update to the proposed Withdrawal Module after 7 day timelock
function setProposedWithdrawalModule() external override onlyOwner

Checks:

• Only callable by owner

• There is an active Withdrawal Module Proposal

• 7 day timelock for the active proposal has surpassed

Flow:

• Update Withdrawal Module address to the proposed address

• Remove the active proposal

Events:

• emit WithdrawalModuleSet(proposal.withdrawalModule)

Manager Fees

7. setManagerFeeBips()

Purpose: Set protocol fee percentage

// Sets a manager/protocol fee on every swap.
function setPoolManagerFeeBips(uint256 _poolManagerFeeBips) external override onlyOwner nonReentrant

Parameters:

• _managerFeeBips: Fee in basis points (1-1000)

Checks:

• Only callable by owner

• Sovereign Pool checks that _poolManagerFeeBips is between 0-1_000

Events:

• emit PoolManagerFeeSet(_poolManagerFeeBips);

STEX LST Withdrawal (Unstake)

1. unstakeToken0Reserves()

Purpose: Allow removal of LST reserves (token0) by the Withdrawal Module for unstaking

// Allows the withdrawal module to transfer `token0` reserves from `pool`
// and send those to the staking protocol's native withdrawal queue.
function unstakeToken0Reserves(uint256 _unstakeAmountToken0) external override onlyWithdrawalModule nonReentrant

Checks:

• only callable by WithdrawalModule

• _unstakeAmountToken0 is less than or equal to the reserves of token0 in the pool

Flow:

• STEXWithdrawalModule calls this function from inside its unstakeToken0Reserves() function to transfer the entire pool's LST reserves to the LST Protocol Unstake Queue.

• _unstakeAmountToken0 of token0 reserve balance in the pool is transferred by the Withdrawal Module to the integrated unstake queue.

Events:

• emit Token0ReservesUnstaked(_unstakeAmountToken0)

STEX Reserve Lending

1. supplyToken1Reserves()

Purpose: Allows removal of Native Token reserves (token1) by Withdrawal Module for deposit in lending-borrowing protocol

// Allows the withdrawal module to supply a portion of `token1` reserves
// from `pool` into a lending protocol.
function supplyToken1Reserves(uint256 _amount1) external override onlyWithdrawalModule nonReentrant

Parameters:

• _amount1 is the amount of token1 reserves to transfer to the Withdrawal Module

Checks:

• Only callable by Withdrawal Module

Flow:

• STEXWithdrawalModule calls this function from inside its supplyToken1ToLendingPool()

Protocol Fees

1. claimPoolManagerFees()

Purpose: Send accrued Pool Manager Fees to receiving addresses

// Anyone can send accrued protocol fees to the receiving addresses
function claimPoolManagerFees() external override nonReentrant

Flow:

• Collected fee is transferred to poolFeeRecipient1 and poolFeeRecipient2 in equal proportion

Events:

• emit PoolManagerFeesClaimed(fee0Received, fee1Received) where fee0Received and fee1Received are measured before splitting equal proportions between poolFeeRecipient1 and poolFeeRecipient2

Pool Manager Fees are accrued on each swap as a percentage of swap fee- specified by PoolManagerFeeBIPS

More documentation on Manager Fees can be found in Pool Manager Docs.

Helper Functions

1. getAmountOut()

Purpose: Helper function estimate amount out

// Helper function to estimate swap quote amounts
function getAmountOut(address _tokenIn, uint256 _amountIn) public view returns (uint256 amountOut)