Documentation Index
Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
Use this file to discover all available pages before exploring further.
Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.Ver versión en inglés →
Esta página describe el esquema y rol de cada cuenta. Las semillas canónicas están listadas en
reference/program-addresses. Un pool CLMM utiliza más cuentas que un pool CPMM porque la liquidez se almacena de forma dispersa a lo largo del rango de ticks; comprender esa dispersión es el tema central de esta página.Inventario de cuentas
Un pool CLMM activo se describe mediante las siguientes familias de cuentas. Todas pertenecen al programa CLMM, excepto los dos mints y sus vaults.| Cuenta | Propósito | Cantidad por pool |
|---|---|---|
AmmConfig | Nivel de comisión: tasa de comisión de trading, porcentaje de protocolo, porcentaje de fondo, tick-spacing por defecto. Compartida entre todos los pools de este nivel. | 1 (compartida) |
PoolState | sqrt_price_x64 actual, tick actual, liquidez total, acumuladores globales de comisiones, información de recompensas, puntero de observación. | 1 |
TickArrayState | Un bloque de TICK_ARRAY_SIZE ticks adyacentes. Solo se inicializa bajo demanda. | 0 ≤ N ≤ rango |
TickArrayBitmapExtension | Bitmap de desbordamiento que registra qué tick arrays existen más allá del bitmap inline de PoolState. | 0 o 1 |
PersonalPositionState | Una por posición de LP. Almacena el rango, la liquidez y el último crecimiento de comisiones/recompensas visto. Authority = propietario del NFT. | 1 por posición |
| NFT mint de posición | Mint con supply 1, asociada a PersonalPositionState. Transferir el NFT transfiere la posición. | 1 por posición |
ObservationState | Buffer circular de observaciones de precio para el TWAP. | 1 |
token_0_vault, token_1_vault | Cuentas de token que contienen los saldos del pool. Propiedad de la authority del pool. | 2 |
DynamicFeeConfig | Conjunto de parámetros reutilizable para el mecanismo de comisión dinámica. Los pools creados con create_customizable_pool pueden activarlo. Administrado por el admin. | compartida (por índice) |
LimitOrderState | Una por orden límite abierta. Registra el propietario, el tick, la dirección, el importe total y el snapshot del output liquidado. | 1 por orden |
LimitOrderNonce | Contador por (wallet, nonce_index) que genera PDAs de orden únicas. | 1 por (wallet, índice) |
PoolState
El estado en vivo del pool, leído en cada swap y en cada cambio de posición.
sqrt_price_x64ytick_currentrepresentan el estado de precio del pool. Se actualizan juntos en cada swap.tick_currentes el entero inferior delog_{1.0001}(price).liquidityes la liquidez activa: la suma de los valoresLde todas las posiciones cuyo rango contiene atick_current. Cambia cada vez que un swap cruza un tick y cada vez que se abre, cierra o redimensiona una posición.fee_growth_global_{0,1}_x64son las comisiones acumuladas por unidad de liquidez a lo largo de toda la historia del pool. Las posiciones los leen para calcular lo que se les debe.tick_spacingqueda fijado alAmmConfigdurante la inicialización y nunca cambia. Determina qué índices de tick pueden ser puntos extremos de una posición.tick_array_bitmapes un bitmap inline que cubre el rango de ticks más habitual alrededor del precio spot. Para pools con posiciones muy alejadas del centro, el seguimiento del desbordamiento vive en la cuenta separadaTickArrayBitmapExtension.fee_onse fija en el momento de la creación del pool. El valor0(FromInput) reproduce el comportamiento clásico de Uniswap V3. Los valores1y2dirigen la comisión de swap a un solo lado del libro — consultaproducts/clmm/feespara ver los compromisos de diseño.dynamic_fee_infoalmacena el estado de volatilidad para el recargo de comisión dinámica. Cuando está habilitado, cada swap recalcula undynamic_fee_componentsobreAmmConfig.trade_fee_rate. El esquema se documenta enDynamicFeeInfomás abajo; los pools sin comisión dinámica dejan toda la estructura en cero.
AmmConfig
GET https://api-v3.raydium.io/main/clmm-config):
| Índice | trade_fee_rate | Tick spacing | Uso típico |
|---|---|---|---|
| 0 | 100 (0,01%) | 1 | Pares estables, USDC/USDT |
| 1 | 500 (0,05%) | 10 | Blue-chips correlacionados |
| 2 | 2_500 (0,25%) | 60 | Pares estándar |
| 3 | 10_000 (1,00%) | 120 | Activos volátiles o de cola larga |
protocol_fee_rate y fund_fee_rate son fracciones de la comisión de trading; misma convención que en CPMM. Consulta products/clmm/fees.
TickArrayState
El CLMM no almacena un registro por tick individual, ya que eso implicaría miles de millones de cuentas. En cambio, agrupa TICK_ARRAY_SIZE ticks adyacentes (inicializados o no, típicamente 60 u 88 según la versión del programa) en un TickArrayState que se crea de forma diferida en el primer uso.
order_phasees el identificador de cohorte. Se incrementa cada vez que una cohorte pasa de «totalmente sin ejecutar» a «parcialmente ejecutada».orders_amountes el total en tokens de entrada de la cohorte actual (la más reciente).part_filled_orders_remaininglleva el seguimiento de la cohorte anterior que está siendo ejecutada en curso por los swaps activos.unfilled_ratio_x64es un multiplicador Q64.64 asociado a la cohorte: cuando un swap ejecuta el X% de la cohorte, el ratio se multiplica por(1 − X). Cada orden abierta almacena su propio snapshot de(order_phase, unfilled_ratio_x64)en el momento de apertura, por lo que la liquidación se reduce a comparar snapshots.
- Un tick t que sea extremo de posición debe satisfacer
t % tick_spacing == 0. El programa rechaza posiciones que no respeten el espaciado. - El array de un tick se ubica en
floor(t / (TICK_ARRAY_SIZE * tick_spacing)) * (TICK_ARRAY_SIZE * tick_spacing). - Un tick array se inicializa de forma diferida: la primera posición o swap que toca un array no inicializado lo crea y paga el alquiler.
- El programa nunca cierra un tick array. Una vez asignado, persiste durante toda la vida del pool, incluso después de que todos los ticks dentro de él vuelvan a
liquidity_gross == 0. Las posiciones y swaps posteriores reutilizan la cuenta existente sin coste adicional de alquiler. No existe una ruta de limpieza de tick arrays derivada deClosePosition.
TickArrayBitmapExtension
PoolState.tick_array_bitmap (inline) cubre el rango «cercano al spot» — ±1.024 tick arrays. Fuera de ese rango (para valores de tick extremos), el programa mantiene una cuenta de extensión:
(MIN_TICK, MAX_TICK)) sí la requieren; el SDK la resuelve por ti.
Posiciones
Una posición CLMM es un conjunto de tres cuentas más un mint:NFT mint de posición
Un mint de token SPL con supply 1. La dirección del mint es un PDA determinista; el NFT de posición en la wallet del propietario es simplemente una ATA que contiene ese único token. Transferir el NFT es el mecanismo por el que cambia de manos una posición — el programa vincula la autorización al titular actual del saldo en la ATA del NFT, no a una Pubkey almacenada en el estado.PersonalPositionState
Una por posición abierta. Su clave se deriva del mint del NFT.
ProtocolPositionState (obsoleto)
Las versiones anteriores del CLMM almacenaban la contabilidad agregada por
(pool, tick_lower, tick_upper) en un PDA llamado ProtocolPositionState. Las versiones más recientes ya no crean ni leen esta cuenta. El slot sigue apareciendo en las listas de cuentas de OpenPosition / IncreaseLiquidity / DecreaseLiquidity como UncheckedAccount por compatibilidad con el ABI, pero el programa no escribe en él. Las cuentas existentes en la cadena son vestigiales; el admin puede llamar a CloseProtocolPosition para recuperar el alquiler.La contabilidad agregada de rango ahora se deriva directamente de los dos ticks extremos (liquidity_gross, liquidity_net y los campos fee_growth_outside_* / reward_growths_outside_x64 por tick) en TickArrayState. La fórmula de crecimiento de comisiones dentro del rango fee_growth_inside = global − outside_lower − outside_upper sigue funcionando sin necesidad de una cuenta de posición agregada.Observation
(tick_cumulative[t1] − tick_cumulative[t0]) / (t1 − t0) y luego price = 1.0001 ** tick. Consulta algorithms/clmm-math.
DynamicFeeConfig y DynamicFeeInfo
Los parámetros de comisión dinámica viven en dos lugares. La plantilla reutilizable — DynamicFeeConfig — es administrada por el admin y compartida entre los pools que la activan. El estado de ejecución por pool — DynamicFeeInfo — está embebido en PoolState y se actualiza en cada swap.
DynamicFeeConfig
["dynamic_fee_config", index.to_be_bytes()]. Se crea mediante create_dynamic_fee_config (solo admin) y se modifica con update_dynamic_fee_config. Un pool creado con enable_dynamic_fee = true copia los cinco parámetros de calibración de la config (filter_period, decay_period, reduction_factor, dynamic_fee_control, max_volatility_accumulator) en su propio DynamicFeeInfo en el momento de la creación; las ediciones posteriores al DynamicFeeConfig no afectan retroactivamente a los pools existentes.
DynamicFeeInfo (embebido en PoolState)
DynamicFeeConfig. La matemática de la comisión y las reglas de decaimiento están documentadas en products/clmm/math y products/clmm/fees.
Constantes usadas por la fórmula:
| Constante | Valor | Significado |
|---|---|---|
VOLATILITY_ACCUMULATOR_SCALE | 10_000 | Granularidad del acumulador de volatilidad |
REDUCTION_FACTOR_DENOMINATOR | 10_000 | Denominador de reduction_factor |
DYNAMIC_FEE_CONTROL_DENOMINATOR | 100_000 | Denominador de dynamic_fee_control |
MAX_FEE_RATE_NUMERATOR | 100_000 | Límite estricto del 10% sobre la tasa de comisión resultante |
LimitOrderState
Una cuenta por orden límite abierta.
- Apertura — el usuario llama a
open_limit_order, depositatotal_amountdel token de entrada y la orden queda vinculada a una cohorte deTickState. - (Opcional) Aumento / Reducción —
increase_limit_orderañade altotal_amount;decrease_limit_orderdevuelve los tokens sin ejecutar (y cualquier output liquidado hasta ese momento). - Liquidación — cuando la cohorte está total o parcialmente ejecutada, el propietario o el keeper operacional llama a
settle_limit_orderpara enviar los tokens de salida a la ATA del propietario. - Cierre — una vez que
unfilled_amount == 0, la cuenta puede cerrarse. El alquiler siempre retorna alowner.
[owner.as_ref(), limit_order_nonce.key().as_ref(), limit_order_nonce.order_nonce.to_be_bytes().as_ref()]. El PDA de la orden es por tanto único por (owner, nonce_index, order_nonce).
LimitOrderNonce
Contador por (wallet, nonce_index) que permite a un mismo usuario ejecutar múltiples pipelines paralelas de órdenes límite sin colisionar en los PDAs.
[user_wallet.as_ref(), &[nonce_index]]. La mayoría de los clientes usan nonce_index = 0 y dejan que order_nonce gestione la cardinalidad.
Derivar las cuentas clave
reference/program-addresses.
Referencia rápida del ciclo de vida
| Evento | Cuentas creadas | Cuentas destruidas |
|---|---|---|
CreatePool | poolState, observation, token_0_vault, token_1_vault | — |
OpenPosition[WithToken22Nft] | NFT mint + ATA, personalPosition, posiblemente nuevos tickArrayState(s), tickArrayBitmapExtension si no existe aún | — |
IncreaseLiquidity | Posiblemente nuevos tickArrayState(s) | — |
DecreaseLiquidity | — | Posiblemente limpia entradas de tick (pero el tickArrayState en sí no se cierra) |
ClosePosition | — | NFT mint, personalPosition |
SwapV2 | Posiblemente nuevo tickArrayState | — |
OpenLimitOrder | limitOrderState, posiblemente limitOrderNonce (init-if-needed), posiblemente nuevo tickArrayState | — |
IncreaseLimitOrder | — | — |
DecreaseLimitOrder | — | Cierra limitOrderState si la orden está totalmente consumida |
SettleLimitOrder | — | — |
CloseLimitOrder | — | limitOrderState (alquiler → owner) |
CreateDynamicFeeConfig | dynamicFeeConfig | — |
CreateCustomizablePool | poolState, observation, vaults — igual que CreatePool. Copia dynamicFeeConfig si enable_dynamic_fee = true. | — |
CollectRewards | — | — |
UpdateRewardInfos | — | — |
CloseProtocolPosition (admin) | — | protocolPositionState vestigial (alquiler → admin) |
TickArrayState nunca son cerradas por el programa — persisten durante toda la vida del pool. Una vez inicializado un tick array, permanece en la cadena aunque todos los ticks dentro de él vuelvan a liquidity_gross == 0. Reutilizar un tick array existente es gratuito; solo la primera posición que toca un array nunca inicializado paga su alquiler.
Dónde leer cada tema
- Matemática de ticks y mecánica de rangos:
products/clmm/ticks-and-positions. - Recorrido del swap y matemática de crecimiento de comisiones:
products/clmm/math. - Listas de cuentas por instrucción:
products/clmm/instructions. - Comisiones y acumulación de recompensas:
products/clmm/fees. - IDs de programa canónicos y semillas:
reference/program-addresses.


