vPair

Implements the functionality of a VirtuSwap reserve-powered AMM Pool

Events

event Mint

event Mint(
    address indexed sender, 
    uint256 amount0, 
    uint256 amount1,
    uint lpTokens,
    uint poolLPTokens
);

Emitted every time liquidity tokens are created in mint function.

event Burn

event Burn(
    address indexed sender, 
    uint256 amount0, 
    uint256 amount1, 
    address indexed to,
    uint256 totalSupply
);

Emitted every time liquidity tokens are destroyed in burn function.

event Swap

event Swap(
        address indexed sender,
        address tokenIn,
        address tokenOut,
        uint256 amountIn,
        uint256 amountOut,
        address indexed to
    );

Emitted every time a native token swap happens in swapNative function.

event SwapReserve

event SwapReserve(
        address indexed sender,
        address tokenIn,
        address tokenOut,
        uint256 amountIn,
        uint256 amountOut,
        address ikPool,
        address indexed to
    );

Emitted every time a reserve-powered token swap happens in swapNativeToReserve or swapReserveToNative function.

ikPool is the address of the pool that composes the virtual pool together with the pool that emits the event.

event AllowListChanged

event AllowListChanged(address[] tokens);

Emitted every time a the list of tokens accepted as reserves is updated in setAllowList function.

event AllowListCountChanged

event AllowListCountChanged(uint24 _maxAllowListCount);

Emitted every time the maximum number of tokens accepted as reserves is updated in setAllowListCount function.

event Sync

event Sync(
        uint112 balance0, 
        uint112 balance1
        )

Emitted every time the balances of native tokens change in swapNative, swapReserveToNative, swapNativeToReserve, mint or burn functions.

event ReserveSync

event ReserveSync(
    address asset, 
    uint256 balance, 
    uint256 rRatio
    );

Emitted every time the balance of a reserve token is updated in swapReserveToNative or swapNativeToReserve

event FeeChanged

event FeeChanged(uint16 fee, uint16 vFee);

Emitted when fee is changed in setFee function.

event ReserveThresholdChanged

event ReserveThresholdChanged(uint256 newThreshold);

Emitted when reserve threshold is changed in setMaxReserveThreshold function.

event BlocksDelayChanged

 event BlocksDelayChanged(uint256 _newBlocksDelay);

Emitted when block delay is changed inside setBlocksDelay function.

event ReserveRatioWarningThresholdChanged

event ReserveRatioWarningThresholdChanged(
     uint256 _newReserveRatioWarningThreshold
);

Emitted when reserve ratio warning parameter is changed in setReserveRatioWarningThreshold function.

State-Changing Functions

function swapNative

function swapNative( 
        uint256 amountOut, 
        address tokenOut, 
        address to, 
        bytes memory data
 ) external override lock returns (uint256 _amountIn)

Performs a swap between the two native assets of the pool, getting the specified amount of a native asset. Sufficient amount of the input token must be transferred to the contract before the call, or can be transferred during the call using IvFhashSwapCallback interface.

emits Sync and Swap events

✏️To safely use the swapNative function, it must be called from a periphery smart contract to ensure the operation is atomic. Calling swapNative method directly after transferring input tokens to the vPair contract is not safe because the sent tokens would be exposed to arbitrage.

Parameters:

Name	Type	Description
amountOut	uint256	Amount of output tokens to receive
tokenOut	address	Address of the token contract of the token to be received
to	address	Recipient of the output tokens
data	byte memory	if populated, the flash swap will be invoked. The data will be passed back to the caller via vFlashSwapCallback method of IvFlashSwapCallback interface

function swapReserveToNative

function swapReserveToNative( 
    uint256 amountOut,
    address ikPair,
    address to,
    bytes calldata data
) external override lock returns (uint256 amountIn)

Performs a swap between a reserve token of the pool and the native token using a virtual pool. The virtual pool is constructed from the called instance as Active Pool and the ikPair as Reference Pool. Sufficient amount of the reserve token must be transferred to the vPaircontract before the call, or can be transferred during the call using IvFhashSwapCallback interface. The output asset is determined automatically from the virtual pool.

emits Sync and SwapReserve event

✏️To safely use the swapReserveToNative function, it must be called from a periphery smart contract to ensure the operation is atomic. Calling the method directly after transferring input tokens to the vPair contract is not safe because the sent tokens would be exposed to arbitrage.

Name	Type	Description
amountOut	uint256	Amount of output token to receive
ikPair	address	Address of the VirtuSwap pool to be used as reference pool for creating the virtual pool
to	address	Recipient of the output tokens
data	bytes calldata	if populated, the flash swap will be invoked. The data will be passed back to the caller via vFlashSwapCallback method of IvFlashSwapCallback interface

