Instruções CLMM

​

Inventário de instruções

​

CreatePool

sqrt_price_x64: u128           // preço inicial
open_time:      u64            // swaps rejeitados antes desta hora

• token_mint_0 < token_mint_1 por ordem de bytes.
• amm_config.disable_create_pool == false.
• Mints não são rejeitados pela lista de permissões de extensão Token-2022.

• pool_state.sqrt_price_x64 = sqrt_price_x64, tick_current = floor(log_{1.0001}(price)).
• pool_state.liquidity = 0 (sem posições ainda).
• pool_state.fee_on = FromInput (padrão legado).
• pool_state.dynamic_fee_info é zerado (taxa dinâmica desabilitada).

​

CreateCustomizablePool

pub struct CreateCustomizableParams {
    pub sqrt_price_x64:    u128,
    pub collect_fee_on:    CollectFeeOn,   // FromInput | Token0Only | Token1Only
    pub enable_dynamic_fee: bool,
}

• pool_state.fee_on definido para a variante CollectFeeOn escolhida.
• Se taxa dinâmica foi habilitada: pool_state.dynamic_fee_info é inicializado a partir do DynamicFeeConfig fornecido (cinco parâmetros de calibração copiados; campos de estado zerados).
• Caso contrário: pool_state.dynamic_fee_info é zerado (= taxa dinâmica inativa para sempre para este pool).

​

CreatePermissionedPool

customizable_params: CreateCustomizableParams   // mesma struct que CreateCustomizablePool
seed_index:          u16                          // deve ser diferente de zero; dobrado nas sementes do PDA do pool

• seed_index != 0. Um seed_index de 0 é reservado para pools legados e é rejeitado aqui; o componente de semente [0, 0] é o que faz um endereço de pool legado colapsar para a forma clássica de quatro sementes.
• O PDA permission para payer existe (criado por um admin via CreatePermissionPda).
• Mesmas regras de mint / lista de permissões que CreatePool.

• Um novo pool_state existe no endereço derivado de seed_index, com pool_state.seed_index = seed_index.
• Todo outro pós-estado corresponde a CreateCustomizablePool (modo de taxa, taxa dinâmica opcional).

​

OpenPositionV2 / OpenPositionWithToken22Nft

tick_lower_index: i32
tick_upper_index: i32
tick_array_lower_start_index: i32
tick_array_upper_start_index: i32
liquidity:  u128              // L desejado (ou 0 para usar valores abaixo)
amount_0_max: u64
amount_1_max: u64
with_metadata: bool           // escreve metadados NFT (Metaplex)
base_flag: Option<bool>       // true = ajusta para amount0; false = ajusta para amount1

• tick_lower < tick_upper, ambos múltiplos de pool.tick_spacing, dentro de [MIN_TICK, MAX_TICK].
• Tick arrays necessários passados e inicializados (ou criados aqui via CPI InitTickArray na transação).
• Usuário tem pelo menos amount_0_max e amount_1_max nas ATAs de origem.

• personal_position existe, liquidity definido, fee_growth_inside_last capturado.
• Entradas de tick-array em tick_lower e tick_upper atualizadas (liquidity_gross += L, liquidity_net ± L, snapshots de crescimento de taxa mantidos).
• pool_state.liquidity += L se a posição está no intervalo (tick_lower ≤ tick_current < tick_upper).
• O mint NFT de posição registra pool_state como autoridade de congelamento. A autoridade de mint é removida após o único NFT ser cunhado. Registrar a autoridade de congelamento não altera o estado da conta de token NFT.
• A conta de token NFT permanece descongelada a menos que a instrução seja OpenPositionV2 ou OpenPositionWithToken22Nft e a autoridade de congelamento de qualquer mint de cofre corresponda à lista de emissores restritos do CLMM. Apenas esse caminho V2 correspondente congela a conta. OpenPosition V1 não congela.

​

IncreaseLiquidityV2

liquidity: u128
amount_0_max: u64
amount_1_max: u64
base_flag: Option<bool>

