2026-05-18 — CLMM: limit orders, single-sided fee, dynamic fee

O próximo lançamento do CLMM adiciona três capacidades no nível do pool. Elas são opcionais no momento da criação do pool e compatíveis com versões anteriores com pools e posições existentes.

​

TL;DR para integradores

• Limit orders agora são primitivos CLMM de primeira classe. LPs podem abrir uma ordem de um único tick em um pool que as suporte; a ordem é preenchida FIFO quando um swap cruza o tick, e um keeper off-chain (limit_order_admin) pode liquidar a saída preenchida sem o proprietário estar online. Sete novos métodos SDK (openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, closeLimitOrder, closeAllLimitOrder, settleAllLimitOrder) e três novos endpoints da Temp API sob /limit-order/ (ordens ativas, histórico por usuário, log de eventos por PDA) cobrem o fluxo completo.
• Taxa unilateral (CollectFeeOn) permite que um pool coleta taxas de swap do lado de entrada (legado, modo 0), ou sempre de token_0 (modo 1), ou sempre de token_1 (modo 2). Útil quando um lado do par é o token de contabilidade canônico.
• Taxa dinâmica permite que um pool opte por uma sobretaxa rastreadora de volatilidade que aumenta com movimento rápido de tick e decai ao longo do tempo, calibrada por uma DynamicFeeConfig por tier e uma DynamicFeeInfo por pool. O novo endpoint /main/clmm-dynamic-config expõe a lista de tiers.
• Uma nova instrução, CreateCustomizablePool, expõe todos os três controles no momento da criação do pool. O CreatePool clássico continua funcionando para pools padrão sem limit orders.
• Mudança de quebra do indexador: os contadores de volume por direção (swap_in_amount_token_{0,1}, swap_out_amount_token_{0,1}) e contadores de taxa vitalícia (total_fees_token_{0,1}, total_fees_claimed_token_{0,1}) em PoolState foram aposentados em padding para abrir espaço para fee_on e dynamic_fee_info. Indexadores que leem esses campos diretamente devem migrar para o ring Observation on-chain ou para a API.

​

Por que isso importa (para traders, LPs e integradores)

• Traders obtêm cotações mais apertadas em pares long-tail e orientados por eventos: taxa dinâmica permite que o pool absorva sobrecargas de volatilidade do taker sem LPs terem que ampliar ativamente os ranges, e escadas de limit orders aprofundam a liquidez on-chain em preços específicos sem comprometer capital em toda a faixa.
• LPs obtêm uma terceira estratégia ao lado de ranges concentrados e posições full-range: estacione ordens de preço exato, seja preenchido quando o preço visita, liquide no token de cotação. Nenhum rebalanceamento ativo necessário para a porção preenchida.
• Integradores podem modelar pools com taxa dinâmica deterministicamente — o algoritmo e parâmetros estão totalmente on-chain, os tiers de calibração são consultáveis, e o caminho de swap é inalterado em forma (apenas a taxa por etapa varia).

​

O que mudou no programa

​

Novas contas

• DynamicFeeConfig — registro de calibração por tier (período de filtro, período de decaimento, fator de redução, controle de taxa dinâmica, acumulador máximo de volatilidade). Criado por CreateDynamicFeeConfig (admin), referenciado por CreateCustomizablePool quando taxa dinâmica está habilitada.
• LimitOrderState — conta por ordem (seeds PDA: [owner, limit_order_nonce, order_nonce]) contendo o pool, tick, lado, quantidade de entrada, razão não preenchida, fase de cohort FIFO e snapshots de contabilidade. O ciclo de vida é implícito (filled_amount vs total_amount, mais existência da conta): Open → Filled → Settled → Closed.
• LimitOrderNonce — contador monotonicamente crescente por (proprietário, nonce_index) que obtém as seeds PDA de limit order. O nonce_index: u8 permite que o mesmo proprietário particione ordens em até 256 fluxos de nonce independentes.

Veja Accounts → DynamicFeeConfig and DynamicFeeInfo e Accounts → LimitOrderState.

​

Reestruturação de PoolState

