LpETH docs

This page provides developer documentation for the most important endpoints of the LpETH contract. The LpETH contract facilitates liquidity pooling of ETH, allowing users to deposit ETH and receive LP tokens, withdraw ETH, swap assets, and participate in the protocol's liquidity mechanisms.

Table of Contents

  • Swap

  • Quote

  • Deposit

  • Withdraw

  • Claim Withdraw Request

  • Redeem Unlock

  • Buy Unlock

  • Claim Relayer Rewards

  • Events

  • Disclaimer

Swap

swap(address asset, uint256 amount, uint256 minOut)

Swaps a supported asset for ETH.

swap(address asset, uint256 amount, uint256 minOut) external nonreentrant returns (uint256 out, uint256 fee)

Parameters:

  • asset (address): The address of the asset to swap.

  • amount (uint256): The amount of the asset to swap.

  • minOut (uint256): The minimum amount of ETH the user expects to receive.

Returns:

  • out (uint256): The amount of ETH received.

  • fee (uint256): The fee charged for the swap.

Description:

  • Transfers the specified asset from the user to the contract.

  • Approves the UnsETH contract to handle the asset.

  • Requests withdrawal from UnsETH, receiving a token ID and expected amount.

  • Calculates the ETH output and fee.

  • Reverts if the ETH output is less than minOut to prevent slippage.

  • Transfers the ETH to the user.

Events:

  • Swap(address indexed caller, address indexed asset, uint256 amountIn, uint256 fee, uint256 unlockId)

Errors:

  • ErrorInvalidAsset(address asset): Thrown if the asset is not supported.

  • ErrorSlippage(uint256 out, uint256 minOut): Thrown if the ETH output is less than minOut.

Quote

quote(address asset, uint256 amount)

Provides an estimate of the ETH amount and fee for swapping a given asset.

quote(address asset, uint256 amount) external view returns (uint256 out, uint256 fee)

Parameters:

  • asset (address): The address of the asset to swap.

  • amount (uint256): The amount of the asset to swap.

Returns:

  • out (uint256): The estimated amount of ETH the user will receive.

  • fee (uint256): The estimated fee for the swap.

Description:

  • Calculates the expected ETH output and fee based on the current pool state.

  • Useful for users to understand the swap outcome before executing.

Errors:

  • ErrorInvalidAsset(address asset): Thrown if the asset is not supported.

Deposit

deposit(uint256 minLpShares)

Allows users to deposit ETH into the pool and receive LP tokens in return.

deposit(uint256 minLpShares) external payable returns (uint256 lpShares)

Parameters:

  • minLpShares (uint256): The minimum amount of LP tokens the user expects to receive to prevent slippage.

Returns:

  • lpShares (uint256): The number of LP tokens minted to the user.

Description:

  • Users send ETH along with this function call.

  • Calculates the number of LP tokens to mint based on the pool's current liabilities and total supply.

  • Mints LP tokens to the user.

Events:

  • Deposit(address indexed from, uint256 amount, uint256 lpSharesMinted)

Errors:

  • ErrorSlippage(uint256 out, uint256 minOut): Thrown if the LP shares to mint are less than minLpShares.

  • ErrorDepositSharesZero(): Thrown if the calculated LP shares are zero.

Withdraw

withdraw(uint256 amount, uint256 maxLpSharesBurnt)

Allows users to withdraw ETH by burning their LP tokens.

withdraw(uint256 amount, uint256 maxLpSharesBurnt) external nonreentrant returns (uint256 requestId)

Parameters:

  • amount (uint256): The amount of ETH the user wants to withdraw.

  • maxLpSharesBurnt (uint256): The maximum number of LP tokens the user is willing to burn to prevent slippage.

Returns:

  • requestId (uint256): The ID of the withdrawal request if applicable.

Description:

  • Calculates the number of LP tokens to burn based on the withdrawal amount.

  • Reverts if the LP shares to burn exceed maxLpSharesBurnt.

  • If there's insufficient liquidity, creates a withdrawal request for the remaining amount.

  • Burns the user's LP tokens.

  • Transfers available ETH to the user.

Events:

  • Withdraw(address indexed to, uint256 amount, uint256 lpSharesBurnt, uint256 requestId)

Errors:

  • DepositedInCurrentTx(): Thrown if a withdrawal is attempted in the same transaction as a deposit.

  • ErrorSlippage(uint256 out, uint256 maxLpSharesBurnt): Thrown if the LP shares to burn exceed maxLpSharesBurnt.

  • ErrorDepositSharesZero(): Thrown if the calculated LP shares are zero.

