IButtonswapPair

Inherits: IButtonswapPairErrors, IButtonswapPairEvents, IButtonswapERC20

Functions

MINIMUM_LIQUIDITY

The smallest value that {IButtonswapERC20-totalSupply} can be.

After the first mint the total liquidity (represented by the liquidity token total supply) can never drop below this value. This is to protect against an attack where the attacker mints a very small amount of liquidity, and then donates pool tokens to skew the ratio. This results in future minters receiving no liquidity tokens when they deposit. By enforcing a minimum liquidity value this attack becomes prohibitively expensive to execute.

function MINIMUM_LIQUIDITY() external pure returns (uint256 MINIMUM_LIQUIDITY);

Returns

Name	Type	Description
MINIMUM_LIQUIDITY	uint256	The MINIMUM_LIQUIDITY value

movingAverageWindow

The duration for which the moving average is calculated for.

function movingAverageWindow() external view returns (uint32 _movingAverageWindow);

Returns

Name	Type	Description
_movingAverageWindow	uint32	The value of movingAverageWindow

setMovingAverageWindow

Updates the movingAverageWindow parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setMovingAverageWindow(uint32 newMovingAverageWindow) external;

Parameters

Name	Type	Description
newMovingAverageWindow	uint32	The new value for movingAverageWindow

maxVolatilityBps

Numerator (over 10_000) of the threshold when price volatility triggers maximum single-sided timelock duration.

function maxVolatilityBps() external view returns (uint16 _maxVolatilityBps);

Returns

Name	Type	Description
_maxVolatilityBps	uint16	The value of maxVolatilityBps

setMaxVolatilityBps

Updates the maxVolatilityBps parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setMaxVolatilityBps(uint16 newMaxVolatilityBps) external;

Parameters

Name	Type	Description
newMaxVolatilityBps	uint16	The new value for maxVolatilityBps

minTimelockDuration

How long the minimum singled-sided timelock lasts for.

function minTimelockDuration() external view returns (uint32 _minTimelockDuration);

Returns

Name	Type	Description
_minTimelockDuration	uint32	The value of minTimelockDuration

setMinTimelockDuration

Updates the minTimelockDuration parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setMinTimelockDuration(uint32 newMinTimelockDuration) external;

Parameters

Name	Type	Description
newMinTimelockDuration	uint32	The new value for minTimelockDuration

maxTimelockDuration

How long the maximum singled-sided timelock lasts for.

function maxTimelockDuration() external view returns (uint32 _maxTimelockDuration);

Returns

Name	Type	Description
_maxTimelockDuration	uint32	The value of maxTimelockDuration

setMaxTimelockDuration

Updates the maxTimelockDuration parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setMaxTimelockDuration(uint32 newMaxTimelockDuration) external;

Parameters

Name	Type	Description
newMaxTimelockDuration	uint32	The new value for maxTimelockDuration

maxSwappableReservoirLimitBps

Numerator (over 10_000) of the fraction of the pool balance that acts as the maximum limit on how much of the reservoir can be swapped in a given timeframe.

function maxSwappableReservoirLimitBps() external view returns (uint16 _maxSwappableReservoirLimitBps);

Returns

Name	Type	Description
_maxSwappableReservoirLimitBps	uint16	The value of maxSwappableReservoirLimitBps

setMaxSwappableReservoirLimitBps

Updates the maxSwappableReservoirLimitBps parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setMaxSwappableReservoirLimitBps(uint16 newMaxSwappableReservoirLimitBps) external;

Parameters

Name	Type	Description
newMaxSwappableReservoirLimitBps	uint16	The new value for maxSwappableReservoirLimitBps

swappableReservoirGrowthWindow

How much time it takes for the swappable reservoir value to grow from nothing to its maximum value.

function swappableReservoirGrowthWindow() external view returns (uint32 _swappableReservoirGrowthWindow);

Returns

Name	Type	Description
_swappableReservoirGrowthWindow	uint32	The value of swappableReservoirGrowthWindow

setSwappableReservoirGrowthWindow

Updates the swappableReservoirGrowthWindow parameter of the pair. This can only be called by the Factory address. Refer to parameters.md for more detail.

function setSwappableReservoirGrowthWindow(uint32 newSwappableReservoirGrowthWindow) external;

