StHYPEWithdrawalModule.sol

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

The Withdrawal Module is responsible for managing the external use of reserves in Stake Exchange

• Depositing Native Token Reserves (token1) in a lending and borrowing protocol for extra yield

• Initiating unstake operations for LST Reserves (token0) to redeem them back to Native Token (token1) at the true rate

The way these operations get triggered is programmable- and in the case of stHYPE AMM we use an offchain keeper to

1. Trigger LST unstaking flexibly.

   1. This is because stHYPE AMMs native integration into the stHYPE Overseer ensures that new HYPE staked is routed to STEX AMM instantly- meaning pool reserves are kept denominated in HYPE if there are net new stakers vs instant withdrawals over a period of time. We would not get this efficiency if we unstaked at swap time. This is because once an LST is sent to the Withdrawal Queue it is illiquid and not able to be cancelled- HYPE reserves wouldn't get back to the pool until the stHYPE Queue settles deposits & withdrawals which happens every 24 hours. The considerations are covered in the Stake Exchange Whitepaper.

2. Deposit Native Tokens in Lending Markets flexibly.

   1. stHYPE AMM allows for multiple lending markets to be whitelisted under timelock: hypurrFi, Hyperlend, HyperDrive, Euler, etc. Mediating exposure to new lending markets requires flexibility in exposure- and not putting 100% of the pool's HYPE reserves in external markets by default.

The Withdrawal Module is also responsible for managing the withdrawal lifecycle for the pool & exiting LPs who do not chose the instant LP withdrawal option.

Note: The above graphic is simplified to show the movement of funds between the pool and external reserves integrations- while in reality the external functions the keeper uses for moving funds between the pool and both the Lending Module and Unstaking Queue are contained in the Withdrawal Module contract.

Note: Functions related to LST withdrawals are specific to the implementation of stHYPE AMM as it integrates with the Overseer contract for stHYPE withdrawals.

Note: This implementation is only valid for LST protocols where slashing cannot occur after a withdrawal is initiated through the native withdrawal queue.

LP Withdrawals

1. burnToken0AfterWithdraw()

Purpose: Initiate LP withdrawal request

// Creates a pending LP token withdrawal request after withdraw() is called
// with the _isInstantWithdrawal set to False
function burnToken0AfterWithdraw(uint256 _amountToken0, address _recipient) external override onlySTEX nonReentrant

Parameters:

• _amountToken0: stHYPE amount to unstake

• _recipient: Future claim recipient

Checks:

• Can only be called by StexAMM, called during the withdraw() function when _isInstantWithdrawal is set to Falseand _amountToken0 > 0.

Flow:

STEXAMM Liquidity Module calls this function to create an LP Withdrawal Request when an LP calls withdraw() and wants to wait for their LST shares to convert to Native Token at the true rate.

• Creates LPWithdrawalRequest record

• Tracks cumulative LP withdrawal amount cumulativeAmountToken1LPWithdrawal.

• LP has a claim to the exact amount of Native Token at the true rate at the time the claim was initiated

Events:

• emit LPWithdrawalRequestCreated(uint256 id, uint256 amountToken1, address recipient)

2. claim()

Purpose: Finalize an LPs processed withdrawal

// Claims a LP withdrawal request which has already been fulfilled
function claim(uint256 _idLPQueue) external nonReentrant

Parameters:

• _idLPQueue: Withdrawal request ID, emitted during burnToken0AfterWithdraw()

Checks:

• There is sufficient claimable balance

• The Withdrawal has not been claimed already

• Claim time priority eligibility: there is enough token0 for all LP Withdrawal Requests filed before this request to also claim.

Events:

• emit LPWithdrawalRequestClaimed(uint256 id)

Note: Anyone can call this function, automatically transferring the corresponding Native Token (Token1) to the recipient

Note: If there is slashing that can occur when a Withdrawal Request in pending in the withdrawal queue- this accounting method is invalid- and this withdrawal module contract should not be used

3. update()

Purpose: Sync state of matured LST withdrawals- shown as the current balance of Native Token in the Withdrawal Module- available for LP claims, and Native Token that can rejoin pool reserves.

This function can be called by anyone, and is necessary to:

• Update the Native Token claimable by Pending LP Withdrawal Requests

• Send Native Token not marked for LP Withdrawals back to the pool reserves

// Checks current balance of native token and updates state for LP claims
function update() external nonReentrant whenPoolNotLocked

Flow:

• Processes pending withdrawals

• Use leftover token to replenishes pool reserves

Updates:

