vRouter 1.1

VirtuSwap vRouter implements trading functionality. vRouter interacts with vPair contracts to perform the actual swaps.

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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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 payable

Receive 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:

Name	Type	Description
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
) external

Receive 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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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.

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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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:

Name	Type	Description
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 onlyOwner

Changes 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.