Mathématiques du concentrated-liquidity

Cette page est traduite automatiquement par IA. La version anglaise fait foi.Voir la version anglaise →

Pourquoi sqrt-price et non price

Les CLMMs de la famille Uniswap-v3 représentent le prix comme sa racine carrée, stockée en virgule fixe Q64.64 :

sqrt_price_x64 = floor(sqrt(price) · 2^64)

Trois raisons :

Mathématiques linéaires du liquidity. La quantité de token0 ou token1 dans une plage de prix s’avère être une fonction linéaire de sqrt_price, non de price. Stocker sqrt_price permet à l’étape de swap d’évaluer ces formules linéaires sans calculer une racine carrée.
Contrôle du débordement. sqrt_price · L tient dans u256 pour tous les paramètres raisonnables ; price · L peut déborder beaucoup plus tôt.
Les mathématiques des ticks sont uniformes. Parce que les ticks sont définis comme 1.0001^i, sqrt(price) = (√1.0001)^i ≈ 1.00005^i est aussi une échelle géométrique exacte. (√1.0001 = 1.00004999875…, donc le traiter comme exactement 1.00005 dérive d’environ 0,6 % au maximum à MAX_TICK.) Chaque franchissement de tick se traduit par une petite multiplication dans l’espace sqrt_price_x64.

Le prix et le sqrt-price sont en bijection ; la conversion est price = (sqrt_price_x64 / 2^64)^2.

Grille de ticks

Les prix sont discrétisés sur une grille :

price(tick_i) = 1.0001^i

tick_i est un i32. La plage active est [MIN_TICK, MAX_TICK] = [−443636, 443636], donnant une plage de prix d’environ [2^−64, 2^64] — environ 5.4e-20 à 1.8e19. Le tick_spacing de chaque pool est défini par son niveau de frais : des espacements plus petits pour les paires serrées (par exemple, le niveau stablecoin 0,01 % utilise un espacement de 1), des espacements plus grands pour les paires volatiles (le niveau 0,25 % utilise 60, le niveau 1 % utilise 120). Les positions doivent avoir tick_lower et tick_upper alignés sur tick_spacing. Les ticks actifs d’un pool (ceux avec du liquidity qui commence ou se termine là) sont les seuls ticks dont l’étape de swap se soucie.

Liquidity-to-amount

Pour une position avec liquidity L et plage de prix [sqrt_lo, sqrt_hi] (toutes les valeurs sqrt_price) :

État du pool	Quantité de token0	Quantité de token1
Prix au-dessus de la plage (`sqrt_p ≥ sqrt_hi`)	0	`L · (sqrt_hi − sqrt_lo)`
Prix dans la plage	`L · (sqrt_hi − sqrt_p) / (sqrt_p · sqrt_hi)`	`L · (sqrt_p − sqrt_lo)`
Prix en dessous de la plage (`sqrt_p ≤ sqrt_lo`)	`L · (sqrt_hi − sqrt_lo) / (sqrt_lo · sqrt_hi)`	0

Dérivation : différencier localement l’invariant CPMM. À l’intérieur de n’importe quelle plage de tick unique, la position se comporte comme un CPMM avec des réserves virtuelles (x_v, y_v) choisies de sorte que le (sqrt_p, L) actuel du pool soit cohérent avec L = sqrt(x_v · y_v). L’intégration de sqrt_p à la limite de la plage donne les quantités ci-dessus. Formules inverses (utilisées lors de la création d’une position pour un amount0 ou amount1 donné) :

L_from_amount0(amount0, sqrt_lo, sqrt_hi, sqrt_p) =
    amount0 · sqrt_p · sqrt_hi / (sqrt_hi − sqrt_p)

L_from_amount1(amount1, sqrt_lo, sqrt_hi, sqrt_p) =
    amount1 / (sqrt_p − sqrt_lo)

// Pour un dépôt symétrique dans une position in-range, prendre le minimum.
L = min(L_from_amount0, L_from_amount1)

Étape de swap single-tick

À l’intérieur d’une plage de tick unique, le pool se comporte comme un CPMM. Étant donné le sqrt_p actuel et le sqrt_target cible :

Δamount0_step = L · (sqrt_target − sqrt_p) / (sqrt_p · sqrt_target)     // si on échange pour token0
Δamount1_step = L · (sqrt_target − sqrt_p)                              // si on échange pour token1

Étape exact-input

Étant donné Δin_remaining :

// Candidat nouveau sqrt_p si on remplissait jusqu'à la limite du tick :
sqrt_after_full = sqrt_target
amount_to_full  = Δamount_in_to_reach(sqrt_p → sqrt_target)

if Δin_remaining ≥ amount_to_full:
    // consommer le reste du bucket
    sqrt_p'         = sqrt_target
    Δin_consumed    = amount_to_full
    Δout            = amount_out_at_boundary
