Saltar para o conteúdo principal
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 complementa products/clmm/accounts (o que são as contas) e products/clmm/math (como funciona a matemática). É a referência definitiva para argumentos e ordenação de contas; os layouts de bytes específicos vêm do IDL.

Inventário de instruções

A maioria das instruções exclusivas de admin (CreateAmmConfig, UpdateAmmConfig, UpdatePoolStatus, CreateSupportMintAssociated, CreateOperationAccount, UpdateOperationAccount, CloseProtocolPosition) é controlada pela chave pública admin embutida no programa. As instruções de admin de fluxo de recompensa (TransferRewardOwner, CollectRemainingRewards) são controladas pelo financiador da recompensa, não pelo admin do programa. O sufixo V2 significa “suporta Token-2022 em vaults/NFT e exige o slot de extensão de bitmap”. O SDK usa V2 por padrão para novos pools.

CreatePool

Argumentos
Contas (resumido) Pré-condições
  • token_mint_0 < token_mint_1 por ordem de bytes.
  • amm_config.disable_create_pool == false.
  • Os mints não são rejeitados pela lista de permissões de extensão Token-2022.
Pós-condições
  • pool_state.sqrt_price_x64 = sqrt_price_x64, tick_current = floor(log_{1.0001}(price)).
  • pool_state.liquidity = 0 (nenhuma posição ainda).
  • pool_state.fee_on = FromInput (padrão legado).
  • pool_state.dynamic_fee_info é zerado (taxa dinâmica desativada).

CreateCustomizablePool

Recomendado para novos pools. Tem o mesmo efeito que CreatePool, com adição do modo de coleta de taxa por pool e uma opção de taxa dinâmica. Argumentos
Contas (resumido) — mesmas que CreatePool, acrescidas de, quando enable_dynamic_fee = true: Pré-condições — mesmas que CreatePool. Se enable_dynamic_fee = false, dynamic_fee_config é ignorado. Pós-condições
  • pool_state.fee_on definido para a variante CollectFeeOn escolhida.
  • Se a 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 permanentemente para este pool).
fee_on e o bit de habilitação de taxa dinâmica são definidos apenas na criação do pool. Não há atualização in-place — pools criados via CreatePool legado não podem adquirir taxa dinâmica ou taxa unilateral retroativamente. Novas implantações devem usar esta instrução por padrão.

OpenPositionV2 / OpenPositionWithToken22Nft

Cria uma nova posição dentro de um pool existente. Argumentos
Contas (resumido) Matemática — consulte products/clmm/math. A partir de base_flag, o programa resolve liquidity ou (amount_0_max, amount_1_max) no L real e nos valores reais de tokens consumidos. Pré-condições
  • 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).
  • O usuário tem pelo menos amount_0_max e amount_1_max nas ATAs de origem.
Pós-condições
  • personal_position existe, liquidity definido, fee_growth_inside_last com snapshot 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 estiver no intervalo (tick_lower ≤ tick_current < tick_upper).
Erros comunsInvalidTickIndex, NotApproved, ZeroAmountSpecified, TransactionTooLarge (se houver tick arrays demais).

IncreaseLiquidityV2

Adiciona liquidez a uma posição já aberta. Argumentos
Contas — semelhante a OpenPosition, sem o mint do NFT (a posição já existe; o NFT é passado como a ATA do dono que contém 1 token). Efeito
  • Transfere amount_0_actual / amount_1_actual do usuário para os vaults.
  • Incrementa personal_position.liquidity e pool_state.liquidity (se estiver no intervalo), além dos valores liquidity_gross / liquidity_net dos ticks extremos.
  • Coleta taxas e recompensas devidas desde o último toque e as credita em tokens_fees_owed_{0,1} / reward_amount_owed. Esses valores são pagos apenas em DecreaseLiquidity ou CollectReward, não no aumento.

DecreaseLiquidityV2

Remove liquidez de uma posição. Argumentos
Contas — mesmo formato que IncreaseLiquidity. Efeito
  • Calcula (amount_0, amount_1) para o L removido com base no sqrt_price_x64 atual.
  • Liquida as taxas/recompensas acumuladas desde o último toque, da mesma forma que IncreaseLiquidity.
  • Transfere amount_0 + fees_owed_0 e amount_1 + fees_owed_1 dos vaults para o usuário.
  • Decrementa os contadores de liquidez; se o novo personal_position.liquidity == 0, a posição é elegível para ClosePosition.
Slippageamount_0_min e amount_1_min são os mínimos aceitos pelo usuário, líquidos das taxas de transferência Token-2022 no lado de saída.

