Skip to content

Pool history

A Raydium CLMM market reads its price from the observations its pool has already stored, never from the pool’s live price, and with nobody’s signature: the market program reads the pool’s own record directly. The rule: a reading spans two observations, two consecutive ones the pool has stored.

Every Raydium CLMM pool keeps a ring of 100 observations, each an accumulator of its price tick multiplied by the seconds it stood. The pool writes a new observation when a swap moves its price to a new tick, at most once every 15 seconds, and each write adds the tick that stood before that swap.

The pool never computes anything from its current tick for this. A reading built from these observations only ever contains prices that already stood in the pool.

Given two consecutive observations a and b, the mean tick between them is

(cumulativeb − cumulativea) ÷ (tb − ta)

the time-weighted average price between them. The pool writes when its price changes, so its price stood still from a until the swap that wrote b. The mean is therefore exactly the pool’s price just before the swap that wrote b, a whole tick.

A market’s reading is that price for one pair of consecutive observations: the pool’s two newest, or, while a ticket waits, the pair that ticket fills at (see first reading after a commit). The move Δ that the keep factor uses is the difference between this reading’s tick and the previous reading’s.

  • On demand. There is no schedule: an execute or a poke takes a reading, and so does a commit or a retirement while no ticket waits.
  • Nothing new, no move. If the pool has stored nothing new since the last reading, the market does not move.
  • A price, not an average. A reading pays the whole move from the previous reading’s price in one step, however long it has been. A move that came and went between two readings is never paid.

A ticket committed in second c fills at the first stored pair whose older observation was written in a second after c. Its reading is a price that stood after the commit’s second ended, which nobody could know at the commit.

While a ticket waits, the market applies only that ticket’s pair: a poke, an execute or a commit before the pair exists moves nothing, and once it exists, the next call applies it, fills every ticket it matured, and goes on to the next waiting ticket’s pair. So no caller can change which reading a ticket gets by choosing when to call.

The ring holds 100 observations, about 25 minutes at the pool’s fastest. Anyone can copy a waiting ticket’s pair into the ticket with secure once the pool holds it, and keepers do, so the ring turning over can’t take it away. If the ring turns over past a ticket’s commit before anyone copies or applies its pair, that ticket alone is refunded.

The market reads the pool’s observation account directly, with no oracle program in between, and never reads the pool’s live price, liquidity or balances. Nothing in a reading comes from the transaction that takes it.

Raydium CLMM can be upgraded by its owners. If the pool’s observation account ever stops reading as that pool’s ring, because its size, its owner or its layout changed, the market treats it as no reading, never as an error: its tickets wait, the market freezes for silence once the oldest has had no reading for 7 days, and every cash-out keeps working. A new market version then follows.

Why a push that never stands can’t move it

Section titled “Why a push that never stands can’t move it”

A push that is moved and moved back inside one transaction never stands in the pool:

  1. A write records the tick from before the swap that makes it.
  2. A push and its revert in one transaction leave the pool where it was, so the write records the old tick.
  3. No transaction can write two observations, so none can complete a pair on its own.

A reading is also always the price before a swap the pool has already stored, so nothing done in the transaction that takes the reading can change it.

A push held until a later swap writes an observation is a different matter: the pushed tick stood, and a reading can be taken at it. See Why held pushes count.

Suppose the market’s last reading came to tick T, and the pool has stood at T since an observation at 0 s. Then:

Time Event Stored
40 s A buyer lifts the price 100 ticks (about 1%) An observation: 40 s at tick T
70 s The buyer sells back to tick T An observation: 30 s at tick T + 100
71 s Someone executes the market

At 71 s the pool’s two newest observations are the ones at 40 s and 70 s. Their mean tick is T + 100, the price that stood just before the swap at 70 s: a rise of 100 ticks that moves about 63% of the DOWN pot to UP. The reading after it, from the observation at 70 s and the pool’s next one, is T again: a fall of 100 ticks that moves about 63% of the UP pot to DOWN.

An execute between 40 s and 70 s would have read T, from the pair at 0 s and 40 s. Had the buyer sold back within the same transaction as the buy, no observation would ever have recorded T + 100.

A pool history market lists on its Raydium CLMM pool once the coin’s route is bound to that pool or pinned there by the timelock, and starts from the pool’s newest pair, which must be at most 1 hour old. See Memecoin markets.