Parameters

Name	Type	Description
newSwappableReservoirGrowthWindow	uint32	The new value for swappableReservoirGrowthWindow

factory

The address of the {ButtonswapFactory} instance used to create this Pair.

Set to msg.sender in the Pair constructor.

function factory() external view returns (address factory);

Returns

Name	Type	Description
factory	address	The factory address

token0

The address of the first sorted token.

function token0() external view returns (address token0);

Returns

Name	Type	Description
token0	address	The token address

token1

The address of the second sorted token.

function token1() external view returns (address token1);

Returns

Name	Type	Description
token1	address	The token address

price0CumulativeLast

The time-weighted average price of the Pair. The price is of token0 in terms of token1.

The price is represented as a UQ112x112 to maintain precision. Consequently this value must be divided by 2^112 to get the actual price. Because of the time weighting, price0CumulativeLast must also be divided by the total Pair lifetime to get the average price over that time period.

function price0CumulativeLast() external view returns (uint256 price0CumulativeLast);

Returns

Name	Type	Description
price0CumulativeLast	uint256	The current cumulative token0 price

price1CumulativeLast

The time-weighted average price of the Pair. The price is of token1 in terms of token0.

The price is represented as a UQ112x112 to maintain precision. Consequently this value must be divided by 2^112 to get the actual price. Because of the time weighting, price1CumulativeLast must also be divided by the total Pair lifetime to get the average price over that time period.

function price1CumulativeLast() external view returns (uint256 price1CumulativeLast);

Returns

Name	Type	Description
price1CumulativeLast	uint256	The current cumulative token1 price

singleSidedTimelockDeadline

The timestamp for when the single-sided timelock concludes. The timelock is initiated based on price volatility of swaps over the last movingAverageWindow, and can be extended by new swaps if they are sufficiently volatile. The timelock protects against attempts to manipulate the price that is used to valuate the reservoir tokens during single-sided operations. It also guards against general legitimate volatility, as it is preferable to defer single-sided operations until it is clearer what the market considers the price to be.

function singleSidedTimelockDeadline() external view returns (uint120 singleSidedTimelockDeadline);

Returns

Name	Type	Description
singleSidedTimelockDeadline	uint120	The current deadline timestamp

swappableReservoirLimitReachesMaxDeadline

The timestamp by which the amount of reservoir tokens that can be exchanged during a single-sided operation reaches its maximum value. This maximum value is not necessarily the entirety of the reservoir, instead being calculated as a fraction of the corresponding token's active liquidity.

function swappableReservoirLimitReachesMaxDeadline()
    external
    view
    returns (uint120 swappableReservoirLimitReachesMaxDeadline);

Returns

Name	Type	Description
swappableReservoirLimitReachesMaxDeadline	uint120	The current deadline timestamp

getSwappableReservoirLimit

Returns the current limit on the number of reservoir tokens that can be exchanged during a single-sided mint/burn operation.

function getSwappableReservoirLimit() external view returns (uint256 swappableReservoirLimit);

Returns

Name	Type	Description
swappableReservoirLimit	uint256	The amount of reservoir token that can be exchanged

getIsPaused

Whether the Pair is currently paused

function getIsPaused() external view returns (bool _isPaused);

Returns

Name	Type	Description
_isPaused	bool	The paused state

setIsPaused

Updates the pause state. This can only be called by the Factory address.

function setIsPaused(bool isPausedNew) external;

Parameters

Name	Type	Description
isPausedNew	bool	The new value for isPaused

getLiquidityBalances

Get the current liquidity values.

function getLiquidityBalances()
    external
    view
    returns (uint112 _pool0, uint112 _pool1, uint112 _reservoir0, uint112 _reservoir1, uint32 _blockTimestampLast);

Returns

Name	Type	Description
_pool0	uint112	The active token0 liquidity
_pool1	uint112	The active token1 liquidity
_reservoir0	uint112	The inactive token0 liquidity
_reservoir1	uint112	The inactive token1 liquidity
_blockTimestampLast	uint32	The timestamp of when the price was last updated

movingAveragePrice0

The current movingAveragePrice0 value, based on the current block timestamp.

This is the token0 price, time weighted to prevent manipulation. Refer to reservoir-valuation.md for more detail. The price is represented as a UQ112x112 to maintain precision. It is used to valuate the reservoir tokens that are exchanged during single-sided operations.

function movingAveragePrice0() external view returns (uint256 _movingAveragePrice0);

Returns

Name	Type	Description
_movingAveragePrice0	uint256	The current movingAveragePrice0 value

mint

Mints new liquidity tokens to to based on amountIn0 of token0 and amountIn1 oftoken1` deposited. Expects both tokens to be deposited in a ratio that matches the current Pair price.

The token deposits are deduced to be the delta between token balance before and after the transfers in order to account for unusual tokens. Refer to mint-math.md for more detail.

function mint(uint256 amountIn0, uint256 amountIn1, address to) external returns (uint256 liquidityOut);

Parameters

Name	Type	Description
amountIn0	uint256	The amount of token0 that should be transferred in from the user
amountIn1	uint256	The amount of token1 that should be transferred in from the user
to	address	The account that receives the newly minted liquidity tokens

Returns

Name	Type	Description
liquidityOut	uint256	THe amount of liquidity tokens minted

mintWithReservoir

Mints new liquidity tokens to to based on how much token0 or token1 has been deposited. The token transferred is the one that the Pair does not have a non-zero inactive liquidity balance for. Expects only one token to be deposited, so that it can be paired with the other token's inactive liquidity.

The token deposits are deduced to be the delta between token balance before and after the transfers in order to account for unusual tokens. Refer to mint-math.md for more detail.

function mintWithReservoir(uint256 amountIn, address to) external returns (uint256 liquidityOut);

Parameters

Name	Type	Description
amountIn	uint256	The amount of tokens that should be transferred in from the user
to	address	The account that receives the newly minted liquidity tokens

Returns

Name	Type	Description
liquidityOut	uint256	THe amount of liquidity tokens minted

burn

Burns liquidityIn liquidity tokens to redeem to to the corresponding amountOut0 of token0 and amountOut1 of token1.

Refer to burn-math.md for more detail.

function burn(uint256 liquidityIn, address to) external returns (uint256 amountOut0, uint256 amountOut1);

Parameters

Name	Type	Description
liquidityIn	uint256	The amount of liquidity tokens to burn
to	address	The account that receives the redeemed tokens

Returns

Name	Type	Description
amountOut0	uint256	The amount of token0 that the liquidity tokens are redeemed for
amountOut1	uint256	The amount of token1 that the liquidity tokens are redeemed for

burnFromReservoir

Burns liquidityIn liquidity tokens to redeem to to the corresponding amountOut0 of token0 and amountOut1 of token1. Only returns tokens from the non-zero inactive liquidity balance, meaning one of amountOut0 and amountOut1 will be zero.

Refer to burn-math.md for more detail.

function burnFromReservoir(uint256 liquidityIn, address to) external returns (uint256 amountOut0, uint256 amountOut1);

Parameters

Name	Type	Description
liquidityIn	uint256	The amount of liquidity tokens to burn
to	address	The account that receives the redeemed tokens

Returns

Name	Type	Description
amountOut0	uint256	The amount of token0 that the liquidity tokens are redeemed for
amountOut1	uint256	The amount of token1 that the liquidity tokens are redeemed for

swap

Swaps one token for the other, taking amountIn0 of token0 and amountIn1 of token1 from the sender and sending amountOut0 of token0 and amountOut1 of token1 to to. The price of the swap is determined by maintaining the "K Invariant". A 0.3% fee is collected to distribute between liquidity providers and the protocol.

The token deposits are deduced to be the delta between the current Pair contract token balances and the last stored balances. Optional calldata can be passed to data, which will be used to confirm the output token transfer with to if to is a contract that implements the {IButtonswapCallee} interface. Refer to swap-math.md for more detail.

function swap(uint256 amountIn0, uint256 amountIn1, uint256 amountOut0, uint256 amountOut1, address to) external;

Parameters

Name	Type	Description
amountIn0	uint256	The amount of token0 that the sender sends
amountIn1	uint256	The amount of token1 that the sender sends
amountOut0	uint256	The amount of token0 that the recipient receives
amountOut1	uint256	The amount of token1 that the recipient receives
to	address	The account that receives the swap output