function swapNativeToReserve

function swapNativeToReserve(
    uint256 amountOut,
    address ikPair,
    address to,
    uint256 incentivesLimitPct,
    bytes calldata data
)
    external
    override
    nonReentrant
    returns (address _leftoverToken, uint256 _leftoverAmount)

Performs a swap of one of the pool's reserve assets to the pool's native asset. The method can be called as part of the Exchange of Reserves process between VirtuSwap pools, or as part of forced liquidation of reserves by the Admin or Emergency Admin. The called vPair sends its reserve token to the target pool or to the Admin/Emergency Admin (specified as to parameter), and receives its own native token in exchange.

The necessary amount of input tokens must be sent to the vPair prior to the call.

The exchange rate R between the two tokens is calculated using a virtual pool constructed between the vPair instance used as Active Pool and the given ikPair as Reference Pool. The method validates that the amount of input tokens passed to the the vPair instance is greater or equal to amountOut * R. When two pools are exchanging reserves, each of them calculates the R differently, thus one of the pools sends an amount that is larger than the recipient pool needs, thus creating leftovers.

A certain percentage of the leftovers, specified by theincentivesLimitPct parameter is sent to the caller as a reward for running the transaction. Initially, the Reserve Exchange routine will be called by the VirtuSwap DAO, and incentivesLimitPct will be set to 0, i.e. all the leftovers will remain in the pools. See vEchangeReserves.

In case of liquidation of reserves (only callable by Admin or Emergency Admin), the vPair instance will agree to receive a lower amount of native token than the amount calculated using the virtual pool. The discount from that amount that the vPair is willing to accept is defined by the emergencyDiscount variable

See vExchangeReserves for more detail on the reserve exchange routine.

✏️ The method can only be called by the vExchangeReserves contract or by the Admin or EmergencyAdmin wallets

✏️ The identity of the two tokens is determined from the virtual pool defined by the called vPair and the ikPair

emits Sync and SwapReserve event

Name	Type	Description
amountOut	uint256	Requested amount of reserve asset
ikPair	address	Address of the vPair to be used as Reference Pool in the Virtual Pool used to determine the token price
to	address	Address of the target pool that will receive reserve tokens
incentivesLimitPct	uint256	The maximum percentage of the leftovers that the caller can receive from calling the method
data	bytes calldata	If populated, the flash swap will be invoked. The data will be passed back to the caller via vFlashSwapCallback method of IvFlashSwapCallback interface

function liquidateReserve

   function liquidateReserve(
        address reserveToken,
        address nativePool
    ) external override nonReentrant

Called by the admin or emergencyAdmin in cases where a reserve asset in a pool cannot be exchanged normally during reserve exchange procedure.

✏️Can only be called by the admin or emergency admin

Name	Type	Description
reserveToken	address	Address of the reserve token to be liquidated
nativePool	address	Address of the pool that will be used for liquidation

function mint

 function mint(
    address to
 ) external override lock returns (uint256 liquidity)

Mints LP tokens representing the caller's share in the pool. Both pool tokens must to be transferred to the vPair contract prior to calling mint.

If successful, the sender receives LP tokens corresponding to the transferred amount. The sender's share of LP tokens is calculated taking into account the total value of reserve tokens present in the pool. The method returns the number of LP tokens minted.

emits Sync and Mint events

✏️The method should be called from a periphery smart contract to avoid exposure to arbitrage.

Parameters:

Name	Type	Description
to	address	Recipient of the LP tokens

function burn

function burn(
    address to
) external override lock returns (uint256 amount0, uint256 amount1)

Burns the LP tokens transferred by the user and transfers the caller's share of the native and reserve tokens to the caller. Returns the amount of native token0 and native token1 transferred.

emits Sync and Burn events

Parameters:

Name	Type	Description
to	address	Recipient of the native and reserve tokens

function setAllowList

function setAllowList(
    address[] memory _allowList
) external override onlyFactoryAdmin

Updates the list of tokens that can be accepted as reserves in the pool.

Emits AllowListChanged event.

✏️ The addresses in the address[] array must be sorted ascending and they must be unique

✏️ Can only be called by the Factory Admin

function setMaxAllowListCount

function setMaxAllowListCount(
    uint24 _maxAllowListCount
) external override onlyFactoryAdmin

Updates the maximum number of tokens hat can be accepted as reserves in the pool.

Emits AllowListCountChanged event.

