KyberSwap Docs
Search
K

Elastic Core Libraries

BaseSplitCodeFactory

Inherited by the Factory contract. Main purpose is to hold the Kyberswap Elastic Pool creation code in a separate address, since its creation code is close to the bytecode size limit of 24kB.
Taken from Balancer Labs's solidity utils repo. The only modification made is the unchecked keyword for sol 0.8 compatibility.

getCreationCodeContracts()

Returns the 2 addresses where the creation code of the contract created by this factory is stored.

getCreationCode()

Returns the creation code of the contract this factory creates.

CodeDeployer

Taken from Balancer Labs's solidity utils repo. Imported and used by the BaseSplitCodeFactory contract to handle deployment.

FullMath

Taken from Mathemagic finale: muldiv - Remco Bloeman. Facilitates multiplication and division that can have overflow of an intermediate value without any loss of precision. Handles "phantom overflow" i.e., allows multiplication and division where an intermediate value overflows 256 bits.

mulDivFloor()

Returns (a * b / denominator) rounded down.
Input
Type
Explanation
a
uint256
multiplicand
b
uint256
multiplier
denominator
uint256
divisor

mulDivCeiling()

Similar to mulDivFloor, but rounded up.

LinkedList

A doubly linked list to be used for tick management.

Struct: Data

Field
Type
Explanation
previous
int24
previous tick
next
int24
next tick

init()

Initializes the LinkedList with the lowestValue and highestValue, where
  • lowestValue.previous = lowestValue
  • lowestValue.next = highestValue
  • highestValue.previous = lowestValue
  • highestValue.next = highestValue
Field
Type
Explanation
self
mapping(int24 => Data)
A mapping of int24 values to the Data struct
lowestValue
int24
lowest value
highestValue
int24
highest value

insert()

Inserts a new value into the LinkedList, given an existing lower value. The new value to be inserted should not be an existing value. Also, the condition lowerValue < newValue < lowerValue.next should be satisfied.
Field
Type
Explanation
self
mapping(int24 => Data)
A mapping of int24 values to the Data struct
newValue
int24
value to be inserted
lowerValue
int24
highest existing value in the linked list that is < newValue

remove()

Removes an existing value from the LinkedList. Returns the next lowest value (existingValue.previous).
Note that no removal is performed if removedValue happens to be the lowestValue or highestValue passed in init().
Field
Type
Explanation
self
mapping(int24 => Data)
A mapping of int24 values to the Data struct
removedValue
int24
value to be removed

LiqDeltaMath

Contains a function to assist with the addition of signed liquidityDelta to unsigned liquidity.

applyLiquidityDelta()

Adds or remove uint128 liquidityDelta to uint128 liquidity
Field
Type
Explanation
liquidity
uint128
Liquidity to be adjusted
liquidityDelta
int128
quantity change to be applied
isAddLiquidity
bool
true = add liquidity, false = remove liquidity

MathConstants

Contains constants commonly used by multiple files.

QtyDeltaMath

Contains functions for calculating token0 and token1 quantites from differences in prices or from burning reinvestment tokens

getQtysForInitialLockup()

Calculate the token0 and token1 quantities needed for unlocking the pool given an initial price and liquidity.
Input
Input Field
Type
Explanation
initialSqrtP
uint160
initial sqrt price raised by 2**96
liquidity
uint128
initial liquidity. should be MIN_LIQUIDITY = 100000
Output
Return Field
Type
Explanation
qty0
uint256
token0 quantity required
qty1
uint256
token1 quantity required

calcRequiredQty0()

Calculates the token0 quantity between 2 sqrt prices for a given liquidity quantity.
Note that the function assumes that upperSqrtP > lowerSqrtP.
Input
Field
Type
Explanation
lowerSqrtP
uint160
the lower sqrt price
upperSqrtP
uint128
the upper sqrt price
liquidity
int128
liquidity quantity
isAddLiquidity
bool
true = add liquidity, false = remove liquidity
Output
Type
Explanation
int256
token0 qty required for position with liquidity between the 2 sqrt prices
Generally, if the return value > 0, it will be transferred into the pool. Conversely, if the return value < 0, it will be transferred out of the pool.

calcRequiredQty1()

Calculates the token1 quantity between 2 sqrt prices for a given liquidity quantity.
Note that the function assumes that upperSqrtP > lowerSqrtP.
Input
Field
Type
Explanation
lowerSqrtP
uint160
the lower sqrt price
upperSqrtP
uint128
the upper sqrt price
liquidity
int128
liquidity quantity
isAddLiquidity
bool
true = add liquidity, false = remove liquidity
Output
Type
Explanation
int256
token0 qty required for position with liquidity between the 2 sqrt prices
Generally, if the return value > 0, it will be transferred into the pool. Conversely, if the return value < 0, it will be transferred out of the pool.

getQty0FromBurnRTokens()

Calculates the token0 quantity to be sent to the user for a given amount of reinvestment tokens to be burnt.
Input Field
Type
Explanation
sqrtP
uint160
the current sqrt price
liquidity
uint128
expected change in reinvestment liquidity due to the burning of reinvestment tokens

getQty1FromBurnRTokens()

Calculates the token1 quantity to be sent to the user for a given amount of reinvestment tokens to be burnt.
Input Field
Type
Explanation
sqrtP
uint160
the current sqrt price
liquidity
uint128
expected change in reinvestment liquidity due to the burning of reinvestment tokens

divCeiling()

Returns ceil(x / y). y should not be zero.

QuadMath

getSmallerRootOfQuadEqn()

Given a variant of the quadratic equation
ax22bx+c0ax^2 - 2bx + c - 0
where
aa
,
bb
and
c>0c > 0
, calculate the smaller root via the quadratic formula.
Returns
bb2aca\frac{b - \sqrt{b^2 - ac}}{a}
Input Field
Type
Explanation
a
uint256
b
uint256
c
uint256

sqrt()

Unchanged from DMMv1. Calculates the square root of a value using the Babylonian method.

ReinvestmentMath

Contains a helper function to calculate reinvestment tokens to be minted given an increase in reinvestment liquidity.

calcRMintQty()

Given the difference between reinvestL and reinvestLLast, calculate how many reinvestment tokens are to be minted.
rMintQty=rTotalSupplyreinvestLreinvestLLastreinvestLLastbaseLbaseL+reinvestLrMintQty = rTotalSupply * \frac{reinvestL - reinvestL_{Last}}{reinvestL_{Last}} * \frac{baseL}{baseL + reinvestL}
Input Field
Type
Explanation
reinvestL
uint256
latest reinvestment liquidity value. Should be >= reinvestLLast
reinvestLLast
uint256
reinvestmentLiquidityLast value
baseL
uint256
active base liquidity
rTotalSupply
uint256
total supply of reinvestment token

SafeCast

Contains methods for safely casting between different types.

toUint32()

Casts a uint256 to a uint32. Reverts on overflow.

toInt128()

Casts a uint128 to a int128. Reverts on overflow.

toUint128()

Casts a uint256 to a uint128. Reverts on overflow.

revToUint128()

Given int128 y, returns uint128 z = -y.

toUint160()

Casts a uint256 to a uint160. Reverts on overflow.

toInt256()

Casts a uint256 to a int256. Reverts on overflow.

revToInt256()

Cast a uint256 to a int256 and reverses the sign. Reverts on overflow.

revToUint256()

Given int256 y, returns uint256 z = -y.

SwapMath

Contains the logic needed for computing swap input / output amounts and fees. The primary function to look at is computeSwapStep, as it is where the bulk of the swap flow logic is in, and where calls to the other functions in the library are made.

computeSwapStep()

Computes the actual swap input / output amounts to be deducted or added, the swap fee to be collected and the resulting price.
Inputs
Field
Type
Explanation
liquidity
uint256
active base liquidity + reinvestment liquidity
currentSqrtP
uint160
current sqrt price
targetSqrtP
uint160
sqrt price limit nextSqrtP can take
feeInBps
uint256
swap fee in basis points
specifiedAmount
int256
amount remaining to be used for the swap
isExactInput
bool
true if specifiedAmount refers to input amount, false if specifiedAmount refers to output amount
isToken0
bool
true if specifiedAmount is in token0, false if specifiedAmount is in token1
Outputs
Field
Type
Explanation
usedAmount
int256
actual amount to be used for the swap. >= 0 if isExactInput = true, <= 0 if isExactInput = false
returnedAmount
int256
output qty (<= 0) to be accumulated if isExactInput = true, input qty (>= 0) if isExactInput = false
deltaL
uint256
collected swap fee, to be incremented to reinvest liquidity
nextSqrtP
uint160
new sqrt price after the computed swap step
Note
nextSqrtP should not exceed targetSqrtP.

calcReachAmount()

Calculates the amount needed to reach targetSqrtP from currentSqrtP. Note that currentSqrtP and targetSqrtP are casted from uint160 to uint256 as they are multiplied by TWO_BPS (20_000) or feeInBps.
The mathematical formulas are provided below for reference.
isExactInput
isToken0
Formula
true
true
2BPSL(pcpn)pc(2BPSpnfeepc)\frac{2*BPS*L(\sqrt{p_c} - \sqrt{p_n})}{\sqrt{p_c}(2*BPS*\sqrt{p_n} - fee\sqrt{p_c})}
(>0)
true
false
2BPSpcL(pnpc)(2BPSpcfeepn)\frac{2*BPS*\sqrt{p_c}*L(\sqrt{p_n} - \sqrt{p_c})}{(2*BPS*\sqrt{p_c} - fee\sqrt{p_n})}
(>0)
false
true
2BPSL(pnpc)pc(2BPSpnfeepc)-\frac{2*BPS*L(\sqrt{p_n} - \sqrt{p_c})}{\sqrt{p_c}(2*BPS*\sqrt{p_n} - fee\sqrt{p_c})}
(<0)
false
false
2BPSpcL(pcpn)(2BPSpcfeepn)-\frac{2*BPS*\sqrt{p_c}*L(\sqrt{p_c} - \sqrt{p_n})}{(2*BPS*\sqrt{p_c} - fee\sqrt{p_n})}
(<0)
Note that while cases 1 and 3 and cases 2 and 4 are mathematically equivalent, the implementation differs by performing a double negation for the exact output cases. It takes the difference of
pn\sqrt{p_n}
and
pc\sqrt{p_c}
in the numerator (>0), then performing a second negation.
Input Field
Type
Formula Variable
Explanation
liquidity
uint256
LL
active base liquidity + reinvestment liquidity
currentSqrtP
uint160
pc\sqrt{p_c}
current sqrt price
targetSqrtP
uint160
pn\sqrt{p_n}
sqrt price limit nextSqrtP can take
feeInBps
uint256
feefee
swap fee in basis points
isExactInput
bool
N.A.
true / false if specified swap amount refers to input / output amount respectively
isToken0
bool
N.A.
true / false if specified swap amount is in token0 / token1 respectively