O tamanho total da conta é inalterado. Indexadores: mude o rastreamento de volume de PoolState para o ring Observation ou para a API. Os contadores aposentados não são zerados em pools existentes (eles contêm o que quer que tenham carregado por último), então relê-los após a atualização retornará dados obsoletos.

​

Adições de TickState (sem mudança de quebra)

Quatro novos campos são adicionados no final de TickState, substituindo parte de seu padding final:

• order_phase: u64 — contador que desambigua cohorts de limit order neste tick.
• orders_amount: u64 — entrada total comprometida por todas as ordens abertas neste tick (nem todas totalmente não preenchidas).
• part_filled_orders_remaining: u64 — entrada ainda não preenchida no cohort sendo consumido por swaps.
• unfilled_ratio_x64: u128 — razão Q64.64 usada para calcular a parcela de preenchimento de cada ordem.

O layout do tick-array, dimensionamento e seeds PDA são inalterados.

​

Novas instruções

• CreateDynamicFeeConfig (admin) — criar um tier DynamicFeeConfig calibrado. Autoridade: mesmo multisig de tesouro que CreateAmmConfig.
• UpdateDynamicFeeConfig (admin) — atualizar parâmetros de um tier existente.
• CreateCustomizablePool — ponto de entrada de criação de pool que expõe collect_fee_on, enable_dynamic_fee e dynamic_fee_config. Coexiste com CreatePool; recomendamos CreateCustomizablePool para qualquer novo pool que necessite dos novos controles.
• OpenLimitOrder — abrir uma limit order de um único tick. Incrementa LimitOrderNonce, aloca LimitOrderState, insere a ordem no cohort FIFO no tick.
• IncreaseLimitOrder / DecreaseLimitOrder — ajustar a porção não preenchida de uma ordem. Reverte em uma ordem totalmente preenchida com InvalidOrderPhase.
• SettleLimitOrder — varrer saída preenchida para o ATA do proprietário. O chamador pode ser o proprietário ou o keeper limit_order_admin do pool.
• CloseLimitOrder — fechar uma ordem totalmente liquidada para recuperar aluguel.

​

Mudanças de comportamento de SwapV2

O caminho de swap em si é inalterado em forma, mas três coisas agora acontecem ao longo do caminho:

1. Taxa dinâmica (quando habilitada): a DynamicFeeInfo do pool é atualizada a cada etapa (decaimento → acumulação → limite), e a sobretaxa resultante é adicionada à taxa base para essa etapa.
2. Correspondência de limit order (quando a etapa cruza um tick inicializado que tem ordens abertas): parte da entrada de swap é consumida FIFO para preencher o cohort naquele tick, com unfilled_ratio_x64 atualizado atomicamente.
3. Roteamento de taxa unilateral (quando fee_on != 0): a taxa é retirada de token_0 ou token_1 independentemente da direção do swap, em vez de sempre do lado de entrada.

Cada um desses é um no-op quando o pool foi criado com os padrões legados. Veja Instructions → SwapV2 para a matriz de mudança de estado atualizada.

​

Novos códigos de erro

O enum ErrorCode foi renumerado neste lançamento: cinco variantes legadas (LOK, ZeroMintAmount, InvalidLiquidity, TransactionTooOld, InvalidRewardDesiredAmount) foram removidas, e onze novas variantes foram anexadas. Como Anchor numera erros por ordem de enum a partir de 6000, cada código de erro nas posições removidas ou depois delas foi deslocado — clientes que codificaram numericamente códigos precisam remapear. Os novos códigos são:

• 6040 OrderAlreadyFilled
• 6041 InvalidOrderPhase
• 6042 InvalidLimitOrderAmount
• 6043 OrderPhaseSaturated
• 6044 InvalidDynamicFeeConfigParams
• 6045 InvalidFeeOn
• 6046 ZeroSqrtPrice
• 6047 ZeroLiquidity
• 6048 MissingBaseFlag
• 6049 MissingMintAccount
• 6050 MissingTokenProgram2022

Strings completas e a tabela pós-deslocamento para todos os erros CLMM estão em Error codes.

​

O que mudou no SDK (@raydium-io/raydium-sdk-v2)

• Novos métodos em raydium.clmm: createCustomizablePool, openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, settleAllLimitOrder, closeLimitOrder, closeAllLimitOrder.
• Novos helpers REST em raydium.api: getClmmDynamicConfigs, getClmmLimitOrderConfigs.
• Novos tipos: enum CollectFeeOn, DynamicFeeConfig, DynamicFeeInfo, LimitOrderState, LimitOrderConfig.
• Reorganização interna: utils/ movido para libraries/. O barrel do pacote é inalterado; apenas importações profundas sob @raydium-io/raydium-sdk-v2/utils/... precisam ser atualizadas para …/libraries/....

Passo a passo TypeScript de ponta a ponta vivem em products/clmm/code-demos.

​

O que mudou nas APIs

• api-v3 — dois novos endpoints sob /main/:
  • GET /main/clmm-dynamic-config — lista de tiers DynamicFeeConfig.
  • GET /main/clmm-limit-order-config — configuração de limit order por pool.
• temp-api-v1 — três novos endpoints sob /limit-order/:
  • GET /limit-order/order/list?wallet=… — ordens atualmente estacionadas de uma carteira (abertas e parcialmente preenchidas, servidas do cache Redis do indexador; mesmo payload cobre ambas as fases via totalAmount / filledAmount / pendingSettle).
  • GET /limit-order/history/order/list-by-user?wallet=… — limit orders históricas de uma carteira. Filtros opcionais: poolId, mint1, mint2, hideCancel. Paginação por cursor via nextPageId / size (máx 100).
  • GET /limit-order/history/event/list-by-pda?pda=… — log de eventos por PDA (open / increase / decrease / settle / close) para um ou mais PDAs de limit order separados por vírgula. Paginação por cursor via nextPageId / size (máx 100).

Todos os cinco estão documentados na aba API Reference.

​

Superfície de autoridade

O limit_order_admin é um keeper operacional off-chain, não um multisig. Ele pode apenas chamar SettleLimitOrder e CloseLimitOrder em ordens existentes, e a saída de uma liquidação sempre vai para o ATA do proprietário. Ele não pode mutar campos de pool, abrir ou modificar ordens, ou assinar qualquer outra coisa. Veja Admin keys and multisig → CLMM.

​

Páginas atualizadas

• products/clmm/overview — nova seção “What’s new” e ponteiros de próximas etapas atualizados.
• products/clmm/accounts — três novas contas, reestruturação de PoolState com aviso de migração, adições de TickState, novos helpers PDA.
• products/clmm/instructions — sete novas instruções, adendo de comportamento de SwapV2, matriz de mudança de estado atualizada.
• products/clmm/fees — seção de taxa unilateral, seção de taxa dinâmica com tabela de parâmetros.
• products/clmm/math — pseudo-código de correspondência de limit order, derivação de taxa dinâmica.
• products/clmm/code-demos — demo de createCustomizablePool, passo a passo completo de limit order, novas armadilhas.
• algorithms/clmm-math — referência cruzada para correspondência de limit order e taxa dinâmica no loop de swap multi-tick.
• sdk-api/typescript-sdk — seção de adições do módulo CLMM, nota de migração utils/ → libraries/.
• api-reference/openapi/api-v3.yaml — dois novos endpoints com esquemas de resposta.
• api-reference/openapi/temp-api-v1.yaml — três novos endpoints de limit order (/limit-order/order/list, /limit-order/history/order/list-by-user, /limit-order/history/event/list-by-pda) com seus esquemas de requisição e resposta.
• api-reference/api-v3/overview — nota sobre os novos endpoints de configuração CLMM.
• api-reference/temp-api-v1/overview — nota sobre os novos endpoints de ordens ativas, histórico por usuário e eventos por PDA.
• reference/error-codes — onze novos códigos de erro CLMM (6040–6050) mais cinco códigos legados removidos; códigos numéricos após os pontos de remoção foram deslocados.
• security/admin-and-multisig — nova linha de admin DynamicFeeConfig e linha de keeper limit_order_admin, com explicador de autoridade limitada.

Verificado contra:

• fonte de raydium-clmm.
• fonte de @raydium-io/raydium-sdk-v2.
• fonte de api-v3 e temp-api-v1.