ClosePosition

Queima o NFT de posição e fecha o PersonalPositionState. Pré-condições
  • personal_position.liquidity == 0.
  • tokens_fees_owed_{0,1} == 0.
  • Todos os contadores de recompensa reward_amount_owed == 0.
(Ou seja, colete tudo e reduza para zero primeiro.) Efeito
  • Queima o NFT.
  • Fecha a conta do mint do NFT e a conta personal_position, devolvendo o rent ao payer.

SwapV2

Percorre a curva de liquidez; entrada exata ou saída exata, dependendo de is_base_input. Argumentos
Contas (resumido) Os chamadores passam uma lista ordenada de tick arrays cobrindo o percurso esperado do swap; o programa usa quantos forem necessários. O SDK calcula essa lista via PoolUtils.computeAmountOutFormat ou o endpoint de cotação da API. Pré-condições
  • pool_state.status permite swap.
  • now >= open_time.
  • sqrt_price_limit_x64 está no lado correto de sqrt_price_x64 para a direção escolhida.
Erros comunsExceededSlippage, SqrtPriceLimitOverflow, TickArrayNotFound, LiquidityInsufficient. O que SwapV2 faz internamente e que os chamadores devem saber (versão pós-2025):
  1. Sobretaxa dinâmica — se pool.dynamic_fee_info for 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 sobre AmmConfig.trade_fee_rate. A taxa total é limitada a 10% (MAX_FEE_RATE_NUMERATOR / 1_000_000).
  2. Correspondência de ordens limitadas — quando o percurso de preço cruza um tick que contém ordens limitadas abertas, o programa preenche primeiro a liquidez disponível de ordens limitadas naquele tick (FIFO por order_phase), e depois continua ao longo da curva de liquidez do LP. Os valores preenchidos atualizam tick.unfilled_ratio_x64 e tick.part_filled_orders_remaining para liquidação posterior; as próprias ordens permanecem pendentes até que o dono chame SettleLimitOrder.
  3. Roteamento de taxa unilateral — quando pool.fee_on = Token0Only ou Token1Only, o passo de swap ainda calcula a mesma negociação entrada-saída; a taxa é então roteada para o lado configurado. Para direções em que o lado de taxa configurado é a saída, a taxa é deduzida da saída do swap (o usuário recebe out − fee); para direções em que é a entrada, o comportamento é igual ao FromInput. Veja is_fee_on_input(zero_for_one) e is_fee_on_token0(zero_for_one) em PoolState.
Swap (V1) implementa a mesma taxa dinâmica, roteamento de taxa unilateral e correspondência de ordens limitadas que SwapV2; a única funcionalidade ausente é o suporte a Token-2022 — ambos os vaults precisam ser SPL Token clássico. Pools com qualquer mint Token-2022 devem ser negociados via SwapV2. O agregador e o SDK já preferem V2 para cada etapa CLMM, de modo que os chamadores não precisam verificar o tipo de mint.

OpenLimitOrder

Coloca uma ordem de venda em um tick específico. A ordem fica em uma fila FIFO por tick e é preenchida à medida que o preço passa. Argumentos
Contas (resumido) Pré-condições
  • tick_index % pool.tick_spacing == 0 e dentro de [MIN_TICK, MAX_TICK].
  • tick_index está no lado correto 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.
  • pool_state.status permite a operação de ordem limitada (bit 5).
Pós-condições
  • limit_order existe, com snapshot de tick.order_phase e tick.unfilled_ratio_x64 no momento da abertura.
  • tick.orders_amount += amount (no coorte atual).
  • limit_order_nonce.order_nonce += 1.
  • Evento OpenLimitOrderEvent emitido.
Erros comunsInvalidLimitOrderAmount (zero ou abaixo do mínimo do pool), InvalidTickIndex (fora de [MIN_TICK, MAX_TICK] ou no lado errado de tick_current para a direção escolhida), TickAndSpacingNotMatch (tick_index % pool.tick_spacing != 0), OrderPhaseSaturated.

IncreaseLimitOrder

Aumenta uma ordem aberta existente. Só pode ser chamado pelo owner da ordem. Argumentos
Contas — semelhante a OpenLimitOrder, sem a conta nonce; o PDA limit_order é passado diretamente. Pré-condições
  • limit_order.owner == signer.
  • A ordem ainda está no mesmo coorte (tick.order_phase == limit_order.order_phase). Se o coorte já começou a ser preenchido, a ordem está parcialmente liquidada — o chamador deve chamar DecreaseLimitOrder ou SettleLimitOrder primeiro para avançar.