• _amountToken0PendingUnstaking

• amountToken1PendingLPWithdrawal

• amountToken1ClaimableLPWithdrawal

• cumulativeAmountToken1ClaimableLPWithdrawal

Variable Overview:

• _amountToken0PendingUnstaking - tracks total LST balance pending unstaking. Includes both Pending Native Tokens that will be sent to exited LPs and the pool. Only updated on unstakeToken0Reserves(); and update().

• amountToken1PendingLPWithdrawal - pending exited LP claims that are not ready to be claimed yet. Native Token owed to LPs who have burned their position. Increased when an LP Withdrawal is initiated after burning the LP token burnToken0AfterWithdraw(); decreased an LP claims their Native Token balance claim(); decreased when LP Withdrawals become mature during update() .

• amountToken1ClaimableLPWithdrawal - pending exited LP Native Tokens that are ready to be claimed. Only updated on LP claim claim() ; and update().

• cumulativeAmountToken1ClaimableLPWithdrawal - a cumulative growing tracker of all matured claims that have become liquid for LPs. Does not reduce when an LP claims their Native Token. Only updated on update().

Lending

Lending related functions in Withdrawal Module are done through calls to Lending Module. This standardizes functions for the Withdrawal Module across different lending markets. New lending integrations can be made through the lending module upgrade process, and don't require redeploying the STEX pool or Withdrawal Module.

1. supplyToken1ToLendingPool()

Purpose: Deploy Native Token (token1) to lending strategy using lendingModule

// Withdraws a portion of pool's token1 reserves and supplies to `lendingPool` to earn extra yield
function supplyToken1ToLendingPool(uint256 _amountToken1) external onlyOwner returns (uint256 amountWithdrawn)

Parameters:

• _amountToken1: Native Token to deposit

Checks:

• Can only be called by owner

Flow:

• Transfers Native Token (token1) to lending module

• Tracks balance of Native Token (token1) deposited in the lending protocol.

2. withdrawToken1FromLendingPool()

Purpose: Withdraw tokens from lending markets when initiated by the owner

// remove Native Token from lending market and send to recipient
function withdrawToken1FromLendingPool(uint256 _amountToken1, address _recipient)
        external
        override
        onlySTEXOrOwner
        nonReentrant
        whenPoolNotLocked

Parameters:

• _amountToken1: amount of Native Token to remove from the lending protocol

• _recipient: the address to send the withdrawn funds in the case of STEX AMM calling the function

Checks:

• Can either be called by owner or StexAMM

• No reentrancy in StHYPEWithdrawalModule

• No reentrancy in STEX AMM's Sovereign Pool

Flow:

• Call withdraw() functions on the lending module

• Funds are transferred to either pool when caller is owner, otherwise they are transferred to recipient as specified by STEXAMM (directly to the user making an LP withdraw if the token does not need to be unwrapped; to the DepositWrapper if the token needs to be unwrapped before before sending to the exited LP)

Unstake Queue

1. unstakeToken0Reserves()

Purpose: start an unstake for a portion of the pool's LST (token0) reserves

// Claims pool's accummulated token0 reserves 
// and executes an unstaking request (burn) via integrated LST unstake queue
function unstakeToken0Reserves(uint256 _unstakeAmountToken0) external override nonReentrant onlyOwner

Checks:

• Can only be called by owner

• _unstakeAmountToken0 sanity checks occur in STEXAMM

Parameter:

• _unstakeAmountToken0 : amount of token0 to send to the unstake queue

Flow:

• Redeems LST (token0) in pool through the integrated LST withdrawal mechanism

• Tracks pending unstaking balance

Set Parameters

1. setSTEX()

Purpose: Initialize STEXAMM address; called once

// Sets the Liquidity Module address
function setSTEX(address _stex) external

Parameters:

• _stex: STEXAMM contract address

Checks:

• Can only be set once

• Valid contract address

Events:

• emit STEXSet(_stex)

Lending Module

The integrated lending market is upgradeable under timelock using a proposal proccess.

NOTE: The lending module is able to hold a potentially uncontrained amount of the pool's token1 reserves, a faulty lending module, or insolvent integrated market, can result in a partial or full loss of funds stored in the lending module.

2. proposeLendingModule()

Purpose: Start process of upgrading lending module under timelock

// Create proposed update to lending module
function proposeLendingModule(address _lendingModule, uint256 _timelockDelay) external onlyOwner

Checks:

• Only callable by owner

• Timelock is between 3 and 7 days

• No reentrancy in STEX AMM's Sovereign Pool

