Provide liquidity

What a position earns

One position followed through a batch, with what it pays out, what it takes in, the fee and the surplus it is credited, and how both reach its owner.

In a batch a position in range does three things. It trades along its range as the clearing moves the pair, at the cleared price. It keeps the pair's liquidity fee on what it gave up. And it is credited the surplus: the difference between what its curve asked for that trade and what the cleared price paid.

What a clearing does to a pair

A batch's price vector gives each pair one cleared price, the ratio of its two tokens' prices. The clearing moves the pair from its own price toward that price and stops short of it by the pair's liquidity fee plus one basis point. A cleared price nearer than that leaves the pair where it is.

The pair's priceThe pair pays outThe pair takes in
Fallsyx
Risesxy
StaysNothingNothing

The move is cut into segments between initialized ticks. For each one the program computes four amounts:

  • out, what the segment's liquidity gives up along its curve.
  • fee, the pair's liquidity fee on out.
  • in, what out less the fee is worth at the cleared price. It is never less than what the curve asks.
  • surplus, in less what the curve asks.

The pair delivers out less the fee to the batch's orders and takes in from them. The clearing conditions gives the arithmetic the proof checks.

One position through one batch

The numbers here are the batch in the program's test fixture. The fixture gives the pair's state, the two orders, the band, the two fee rates and the cleared prices. Every other number below follows from those by the program's arithmetic.

The pair's liquidity in the fixture is one range, so it is followed here as one position.

The fixture's inputs

PairToken 0, wSOL, is x. Token 1 is y. The price is atoms of token 1 per lamport.
Liquidity fee5 basis points, this fixture's rate
Clearing fee10 basis points, this fixture's rate
Tick spacing10
Pair price before100, at tick 46054
PositionLiquidity 50,000,000,000 from tick 45650 to tick 46450, prices 96.0407 to 104.0392
Order 1Sells 200,000,000 lamports for token 1, limit 95 atoms per lamport
Order 2Sells 12,000,000,000 atoms of token 1 for SOL, limit 1/105 lamport per atom

Before the batch the position holds 98,020,404 lamports and 9,998,286,500 atoms of token 1.

The clearing

Order 1 wants more of token 1 than order 2 offers, so token 1's price rises. The fixture's result prices it at 0.010309061 lamports per atom, up from a last proven price of 0.01. That is a cleared price of 97.0020 atoms of token 1 per lamport for the pair.

The pair's fee is 5 basis points, so the pair stops 6 basis points short: its price falls from 100 to the cleared price divided by 0.9994, which is 97.0603, tick 45755. That is inside the range, so the move is one segment and the position stays in range.

The price fell, so the position pays out token 1 and takes in SOL.

AmountArithmeticResult
outToken 1 the curve gives up from 100 down to 97.0603, rounded down7,404,111,565 atoms
Curve asksSOL the curve takes for it, rounded up75,154,014 lamports
feefloor(7,404,111,565 × 5 / 10000)3,702,055 atoms
Delivered7,404,111,565 − 3,702,0557,400,409,510 atoms
infloor(7,400,409,510 × 0.010309061), the delivered amount at the cleared price76,291,271 lamports
surplus76,291,271 − 75,154,0141,137,257 lamports

Along its curve the position would have sold those atoms at an average of 0.01015 lamports each. The batch pays 0.010309 for each one delivered.

Where the tokens went

The 7,400,409,510 atoms the pair delivered and the 12,000,000,000 atoms of order 2 add up to 19,400,409,510 atoms of token 1. Order 1's 200,000,000 lamports at the cleared price buy exactly that many. Order 1 pays 19,400,409 of them as the clearing fee, the fee the fixture's result reports for token 1.

Order 2's atoms buy 123,708,728 lamports, of which 123,708 are its clearing fee, the fee the fixture's result reports for SOL. The pair takes its 76,291,271. Together that is 199,999,999 of the 200,000,000 lamports order 1 paid in.

The position after the batch

BeforeAfter
Holds, SOL98,020,404 lamports173,174,417 lamports
Holds, token 19,998,286,500 atoms2,594,174,935 atoms
Credited, SOL01,137,256 lamports of surplus
Credited, token 103,702,054 atoms of fee

What it holds moved by the curve's own amounts: 7,404,111,565 atoms out and 75,154,013 lamports in, one lamport under the curve's rounded-up figure because holdings round down. The fee and the surplus are kept apart from the holdings, as credits. Each credit is one atom under the segment's amount because both divisions round down.

At the cleared price, the tokens the position held before the batch are worth 201,093,346 lamports. What it holds after the batch plus its two credits is worth 201,093,344 lamports. The position sold 7.4 billion atoms of a token whose price rose 3.09%, and it ends with the value its starting tokens have at the new price, to within 3 lamports of rounding.

The surplus

The surplus is 1,137,257 lamports in this batch: the gap between selling 7,400,409,510 atoms along the curve and selling them all at the cleared price. It is credited to the positions active in the segment, in the token the pair took in.

The surplus grows with the size of the move. A batch that leaves the pair's price where it was trades nothing through the position and credits nothing.

How both reach the owner

The clearing adds the fee and the surplus to the pair's fee growth, each divided by the segment's active liquidity. Ranges and fees has the bookkeeping. The position's share is its liquidity times the growth inside its range since its last credit. Here the position is all of the segment's liquidity, so it is credited all of both.

The credit is on the pair as soon as the clearing is posted. From then the owner sends collect_fees, and the program pays 1,137,256 lamports and 3,702,054 atoms of token 1 from the vaults to the owner's token accounts. Anyone else may send settle_position with the same result. Both are on Add and remove liquidity.

TypeScript
for (const p of (await una.positions()).items) {
  console.log(`${p.pairSlug} ${p.priceLowerUi} to ${p.priceUpperUi}: owed ${p.feesOwedX} ${p.tokenX.symbol} and ${p.feesOwedY} ${p.tokenY.symbol}`)
}

Through more batches

Each later clearing that moves the pair inside the range repeats the same steps from the price the last one left. The growth accumulates on the pair, so the total a position is paid does not depend on how often it is collected, beyond one atom of rounding per credit.

When a clearing moves the price across one end of the range, the position trades up to that end and stops. It then holds one token, sits out of range and is credited nothing until a clearing brings the price back.

remove_liquidity returns what the position holds at the pair's price then, once the last batch that cleared against the pair is proven. Removing all of it after this batch is proven returns 173,174,417 lamports and 2,594,174,935 atoms of token 1, and the credits stay on the position for collect_fees.