Skip to main content
Cette page est traduite automatiquement par IA. La version anglaise fait foi.Voir la version anglaise →
Cette page décrit la structure et le rôle de chaque compte. Les seeds canoniques sont répertoriées dans reference/program-addresses. Un pool CLMM mobilise davantage de comptes qu’un pool CPMM, car la liquidité est stockée de façon clairsemée sur l’ensemble de la plage de ticks ; comprendre cette dispersion constitue l’essentiel de cette page.

Inventaire des comptes

Un pool CLMM actif est décrit par les familles de comptes suivantes. Tous appartiennent au programme CLMM, à l’exception des deux mints et de leurs vaults.

PoolState

L’état en temps réel du pool, lu à chaque swap et à chaque modification de position.
Champs avec lesquels vous interagirez réellement :
  • sqrt_price_x64 et tick_current représentent l’état de prix du pool. Ils sont mis à jour ensemble à chaque swap. tick_current est la partie entière inférieure de log_{1.0001}(price).
  • liquidity est la liquidité active — la somme des valeurs L de toutes les positions dont la plage contient tick_current. Elle change à chaque fois qu’un swap franchit un tick et à chaque ouverture, fermeture ou redimensionnement de position.
  • fee_growth_global_{0,1}_x64 représentent les frais cumulés par unité de liquidité sur toute l’histoire du pool. Les positions les consultent pour calculer ce qui leur est dû.
  • tick_spacing est figé à la valeur de AmmConfig lors de l’initialisation et ne change jamais. Il détermine quels indices de ticks sont autorisés comme extrémités de position.
  • tick_array_bitmap est un bitmap inline couvrant la plage de ticks communément utilisée autour du prix spot. Pour les pools dont les positions s’étendent loin, le suivi du débordement est délégué au compte séparé TickArrayBitmapExtension.
  • fee_on est fixé à la création du pool. 0 (FromInput) reproduit le comportement classique d’Uniswap-V3. 1 et 2 dirigent les frais de swap vers un seul côté du carnet — voir products/clmm/fees pour les compromis associés.
  • dynamic_fee_info porte l’état de volatilité pour la majoration de frais dynamiques. Lorsqu’il est activé, chaque swap recalcule un dynamic_fee_component en plus de AmmConfig.trade_fee_rate. La structure est documentée sous DynamicFeeInfo ci-dessous ; les pools sans frais dynamiques laissent l’intégralité de cette struct à zéro.

AmmConfig

Exemple de paliers de frais CLMM publiés (à vérifier via GET https://api-v3.raydium.io/main/clmm-config) : protocol_fee_rate et fund_fee_rate sont des fractions du frais de trading ; même convention que pour le CPMM. Voir products/clmm/fees.

TickArrayState

Le CLMM ne stocke pas un enregistrement par tick — cela représenterait des milliards de comptes. Il regroupe plutôt TICK_ARRAY_SIZE ticks adjacents (initialisés ou non, typiquement 60 ou 88 selon la version du programme) dans un TickArrayState créé paresseusement à la première utilisation.
Les quatre champs d’ordre limite sont à zéro pour tout tick n’ayant jamais servi à un ordre limite. Lorsque des ordres sont ouverts sur un tick, le programme les suit sous forme de séquence de cohortes :
  • order_phase est l’identifiant de cohorte. Il s’incrémente à chaque fois qu’une cohorte passe de « entièrement non exécutée » à « partiellement exécutée ».
  • orders_amount est le total en token d’entrée de la cohorte courante (la plus récente).
  • part_filled_orders_remaining suit la cohorte précédente en cours d’exécution par les swaps en cours.
  • unfilled_ratio_x64 est un multiplicateur Q64.64 porté par la cohorte : lorsqu’un swap exécute X% de la cohorte, le ratio est multiplié par (1 − X). Chaque ordre ouvert stocke son propre snapshot (order_phase, unfilled_ratio_x64) au moment de l’ouverture, ce qui ramène le calcul de règlement à une simple comparaison de snapshots.
Règles :
  • Un tick extrémité de position t doit satisfaire t % tick_spacing == 0. Le programme rejette les positions dont les extrémités ne sont pas alignées sur l’espacement.
  • Le tableau du tick est localisé à floor(t / (TICK_ARRAY_SIZE * tick_spacing)) * (TICK_ARRAY_SIZE * tick_spacing).
  • Un tableau de ticks est initialisé paresseusement : la première position ou le premier swap qui touche un tableau non initialisé le crée, en payant le rent.
  • Un tableau de ticks n’est jamais fermé par le programme. Une fois alloué, il persiste pour toute la durée de vie du pool, même après que tous les ticks qu’il contient sont revenus à liquidity_gross == 0. Les positions et swaps ultérieurs réutilisent le compte existant sans rent supplémentaire. Il n’existe aucun mécanisme de nettoyage des tableaux de ticks déclenché par ClosePosition.

TickArrayBitmapExtension

PoolState.tick_array_bitmap (inline) couvre la plage « proche du prix spot » — ±1 024 tableaux de ticks. Au-delà de cette plage (pour des valeurs de ticks extrêmes), le programme maintient un compte d’extension :
Si votre plage de position est « normale », vous n’aurez jamais à vous préoccuper du compte d’extension. Les positions pleine plage (par ex. (MIN_TICK, MAX_TICK)) en ont besoin ; le SDK le résout pour vous.

Positions

Une position CLMM est un ensemble de trois comptes plus un mint :

Mint du NFT de position

Un mint SPL Token de supply 1. L’adresse du mint est un PDA déterministe ; le NFT de position dans le wallet du propriétaire n’est qu’un ATA détenant ce token unique. Transférer le NFT est la façon dont une position change de mains — le programme conditionne l’autorisation au détenteur actuel du solde ATA du NFT, et non à une Pubkey stockée dans l’état.

PersonalPositionState

Un par position ouverte. Indexé sur le mint du NFT.

ProtocolPositionState (déprécié)

Les versions antérieures du CLMM stockaient la comptabilité agrégée par (pool, tick_lower, tick_upper) dans un PDA ProtocolPositionState. Les versions récentes ne créent plus ni ne lisent ce compte. L’emplacement figure toujours dans les listes de comptes des instructions OpenPosition / IncreaseLiquidity / DecreaseLiquidity en tant qu’UncheckedAccount pour la compatibilité ABI, mais le programme n’y écrit plus. Les comptes existants on-chain sont des vestiges ; l’administrateur peut appeler CloseProtocolPosition pour en récupérer le rent.La comptabilité agrégée de plage est désormais dérivée directement des deux ticks extrémités (liquidity_gross, liquidity_net et les fee_growth_outside_* / reward_growths_outside_x64 par tick) dans TickArrayState. La formule de croissance des frais inside fee_growth_inside = global − outside_lower − outside_upper continue de fonctionner sans compte de position agrégé.

Observation

Le buffer d’observation du CLMM stocke un tick cumulatif, et non un prix cumulatif. Les consommateurs externes calculent le prix moyen géométrique sur un intervalle à partir de (tick_cumulative[t1] − tick_cumulative[t0]) / (t1 − t0), puis appliquent price = 1.0001 ** tick. Voir algorithms/clmm-math.

DynamicFeeConfig et DynamicFeeInfo

Les paramètres de frais dynamiques se trouvent à deux endroits. Le modèle réutilisable — DynamicFeeConfig — est géré par l’administrateur et partagé entre les pools qui y adhèrent. L’état d’exécution par pool — DynamicFeeInfo — est intégré dans PoolState et mis à jour à chaque swap.

DynamicFeeConfig

Seed PDA : ["dynamic_fee_config", index.to_be_bytes()]. Créé via create_dynamic_fee_config (réservé à l’administrateur) et modifié via update_dynamic_fee_config. Un pool créé avec enable_dynamic_fee = true copie les cinq paramètres de calibration de la config (filter_period, decay_period, reduction_factor, dynamic_fee_control, max_volatility_accumulator) dans son propre DynamicFeeInfo à la création ; les modifications ultérieures de DynamicFeeConfig n’affectent pas rétroactivement les pools existants.

DynamicFeeInfo (intégré dans PoolState)

Les quatre derniers champs sont des données d’état ; les cinq premiers sont des paramètres de calibration copiés depuis DynamicFeeConfig. Le calcul des frais et les règles de décroissance sont documentés dans products/clmm/math et products/clmm/fees. Constantes utilisées par la formule :

LimitOrderState

Un compte par ordre limite ouvert.
Cycle de vie :
  1. Ouverture — l’utilisateur appelle open_limit_order, dépose total_amount du token d’entrée ; l’ordre est lié à une cohorte TickState.
  2. (optionnel) Augmentation / Diminutionincrease_limit_order ajoute au total_amount ; decrease_limit_order restitue les tokens non exécutés (et tout output réglé jusqu’à ce point).
  3. Règlement — lorsque la cohorte est entièrement ou partiellement exécutée, le propriétaire ou le keeper opérationnel appelle settle_limit_order pour transférer les tokens de sortie vers l’ATA du propriétaire.
  4. Fermeture — une fois que unfilled_amount == 0, le compte peut être fermé. Le rent est toujours restitué au owner.
Seed PDA : [owner.as_ref(), limit_order_nonce.key().as_ref(), limit_order_nonce.order_nonce.to_be_bytes().as_ref()]. Le PDA d’ordre est donc unique par (owner, nonce_index, order_nonce).

LimitOrderNonce

Compteur par (wallet, nonce_index) permettant à un même utilisateur de gérer plusieurs pipelines parallèles d’ordres limites sans collision de PDAs.
Seed PDA : [user_wallet.as_ref(), &[nonce_index]]. La plupart des clients utilisent nonce_index = 0 et laissent order_nonce porter la cardinalité.

Dériver les comptes clés

Les chaînes de seeds exactes doivent toujours être vérifiées par rapport à l’IDL on-chain et à reference/program-addresses.

Référence rapide du cycle de vie

Les comptes TickArrayState ne sont jamais fermés par le programme — ils persistent pour toute la durée de vie du pool. Une fois initialisé, un tableau de ticks reste on-chain même lorsque tous les ticks qu’il contient reviennent à liquidity_gross == 0. La réutilisation d’un tableau existant est gratuite ; seule la première position à toucher un tableau jamais initialisé acquitte son rent.

Où trouver quoi

Sources :