Functions
addLiquidity(_tokenA: address, _tokenAId: uint256, _tokenB: address, _amountADesired: uint256, _amountBDesired: uint256, _amountAMin: uint256, _amountBMin: uint256, _to: address, _deadline: uint256) -> (uint256, uint256, uint256)
The addLiquidity function allows a user to supply liquidity to the pool for a specific token pair. In return, the user receives liquidity tokens, which represent their share in the pool. The liquidity tokens can later be redeemed for the underlying tokens.
Parameters
_tokenA: The address of the first token (tokenA) you want to provide as liquidity.
_tokenAId: The ID for the ERC1155 tokenA, typically a unique identifier for different types of tokens within the ERC1155 standard.
_tokenB: The address of the second token (tokenB) you want to provide as liquidity.
_amountADesired: The maximum amount of tokenA you wish to provide.
_amountBDesired: The maximum amount of tokenB you wish to provide.
_amountAMin: The minimum amount of tokenA you are willing to provide.
_amountBMin: The minimum amount of tokenB you are willing to provide.
_to: The address that will receive the liquidity tokens.
_deadline: The latest time this transaction can be executed.
Returns
uint256: The amount of tokenA that was actually provided as liquidity.
uint256: The amount of tokenB that was actually provided as liquidity.
uint256: The amount of liquidity tokens minted for the provided tokens.
Implementation Details
The function checks whether the _deadline has passed or not. If it's expired, the transaction is reverted.
It calculates the optimal amounts of _tokenA and _tokenB to be added to the liquidity pool such that the ratio between them remains as close to the desired amounts as possible. However, it ensures that the amounts provided are at least _amountAMin and _amountBMin respectively.
The function then retrieves the address of the liquidity pool (pair) for the two tokens from the factory.
It transfers the calculated amounts of _tokenA and _tokenB from the user to the liquidity pool.
Calls the mint function on the liquidity pool, which mints the liquidity tokens and sends them to the _to address.
Returns the amounts of _tokenA and _tokenB that were provided as liquidity, as well as the amount of liquidity tokens minted.
Usage
This function is commonly used by users who want to become liquidity providers (LPs) in a specific liquidity pool. By providing liquidity, LPs can earn fees from trades that happen in that pool. The minted liquidity tokens can later be burned to retrieve the underlying tokens.
Notes
The provided _amountADesired and _amountBDesired are the maximum amounts. The actual amounts can be less but will not be more.
The function ensures that the provided amounts are at least _amountAMin and _amountBMin. This is to avoid scenarios where due to price fluctuations, a user ends up providing much less liquidity than intended.
The _deadline is useful to ensure that the transaction doesn't get stuck in the mempool and gets executed at an undesired time due to network congestion or other reasons.
addLiquidityETH(_token: address, _tokenId: uint256, _amountTokenDesired: uint256, _amountTokenMin: uint256, _amountETHMin: uint256, _to: address, _deadline: uint256) -> (uint256, uint256, uint256)
The addLiquidityETH function allows a user to supply liquidity to the pool for a specific token and ETH pair. In return, the user receives liquidity tokens, representing their share in the pool. These liquidity tokens can later be redeemed for the underlying tokens and ETH.
Parameters
_token: The address of the token you want to provide as liquidity alongside ETH.
_tokenId: The ID for the ERC1155 token, a unique identifier for different types of tokens within the ERC1155 standard.
_amountTokenDesired: The maximum amount of the token you wish to provide.
_amountTokenMin: The minimum amount of the token you are willing to provide.
_amountETHMin: The minimum amount of ETH you are willing to provide.
_to: The address that will receive the liquidity tokens.
_deadline: The latest time this transaction can be executed.
Returns
uint256: The amount of _token that was actually provided as liquidity.
uint256: The amount of ETH that was actually provided as liquidity.
uint256: The amount of liquidity tokens minted for the provided tokens and ETH.
Implementation Details
The function checks if the _deadline has passed. If it has, the transaction is reverted.
It calculates the optimal amounts of _token and ETH to be added to the liquidity pool such that the ratio between them remains as close to the desired amounts as possible. However, it ensures the amounts provided are at least _amountTokenMin and _amountETHMin respectively.
The function then fetches the address of the liquidity pool (pair) for the token and ETH from the factory.
It transfers the calculated amount of _token from the user to the liquidity pool.
Deposits the specified amountETH to the WETH contract, effectively wrapping the ETH into WETH (Wrapped ETH).
Transfers the wrapped ETH (WETH) to the liquidity pool.
Calls the mint function on the liquidity pool, which mints the liquidity tokens and sends them to the _to address.
If the sent ETH (msg.value) is greater than the required amountETH, the excess ETH is refunded to the sender.
Returns the amounts of _token and ETH that were provided as liquidity, and the amount of liquidity tokens minted.
Usage
This function is intended for users wishing to provide liquidity with a token and ETH. As ETH is not an ERC20 token, it needs to be wrapped into WETH to interact with the ERC20 interface, which is why WETH is used in the liquidity pool rather than raw ETH.
Notes
The provided _amountTokenDesired and msg.value (for ETH) are the maximum amounts. The actual amounts can be less, but will not be more.
The function ensures that the provided amounts are at least _amountTokenMin and _amountETHMin to prevent scenarios where, due to price fluctuations, a user ends up providing much less liquidity than intended.
The _deadline parameter is there to ensure that the transaction doesn't get stuck and executed at an undesired time due to reasons like network congestion.
Any extra ETH sent with the transaction (more than what's used for liquidity) is sent back to the sender.
removeLiquidity(_tokenA: address, _tokenAId: uint256, _tokenB: address, _liquidity: uint256, _amountAMin: uint256, _amountBMin: uint256, _to: address, _deadline: uint256) -> (uint256, uint256)
The removeLiquidity function enables a liquidity provider to redeem their liquidity tokens for the underlying tokens in a pair. They will specify the amount of liquidity they want to remove and provide a minimum acceptable amount for each token to protect against large price swings. The redeemed tokens will be sent to the specified address (_to).
Parameters
_tokenA: The address of the first token in the pair you wish to remove liquidity from.
_tokenAId: The ID for the ERC1155 token _tokenA.
_tokenB: The address of the second token in the pair you wish to remove liquidity from.
_liquidity: The amount of liquidity tokens you wish to redeem.
_amountAMin: The minimum amount of _tokenA you are willing to accept.
_amountBMin: The minimum amount of _tokenB you are willing to accept.
_to: The address that will receive the underlying tokens once liquidity is removed.
_deadline: The latest time this transaction can be executed.
Returns
uint256: The amount of _tokenA that was redeemed.
uint256: The amount of _tokenB that was redeemed.
Implementation Details
The function first ensures that the _deadline has not passed. If it has, the transaction is reverted.
The liquidity pool (pair) address for the tokens _tokenA and _tokenB is fetched from the factory.
The specified amount of liquidity tokens (_liquidity) is transferred from the user to the liquidity pool. This indicates the user's intention to redeem these tokens.
The burn function is called on the liquidity pool, which destroys the specified amount of liquidity tokens and sends the corresponding amounts of _tokenA and _tokenB to the _to address. The amounts of _tokenA and _tokenB returned are captured as amountA and amountB respectively.
The function ensures that amountA is at least _amountAMin and amountB is at least _amountBMin. This ensures that the user does not receive less than the minimum specified amounts due to price fluctuations.
The function returns the amounts of _tokenA and _tokenB that were redeemed.
Usage
This function is meant for liquidity providers who wish to exit the liquidity pool and retrieve their share of the underlying tokens. By specifying minimum acceptable amounts, users protect themselves from unfavorable price movements.
Notes
The provided _amountAMin and _amountBMin are the minimum amounts the user is willing to accept. If the amounts returned from the liquidity pool are less than these thresholds, the transaction will be reverted.
The _deadline parameter ensures that the transaction doesn't get stuck and executed at an undesired time, such as during network congestion or adverse market conditions.
Liquidity tokens represent a user's share in the liquidity pool. By burning these tokens, a user redeems their share of the underlying assets.
removeLiquidityETH(_token: address, _tokenId: uint256, _liquidity: uint256, _amountTokenMin: uint256, _amountETHMin: uint256, _to: address, _deadline: uint256) -> (uint256, uint256)
The removeLiquidityETH function allows a liquidity provider to redeem their liquidity tokens for the underlying ERC1155 token and ETH from a pair. The user specifies the amount of liquidity they want to remove and provides minimum acceptable amounts for the token and ETH to protect against significant price movements. The redeemed tokens and ETH will be sent to the specified address (_to).
Parameters
_token: The address of the ERC1155 token you wish to remove liquidity from.
_tokenId: The ID for the ERC1155 token _token.
_liquidity: The amount of liquidity tokens you wish to redeem.
_amountTokenMin: The minimum amount of _token you are willing to accept.
_amountETHMin: The minimum amount of ETH you are willing to accept.
_to: The address that will receive the underlying tokens and ETH once liquidity is removed.
_deadline: The latest time this transaction can be executed.
Returns
uint256: The amount of _token that was redeemed.
uint256: The amount of ETH that was redeemed.
Implementation Details
The function first checks if the _deadline has passed. If it has, the transaction is reverted.
Using the _removeLiquidity helper function, the function redeems the specified liquidity amount for the underlying _token and wrapped ether (WETH). The amount returned is captured in amountToken and amountETH respectively.
The _token is transferred from the router contract to the _to address.
The wrapped ether (WETH) is then unwrapped into its native ETH format.
The resulting ETH is sent to the _to address.
Finally, the function returns the redeemed amounts of _token and ETH.
Usage
This function is used by liquidity providers who wish to exit the liquidity pool and retrieve their share of the ERC1155 token and ETH. By specifying minimum thresholds, users can protect themselves against drastic price changes.
Notes
The provided _amountTokenMin and _amountETHMin are the minimum amounts the user is willing to accept. If the amounts returned from the liquidity pool are less than these minimums, the transaction will be reverted.
The _deadline parameter provides a time safeguard, ensuring the transaction does not execute at an undesired moment, like during network congestion or unfavorable market conditions.
This function simplifies the process of removing liquidity involving ETH by handling the unwrapping of WETH into native ETH.
removeLiquidityWithPermit(_tokenA: address, _tokenAId: uint256, _tokenB: address, _liquidity: uint256, _amountAMin: uint256, _amountBMin: uint256, _to: address, _deadline: uint256, _approveMax: bool, _v: uint8, _r: bytes32, _s: bytes32) -> (uint256, uint256)
The removeLiquidityWithPermit function allows a user to remove liquidity from a pool for a pair of ERC1155 tokens without the need for an additional approval transaction. Instead, the approval is granted through the provided signature components (_v, _r, _s). This signature is validated using the permit function of the liquidity pair contract, after which liquidity is removed as specified.
Parameters
_tokenA: The address of the first ERC1155 token in the pair.
_tokenAId: The ID for the ERC1155 token _tokenA.
_tokenB: The address of the second ERC1155 token in the pair.
_liquidity: The amount of liquidity tokens the caller wishes to redeem.
_amountAMin: The minimum amount of _tokenA the caller is willing to accept.
_amountBMin: The minimum amount of _tokenB the caller is willing to accept.
_to: The recipient address for the redeemed tokens.
_deadline: The latest time by which the transaction should be executed.
_approveMax: A boolean flag determining if the maximum value should be approved.
_v, _r, _s: Components of the signature required to permit the router to pull liquidity on behalf of the user.
Returns
uint256: The amount of _tokenA that was redeemed.
uint256: The amount of _tokenB that was redeemed.
Implementation Details
The function calculates the liquidity pair's address by calling FiveFiveSwapFactory(self.factory).getPair.
If _approveMax is true, the function sets value to the maximum representable integer, otherwise, it sets value to _liquidity.
Using the signature components provided (_v, _r, _s), the function approves the router to pull the specified liquidity amount from the user's account using the pair's permit function.
The function then invokes the internal helper function _removeLiquidity to remove the specified amount of liquidity.
The amounts of _tokenA and _tokenB redeemed are returned.
Usage
This function is especially beneficial for users who wish to optimize transaction gas fees. Instead of requiring an additional transaction to approve the router to pull liquidity, users can provide a signature granting this permission, all within a single transaction.
Notes
The provided _amountAMin and _amountBMin are the minimum amounts the user is willing to accept. If the amounts returned from the liquidity pool are less than these minimums, the transaction will be reverted.
The _deadline parameter provides a time safeguard, ensuring the transaction does not execute at an undesired moment, like during network congestion or unfavorable market conditions.
The _approveMax flag is useful in cases where a user does not want to specify the exact liquidity amount they're approving for removal but would rather approve the maximum amount possible.
removeLiquidityETHWithPermit(_token: address, _tokenId: uint256, _liquidity: uint256, _amountTokenMin: uint256, _amountETHMin: uint256, _to: address, _deadline: uint256, _approveMax: bool, _v: uint8, _r: bytes32, _s: bytes32) -> (uint256, uint256)
The removeLiquidityETHWithPermit function facilitates users to remove liquidity for an ERC1155 token and ether (in the form of wrapped ETH or WETH) pair without requiring a separate approval transaction. This is accomplished through a permit mechanism, where the user signs off on the action, allowing it to proceed without explicit blockchain approval. The transaction reverts if the actual amount received from removing the liquidity is less than the minimum amounts specified by the user.
Parameters
_token: The address of the ERC1155 token.
_tokenId: The ID for the ERC1155 token _token.
_liquidity: The amount of liquidity tokens the user wishes to redeem.
_amountTokenMin: The minimum amount of _token the caller expects to receive.
_amountETHMin: The minimum amount of ether (ETH) the caller expects to receive.
_to: The address to which the tokens and ETH will be sent after liquidity is removed.
_deadline: The latest timestamp until which the transaction should be considered valid.
_approveMax: A boolean flag; if true, approves the maximum integer value.
_v, _r, _s: Components of the signature allowing the function to act with the sender's approval without requiring a prior approve transaction.
Returns
uint256: The amount of _token that was received from removing liquidity.
uint256: The amount of ether (ETH) that was received from removing liquidity.
Implementation Details
Using the FiveFiveSwapFactory contract's getPair function, it determines the liquidity pool pair's address for the provided _token, _tokenId, and the contract's WETH.
If _approveMax is set to true, it assigns the maximum representable integer to value, otherwise, value retains _liquidity's value.
The function then invokes the permit function of the liquidity pool pair (FiveFiveSwapPair) to confirm the withdrawal. The permit is validated using the provided signature (_v, _r, _s).
It calls the internal _removeLiquidityETH function to remove the specified liquidity. This involves:
Ensuring the transaction is still valid by checking that the current block timestamp hasn't exceeded _deadline.
Removing liquidity through the private _removeLiquidity method.
Transferring the respective ERC1155 tokens to the recipient address _to.
Withdrawing the corresponding ether amount using the IWETH interface and sending it to _to.
Returns the amounts of the ERC1155 token and ETH received from the liquidity removal.
Usage
This function is beneficial for users wanting to optimize gas costs. Rather than initiating a distinct transaction to authorize the router to extract liquidity, users can provide a signature that grants this permission, all in a single transaction. This function specifically handles the case where one of the tokens in the pair is ether (wrapped as WETH).
swapExactTokensForTokens(_amountIn: uint256, _amountOutMin: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapExactTokensForTokens function facilitates users to perform a token-to-token swap, where they specify the exact input amount and expect a minimum output amount. The swap can take place across multiple pairs, with the _path parameter outlining the route. Depending on the tokens being ERC1155 or another standard, the swap mechanism slightly varies.
Parameters
_amountIn: The exact amount of input tokens the user is willing to spend.
_amountOutMin: The minimum amount of output tokens the caller expects to receive.
_path: A dynamic array that represents the trading path where each address is a token. The first and last tokens are the input and output tokens, respectively.
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that represents whether each token in the _path is an ERC1155 or not.
_to: The address to which the output tokens will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that are involved in the swap.
Implementation Details
Ensures that the transaction has not expired based on the _deadline.
Computes the expected output amounts for each token in the swap using the _getAmountsOut method. These amounts are based on the input amount, the specified trading path, and the liquidity available in each pair.
Ensures that the last amount in the amounts array (i.e., the final output amount) is greater than or equal to _amountOutMin, ensuring the user gets at least their expected value.
Depending on the type of the first token in _path, the function transfers the input token amount into the first pair contract. If it's an ERC1155 token, it uses the safeTransferFrom method of the ERC1155 standard. Otherwise, it uses the internal _safeTransferFrom method.
Calls the internal _swap method to execute the trades across the specified path.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is used when a user wants to swap an exact amount of one token for another token (or a series of tokens). By providing a path, users can find the most efficient route through multiple pairs.
swapTokensForExactTokens(_amountOut: uint256, _amountInMax: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapTokensForExactTokens function allows users to perform a token-to-token swap where they specify the exact output amount they want and indicate the maximum input amount they're willing to pay. The swap can transpire across multiple pairs, with the _path parameter indicating the route. The mechanism differs slightly based on the token being ERC1155 or another standard.
Parameters
_amountOut: The exact amount of output tokens the user expects to receive.
_amountInMax: The maximum amount of input tokens the user is willing to spend to obtain the desired _amountOut.
_path: A dynamic array that represents the trading path where each address is a token. The first and last tokens are the input and output tokens, respectively.
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that represents whether each token in the _path is an ERC1155 or not.
_to: The address to which the output tokens will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that were involved in the swap.
Implementation Details
Ensures that the transaction has not expired based on the _deadline.
Computes the required input amounts for each token in the swap using the _getAmountsIn method. These amounts are based on the desired output amount, the specified trading path, and the liquidity available in each pair.
The amounts array, which originally presents the amounts in reverse (from output to input), is reversed using _reverseArray so that it starts with the input token amount and ends with the output token amount.
Ensures that the first amount in the amounts array (i.e., the required input amount) is less than or equal to _amountInMax, ensuring the user doesn't pay more than they're willing to.
Depending on the type of the first token in _path, the function transfers the required input token amount into the first pair contract. If it's an ERC1155 token, it uses the safeTransferFrom method of the ERC1155 standard. Otherwise, it uses the internal _safeTransferFrom method.
Calls the internal _swap method to execute the trades across the specified path.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is ideal for users who have a specific output token amount in mind and want to ensure they don't pay more than a certain amount of input tokens. By providing a trading path, users can find the most efficient route through multiple pairs.
swapExactETHForTokens(_amountOutMin: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapExactETHForTokens function allows users to perform a token swap using ETH as input to buy tokens. The function calculates how much of the tokens in the trading path will be received for the provided ETH. If the calculated output token amount is below _amountOutMin, the transaction will fail, ensuring the user gets at least their desired amount.
Parameters
_amountOutMin: The minimum amount of output tokens the user expects to receive.
_path: A dynamic array that represents the trading path where each address is a token. The first and last tokens are the input and output tokens, respectively.
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that represents whether each token in the _path is an ERC1155 or not.
_to: The address to which the output tokens will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that were involved in the swap.
Implementation Details
Checks if the transaction deadline has passed, and if so, the function reverts with an "EXPIRED" error message.
Ensures that the first token in the trading _path is WETH (Wrapped Ether) and that it's not an ERC1155 token.
Calculates the expected output amounts for each token in the swap using the provided ETH amount (i.e., msg.value), the specified trading path, and the liquidity available in each pair.
Ensures the output token amount meets the user's expectations (i.e., it should be at least _amountOutMin).
Deposits the sent ETH into the WETH contract, which in turn mints an equivalent amount of WETH tokens for this contract.
Transfers the minted WETH amount to the first pair in the trading path.
Calls the internal _swap method to execute the trades across the specified path.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is beneficial for users wanting to exchange their ETH for tokens directly without the need to wrap their ETH into WETH manually. The trading path should start with WETH and end with the desired output token. The user can define intermediate tokens in the path to potentially get better rates or liquidity.
swapTokensForExactETH(_amountOut: uint256, _amountInMax: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapTokensForExactETH function enables users to exchange their tokens for a specific amount of ETH. The function calculates the amount of input tokens required to achieve the specified ETH output. If the required input token amount exceeds _amountInMax, the transaction will fail, ensuring the user does not spend more than they intended.
Parameters
_amountOut: The exact amount of ETH the user wants to receive.
_amountInMax: The maximum amount of input tokens the user is willing to spend.
_path: A dynamic array that represents the trading path where each address is a token. The first token is the input, and the last token is ETH (WETH).
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that represents whether each token in the _path is an ERC1155 or not.
_to: The address to which the ETH will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that were involved in the swap.
Implementation Details
Checks if the transaction deadline has passed, and if so, the function reverts with an "EXPIRED" error message.
Ensures that the last token in the trading _path is WETH (Wrapped Ether).
Calculates the required input amounts for each token in the swap to achieve the desired ETH output.
Reverses the amounts array to get the amounts in the correct order for swapping.
Verifies that the required input token amount does not exceed _amountInMax.
Depending on whether the input token is an ERC1155 or not, it safely transfers the required input token amount from the user to the initial liquidity pair in the trading path.
Executes the swaps across the specified path using the internal _swap method.
Withdraws the received WETH amount into ETH.
Sends the received ETH amount to the specified _to address.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is ideal for users who wish to sell their tokens and receive a precise amount of ETH in return. The trading path should start with the input token and end with WETH. Intermediate tokens can be specified in the path for potentially better rates or liquidity.
swapExactTokensForETH(_amountIn: uint256, _amountOutMin: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapExactTokensForETH function allows users to exchange a precise amount of their tokens for at least a specified amount of ETH. The function calculates the expected ETH output for the given token input. If the resulting ETH amount is less than _amountOutMin, the transaction will fail, ensuring the user receives at least the amount they expect.
Parameters
_amountIn: The exact amount of input tokens the user wants to sell.
_amountOutMin: The minimum amount of ETH the user expects to receive.
_path: A dynamic array that represents the trading path where each address is a token. The first token is the input, and the last token is ETH (WETH).
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that indicates whether each token in the _path is an ERC1155 or not.
_to: The address to which the ETH will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that were involved in the swap.
Implementation Details
Checks if the transaction deadline has passed, and if so, the function reverts with an "EXPIRED" error message.
Ensures that the last token in the trading _path is WETH (Wrapped Ether).
Calculates the expected output amounts for each token in the swap given the exact token input.
Verifies that the resulting ETH amount is at least _amountOutMin.
Depending on whether the input token is an ERC1155 or not, it safely transfers the exact input token amount from the user to the initial liquidity pair in the trading path.
Executes the swaps across the specified path using the internal _swap method.
Withdraws the received WETH amount into ETH.
Sends the received ETH amount to the specified _to address.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is ideal for users who have a precise amount of tokens they wish to sell and want to receive at least a specified amount of ETH in return. The trading path should start with the input token and end with WETH. Intermediate tokens can be specified in the path for potentially better rates or liquidity.
swapETHForExactTokens(_amountOut: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS], _to: address, _deadline: uint256) -> DynArray[uint256, MAX_PATHS]
The swapETHForExactTokens function lets users buy an exact amount of tokens by sending ETH. The function calculates the required amount of ETH for the desired token amount. If the ETH sent by the user is more than the required amount, the excess ETH is refunded.
Parameters
_amountOut: The exact amount of tokens the user wants to receive.
_path: A dynamic array that represents the trading path where the first token is ETH (or more precisely, WETH), and the last token is the desired output token.
_tokenIds: A dynamic array of token IDs corresponding to each token in the _path.
_isERC1155: A dynamic boolean array that indicates whether each token in the _path is an ERC1155 or not.
_to: The address to which the tokens will be sent.
_deadline: The latest timestamp until which the transaction should be considered valid.
Returns
DynArray[uint256, MAX_PATHS]: An array representing the amounts of each token that were involved in the swap.
Implementation Details
Checks if the transaction deadline has passed, and if so, the function reverts with an "EXPIRED" error message.
Ensures that the first token in the trading _path is WETH and it's not an ERC1155.
Calculates the expected input amounts (ETH in this case) required to receive the specified token output.
The array amounts is reversed to align the ETH input with the desired token output.
Verifies that the calculated ETH input is less than or equal to the ETH sent by the user.
Deposits the required ETH amount to get WETH (Wrapped Ether).
Transfers the required WETH amount to the initial liquidity pair in the trading path.
Executes the swaps across the specified path using the internal _swap method.
If the user has sent more ETH than required, the function refunds the excess amount.
Returns the array of amounts representing how much of each token was involved in the swap.
Usage
This function is perfect for users who want to buy an exact amount of a specific token by sending ETH. The trading path should start with WETH and end with the desired output token. Intermediate tokens can be specified in the path for potentially better rates or liquidity. If a user sends more ETH than required, they'll be refunded the difference.
quote(_amountA: uint256, _reserveA: uint112, _reserveB: uint112) -> uint256
The quote function is used to estimate the amount of token B that can be obtained for a given amount of token A, based on the current liquidity reserves in the liquidity pool. It's a view function, meaning it only reads the state of the blockchain and does not modify it. It uses an internal function called _quote to perform the actual calculation.
Parameters
_amountA: The amount of token A, the token for which you want to find the equivalent amount in token B.
_reserveA: The liquidity reserve of token A in the liquidity pool.
_reserveB: The liquidity reserve of token B in the liquidity pool.
Returns
uint256: The calculated amount of token B that is equivalent to the given _amountA of token A, based on the current reserves in the liquidity pool.
Implementation Details
Checks that _amountA is greater than 0; otherwise, an "INSUFFICIENT_AMOUNT" error is thrown.
Checks that both _reserveA and _reserveB are greater than 0; otherwise, an "INSUFFICIENT_LIQUIDITY" error is thrown.
Calculates the equivalent amount of token B using the formula (_amountA * convert(_reserveB, uint256)) / convert(_reserveA, uint256).
Usage
This function is useful when a user wants to know how much of token B they can get for a specific amount of token A, given the current liquidity pool reserves. It allows for calculations that inform the user about potential swap outcomes without actually executing the trade.
Note that the returned amount is a quote at the current reserves, and actual execution might vary slightly due to fees or changes in the liquidity pool.
getAmountOut(amountIn: uint256, _reserveIn: uint112, _reserveOut: uint112) -> uint256
The getAmountOut function provides an estimate of the amount of the output token a user will receive when swapping a specific amount of the input token. This is based on the current liquidity reserves in the pool and takes into account a swap fee. The function relies on an internal helper function, _getAmountOut, to perform the actual computation.
Parameters
_amountIn: The amount of an input token that a user wants to swap.
_reserveIn: The liquidity reserve of the input token in the liquidity pool.
_reserveOut: The liquidity reserve of the output token in the liquidity pool.
Returns
uint256: The estimated amount of the output token that will be received for the provided _amountIn of the input token, based on the current liquidity reserves and the swap fee.
Implementation Details
Checks that _amountIn is greater than 0; if not, an "INSUFFICIENT_INPUT_AMOUNT" error is thrown.
Validates that both _reserveIn and _reserveOut have positive values. If either is zero, an "INSUFFICIENT_LIQUIDITY" error is raised.
Calculates the amountInWithFee by multiplying _amountIn with 997. This step incorporates the swap fee, which is usually 0.3% (hence, 997 out of 1000 represents the remaining 99.7%).
Computes the numerator as the product of amountInWithFee and the converted value of _reserveOut.
Determines the denominator by adding amountInWithFee to the product of the converted value of _reserveIn and 1000.
Derives the amountOut by dividing the numerator by the denominator.
Usage
This function is crucial for users who want to understand the amount of the output token they would receive for a given input before executing a swap. It provides a transparent way to account for fees and ensure users receive a fair rate based on current liquidity conditions.
It's important to note that while this function provides an estimate, the actual amount received might differ slightly due to potential changes in liquidity or other dynamic conditions on the blockchain.
getAmountIn(_amountOut: uint256, _reserveIn: uint112, _reserveOut: uint112) -> uint256
The getAmountIn function provides an estimate of the amount of an input token a user will need to provide in order to receive a specified amount of the output token. This calculation is based on the current liquidity reserves in the pool and takes the swap fee into account. The function utilizes an internal helper function, _getAmountIn, to execute the primary computation.
Parameters
_amountOut: The desired amount of the output token that a user wants to receive.
_reserveIn: The liquidity reserve of the input token in the liquidity pool.
_reserveOut: The liquidity reserve of the output token in the liquidity pool.
Returns
uint256: The estimated amount of the input token that will need to be provided to receive the specified _amountOut of the output token, based on current liquidity reserves and the swap fee.
Implementation Details
Checks that _amountOut is greater than 0; if not, an "INSUFFICIENT_INPUT_AMOUNT" error is thrown.
Validates that both _reserveIn and _reserveOut have positive values. If either is zero, an "INSUFFICIENT_LIQUIDITY" error is raised.
Calculates the numerator by multiplying the converted value of _reserveIn with _amountOut and then by 1000.
Computes the denominator by multiplying the difference between the converted value of _reserveOut and _amountOut by 997. This step incorporates the swap fee, usually 0.3% (thus, 997 out of 1000 represents the remaining 99.7%).
Determines the amountIn by dividing the numerator by the denominator and then adding 1.
Usage
This function is essential for users who want to ascertain the amount of the input token they'd need to provide in order to obtain a desired amount of the output token. It offers a transparent way to account for fees and ensures users get a fair rate based on the prevailing liquidity conditions.
It's crucial to note that while this function provides an estimate, the actual amount needed might vary marginally due to potential liquidity changes or other dynamic blockchain conditions.
getAmountsOut(_amountIn: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS]) -> DynArray[uint256, MAX_PATHS]
The getAmountsOut function provides estimates of the output amounts for a multi-token swap. It uses the specified swap path to determine the expected output amounts based on current liquidity reserves and swap fees. The function utilizes an internal helper function, _getAmountsOut, to execute the primary computation.
Parameters
_amountIn: The initial amount of the input token that a user plans to swap.
_path: A dynamic array indicating the route the swap will take across multiple tokens.
_tokenIds: A dynamic array representing the token IDs associated with the provided path (relevant for ERC-1155 tokens).
_isERC1155: A dynamic array indicating if each token in the path is an ERC-1155 token.
Returns
DynArray[uint256, MAX_PATHS]: A dynamic array indicating the expected output amounts of each token in the path, for the provided input amount.
Implementation Details
Validates that the length of path is at least 2. Otherwise, it raises an "INVALID_PATH" error.
Ensures the lengths of tokenIds and isERC1155 arrays match the length of path. If not, it throws an "INVALID_PATH" error.
Initializes the amounts array and appends the initial input amount, amountIn, to it.
Iterates through each token in the path (up to MAX_PATHS-1):
If the current index plus one reaches the end of the path, the loop breaks.
Fetches the liquidity reserves for the current and next tokens in the path. The order of reserves (input vs. output) depends on whether the token is ERC-1155.
Uses the _getAmountOut function to calculate the expected output amount for the current swap step and appends it to the amounts array.
Returns the amounts array containing the expected output amounts for the entire swap path.
Usage
The getAmountsOut function is critical for users or DApps that intend to conduct multi-token swaps. It offers a transparent way to anticipate the expected output for each token in the path, taking into account prevailing liquidity conditions and swap fees.
It's important to note that while this function provides estimates, actual amounts may slightly vary due to potential changes in liquidity or other dynamic blockchain conditions.
getAmountsIn(_amountOut: uint256, _path: DynArray[address, MAX_PATHS], _tokenIds: DynArray[uint256, MAX_PATHS], _isERC1155: DynArray[bool, MAX_PATHS]) -> DynArray[uint256, MAX_PATHS]
The getAmountsIn function provides estimates of the input amounts required to achieve a specified output amount for a multi-token swap. It uses the given swap path to determine the needed input amounts based on current liquidity reserves and swap fees. The function leverages an internal helper function, _getAmountsIn, to execute the primary computation. It then reverses the output array before returning the results.
Parameters
_amountOut: The desired final amount of the output token in a swap.
_path: A dynamic array indicating the route the swap will take across multiple tokens.
_tokenIds: A dynamic array representing the token IDs associated with the provided path (relevant for ERC-1155 tokens).
_isERC1155: A dynamic array indicating if each token in the path is an ERC-1155 token.
Returns
DynArray[uint256, MAX_PATHS]: A dynamic array indicating the required input amounts of each token in the path, to achieve the provided output amount.
Implementation Details
Validates that the length of path is at least 2. If not, it raises an "INVALID_PATH" error.
Checks that the lengths of tokenIds and isERC1155 arrays match the length of path. If not, it raises an "INVALID_PATH" error.
Initializes the amounts array and appends the desired output amount, amountOut, to it.
Sets a numAmounts counter to 0.
Gets the length of the path and starts iterating through each token in the path in a reverse manner (from last to first).
Fetches the liquidity reserves for the current and previous tokens in the path. The order of reserves depends on whether the token is an ERC-1155 or not.
Uses the _getAmountIn function to calculate the required input amount for the current swap step and appends it to the amounts array. The counter numAmounts is then incremented.
Returns the amounts array containing the required input amounts for the entire swap path.
Usage
The getAmountsIn function is vital for users or DApps planning to execute multi-token swaps. It offers a transparent way to determine the necessary input for each token in the path to achieve a desired output, considering prevailing liquidity conditions and swap fees.
Users should be aware that while this function offers estimates, the actual amounts might differ slightly due to potential fluctuations in liquidity or other dynamic blockchain factors.
Last updated