✏️Can only be called by the Factory Admin

function setMaxReserveThreshold

function setMaxReserveThreshold(
    uint256 threshold
) external override onlyFactoryAdmin

Sets the maximum allowed value of reserve threshold. Reserve threshold is the ratio between the total value of reserve tokens in the pools and the value of native tokens. The value should be passed as desired percent * 1000, e.g. for 1.9% reserve threshold, pass 1900. Normally, the ratio is very low, e.g. 2%.

Emits ReserveThresholdChanged event.

✏️Can only be called by the factory admin.

Parameters:

Name	Type	Description
threshold	uint256	Updated value of the threshold

function setFee

function setFee(
    uint16 _fee, 
    uint16 _vFee
) external override onlyFactoryAdmin

Sets the trading fees for the pool. A separate fee can be set for the native token swap (swapNative) and for swap using virtual pools (swapReserveToNative).

The fee applied to each trade is calculated as follows: (1000 - _fee)/1000, so in order to set the trading fee at 0.3%, the caller needs to pass 997 as the parameter.

Emits FeeChanged event.

✏️Can only be called by the admin.

Parameters:

Name	Type	Description
_fee	uint16	value for native to native token swaps
_vFee	uint16	value for reserve to native token swaps

function setBlocksDelay

function setBlocksDelay(uint128 _newBlocksDelay) 

Sets the delay in blocks that needs to expire before a trade performed on a reference pool can influence the price in a virtual pool using that reference pool.

✏️Can only be called by the admin or emergency admin

function setReserveRatioWarningThreshold

function setReserveRatioWarningThreshold(
        uint256 _reserveRatioWarningThreshold
    ) external override onlyEmergencyAdmin

Sets the threshold above which the emergencyAdmin can call the liquidateReserve method.

✏️Can only be called by the Emergency Admin

function emergencyToggle

function emergencyToggle() external;

Stops all trading on a pool, leaving only burn available for use. emergencyToggle can be used in extreme cases to protect LPs.

✏️Can only be called by the emergency admin

Read-only Functions

function getBalances

function getBalances(
) external view override 
returns ( 
    uint112 _balance0, 
    uint112 _balance1 )

Returns the state of liquidity balances for native tokens.

function pairBalance0

function balance0(
) external view returns (uint112);

Returns the amount of liquidity for the first native token in the pool.

function pairBalance1

function balance1(
) external view returns (uint112);

Returns the amount of liquidity for the second native token in the pool.

function calculateReserveRatio

function calculateReserveRatio(
    ) public view override returns (uint256 rRatio)

Calculates the ratio between the total value of reserve tokens currently present in the pool and total value of the native tokens.

Returns the per mille ratio of total value of all reserves divided by the total value locked in the pool. The value of the reserves is calculated relative to the first native asset in the pool.

See also setMaxReserveThreshold

function reservesBaseValue

function reservesBaseValue(
    address reserveAddress
) external view override returns (uint256 rRatio)

Calculates the value of the given reserve asset in terms of the token0 native token.

function getTokens

function getTokens(
) external view  
returns ( 
    address token0, 
    address token1
)

Returns addresses of the native tokens in the pool.

function token0

function token0(
) external view returns (address);

Returns address of the first native token in the pool.

function token1

function token1(
) external view returns (address);

Returns address of the second native token in the pool.

function lastSwapBlock

function lastSwapBlock() external view returns (uint128);

Returns the number of the last block in which a swap was performed in the vPair instance.

function blocksDelay

function blocksDelay() external view returns (uint128);

Returns the current value of blocksDelay.

function reserves

function reserves(address reserveAddress) external view returns (uint256);

Returns the amount of a given reserve asset currently present in the pool

function reservesBaseValueSum

function reservesBaseValueSum() external view returns (uint256);

Returns the value of reserve in units of token0 in the pool.

function reserveRatioFactor

function reserveRatioFactor() external pure returns (uint256);

Returns the factor used to convert Reserve Ratio into percentage. The default factor is 100,000, i.e. 2000 means 0.02.

function maxAllowListCount

function maxAllowListCount() external view returns (uint24);

returns the current length of the allow list.

function maxReserveRatio

function maxReserveRatio() external view returns (uint256);

Returns the maximum allowed reserve ratio for the pool

function fee

function fee() external view returns (uint16);

returns the native asset swap fee in the pool

function vFee

function vFee()  external view returns (uint16);

returns the fee for reserve to native swaps

function allowLisMap

function allowListMap(address _token) external view returns (bool allowed);

Returns true if a given token address is in the Reserve Allow List, and false otherwise.