vRouter 1.2
VirtuSwap vRouter implements trading functionality. vRouter interacts with vPair contracts to perform the actual swaps. Version 1.2 supports payable multicalls.
Events
Event RouterFactoryChanged
event RouterFactoryChanged(
address newFactoryAddress
);Emitted when the Factory address is changed in changeFactory function.
Read-only functions
function getAmountOut
function getAmountOut(
address tokenIn,
address tokenOut,
uint256 amountIn
) external view virtual override returns (uint256 amountOut)Returns the amount that will be returned by swapping a given amount of tokenIn to tokenOut in the direct pool between the two tokens.
✏️ A native pool between tokenIn and tokenOut must exist in VirtuSwap. If it doesn't exist, the operation fails.
Parameters:
tokenIn
address
Address of the token to be sold (input token)
tokenOut
address
Address of the token to be bought (output token)
amountIn
uint256
Amount to be sold
function getAmountIn
function getAmountIn(
address tokenIn,
address tokenOut,
uint256 amountOut
) external view virtual override returns (uint256 amountIn)Returns the amount of tokenIn that is required to be swapped to receive a given amount of tokenOut from the direct pool between the two tokens.
✏️ A native pool between tokenIn and tokenOut must exist in VirtuSwap. If it doesn't exist, the operation fails.
Parameters:
tokenIn
address
Address of the token to be sold (input token)
tokenOut
address
Address of the token to be bought (output token)
amountOut
uint256
Amount to be bought
function getVirtualAmountOut
function getVirtualAmountOut(
address jkPair,
address ikPair,
uint256 amountIn
) public view override returns (uint256 amountOut) Returns the amount of output tokens that will be returned by swapping a given amount of input tokens in a Virtual Pool constructed from given Active Pool and Reference Pool.
✏️ The identity of input and output tokens is determined automatically: the input token is the non-common token of the Reference Pool, and the output token is the non-common token of the Active Pool. See Virtual Pools for more details.
Parameters:
jkPair
address
Address of the Active Pool
ikPair
address
Address of the Reference Pool
amountIn
uint256
Amount to be sold
function getVirtualAmountIn
function getVirtualAmountIn(
address jkPair,
address ikPair,
uint256 amountOut
) external view override returns (uint256 amountIn)Returns the amount of input tokens required to receive a given amount of output tokens from the Virtual Pool constructed from given Active Pool and Reference Pool.
✏️ The identity of input and output tokens is determined automatically: the input token is the non-common token of the Reference Pool, and the output token is the non-common token of the Active Pool. See Virtual Pools for more details.
Parameters:
jkPair
address
Address of the Active Pool
ikPair
address
Address of the Reference Pool
amountOut
uint256
Amount to be bought
function quote
function quote(
address inputToken,
address outputToken,
uint256 amountIn
) external view override returns (uint256 amountOut)Returns the implied output amount of output token in the direct pool between input token and output token, given an amountIn. Essentially, the implied amount out is the the input amount multiplied by the ratio between the amounts of two assets in the pool. Implied amount out can be thought of as the output amount that would be received with infinite liquidity and without fees.
✏️ A native pool between tokenIn and tokenOut must exist in VirtuSwap. If it doesn't exist, the operation fails.
Parameters:
inputToken
address
Input token
outputToken
address
Output token
amountIn
uint256
amount to be sold
function getMaxVirtualTradeAmountRtoN
function getMaxVirtualTradeAmountRtoN(
address jkPair,
address ikPair
) external view override returns (uint256 maxAmountIn) Returns the maximum amount of a reserve asset token that can be swapped for the native asset in a Virtual Pool created from a given Active and Reference Pools. The method takes into account the value of all reserves already present in the Active Pool and the Reserve Threshold of the Active Pool. See Reserve Ratio and Threshold for more details.
✏️ The identity of the reserve and the native tokens to be swapped is determined automatically: the reserve token is the non-common token of the Reference Pool, and the native token is the non-common token of the Active Pool. See Virtual Pools for more details.
Parameters:
jkPair
address
Address of the Active Pool of the Virtual Pool
ikPair
address
Address of the Reference Pool of the Virtual Pool
function getVirtualPool
function getVirtualPool(
address jkPair,
address ikPair
) internal view returns (VirtualPoolModel memory vPool)Returns a VirtualPoolModel structure reflecting the state of the virtual pool composed from the given Active Pool and Reference Pool.
✏️ Active Pool and the Reference Pool must have one asset in common. Also, Active Pool must accept the non-common token of Reference Pool as reserve. If either of those conditions is false, the operation fails.
Parameters:
jkPair
address
Address of the Active Pool of the Virtual Pool
ikPair
address
Address of the Reference Pool of the Virtual Pool
function getVirtualPools
function getVirtualPools(
address token0,
address token1
) external view returns (VirtualPoolModel[] memory vPools);Returns an array of VirtualPoolModel instances representing all Virtual Pools that are available between two given tokens.
See How Virtual Pools Work for details on how Virtual Pools are constructed.
Parameters:
token0
address
First token
token1
address
Second token
function factory
function factory()
external view
returns (address);Returns the vPairFactory instance.
function WETH9
function WETH9() external view returns (address);Returns the canonical address of the network's native currency (ETH for Ethereum mainnet, MATIC for Polygon PoS, etc.)
The WETH9 address is passed by the creator to the constructor of the vRouter instance.
Swap Functions
function swapExactETHForTokens
function swapExactETHForTokens(
address[] memory path,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external payable;Receive a maximum amount of output token for a given amount of WETH9 following a given swap path provided in the path array of token addresses. The list of token addresses determines the list of pools between those tokens. The output token is the last token in the path array. The first element of the path array must be WETH9.
The function uses the swapNative method of the relevant vPair instances.
If the resulting output amount is lower than minAmountOut, the operation fails.
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountIn
uint256
amount of WETH9 to be swapped
minAmountOut
uint256
Minimum amount to be received
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapExactTokensForETH
function swapExactTokensForETH(
address[] memory path,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external;Receive a maximum amount of WETH9 for a given amount of input token following a given swap path provided in the path array of token addresses. The list of token addresses determines the list of pools between those tokens. The first token in the path array is the input token. The last element of the path array must be WETH9.
The function uses the swapNative method of the relevant vPair instance.
If the resulting output amount is lower than minAmountOut, the operation fails.
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountIn
uint256
amount of input token to be swapped
minAmountOut
uint256
Minimum WETH9 amount to be received
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapETHForExactTokens
function swapETHForExactTokens(
address[] memory path,
uint256 amountOut,
uint256 maxAmountIn,
address to,
uint256 deadline
) external payable;Receive an exact amount of output token for as few WETH9 as possible, following a given swap path provided in the path array of token addresses. The list of token addresses determines the list of pools between those tokens. The first token in the path array must be WETH9. The last element of the path array is the output token.
The function uses the swapNative method of the relevant vPair instances.
If the amount of ETH required to receive the amountOut is greater than maxAmountIn, the operation fails.
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountOut
uint256
required amount of the target token
maxAmountIn
uint256
Maximum amount of ETH to be spent
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapTokensForExactETH
function swapExactTokensForETH(
address[] memory path,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external Receive an exact amount of WETH9 for as few input tokens as possible, following a given swap path provided as the path array of token addresses. The list of token addresses determines the list of pools between those tokens. The first token in the path array is the input token. The last element of the path array must be WETH9.
The function uses the swapNative method of the relevant vPair instances.
If the amount of token required to receive the amountOut WETH9 is greater than maxAmountIn, the operation fails.
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountOut
uint256
required amount of ETH
maxAmountIn
uint256
Maximum amount of source token to be spent
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveETHForExactTokens
function swapReserveETHForExactTokens(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountOut,
uint256 maxAmountIn,
address to,
uint256 deadline
) external payableReceive an exact amountOut of output tokens for as few WETH9 as possible performing a swap on the virtual pool defined by a jkPair between tokenOut and commonToken, and an ikPair.
✏️ The ikPair must be between commonToken and WETH9
If the WETH9 amount required to receive the specified amountOut is greater than maxAmountIn, the operation fails.
Parameters:
tokenOut
address
The token to be bought
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountOut
uint256
required amount to be received
maxAmountIn
uint256
Maximum amount to be sold
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveTokensForExactETH
function swapReserveTokensForExactETH(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountOut,
uint256 maxAmountIn,
address to,
uint256 deadline
) externalReceive an exact amountOut of WETH9 for as few input tokens as possible performing a swap on the virtual pool is defined by the jkPair between tokenOut and commonToken, and the given ikPair
✏️ The ikPair must be between the commonToken and the token that is being sold
If the amount of sold token required to receive the amountOut is greater than maxAmountIn, the operation fails
Parameters:
tokenOut
address
The token to be bought. Must be WETH9
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountOut
uint256
required amount to be received
maxAmountIn
uint256
Maximum amount of ETH to be sold
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveExactETHForTokens
function swapReserveExactETHForTokens(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external payable;Swap a given amountIn of WETH9 for as much tokenOut as possible on a virtual pool defined by a jkPair between tokenOut and commonToken, and an ikPair.
✏️ The ikPair must be between commonToken and ETH
If the output amount is below minAmountOut, the operation fails
Parameters:
tokenOut
address
The token to be bought
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountIn
uint256
amount of WETH9 to be sold
minAmountOut
uint256
Minimum amount of tokenOut to be received
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveExactTokensForETH
function swapReserveExactTokensForETH(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external;Swaps a given amountIn of input token for as much WETH9 as possible using a virtual pool. The virtual pool is defined by the jkPair between tokenOut and commonToken, and the given ikPair
✏️ The ikPair must be between the commonToken and the input token
If the amount of WETH9 received is smaller than minAmountOut, the operation fails
Parameters:
tokenOut
address
The token to be bought. Must be WETH9
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountOut
uint256
required amount to be received
maxAmountIn
uint256
Maximum amount of WETH9 to be sold
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapTokensForExactTokens
function swapTokensForExactTokens(
address[] memory path,
uint256 amountOut,
uint256 maxAmountIn,
address to,
uint256 deadline
) external;Receive a given amountOut of the output token for as few input tokens as possible performing a series of swaps along the route determined by the path. The path parameter is an array of token addresses and it determines the array of pools between those tokens (note: in VirtuSwap there is always one pool connecting two tokens). In the path array, the first token is the input token and the last token in the output token.
If the amount of sold token required to receive the amountOut is greater than maxAmountIn, the operation fails
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountOut
uint256
Required amount of output token to be received
maxAmountIn
uint256
Maximum amount of input token to be spent
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapExactTokensForTokens
function swapExactTokensForTokens(
address[] memory path,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external;Swaps an exact amount input token for as many output tokens as possible, along the route determined by the path. The path parameter is an array of token addresses and it determines the array of pools between those tokens (note: in VirtuSwap there is always one pool connecting two tokens). In the path array, the first element is the input token and the last element in the output token.
If the amount of received token is lower than minAmountOut, the operation fails
Parameters:
path
address[] memory
List of addresses of tokens that define vPair instances to be used to perform the swap
amountIn
uint256
Amount of the input token to be sold
minAmountOut
uint256
Minimum amount of output token to be received
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveTokensForExactTokens
function swapTokensForExactTokens(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountOut,
uint256 maxAmountIn,
address to,
uint256 deadline
) external;Receive a given amountOut of the output token for as few input tokens as possible performing a swap on the virtual pool defined by a jkPair between tokenOut and commonToken, and an ikPair.
✏️ The ikPair must be between the commonToken and the token that is being sold
If the amount of sold token required to receive the amountOut is greater than maxAmountIn, the operation fails
Parameters:
tokenOut
address
The token to be bought.
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountOut
uint256
required amount to be received
maxAmountIn
uint256
Maximum amount be sold
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
function swapReserveExactTokensForTokens
function swapReserveExactTokensForTokens(
address tokenOut,
address commonToken,
address ikPair,
uint256 amountIn,
uint256 minAmountOut,
address to,
uint256 deadline
) external;Swap a given amountIn of the input token for as much input tokens as possible performing a swap on the virtual pool defined by a jkPair between tokenOut and commonToken, and an ikPair.
✏️ The ikPair must be between the commonToken and the token that is being sold
If the output amount is less than minAmountOut, the operation fails
Parameters:
tokenOut
address
The token to be bought.
commonToken
address
Common token between jkPair and ikPair
ikPair
address
ikPair used as reference pool in the virtual pool
amountIn
uint256
amount to be swapped
minAmountOut
uint256
Minimum amount of to be received
to
address
Address to receive the bought tokens
deadline
uint256
The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
Refund functions
function refundETH
function refundETH() external payable;Refund excess ETH sent during a transaction.
If the sender interacts with this vRouter contract and sends more ETH than necessary, this function ensures that the extra ETH is returned to the sender.
The refundETH should be called after any swap*ETHFor*Tokens function call to prevent any loss of funds.
Liquidity provision functions
function addLiquidity
function addLiquidity(
address tokenA,
address tokenB,
uint256 amountADesired,
uint256 amountBDesired,
uint256 amountAMin,
uint256 amountBMin,
address to,
uint256 deadline
) external override notAfter(deadline)
returns (
uint256 amountA,
uint256 amountB,
address pairAddress,
uint256 liquidity
)Adds liquidity to a pool, according to the current ratio between the two assets in the pool.
Prior to the call, the sender must give the router allowance of at least amountADesired and amountBDesired of tokenA and tokenB respectively. The functions adds assets according to the ratio between the two sides at the moment the function is called.
The function calls the mint function of the underlying vPair instance.
✏️ The actual amount to be deposited is calculated according to the ratio between the tokens at the time of the actual transaction, and thus may not be equal to the desired amounts. If the calculated amounts in one of the tokens is lower than the respective minimum amount, the transaction fails.
✏️ If the pair between TokenA and TokenB does not exist, it will be created.
Parameters:
tokenA
address
Address of the first token in the pair
tokenB
address
Address of the second token in the pair
amountADesired
uint256
Amount of token A the caller wishes to deposit to the pool
amountBDesired
uint256
Amount of token A the caller wishes to deposit to the pool
amountAMin
uint256
Minimum amount of token A the caller is willing to deposit in the pool.
amountBMin
address
Minimum amount of token B the caller is willing to deposit in the pool.
to
address
address to receive the LP tokens
deadline
uint256
The deadline for the operation to happen.
Returns:
amountA
uint256
Amount of tokenA that was actually deposited to the pool
amountB
uint256
Amount of tokenB that was actually deposited to the pool
pairAddress
address
Address of the pool
liquidity
uint256
Product of balances of the two tokens in the pool (K)
function removeLiquidity
function removeLiquidity(
address tokenA,
address tokenB,
uint256 liquidity,
uint256 amountAMin,
uint256 amountBMin,
address to,
uint256 deadline
) external override notAfter(deadline)
returns (
uint256 amountA,
uint256 amountB
)Removes liquidity from a, according to the current ratio between the two assets in the pool.
Prior to the call, the sender must give the router allowance of the amount of LP Tokens they wish to redeem
The function calls the burn function of the underlying vPair instance.
✏️ The actual amount to be removed is calculated according to the ratio between the tokens at the time of the actual transaction. If the calculated amounts in one of the tokens is lower than the respective minimum amount, the transaction fails.
✏️ A pair between TokenA and TokenB must exist.
Parameters:
tokenA
address
Address of the first token in the pair
tokenB
address
Address of the second token in the pair
liquidity
uint256
Number of LP tokens to be redeemed
amountAMin
uint256
Minimum amount of token A the caller is willing to get.
amountBMin
address
Minimum amount of token B the caller is willing to get.
to
address
address to receive the tokens
deadline
uint256
The deadline for the operation to happen.
Returns:
amountA
uint256
Amount of tokenA that was actually removed from the pool
amountB
uint256
Amount of tokenB that was actually removed from the pool
State-changing Functions
function changeFactory
function changeFactory(
address _factory
) external override onlyOwnerChanges the address of the PairFactory contract instance. The PairFactory is responsible for creating and keeping the information on Pair instances.
✏️Can only be called by the owner of the Router contract.
Last updated