Efeito
  • Transfere amount da ATA do dono para input_vault.
  • limit_order.total_amount += amount; tick.orders_amount += amount.

DecreaseLimitOrder

Reduz ou cancela completamente uma ordem aberta. Devolve o saldo não preenchido ao dono, mais qualquer saída já liquidada por preenchimentos parciais anteriores. Argumentos
Contas — ambos os lados de token de entrada e saída: Efeito
  • Recalcula o valor preenchido da ordem a partir do unfilled_ratio_x64 do coorte desde a abertura.
  • Envia a saída preenchida para output_token_account.
  • Envia amount da entrada não preenchida de volta para input_token_account.
  • Atualiza limit_order conforme necessário. Se o novo saldo não preenchido for zero, o programa fecha a conta e devolve o rent ao owner.

SettleLimitOrder

Envia tokens de saída preenchidos ao dono sem alterar o saldo não preenchido da ordem. Útil quando keepers auto_withdraw querem pagar preenchimentos parciais de longa duração em parcelas. Chamador — o owner da ordem ou o limit_order_admin do programa (uma carteira operacional off-chain que executa um loop de keeper automatizado). O keeper não tem outra autoridade — não pode movimentar fundos de usuários além de enviar a saída preenchida para a ATA de owner da ordem. Contas Efeito
  • Calcula a saída acumulada 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 continua aberta para qualquer entrada restante.

CloseLimitOrder

Fecha uma conta de ordem totalmente consumida. O rent é sempre devolvido ao limit_order.owner, independentemente de quem assina. Chamador — o owner ou o limit_order_admin. Pré-condições
  • A ordem tem saldo não preenchido zero (seja porque amount == total_amount foi preenchido e liquidado, seja porque o dono reduziu anteriormente a ordem para zero e não a fechou).
Efeito
  • Fecha limit_order; o rent é enviado para limit_order.owner.

CreateDynamicFeeConfig (admin)

Cria um conjunto de parâmetros reutilizável sob um índice u16. Argumentos
Contas Erros comunsInvalidDynamicFeeConfigParams se decay_period <= filter_period ou qualquer campo com valor 0 estiver fora dos limites.

UpdateDynamicFeeConfig (admin)

Modifica um DynamicFeeConfig existente. Pools que já capturaram o snapshot da configuração no momento da criação não são atualizados retroativamente; apenas pools recém-criados que referenciem esta configuração receberão os novos valores. Argumentos — os mesmos cinco campos de calibração que CreateDynamicFeeConfig (filter_period, decay_period, reduction_factor, dynamic_fee_control, max_volatility_accumulator); o index é fixado na criação e não é repassado aqui.

CollectProtocolFee / CollectFundFee

Formato idêntico ao CollectProtocolFee / CollectFundFee do CPMM. O assinante deve corresponder a AmmConfig.owner / AmmConfig.fund_owner. Varre as taxas de protocolo/fundo acumuladas dos vaults do pool para um destinatário e zera os campos PoolState.protocol_fees_* / fund_fees_* correspondentes.

InitializeReward

Adiciona um novo fluxo de recompensa a um pool. Até 3 fluxos podem estar ativos simultaneamente. Argumentos
Contas Pré-condições
  • Menos de 3 fluxos ativos no pool no momento.
  • O financiador deposita total_emission = emissions_per_second × (end_time − open_time) de token de recompensa no vault como parte desta instrução.
  • Mint de recompensa na whitelist conforme operation_state.

SetRewardParams

Estende, recarrega ou altera a taxa de emissão de um fluxo de recompensa existente. Normalmente chamado pelo criador do pool ou pelo multisig da Raydium. As restrições vivem on-chain: geralmente é possível estender end_time ou aumentar as emissões, mas não reduzi-las retroativamente. Verifique a lista de donos de operation_state.

UpdateRewardInfos

Pura contabilidade — liquida reward_growth_global_x64 até o momento atual multiplicando emissions_per_second × Δt / liquidity. Chamada internamente por todas as instruções que tocam liquidez. Exposta como instrução autônoma porque agentes externos (UIs, cranks) às vezes querem acioná-la diretamente.

CollectReward

O dono da posição reivindica os tokens de recompensa devidos. Contas Efeito
  • Liquida o crescimento de recompensas (mesmo padrão das taxas).
  • Transfere o valor devido para a ATA destinatária e zera reward_amount_owed[i].

Matriz de mudanças de estado

Próximos passos

Fontes: