Provide liquidity

Ranges and fees

How a tick maps to a price, what a position holds inside and outside its range, and how a pair's liquidity fee is divided across positions.

A position sits between two ticks on one pair. This page covers the ticks, what the position holds as the pair's price moves across them, and the fee the pair pays its positions.

The pair's price

A pair has two tokens. The one with the lower token index is x, the other is y, and the pair's price is atoms of y per atom of x. For a pair of SOL and a token, SOL is x, since wSOL is token 0.

The pair stores its price as a square root in Q64.64, sqrt_price, together with the tick that price falls in. create_pair sets both from the two tokens' last proven prices:

Text
sqrt_price = isqrt((price(x) << 128) / price(y))

price(x) and price(y) are the tokens' prices in lamports per atom. The same formula turns a batch's cleared prices into the cleared price of the pair. Each clearing moves the pair toward that price and stops short of it by the pair's fee plus one basis point. A cleared price closer to the pair's price than that leaves the pair where it is. The clearing conditions has the move itself.

Ticks

A tick is an integer that names a price. Tick 0 is a price of 1, and each tick up multiplies the price by 1.0001, one basis point.

Text
sqrt_price(tick) = sqrt(1.0001 ^ tick) * 2^64        Q64.64, rounded up
price(tick)      = (sqrt_price(tick) / 2^64) ^ 2  =  1.0001 ^ tick

The program computes sqrt_price(tick) in integers: it multiplies one fixed 128-bit constant for each bit set in the tick's absolute value, inverts the product for a positive tick, and rounds the Q64.64 result up. This is the tick arithmetic of Uniswap v3 in the form Orca Whirlpools uses. Ticks run from -443,636 to 443,636.

The pair's tick is the highest tick whose sqrt_price is at or under the pair's sqrt_price.

price(tick) is in atoms. For whole tokens, multiply by 10 ^ (decimals of x - decimals of y):

TypeScript
// A tick as a price: atoms of the second token per atom of the first, then in whole tokens.
const atomsPerAtom = (tick: number) => 1.0001 ** tick
const wholeTokens = (tick: number) => atomsPerAtom(tick) * 10 ** (pair.tokenX.decimals - pair.tokenY.decimals)

The API returns prices in whole tokens wherever it returns a tick: currentPriceUi on a pair, priceUi on each of its ticks, and priceLowerUi and priceUpperUi on a position.

Tick spacing

Each pair has a tick spacing, set when the pair is created and always above 0. Both ends of a range are multiples of it. With a spacing of 10, a range can end on tick 45650 or 45660 and on nothing between them.

A tick is initialized while at least one position starts or ends on it. A pair holds up to 64 initialized ticks at a time.

TypeScript
const { items: pairs } = await una.pairs()
for (const p of pairs) console.log(`${p.slug}: liquidity fee ${p.feeBps} basis points, tick spacing ${p.tickSpacing}, tick ${p.currentTick}`)

una.pair(slug) returns one pair with every initialized tick: its price, the liquidity that starts or ends there as liquidityNet, and the liquidity active from that tick up to the next as liquidityActive. The fields are under PairDetail.

A range

A range is a lower tick and an upper tick, the lower below the upper. A position's liquidity is spread over the prices between them.

The position is in range while

Text
tick_lower <= the pair's tick < tick_upper

What it holds depends on where the pair's price is against the range.

The pair's price isThe position holdsIn a clearing it
At or under the lower endOnly xDoes not trade
Inside the rangeBoth x and yTrades along its range as far as the pair moves
At or over the upper endOnly yDoes not trade

Inside the range the position sells x for y as the price rises and sells y for x as it falls. At the upper end all of it is y, and at the lower end all of it is x. The exact amounts for a liquidity and a price are on Add and remove liquidity.

A range placed wholly above the pair's price is funded with x alone, and one placed wholly below it with y alone. Such a position starts trading when a clearing brings the price into its range.

Active liquidity

The pair keeps one number, its active liquidity: the sum of the liquidity of every position in range. When a clearing moves the price across an initialized tick, the liquidity of the positions that start there joins it and the liquidity of those that end there leaves.

A clearing's move is therefore cut into segments, one for each stretch between initialized ticks, each with its own active liquidity L. A segment with no liquidity trades nothing.

The liquidity fee

Each pair has one fee rate, fee_bps, in basis points. create_pair sets it with the pair, under 10,000. Read it as feeBps from una.pairs() or una.pair(slug). The app shows it in the Fee column on /pool and at the top of /pool/[pair].

The fee is taken in every segment of a clearing's move, from the token the pair pays out. The segment's liquidity gives up an amount out along its curve. The fee is floor(out * fee_bps / 10000). The pair delivers out less the fee to the batch, and the fee stays in the vault for the positions.

So the fee is in y when the price falls, since the pair pays out y, and in x when it rises.

How the fee is divided

The fee of a segment belongs to the positions active in that segment, in proportion to their liquidity. The pair records it as fee growth: an amount per unit of liquidity, in Q64.64, kept for each token.

Text
growth += floor(fee * 2^64 / L)            for the segment's fee, with L the segment's active liquidity

Each initialized tick keeps the growth that happened on its far side, and the program turns it over when the price crosses the tick. From those the program reads the growth inside any range: the pair's total, less what happened under the lower tick, less what happened over the upper tick.

A position remembers the growth inside its range at its last credit. At the next credit it is owed

Text
owed = floor((growth inside now - growth inside at last credit) * liquidity / 2^64)

in each token. A position with a tenth of a segment's active liquidity is credited a tenth of that segment's fee. Growth that happened while the price was outside its range does not count toward it.

The pair keeps a second amount in the same counters: the surplus of each segment, in the token the pair takes in. It is divided across positions the same way.

A credit happens whenever the position is touched: add_liquidity on it, remove_liquidity, collect_fees and settle_position. The last two also pay it out. See Collect fees.