estimateIncrementalLiquidity()

Estimates deltaL, the swap fee to be collected based on amountSpecified. This is called only for the final swap step, where the next (temporary) tick will not be crossed.
In the case where exact input is specified, the formula is rather straightforward.
isToken0
Formula
true
deltafeepc2BPS\frac{delta*fee*\sqrt{p_c}}{2*BPS}
false
deltafee2BPSpc\frac{delta*fee}{2*BPS*\sqrt{p_c}}
In the case where exact output is specified, a quadratic equation has to be solved. The desired result is the smaller root of the quadratic equation.
isToken0
Formula
true
fee(ΔL)22[(BPSfee)LBPSdeltapc]ΔL+feeLdeltapc=0fee*(\Delta{L})^2-2[(BPS-fee)*L-BPS*delta*\sqrt{p_c}]\Delta{L}+fee*L*delta*\sqrt{p_c}=0
false
fee(ΔL)22[(BPSfee)LBPSdeltapc]ΔL+feeLdeltapc=0fee*(\Delta{L})^2-2[(BPS-fee)*L-\frac{BPS*delta}{\sqrt{p_c}}]\Delta{L}+\frac{fee*L*delta}{\sqrt{p_c}}=0
Input Field
Type
Formula Variable
Explanation
absDelta
uint256
deltadelta
∥∥∥∥
usedAmount
∥∥∥∥
, absolute value of usedAmount (actual amount used for swap)
liquidity
uint256
LL
active base liquidity + reinvestment liquidity
currentSqrtP
uint160
pc\sqrt{p_c}
current sqrt price
feeInBps
uint256
feefee
swap fee in basis points
isExactInput
bool
N.A.
true / false if specified swap amount refers to input / output amount respectively
isToken0
bool
N.A.
true / false if specified swap amount is in token0 / token1 respectively

calcIncrementalLiquidity()

Calculates deltaL, the swap fee to be collected based on amountSpecified. This is called for an intermediate swap step, where the next (temporary) tick will be crossed.
The mathematical formulas are provided below for reference.
isExactInput
isToken0
Formula
true
true
pn(Lpc+delta)L\sqrt{p_n}*(\frac{L}{\sqrt{p_c}}+\|delta\|)-L
true
false
(Lpc)+deltapnL\frac{(L*\sqrt{p_c})+\|delta\|}{\sqrt{p_n}}-L
false
true
pn(Lpcdelta)L\sqrt{p_n}*(\frac{L}{\sqrt{p_c}}-\|delta\|)-L
false
false
(Lpc)deltapnL\frac{(L*\sqrt{p_c})-\|delta\|}{\sqrt{p_n}}-L
Inputs
Input Field
Type
Formula Variable
Explanation
absDelta
uint256
|
deltadelta
|
∥∥∥∥
usedAmount
∥∥∥∥
, absolute value of usedAmount (actual amount used for swap)
liquidity
uint256
LL
active base liquidity + reinvestment liquidity
currentSqrtP
uint160
pc\sqrt{p_c}
current sqrt price
nextSqrtP
uint160
pn\sqrt{p_n}
next sqrt price
isExactInput
bool
N.A.
true / false if specified swap amount refers to input / output amount respectively
isToken0
bool
N.A.
true / false if specified swap amount is in token0 / token1 respectively

calcFinalPrice()

Calculates the sqrt price of the final swap step where the next (temporary) tick will not be crossed.
The mathematical formulas are provided below for reference.
isExactInput
isToken0
Formula
true
true
(L+ΔL)pcL+deltapc\frac{(L+\Delta{L})\sqrt{p_c}}{L+\|delta\|\sqrt{p_c}}
true
false
Lpc+deltaL+ΔL\frac{L\sqrt{p_c}+\|delta\|}{L+\Delta{L}}
false
true
(L+ΔL)pcLdeltapc\frac{(L+\Delta{L})\sqrt{p_c}}{L-\|delta\|\sqrt{p_c}}
false
false
LpcdeltaL+ΔL\frac{L\sqrt{p_c}-\|delta\|}{L+\Delta{L}}
Input
Input Field
Type
Formula Variable
Explanation
absDelta
uint256
|
deltadelta
|
∥∥∥∥
usedAmount
∥∥∥∥
, absolute value of usedAmount (actual amount used for swap)