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 foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →
Esta página descreve o layout e a função de cada conta. As seeds canônicas estão listadas em
reference/program-addresses. Um pool CLMM utiliza mais contas do que um pool CPMM porque a liquidez é armazenada de forma esparsa ao longo do intervalo de ticks; entender essa esparsidade é o tema principal desta página.Inventário de contas
Um pool CLMM ativo é descrito pelas seguintes famílias de contas. Todas pertencem ao programa CLMM, exceto as duas mints e seus vaults.| Conta | Finalidade | Quantidade por pool |
|---|---|---|
AmmConfig | Fee tier: taxa de negociação, participação do protocolo, participação do fundo, tick-spacing padrão. Compartilhada entre todos os pools desse tier. | 1 (compartilhada) |
PoolState | sqrt_price_x64 atual, tick atual, liquidez total, crescimento global de taxas, informações de recompensa, ponteiro de observação. | 1 |
TickArrayState | Um bloco de TICK_ARRAY_SIZE ticks adjacentes. Inicializado apenas sob demanda. | 0 ≤ N ≤ intervalo |
TickArrayBitmapExtension | Bitmap de overflow que rastreia quais arrays de tick existem além do bitmap inline em PoolState. | 0 ou 1 |
PersonalPositionState | Um por posição de LP. Armazena o intervalo, a liquidez e o crescimento de taxas/recompensas visto pela última vez. Autoridade = dono do NFT. | 1 por posição |
| NFT mint da posição | Mint com supply 1, associada ao PersonalPositionState. Transferir o NFT transfere a posição. | 1 por posição |
ObservationState | Buffer circular de observações de preço para o TWAP. | 1 |
token_0_vault, token_1_vault | Contas de token que guardam os saldos do pool. Pertencentes à autoridade do pool. | 2 |
DynamicFeeConfig | Conjunto de parâmetros reutilizável para o mecanismo de taxa dinâmica. Pools criados via create_customizable_pool podem aderir. Gerenciado pelo admin. | compartilhada (por índice) |
LimitOrderState | Um por ordem limitada aberta. Registra o dono, tick, direção, valor total e snapshot da saída liquidada. | 1 por ordem |
LimitOrderNonce | Contador por (wallet, nonce_index) que deriva PDAs únicas para cada ordem. | 1 por (wallet, índice) |
PoolState
O estado ativo do pool, lido a cada swap e a cada alteração de posição.
sqrt_price_x64etick_currentrepresentam o estado de preço do pool. São atualizados juntos a cada swap.tick_currenté o piso delog_{1.0001}(price).liquidityé a liquidez ativa — a soma dos valoresLde todas as posições cujo intervalo contémtick_current. Ela muda sempre que um swap cruza um tick e sempre que uma posição é aberta, fechada ou redimensionada.fee_growth_global_{0,1}_x64são as taxas acumuladas por unidade de liquidez ao longo de todo o histórico do pool. As posições consultam esses valores para calcular o que lhes é devido.tick_spacingé fixado noAmmConfigna inicialização e nunca muda. Ele determina quais índices de tick podem ser endpoints de posição.tick_array_bitmapé um bitmap inline que cobre o intervalo de tick mais utilizado em torno do preço spot. Para pools cujas posições se estendem muito além desse intervalo, o rastreamento de overflow fica na conta separadaTickArrayBitmapExtension.fee_oné definido na criação do pool.0(FromInput) reproduz o comportamento clássico do Uniswap-V3.1e2direcionam a taxa de swap para um único lado do livro — vejaproducts/clmm/feespara as implicações.dynamic_fee_infocarrega o estado de volatilidade para o acréscimo de taxa dinâmica. Quando habilitado, cada swap recalcula umdynamic_fee_componentsobre oAmmConfig.trade_fee_rate. O layout está documentado emDynamicFeeInfoabaixo; pools sem taxa dinâmica mantêm toda a struct zerada.
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 estáveis, USDC/USDT |
| 1 | 500 (0,05%) | 10 | Blue-chips correlacionadas |
| 2 | 2_500 (0,25%) | 60 | Pares padrão |
| 3 | 10_000 (1,00%) | 120 | Ativos voláteis ou de cauda longa |
protocol_fee_rate e fund_fee_rate são frações da taxa de negociação; mesma convenção do CPMM. Veja products/clmm/fees.
TickArrayState
O CLMM não armazena um registro por tick — isso resultaria em bilhões de contas. Em vez disso, ele agrupa TICK_ARRAY_SIZE ticks adjacentes (tipicamente 60 ou 88, dependendo da versão do programa), sejam eles inicializados ou não, em um TickArrayState criado de forma lazy no primeiro uso.
order_phaseé o id da coorte. Ele incrementa toda vez que uma coorte transita de “totalmente não preenchida” para “parcialmente preenchida.”orders_amounté o total do token de entrada da coorte atual (a mais recente).part_filled_orders_remainingrastreia a coorte anterior que está sendo preenchida pelos swaps em andamento.unfilled_ratio_x64é um multiplicador Q64.64 mantido na coorte: quando um swap preenche X% da coorte, a razão é multiplicada por(1 − X). Cada ordem aberta armazena seu próprio snapshot de(order_phase, unfilled_ratio_x64)no momento da abertura, de modo que o cálculo de liquidação se reduz a comparar snapshots.
- Um tick de endpoint de posição t deve satisfazer
t % tick_spacing == 0. O programa rejeita posições fora do espaçamento. - O array do tick está localizado em
floor(t / (TICK_ARRAY_SIZE * tick_spacing)) * (TICK_ARRAY_SIZE * tick_spacing). - Um tick array é inicializado de forma lazy: a primeira posição ou swap que toca um array não inicializado o cria, pagando o rent.
- Um tick array nunca é fechado pelo programa. Uma vez alocado, ele persiste durante toda a vida do pool, mesmo após todos os ticks dentro dele retornarem a
liquidity_gross == 0. Posições e swaps subsequentes reutilizam a conta existente sem custo adicional de rent. Não há caminho de limpeza viaClosePositionpara tick arrays.
TickArrayBitmapExtension
PoolState.tick_array_bitmap (inline) cobre o intervalo “próximo ao spot” — ±1.024 tick arrays. Além desse intervalo (para valores extremos de tick), o programa mantém uma conta de extensão:
(MIN_TICK, MAX_TICK)) exigem ela; o SDK resolve isso por você.
Posições
Uma posição CLMM é um conjunto de três contas mais uma mint:NFT mint da posição
Uma mint SPL Token com supply 1. O endereço da mint é um PDA determinístico; o NFT da posição na carteira do dono é simplesmente uma ATA que guarda esse único token. Transferir o NFT é como uma posição muda de titular — o programa vincula a autorização ao portador atual do saldo da ATA do NFT, não a uma Pubkey armazenada no estado.PersonalPositionState
Um por posição aberta. Indexado pela mint do NFT.
ProtocolPositionState (obsoleto)
Versões anteriores do CLMM armazenavam bookkeeping agregado por
(pool, tick_lower, tick_upper) em um PDA ProtocolPositionState. As versões mais recentes não criam nem leem mais essa conta. O slot ainda aparece nas listas de contas de OpenPosition / IncreaseLiquidity / DecreaseLiquidity como UncheckedAccount por compatibilidade de ABI, mas o programa não escreve nela. As contas existentes on-chain são vestigiais; o admin pode chamar CloseProtocolPosition para recuperar o rent delas.O bookkeeping agregado de intervalos agora é derivado diretamente dos dois ticks de endpoint (liquidity_gross, liquidity_net e os fee_growth_outside_* / reward_growths_outside_x64 por tick) no TickArrayState. A fórmula de crescimento de taxa interna fee_growth_inside = global − outside_lower − outside_upper continua funcionando sem uma conta de posição agregada.Observation
(tick_cumulative[t1] − tick_cumulative[t0]) / (t1 − t0) e depois price = 1.0001 ** tick. Veja algorithms/clmm-math.
DynamicFeeConfig e DynamicFeeInfo
Os parâmetros de taxa dinâmica residem em dois lugares. O template reutilizável — DynamicFeeConfig — é gerenciado pelo admin e compartilhado entre os pools que aderem. O estado de execução por pool — DynamicFeeInfo — está embutido em PoolState e atualizado a cada swap.
DynamicFeeConfig
["dynamic_fee_config", index.to_be_bytes()]. Criado via create_dynamic_fee_config (restrito ao admin) e modificado via update_dynamic_fee_config. Um pool criado com enable_dynamic_fee = true copia os cinco parâmetros de calibração da config (filter_period, decay_period, reduction_factor, dynamic_fee_control, max_volatility_accumulator) para seu próprio DynamicFeeInfo no momento da criação; edições posteriores ao DynamicFeeConfig não afetam retroativamente pools já existentes.
DynamicFeeInfo (embutido em PoolState)
DynamicFeeConfig. O cálculo da taxa e as regras de decaimento estão documentados em products/clmm/math e products/clmm/fees.
Constantes utilizadas pela fórmula:
| Constante | Valor | Significado |
|---|---|---|
VOLATILITY_ACCUMULATOR_SCALE | 10_000 | Granularidade do acumulador de volatilidade |
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 | Limite máximo de 10% sobre a taxa resultante |
LimitOrderState
Uma conta por ordem limitada aberta.
- Abrir — o usuário chama
open_limit_order, depositatotal_amountdo token de entrada; a ordem é vinculada a uma coorte doTickState. - (opcional) Aumentar / Diminuir —
increase_limit_orderadiciona atotal_amount;decrease_limit_orderdevolve os tokens não preenchidos (e qualquer saída liquidada até aquele ponto). - Liquidar — quando a coorte é total ou parcialmente preenchida, o dono ou o keeper operacional chama
settle_limit_orderpara enviar os tokens de saída para a ATA do dono. - Fechar — assim que
unfilled_amount == 0, a conta pode ser fechada. O rent sempre retorna aoowner.
[owner.as_ref(), limit_order_nonce.key().as_ref(), limit_order_nonce.order_nonce.to_be_bytes().as_ref()]. O PDA da ordem é, portanto, único por (owner, nonce_index, order_nonce).
LimitOrderNonce
Contador por (wallet, nonce_index) que permite a um único usuário executar múltiplos pipelines paralelos de ordens limitadas sem colisão de PDAs.
[user_wallet.as_ref(), &[nonce_index]]. A maioria dos clientes usa nonce_index = 0 e deixa o order_nonce controlar a cardinalidade.
Derivando as contas principais
reference/program-addresses.
Referência rápida do ciclo de vida
| Evento | Contas criadas | Contas destruídas |
|---|---|---|
CreatePool | poolState, observation, token_0_vault, token_1_vault | — |
OpenPosition[WithToken22Nft] | NFT mint + ATA, personalPosition, possivelmente novos tickArrayState(s), tickArrayBitmapExtension se ainda não existir | — |
IncreaseLiquidity | Possivelmente novos tickArrayState(s) | — |
DecreaseLiquidity | — | Possivelmente limpa entradas de tick (mas o tickArrayState em si não é fechado) |
ClosePosition | — | NFT mint, personalPosition |
SwapV2 | Possivelmente novo tickArrayState | — |
OpenLimitOrder | limitOrderState, possivelmente limitOrderNonce (init-if-needed), possivelmente novo tickArrayState | — |
IncreaseLimitOrder | — | — |
DecreaseLimitOrder | — | Fecha limitOrderState se a ordem for totalmente consumida |
SettleLimitOrder | — | — |
CloseLimitOrder | — | limitOrderState (rent → owner) |
CreateDynamicFeeConfig | dynamicFeeConfig | — |
CreateCustomizablePool | poolState, observation, vaults — igual a CreatePool. Copia dynamicFeeConfig se enable_dynamic_fee = true. | — |
CollectRewards | — | — |
UpdateRewardInfos | — | — |
CloseProtocolPosition (admin) | — | protocolPositionState vestigial (rent → admin) |
TickArrayState nunca são fechadas pelo programa — elas persistem durante toda a vida do pool. Uma vez que um tick array tenha sido inicializado, ele permanece on-chain mesmo quando todos os ticks dentro dele retornam a liquidity_gross == 0. Reutilizar um tick array existente é gratuito; apenas a primeira posição a tocar um array nunca inicializado paga seu rent.
O que ler e onde
- Matemática de tick e mecânica de intervalos:
products/clmm/ticks-and-positions. - Percurso de swap e matemática de crescimento de taxas:
products/clmm/math. - Listas de contas por instrução:
products/clmm/instructions. - Taxas e acúmulo de recompensas:
products/clmm/fees. - IDs de programa canônicos e seeds:
reference/program-addresses.