Events:

• emit LendingModuleProposed(_lendingModule, block.timestamp + _timelockDelay)

3. cancelLendingModuleProposal()

Purpose: Cancel the lending module prososal before its executed

// Cancel an active lending module change proposal
function cancelLendingModuleProposal() external onlyOwner

Checks:

• Only callable by owner

• There is an active lending module upgrade proposal

Flow:

• lendingModuleProposal deleted

Events:

• emit LendingModuleProposalCancelled()

4. setProposedLendingModule()

Purpose: Set the lending module once the active proposal has surpassed timelock

// Implement new lending module after proposal timelock has passed
function setProposedLendingModule() external onlyOwner whenPoolNotLocked

Checks:

• Timelock delay has completed

• There is an active lending module change proposal

Flow:

• If there was a previous lendingModule set with non-zero `assetBalance()`, withdraw funds from previous lendingModule to STEX AMM's pool.

• Update lendingModule

• lendingModuleProposal deleted

Events:

• emit LendingModuleSet(address(lendingModule))

Helper Functions

External Reserve Balances

1. amountToken0PendingUnstaking()

Purpose: Returns amount of LST (token0) which is pending conversion to Native Token (token1) through the Unstaking Queue

// Tracks amount of token1 which is pending unstaking through the 
// token0 Withdrawal Queue
function amountToken0PendingUnstaking() external view returns (uint256)

NOTE: This is a custom getter function, which is in perfect sync with the contract's ETH balance, so that accounting is accurate even before update gets called.

2. amountToken1PendingLPWithdrawal()

Purpose: Returns amount of Native Token owed to LPs which have created withdrawal requests.

// Tracks amount of token1 which is owed to LP withdrawal requests.
function amountToken1PendingLPWithdrawal() external view returns (uint256)

NOTE: This is a custom getter function, which is in perfect sync with the contract's ETH balance, so that accounting is accurate even before update gets called.

2. amountToken1LendingPool()

Purpose: Returns amount of Native Token (token1) which are parked in lending module

// Returns amount of Native Token (token1) owned by the lending module
// including any yield accrued
function amountToken1LendingPool() external view returns (uint256)

Token Conversions

3. convertToToken0()

Purpose: Returns equivalent amount of token1 in amount of token0

function convertToToken0(uint256 amount1) external pure returns (uint256) 

In the case of a rebase token- this function returns 1:1

4. convertToToken1()

Purpose: Returns equivalent amount of token0 in amount of token1

function convertToToken1(uint256 amount0) external pure returns (uint256) 

In the case of a rebase token- this function returns 1:1

5. token0SharesToBalance()

Purpose: returns the underlying token0 balance given a rebase token (token0) shares

// Return the underlying token0 balance given the shares of the rebase token
function token0SharesToBalance(uint256 _shares) public view override returns (uint256)

Parameters:

• _shares: the shares value to convert to token balance

Returns:

• balance associated with input shares value for token0

6. token0BalanceToShares()

Purpose: returns the underlying token0 balance given a rebase token (token0) shares

// Return the underlying token0 shares given the balance of the rebase token
function token0BalanceToShares(uint256 _balance) public view override returns (uint256)

Parameters:

• _balance: the token0 balance to convert to a shares value

Returns:

• shares associated with input balance for token0

7. token0SharesOf()

Purpose: Returns the share of token0 for an input address

// Return the token0 shares for the input address
function token0SharesOf(address _account) public view override returns (uint256)

Parameters:

• _account: address to measure the token0 shares of

Returns:

• shares associated with input address

LP Withdrawals

8. getLPWithdrawals

Purpose: return LP Withdrawal Request for a specific id

// Return Withdrawal Request Struct for id
function getLPWithdrawals(uint256 _idLPWithdrawal) public view override returns (LPWithdrawalRequest memory)

parameters:

• _idLPWithdrawal: the id of a LP withdrawal request, emitted during burnToken0AfterWithdraw()

return Struct:

struct LPWithdrawalRequest {
    address recipient;
    uint96 amountToken1;
    uint256 cumulativeAmountToken1LPWithdrawalCheckpoint;
}

• recipient: address that will receive the Native Token when claim() is called by anyone with the corresponding withdrawal id

• amountToken1: amount of Native Token to be sent to recipient

• cumulativeAmountToken1LPWithdrawalCheckpoint: checkpoint used to enforce time priority on LP withdrawals. LP request cannot be claimed unless there is enough token1 to fulfill all pending LP Withdrawals made prior and enough to fill this one.