else:
    // on ne franchit pas ; résoudre pour le sqrt_p terminal
    sqrt_p'         = L · sqrt_p / (L + Δin_remaining · sqrt_p)      // pour les swaps 0→1
    Δin_consumed    = Δin_remaining
    Δout            = L · (sqrt_p − sqrt_p')                          // proportionnel à Δsqrt

Le swap 0→1 abaisse sqrt_p (le prix baisse à mesure qu’on vend du token0). Un swap 1→0 l’élève. Les formules sont symétriques avec sqrt_p et sqrt_target échangés.

Étape exact-output

Même structure, en résolvant pour Δin à la place.

Boucle de swap multi-tick

Un swap itère sur les ticks jusqu’à ce que l’entrée soit épuisée ou que la limite de prix soit atteinte :

while Δin_remaining > 0 and sqrt_p != sqrt_price_limit:
    next_tick = find_next_initialized_tick(pool.tick_current, direction)
    sqrt_target = min(next_tick.sqrt_price, sqrt_price_limit)       // directionnellement

    (Δin, Δout, sqrt_p') = single_step(sqrt_p, sqrt_target, L, Δin_remaining)

    Δin_remaining -= Δin
    accumulated_out += Δout

    if sqrt_p' == next_tick.sqrt_price:
        // franchissement du tick
        L += next_tick.liquidity_net * direction_sign
        flip_fee_growth_outside(next_tick)
        match_limit_orders_at_tick(next_tick, ...)        // voir products/clmm/math
        pool.tick_current = next_tick.tick_index
    sqrt_p = sqrt_p'

Chaque single_step utilise le L actuel du pool. L change uniquement lors du franchissement d’un tick initialisé. Le liquidity entre les ticks est constant, ce qui rend les mathématiques de l’étape en forme fermée. liquidity_net à un tick est la somme signée des liquidités de position qui commencent à ce tick moins celles qui s’y terminent. Franchir vers le haut ajoute liquidity_net ; franchir vers le bas le soustrait. Lorsque le pool a des ordres limites ouverts à un tick, l’étape de franchissement de tick consomme également opportunément une partie de l’entrée de swap pour remplir ces ordres (FIFO entre les cohortes). L’algorithme d’appariement et la surcharge de frais dynamiques qui peut s’appliquer en plus de l’étape de base sont documentés dans products/clmm/math ; ils ne modifient pas les formules en forme fermée de single-step ci-dessus.

Accumulateurs de croissance des frais

Le CLMM suit les frais par unité de liquidity actif, par côté, globalement et par tick :

fee_growth_global_0_x64     // Q64.64, monotone
fee_growth_global_1_x64
tick.fee_growth_outside_0_x64   // « frais accumulés tandis que ce tick était en dehors de la plage active »
tick.fee_growth_outside_1_x64

À chaque single_step :

step_lp_fee = (Δin · fee_rate) · (1 − protocol_fraction − fund_fraction)
fee_growth_global += step_lp_fee · 2^64 / L     // uniquement pour le côté d'entrée

(Le fee_growth_global de l’autre côté ne bouge pas à cette étape, puisqu’aucun token de ce côté n’a été payé en entrée.) Lors du franchissement d’un tick, le programme bascule fee_growth_outside :

tick.fee_growth_outside_0_x64 = fee_growth_global_0_x64 − tick.fee_growth_outside_0_x64
tick.fee_growth_outside_1_x64 = fee_growth_global_1_x64 − tick.fee_growth_outside_1_x64

« Outside » est relatif à tick_current. Lorsque tick_current est au-dessus du tick, outside signifie « en dessous ». Lorsque tick_current est en dessous, outside signifie « au-dessus ». La bascule échange l’interprétation.

`fee_growth_inside` pour une position

Étant donné une position [tick_lower, tick_upper] et le tick_current actuel :

if tick_current >= tick_upper:
    inside = tick_upper.fee_growth_outside − tick_lower.fee_growth_outside
else if tick_current < tick_lower:
    inside = tick_lower.fee_growth_outside − tick_upper.fee_growth_outside
else:     // la position est in-range
    inside = fee_growth_global
           − tick_lower.fee_growth_outside
           − tick_upper.fee_growth_outside

Les frais non collectés d’une position pour le côté token s sont :

tokens_owed_s += L · (fee_growth_inside_s − fee_growth_inside_last_s) / 2^64
fee_growth_inside_last_s = fee_growth_inside_s

Cette mise à jour s’exécute à chaque interaction avec la position (IncreaseLiquidity, DecreaseLiquidity, CollectFees).

Exemple travaillé — franchissement d’un tick

Pool (simplifié) :

sqrt_p_x64 = 2^64 · 1.0 = 2^64 (price = 1.0)
L = 1_000_000
tick_current = 0
Prochain tick initialisé en dessous : tick = −60, sqrt_price = 1.0001^(−30) ≈ 0.99700, liquidity_net = −400_000 (ce tick termine une position, donc un franchissement vers le bas supprime 400k)
Taux de frais : 0,25 %

Swap : Δin = 10_000 token0, direction = 0→1. Étape 1 — jusqu’à sqrt_target = 0.99700 · 2^64 :

amount_in_to_target = L · (1/sqrt_target − 1/sqrt_p)
                    = 1_000_000 · (1/0.99700 − 1/1.0)
                    ≈ 1_000_000 · 0.003009
                    ≈ 3_009

3 009 < 10 000, donc on remplit cette étape complètement :

Δin_step  = 3_009 / (1 − 0.0025)  = 3_017    // brut de frais
Δout_step = L · (sqrt_p − sqrt_target) ≈ 1_000_000 · 0.00299 ≈ 2_990
sqrt_p    = 0.99700 · 2^64
tick_current = −60
L         = 1_000_000 + (−400_000)  = 600_000         // tick franchi
fee_growth_outside au tick −60 est basculé
Δin_remaining = 10_000 − 3_017 = 6_983

Étape 2 — avec nouveau L = 600_000 : Le prochain tick initialisé (disons tick = −120) est à sqrt = 0.99402. Recalculer amount_in_to_target :

amount_in_to_target = 600_000 · (1/0.99402 − 1/0.99700)
                    ≈ 600_000 · 0.003010
                    ≈ 1_806

Toujours moins que Δin_remaining. Franchir à nouveau. Continuer jusqu’à ce que Δin_remaining atteigne zéro. La séquence complète de Δout s’accumule à la sortie de swap finale.

Initialisation et gardes contre le débordement

MIN_SQRT_PRICE_X64 et MAX_SQRT_PRICE_X64 correspondent à tick = ±443636. Tout swap qui pousserait sqrt_p en dehors de cette plage revient.
Le paramètre sqrt_price_limit de l’utilisateur doit se situer dans le même intervalle ; le programme le vérifie.
Les produits de L · Δsqrt sont calculés en u256 puis décalés vers u128 pour éviter le débordement.

Différences par rapport à Uniswap v3

Oracle. Le ObservationState ring buffer de Raydium stocke uniquement (block_timestamp: u32, tick_cumulative: i64) par slot plus [u64; 4] de remplissage réservé — il n’y a pas de champ seconds_per_liquidity_cumulative, donc les dérivations pondérées par liquidity d’Uniswap ne sont pas disponibles on-chain.
Token-2022. Le CLMM de Raydium supporte les mints Token-2022 ; la variante avec frais de transfert nécessite des ajustements supplémentaires de montant pré/post-swap. Voir algorithms/token-2022-transfer-fees.
Bitmap de ticks. Raydium compacte le bitmap des ticks initialisés dans [u64; 16] par pool pour un find_next_initialized_tick rapide ; Uniswap utilise un mapping on-chain par mot. Le compromis est entre le loyer et le coût de recherche.
Slots de récompenses. Raydium supporte 3 flux de récompenses par pool avec des compteurs reward_growth_global_x64 séparés ; même structure que l’accumulateur de croissance des frais.

Pointeurs

products/clmm/math — l’implémentation on-chain et l’exemple travaillé avec les champs réels de la struct CLMM.
products/clmm/ticks-and-positions — grille de ticks, sémantique liquidity_net/gross, plage active.
products/clmm/fees — l’accumulateur de croissance des frais en action.

Sources :

Uniswap v3 whitepaper (dérivation canonique des mathématiques sqrt-price).
Code source du programme CLMM de Raydium.

Produits

Algorithmes

Mathématiques du concentrated-liquidity

Pourquoi sqrt-price et non price

Grille de ticks

Liquidity-to-amount

Étape de swap single-tick

Étape exact-input

Étape exact-output

Boucle de swap multi-tick

Accumulateurs de croissance des frais

`fee_growth_inside` pour une position

Exemple travaillé — franchissement d’un tick

Initialisation et gardes contre le débordement

Différences par rapport à Uniswap v3

Pointeurs

​Pourquoi sqrt-price et non price

​Grille de ticks

​Liquidity-to-amount

​Étape de swap single-tick

​Étape exact-input

​Étape exact-output

​Boucle de swap multi-tick

​Accumulateurs de croissance des frais

​fee_growth_inside pour une position

​Exemple travaillé — franchissement d’un tick

​Initialisation et gardes contre le débordement

​Différences par rapport à Uniswap v3

​Pointeurs

Pourquoi sqrt-price et non price

Grille de ticks

Liquidity-to-amount

Étape de swap single-tick

Étape exact-input

Étape exact-output

Boucle de swap multi-tick

Accumulateurs de croissance des frais

`fee_growth_inside` pour une position

Exemple travaillé — franchissement d’un tick

Initialisation et gardes contre le débordement

Différences par rapport à Uniswap v3

Pointeurs