• Transfere amount_0_actual / amount_1_actual do usuário → cofres.
• Incrementa personal_position.liquidity e pool_state.liquidity (se no intervalo), e o liquidity_gross / liquidity_net do tick de ponto final de acordo.
• Coleta taxas e recompensas devidas desde o último toque e as credita a tokens_fees_owed_{0,1} / reward_amount_owed. Aquelas são pagas apenas em DecreaseLiquidity ou CollectReward, não em aumento.

​

DecreaseLiquidityV2

liquidity: u128
amount_0_min: u64
amount_1_min: u64

• Computa (amount_0, amount_1) para o L removido dado sqrt_price_x64 atual.
• Liquida taxas/recompensas acumuladas desde o último toque, mesmo que IncreaseLiquidity.
• Transfere amount_0 + fees_owed_0 e amount_1 + fees_owed_1 dos cofres para o usuário.
• Decrementa contadores de liquidez; se o novo personal_position.liquidity == 0, a posição é elegível para ClosePosition.

​

ClosePosition

• NFT descongelado: nenhum necessário; uma conta de pool extra é inofensiva porque o manipulador não a lê.
• NFT congelado: anexa personal_position.pool_id como a primeira conta restante. O programa a carrega como PoolState e usa suas sementes de PDA para assinar o descongelamento.

• personal_position.liquidity == 0.
• tokens_fees_owed_{0,1} == 0.
• Todos os contadores de recompensa reward_amount_owed == 0.

• Se a conta de token NFT estiver congelada, verifica se a primeira conta restante é igual a personal_position.pool_id, então a descongela com o PDA do pool.
• Queima o NFT.
• Fecha a conta de token NFT e personal_position, reembolsando aluguel para nft_owner. Se o NFT de posição usar Token-2022, também fecha o mint NFT; mints Token SPL clássicos não podem ser fechados e permanecem com fornecimento zero.

​

SwapV2

amount: u64                  // entrada se is_base_input=true, saída caso contrário
other_amount_threshold: u64  // mín. saída ou máx. entrada
sqrt_price_limit_x64: u128   // limite rígido; 0 ⇒ ilimitado
is_base_input: bool

• pool_state.status permite swap.
• now >= open_time.
• sqrt_price_limit_x64 está no lado correto de sqrt_price_x64 para a direção.

1. Sobretaxa de taxa dinâmica — se pool.dynamic_fee_info é diferente de zero, o programa atualiza o acumulador de volatilidade usando a distância de tick percorrida desde o último swap (com as regras de filtro/decaimento de products/clmm/fees) e adiciona um dynamic_fee_component em cima de AmmConfig.trade_fee_rate. Taxa total é limitada a 10% (MAX_FEE_RATE_NUMERATOR / 1_000_000).
2. Correspondência de ordem limitada — quando a caminhada de preço cruza um tick que contém ordens limitadas abertas, o programa primeiro preenche liquidez de ordem limitada disponível naquele tick (FIFO por order_phase), depois prossegue ao longo da curva de liquidez LP. Quantidades preenchidas atualizam tick.unfilled_ratio_x64 e tick.part_filled_orders_remaining para liquidação posterior; as próprias ordens permanecem não gastas até que seu proprietário chame SettleLimitOrder.
3. Roteamento de taxa unilateral — quando pool.fee_on = Token0Only ou Token1Only, a etapa de swap ainda computa o mesmo comércio entrada-saída; a taxa é então roteada para o lado configurado. Para direções onde o lado de taxa configurado é a saída, a taxa é deduzida da saída de swap (o usuário recebe out − fee); para direções onde é a entrada, o comportamento corresponde a FromInput. Veja is_fee_on_input(zero_for_one) e is_fee_on_token0(zero_for_one) em PoolState.

​

OpenLimitOrder

nonce_index:    u8       // índice de conta nonce escolhido pelo usuário (0..255 por carteira)
zero_for_one:   bool     // true: vende token0 por token1; false: vende token1 por token0
tick_index:     i32      // deve ser múltiplo de pool.tick_spacing
amount:         u64      // quantidade de token de entrada

• Nem input_token_account nem output_token_account está congelado (senão NotApproved).
• pool_state.status permite tanto swap (bit 4) quanto operações de ordem limitada (bit 5) (senão NotApproved).
• tick_index % pool.tick_spacing == 0 e dentro de [MIN_TICK, MAX_TICK].
• tick_index está no lado direito de pool.tick_current para a direção escolhida (vender token0 → tick deve estar acima do atual, e vice-versa). Vender em um tick já cruzado seria correspondido imediatamente e é rejeitado.

• limit_order existe, capturando tick.order_phase e tick.unfilled_ratio_x64 no tempo de abertura.
• tick.orders_amount += amount (na coorte atual).
• limit_order_nonce.order_nonce += 1.
• OpenLimitOrderEvent emitido.

​

IncreaseLimitOrder

amount: u64    // quantidade adicional de token de entrada

• limit_order.owner == signer.
• A ordem ainda está na mesma coorte (tick.order_phase == limit_order.order_phase). Se a coorte já começou a ser preenchida, a ordem é parcialmente liquidada — o chamador deve chamar DecreaseLimitOrder ou SettleLimitOrder primeiro para avançar.

• Transfere amount da ATA do proprietário para input_vault.
• limit_order.total_amount += amount; tick.orders_amount += amount.

​

DecreaseLimitOrder

amount:     u64    // quantidade de token de entrada para retirar (máx. = restante não preenchido)
amount_min: u64    // piso de slippage na retirada do lado de entrada

• Recomputa a quantidade preenchida da ordem a partir de unfilled_ratio_x64 da coorte desde a abertura.
• Envia saída preenchida para output_token_account.
• Envia amount de entrada não preenchida de volta para input_token_account.
• Atualiza limit_order de acordo. Se o novo restante não preenchido for zero, o programa fecha a conta e reembolsa aluguel para owner.

​

SettleLimitOrder

• Computa a saída cumulativa devida usando (limit_order.unfilled_ratio_x64, tick.unfilled_ratio_x64).
• Transfere o delta para output_token_account.
• Atualiza limit_order.settled_output.
• Não fecha a ordem; ela ainda está aberta contra qualquer entrada restante.

​

CloseLimitOrder

• A ordem tem zero restante não preenchido (ou amount == total_amount foi preenchido e liquidado, ou o proprietário diminuiu anteriormente a ordem para zero e esqueceu de fechar).

• Fecha limit_order; aluguel é enviado para limit_order.owner.

​

CreateDynamicFeeConfig (admin)

index:                       u16
filter_period:               u16   // segundos; por exemplo, 30
decay_period:                u16   // segundos; por exemplo, 600. Deve ser > filter_period
reduction_factor:            u16   // 1..10_000; por exemplo, 5_000 = 50% retenção por janela de decaimento
dynamic_fee_control:         u32   // 1..100_000; ganho na curva volatilidade-para-taxa
max_volatility_accumulator:  u32   // teto

​

UpdateDynamicFeeConfig (admin)

​

CollectProtocolFee / CollectFundFee

​

InitializeReward

open_time:     u64
end_time:      u64
emissions_per_second_x64: u128   // Q64.64

• Menos de 3 fluxos atualmente ativos no pool.
• Financiador deposita total_emission = emissions_per_second × (end_time − open_time) de token de recompensa no cofre como parte desta instrução.
• Mint de recompensa na lista de permissões por operation_state.

​

SetRewardParams

​

UpdateRewardInfos

​

CollectReward

• Liquida crescimento de recompensa (mesmo padrão que taxas).
• Transfere a quantidade devida para a ATA do destinatário, zera reward_amount_owed[i].

​

Matriz de mudança de estado

​

Próximos passos

• products/clmm/code-demos — amostras TypeScript executáveis.
• products/clmm/fees — detalhes sobre acúmulo de taxa e recompensa.
• reference/error-codes — tabela de erro Anchor CLMM completa.

• raydium-io/raydium-clmm — programs/amm/src/instructions
• Raydium SDK v2 — @raydium-io/raydium-sdk-v2