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
Pré-condições
token_mint_0 < token_mint_1por 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.
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
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_ondefinido para a varianteCollectFeeOnescolhida.- Se a taxa dinâmica foi habilitada:
pool_state.dynamic_fee_infoé inicializado a partir doDynamicFeeConfigfornecido (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
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 depool.tick_spacing, dentro de[MIN_TICK, MAX_TICK].- Tick arrays necessários passados e inicializados (ou criados aqui via CPI
InitTickArrayna transação). - O usuário tem pelo menos
amount_0_maxeamount_1_maxnas ATAs de origem.
personal_positionexiste,liquiditydefinido,fee_growth_inside_lastcom snapshot capturado.- Entradas de tick-array em
tick_loweretick_upperatualizadas (liquidity_gross += L,liquidity_net ± L, snapshots de crescimento de taxa mantidos). pool_state.liquidity += Lse a posição estiver no intervalo (tick_lower ≤ tick_current < tick_upper).
InvalidTickIndex, NotApproved, ZeroAmountSpecified, TransactionTooLarge (se houver tick arrays demais).
IncreaseLiquidityV2
Adiciona liquidez a uma posição já aberta.
Argumentos
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_actualdo usuário para os vaults. - Incrementa
personal_position.liquidityepool_state.liquidity(se estiver no intervalo), além dos valoresliquidity_gross/liquidity_netdos 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 emDecreaseLiquidityouCollectReward, não no aumento.
DecreaseLiquidityV2
Remove liquidez de uma posição.
Argumentos
IncreaseLiquidity.
Efeito
- Calcula
(amount_0, amount_1)para oLremovido com base nosqrt_price_x64atual. - Liquida as taxas/recompensas acumuladas desde o último toque, da mesma forma que
IncreaseLiquidity. - Transfere
amount_0 + fees_owed_0eamount_1 + fees_owed_1dos vaults para o usuário. - Decrementa os contadores de liquidez; se o novo
personal_position.liquidity == 0, a posição é elegível paraClosePosition.
amount_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.
- Queima o NFT.
- Fecha a conta do mint do NFT e a conta
personal_position, devolvendo o rent aopayer.
SwapV2
Percorre a curva de liquidez; entrada exata ou saída exata, dependendo de is_base_input.
Argumentos
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.statuspermite swap.now >= open_time.sqrt_price_limit_x64está no lado correto desqrt_price_x64para a direção escolhida.
ExceededSlippage, SqrtPriceLimitOverflow, TickArrayNotFound, LiquidityInsufficient.
O que SwapV2 faz internamente e que os chamadores devem saber (versão pós-2025):
- Sobretaxa dinâmica — se
pool.dynamic_fee_infofor 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 deproducts/clmm/fees) e adiciona umdynamic_fee_componentsobreAmmConfig.trade_fee_rate. A taxa total é limitada a 10% (MAX_FEE_RATE_NUMERATOR / 1_000_000). - 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 atualizamtick.unfilled_ratio_x64etick.part_filled_orders_remainingpara liquidação posterior; as próprias ordens permanecem pendentes até que o dono chameSettleLimitOrder. - Roteamento de taxa unilateral — quando
pool.fee_on = Token0OnlyouToken1Only, 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 recebeout − fee); para direções em que é a entrada, o comportamento é igual aoFromInput. Vejais_fee_on_input(zero_for_one)eis_fee_on_token0(zero_for_one)emPoolState.
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
Pré-condições
tick_index % pool.tick_spacing == 0e dentro de[MIN_TICK, MAX_TICK].tick_indexestá no lado correto depool.tick_currentpara 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.statuspermite a operação de ordem limitada (bit 5).
limit_orderexiste, com snapshot detick.order_phaseetick.unfilled_ratio_x64no momento da abertura.tick.orders_amount += amount(no coorte atual).limit_order_nonce.order_nonce += 1.- Evento
OpenLimitOrderEventemitido.
InvalidLimitOrderAmount (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
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 chamarDecreaseLimitOrderouSettleLimitOrderprimeiro para avançar.
- Transfere
amountda ATA do dono parainput_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
Efeito
- Recalcula o valor preenchido da ordem a partir do
unfilled_ratio_x64do coorte desde a abertura. - Envia a saída preenchida para
output_token_account. - Envia
amountda entrada não preenchida de volta parainput_token_account. - Atualiza
limit_orderconforme necessário. Se o novo saldo não preenchido for zero, o programa fecha a conta e devolve o rent aoowner.
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_amountfoi preenchido e liquidado, seja porque o dono reduziu anteriormente a ordem para zero e não a fechou).
- Fecha
limit_order; o rent é enviado paralimit_order.owner.
CreateDynamicFeeConfig (admin)
Cria um conjunto de parâmetros reutilizável sob um índice u16.
Argumentos
Erros comuns —
InvalidDynamicFeeConfigParams 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
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
products/clmm/code-demos— exemplos TypeScript executáveis.products/clmm/fees— detalhes sobre acúmulo de taxas e recompensas.reference/error-codes— tabela completa de erros Anchor do CLMM.
raydium-io/raydium-clmm—programs/amm/src/instructions- Raydium SDK v2 —
@raydium-io/raydium-sdk-v2