Claim Withdraw Request

claimWithdrawRequest(uint256 id)

Allows users to claim their finalized withdrawal requests.

claimWithdrawRequest(uint256 id) external returns (uint256 amount)

Parameters:

  • id (uint256): The ID of the withdrawal request.

Returns:

  • amount (uint256): The amount of ETH claimed.

Description:

  • Finalizes the withdrawal request and transfers the ETH to the requester.

  • Updates the pool's liabilities.

Events:

  • ClaimWithdrawRequest(uint256 indexed requestId, address indexed to, uint256 amount)

Redeem Unlock

redeemUnlock()

Allows relayers to redeem finalized unlocks and claim rewards.

redeemUnlock() external nonreentrant

Description:

  • Retrieves the oldest unlock from the queue.

  • Checks if the unlock is finalized.

  • Claims the withdrawal from the UnsETH contract.

Events:

  • UnlockRedeemed(address indexed relayer, uint256 tokenId, uint256 amount, uint256 reward, uint256 lpFees)

Errors:

  • ErrorNotFinalized(uint256 tokenId): Thrown if the unlock is not finalized.

Buy Unlock

buyUnlock(uint256 expectedTokenId)

Allows users to purchase unfinalized unlocks at a discounted rate.

buyUnlock(uint256 expectedTokenId) external payable nonreentrant returns (uint256 tokenId)

Parameters:

  • expectedTokenId (uint256): The expected token ID of the unlock to purchase.

Returns:

  • tokenId (uint256): The actual token ID of the unlock purchased.

Description:

  • Retrieves the newest unlock from the queue.

  • Checks if the unlock is not finalized and not expired.

  • Verifies that the token ID matches expectedTokenId.

  • Calculates the reward (discount) for purchasing the unlock.

  • Transfers the unlock to the buyer.

Events:

  • UnlockBought(address indexed caller, uint256 tokenId, uint256 amount, uint256 reward, uint256 lpFees)

Errors:

  • UnexpectedTokenId(): Thrown if the token ID does not match expectedTokenId.

  • ErrorIsFinalized(uint256 tokenId): Thrown if the unlock is already finalized.

  • ErrorRecoveryMode(): Thrown if the pool is in recovery mode.

  • ErrorInsufficientAmount(): Thrown if the sent ETH is insufficient.

Claim Relayer Rewards

claimRelayerRewards()

Allows relayers to claim their accumulated rewards.

claimRelayerRewards() external returns (uint256 relayerReward)

Returns:

  • relayerReward (uint256): The amount of rewards claimed.

Description:

  • Transfers the accumulated rewards to the relayer.

  • Resets the relayer's reward balance.

  • Emits a RelayerRewardsClaimed event.

Events:

  • RelayerRewardsClaimed(address indexed relayer, uint256 rewards)

Events

  • Deposit(address indexed from, uint256 amount, uint256 lpSharesMinted)

  • Withdraw(address indexed to, uint256 amount, uint256 lpSharesBurnt, uint256 requestId)

  • ClaimWithdrawRequest(uint256 indexed requestId, address indexed to, uint256 amount)

  • Swap(address indexed caller, address indexed asset, uint256 amountIn, uint256 fee, uint256 unlockId)

  • UnlockRedeemed(address indexed relayer, uint256 tokenId, uint256 amount, uint256 reward, uint256 lpFees)

  • UnlockBought(address indexed caller, uint256 tokenId, uint256 amount, uint256 reward, uint256 lpFees)

  • RelayerRewardsClaimed(address indexed relayer, uint256 rewards)

Notes

  • Access Control: Some functions are restricted using modifiers like onlyOwner and nonreentrant.

  • Upgradeable Contract: The contract uses OpenZeppelin's upgradeable pattern via UUPSUpgradeable.

  • External Contracts: Interacts with external contracts like UnsETH, Registry, and LPToken.

  • Mathematical Libraries: Utilizes libraries like FixedPointMathLib and UD60x18 for precise calculations.

  • ETH Handling: Functions are marked payable where necessary, and ETH transfers are handled carefully to prevent issues.

Disclaimer: This documentation provides a high-level overview of the most important endpoints of the LpETH contract. Developers should refer to the actual contract code and conduct thorough testing before interacting with the contract in a production environment.

PreviousOverviewNextDeployed contracts

Last updated