vRouter 1.3

VirtuSwap vRouter implements trading functionality by interacting with vPair contracts to perform the swaps. Version 1.3 is more gas-optimized and can use rerouting when virtual pools are locked.

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 multiSwapExactETHForTokens

function multiSwapExactETHForTokens(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenOut,
    address to,
    uint256 minAmountOut
) external payable;

Receive a maximum amount of output token for a given amount of WETH9 following a given swap path provided in the routeData array of route steps. The transitTokens array of token addresses determines the list of pools between those tokens. The tokenOut is the output token.

The function uses the swapNative and swapReserveToNative methods of the relevant vPair instances.

If the resulting output amount is lower than minAmountOut, the operation fails.

Parameters:

Name	Type	Description
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenOut	address	The output token
to	address	Address to receive the bought tokens
minAmountOut	uint256	Minimum amount of tokenOut to be received

function multiSwapExactTokensForETH

function multiSwapExactTokensForETH(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenIn,
    address to,
    uint256 minAmountOut
) external;

Receive a maximum amount of WETH9 for a given amount of input token following a given swap path provided in the routeData array of route steps. The transitTokens array of token addresses determines the list of pools between those tokens. The tokenIn is the input token.

The function uses the swapNative and swapReserveToNative methods of the relevant vPair instances.

If the resulting output amount is lower than minAmountOut, the operation fails.

Parameters:

Name	Type	Description
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenIn	address	The input token
to	address	Address to receive the bought tokens
minAmountOut	uint256	Minimum amount of ETH to be received

function multiSwapETHForExactTokens

function multiSwapETHForExactTokens(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenOut,
    address to,
    uint256 maxAmountIn
) external payable;

Receive an exact amount of output token for as few WETH9 as possible, following a given swap path provided in the routeData array of route steps. The transitTokens array of token addresses determines the list of pools between those tokens. The tokenOut is the output token.

The function uses the swapNative and swapReserveToNative methods 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
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenOut	address	The output token
to	address	Address to receive the bought tokens
maxAmountIn	uint256	Maximum amount of ETH to be spent

function multiSwapTokensForExactETH

function multiSwapTokensForExactETH(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenIn,
    address to,
    uint256 maxAmountIn
) external;

Receive an exact amount of WETH9 for as few input tokens as possible, following a given swap path provided in the routeData array of route steps. The transitTokens array of token addresses determines the list of pools between those tokens. The tokenIn is the input token.

The function uses the swapNative and swapReserveToNative methods 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
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenIn	address	The input token
to	address	Address to receive the bought tokens
maxAmountIn	uint256	Maximum amount of tokenIn to be spent

function multiSwapTokensForExactTokens

function multiSwapTokensForExactTokens(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenIn,
    address tokenOut,
    address to,
    uint256 maxAmountIn
) 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 routeData array of route steps. The transitTokens is an array of token addresses that determines the list of pools between those tokens (note: in VirtuSwap there is always one pool connecting two tokens). The tokenIn is the input token and the tokenOut in the output token.

The function uses the swapNative and swapReserveToNative methods of the relevant vPair instances.

If the amount of sold token required to receive the amountOut is greater than maxAmountIn, the operation fails.

Parameters:

Name	Type	Description
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenIn	address	The input token
tokenOut	address	The output token
to	address	Address to receive the bought tokens
maxAmountIn	uint256	Maximum amount of tokenIn to be spent

function multiSwapExactTokensForTokens

function multiSwapExactTokensForTokens(
    uint256 deadline,
    RouteData[] calldata routeData,
    address[] calldata transitTokens,
    address tokenIn,
    address tokenOut,
    address to,
    uint256 minAmountOut
) external;

Swaps an exact amount input token for as many output tokens as possible, along the route determined by the routeData array of route steps. The transitTokens is an array of token addresses that determines the list of pools between those tokens (note: in VirtuSwap there is always one pool connecting two tokens). The tokenIn is the input token and the tokenOut in the output token.

The function uses the swapNative and swapReserveToNative methods of the relevant vPair instances.

If the amount of received token is lower than minAmountOut, the operation fails.

Parameters:

Name	Type	Description
deadline	uint256	The deadline for the trade to happen. If the trade is executed after the deadline timestamp, it will be reverted.
routeData	RouteData[] calldata	List of compact information about trading routes
transitTokens	address[] calldata	List of addresses of transit tokens that define vPair instances to be used to perform the swap
tokenIn	address	The input token
tokenOut	address	The output token
to	address	Address to receive the bought tokens
minAmountOut	uint256	Minimum amount of tokenOut to be received

function vFlashSwapCallback

function vFlashSwapCallback( 
        address tokenIn, 
        address tokenOut, 
        uint256 requiredBackAmount, 
        bytes calldata data 
) external override

A callback method called by a vPair instance to request transfer of the necessary amount of input tokens to perform the swap. The call is performed from vPair's swapReserveToNative method after it is called from vRouter's trySwapReserveExactIn or trySwapReserveExactOut methods. vFlashSwapCallback checks that the sender is the expected vPair and performs the transfer to the vPair instance.

Parameters:

Name	Type	Description
tokenIn	address	Address of the token being sold in the swap
tokenOut	address	Address of the token being bought in the swap
requiredBackAmount	uint256	Amount of tokens requested to transfer to vPair
calldata	bytes	Encoded call data struct PoolCallbackData { address from; // token sender address poolToken; // token to recover and verify the pair address }

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.