Matemática do CPMM

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

O invariante

O CPMM mantém o invariante clássico de produto constante em seus dois vaults:

x \cdot y = k

onde x é o saldo do vault0 após qualquer taxa de transferência Token-2022 no recebimento, e similarmente para y. Cada swap deve deixar k' ≥ k após contabilizar as taxas de negociação creditadas ao LP (os buckets de protocolo, fundo e criador não são contados em k — ficam no vault mas são excluídos da visualização da curva, veja Taxas na curva abaixo). k portanto cresce monotonicamente ao longo do tempo conforme os LPs acumulam taxas. As cotas de LP são precificadas pelas reservas do pool, não por k:

\text{Preço de LP em token0} = \frac{x}{\text{lpSupply}}, \qquad \text{Preço de LP em token1} = \frac{y}{\text{lpSupply}}

Queimar ΔLP tokens de LP retorna exatamente ΔLP × x / lpSupply de token0 e ΔLP × y / lpSupply de token1. Nem a curva nem k se movem em depósito ou saque — apenas swaps alteram o preço.

Modelo de taxa no caminho de swap

O CPMM aplica duas taxas independentemente classificadas em cada swap:

A taxa de negociação é cobrada no lado de entrada, com taxa de AmmConfig.trade_fee_rate. Ela é então dividida em cotas de LP, protocolo e fundo (a cota de LP permanece no vault e cresce k; as cotas de protocolo e fundo são extraídas da contabilidade do vault).
A taxa de criador (ativa apenas quando enable_creator_fee == true) é cobrada em AmmConfig.creator_fee_rate. É cobrada no lado de entrada ou no lado de saída dependendo de PoolState.creator_fee_on e da direção do swap (veja products/cpmm/fees). É seu próprio bucket — nunca uma fatia da taxa de negociação.

A cota do protocolo da taxa de criador não aparece em nenhum lugar nesta página, e isso é deliberado. É aplicada quando CollectCreatorFee move taxas acumuladas entre dois contadores que a curva já exclui — não durante um swap. A matemática de swap, cotações e k são idênticas com e sem ela. Veja products/cpmm/fees.

Seja:

FEE_RATE_DENOMINATOR = 1_000_000
trade_fee_rate — de AmmConfig, ex., 2500 = 0,25% do lado de volume relevante
creator_fee_rate — de AmmConfig, ex., 1000 = 0,10% do lado de volume relevante
protocol_fee_rate, fund_fee_rate — denominados em unidades de 1/FEE_RATE_DENOMINATOR da taxa de negociação, não do volume

Quando a taxa de criador está no lado de entrada:

total_input_fee = ceil(amount_in * (trade_fee_rate + creator_fee_rate) / FEE_RATE_DENOMINATOR)
creator_fee     = floor(total_input_fee * creator_fee_rate / (trade_fee_rate + creator_fee_rate))
trade_fee       = total_input_fee - creator_fee
amount_in_after_fees = amount_in - total_input_fee

Quando a taxa de criador está no lado de saída:

trade_fee            = ceil(amount_in * trade_fee_rate / FEE_RATE_DENOMINATOR)
amount_in_after_fees = amount_in - trade_fee
amount_out_curve     = curve_output(amount_in_after_fees, ...)
creator_fee          = ceil(amount_out_curve * creator_fee_rate / FEE_RATE_DENOMINATOR)
amount_out           = amount_out_curve - creator_fee

Em ambos os casos a taxa de negociação é dividida da mesma forma:

protocol_fee   = floor(trade_fee * protocol_fee_rate / FEE_RATE_DENOMINATOR)
fund_fee       = floor(trade_fee * fund_fee_rate     / FEE_RATE_DENOMINATOR)
lp_fee         = trade_fee - protocol_fee - fund_fee     // creator_fee NÃO é subtraído aqui

O montante protocol_fee + fund_fee + creator_fee é mantido nos vaults mas rastreado separadamente no estado do pool (protocol_fees_token*, fund_fees_token*, creator_fees_token*). Quando a verificação do invariante de produto constante verifica k' ≥ k, ela usa saldos do vault menos todas as três taxas acumuladas mas não coletadas — então os LPs capturam apenas lp_fee. Veja products/cpmm/fees para as instruções de coleta e exemplos numéricos trabalhados.

SwapBaseInput (entrada exata)

“O usuário nos dá exatamente amount_in do mint de entrada e recebe pelo menos minimum_amount_out do mint de saída.” Ignorando Token-2022 por um momento:

amount_in_after_trade_fee = amount_in - trade_fee
amount_out                = y − (x * y) / (x + amount_in_after_trade_fee)

Por álgebra:

\text{amount\_out} = \frac{y \cdot \Delta x_{\text{net}}}{x + \Delta x_{\text{net}}}

onde Δx_net = amount_in_after_trade_fee. O programa então atualiza a contabilidade do vault de forma que a porção de trade_fee devida ao protocolo/fundo/criador fica em buckets “acumulados” (não incluídos no próximo x da curva), enquanto a cota de LP se junta a x para o próximo swap.

Token-2022 no lado de entrada

Se o mint de entrada tem uma extensão de taxa de transferência, o mint deduz sua taxa na transferência de usuário → vault. Então o vault realmente recebe amount_in − transfer_fee_in(amount_in). O programa CPMM portanto computa:

amount_actually_received = amount_in − transfer_fee_in(amount_in)
trade_fee                = ceil(amount_actually_received * trade_fee_rate / FEE_RATE_DENOMINATOR)
amount_in_after_trade_fee = amount_actually_received − trade_fee

e executa a curva contra amount_in_after_trade_fee. Isso importa porque o preço da curva é computado do montante líquido que chegou ao vault, não do montante de manchete do usuário.

Token-2022 no lado de saída

Se o mint de saída tem uma taxa de transferência, o pool envia amount_out de seu vault para o usuário. O mint então vai descontar sua taxa no caminho, então o usuário recebe amount_out − transfer_fee_out(amount_out). O programa computa amount_out da curva como usual, mas é responsabilidade do integrador converter o número de “envio do vault” do pool em um número de “recebimento do usuário” ao mostrar cotações.

Verificação de slippage

Após computar amount_out:

require(amount_out >= minimum_amount_out, "AmountSpecifiedLessThanMinimum")

Se o mint de saída cobra uma taxa de transferência, o SDK aplica a taxa de transferência antes de definir minimum_amount_out para que a constante de slippage seja denominada no que o usuário realmente receberá, não no que o vault envia.

SwapBaseOutput (saída exata)

“O usuário receberá exatamente amount_out do mint de saída e está disposto a pagar até maximum_amount_in do mint de entrada.” Invertendo a curva para Δx_net:

\Delta x_{\text{net}} = \left\lceil \frac{x \cdot \text{amount\_out}}{y - \text{amount\_out}} \right\rceil

O teto é importante — garante k' ≥ k após truncamento inteiro. Então:

// Trabalhe para trás do net in para o gross in.
// taxa é aplicada no gross, então:
//   net = gross − ceil(gross * rate / D)
//       ≈ gross * (D − rate) / D
// invertendo com teto nos lugares certos:
gross_needed = ceil(Δx_net * D / (D − trade_fee_rate))

Em Token-2022 de entrada, envolva com:

gross_needed_before_mint_fee
  = inflate_for_transfer_fee(gross_needed, input_mint)

para que o usuário pague o suficiente para que após a dedução de taxa de transferência do mint o pool ainda receba gross_needed.

Verificação de slippage

require(gross_needed_before_mint_fee <= maximum_amount_in, "AmountSpecifiedExceedsMaximum")

Exemplo trabalhado

Estado do pool, ignorando Token-2022:

x = 1_000_000_000_000 (1.000.000,000000 de token0, 6 decimais)
y = 2_000_000_000_000 (2.000.000,000000 de token1, 6 decimais)
AmmConfig: trade_fee_rate = 2500, protocol_fee_rate = 120_000, fund_fee_rate = 40_000, creator_fee_rate = 0

Usuário: SwapBaseInput com amount_in = 1_000_000_000 (1.000,000000 de token0). Taxa de criador desabilitada (enable_creator_fee = false).

trade_fee                = ceil(1_000_000_000 * 2500 / 1_000_000)       = 2_500_000
  protocol_fee           = floor(2_500_000 * 120_000 / 1_000_000)       = 300_000
  fund_fee               = floor(2_500_000 *  40_000 / 1_000_000)       = 100_000
  lp_fee                 = 2_500_000 − 300_000 − 100_000                 = 2_100_000
creator_fee              = 0                                              // desabilitada

amount_in_after_trade_fee = 1_000_000_000 − 2_500_000                    = 997_500_000

amount_out = y − (x * y) / (x + Δx_net)
           = 2_000_000_000_000
             − (1_000_000_000_000 * 2_000_000_000_000)
               / (1_000_000_000_000 + 997_500_000)
           = 1_993_011_971

new_vault0_raw   = x + amount_in                                        = 1_001_000_000_000
new_vault1       = y − amount_out                                       = 1_998_006_988_029

// Dos 1_000_000_000 recebidos em vault0, 400_000 é "taxa acumulada"
// (protocolo + fundo) que a curva deve excluir:
curve_x          = new_vault0_raw − (protocol_fees_token0 + fund_fees_token0)
                 = 1_001_000_000_000 − 400_000
                 = 1_000_999_600_000

k' = curve_x * new_vault1 ≈ 2.000_004_196_E24  ≥  k = 2.0E24   ✓

Se o mesmo pool tivesse enable_creator_fee = true com creator_fee_rate = 1000 (0,10%) no lado de entrada, o programa cobraria total_input_fee = ceil(1_000_000_000 * 3500 / 1_000_000) = 3_500_000, então dividiria como creator_fee = 1_000_000 e trade_fee = 2_500_000. A aritmética de protocolo/fundo/LP em trade_fee é inalterada do exemplo acima — a taxa de criador é seu próprio bucket, acumulada em creator_fees_token0 e excluída de curve_x junto com os buckets de protocolo e fundo. Se o mint de entrada tem uma taxa de transferência Token-2022 de 1%, o vault recebe 990_000_000 tokens em vez de 1_000_000_000, e cada cálculo subsequente usa esse montante líquido.

Regra de atualização de observação

Em cada swap, o programa avalia se deve enviar uma nova observação para o buffer de anel:

let since_last = now − observations[head].block_timestamp;
if since_last >= MIN_OBSERVATION_INTERVAL {
    let price0 = (vault1 << 32) / vault0;            // Q32.32-ish
    let price1 = (vault0 << 32) / vault1;
    let head' = (head + 1) % OBSERVATION_NUM;
    observations[head'] = Observation {
        block_timestamp: now,
        cumulative_token0_price_x32:
            observations[head].cumulative_token0_price_x32 + price0 * since_last,
        cumulative_token1_price_x32:
            observations[head].cumulative_token1_price_x32 + price1 * since_last,
    };
    head = head';
}

Duas propriedades:

Preço cumulativo, não preço spot. Uma única observação não é um preço. Para obter um TWAP do tempo t0 para t1, leia as observações mais próximas de cada extremidade e compute (cumulative(t1) − cumulative(t0)) / (t1 − t0).
Amostras são limitadas por taxa. Swaps consecutivos no mesmo slot podem compartilhar uma observação. Ler uma observação imediatamente após um swap pode portanto parecer obsoleta por um slot — isso é normal.

Mais em products/clmm/accounts.

Taxas na curva

Esta é a parte sutil e vale a pena chamar atenção. A aritmética da curva funciona contra os saldos líquidos do vault — ou seja, saldo SPL bruto menos taxas acumuladas de protocolo, fundo e criador (todos os três são buckets independentes — veja products/cpmm/fees). Uma imagem concreta:

raw_vault_balance   = o que um getTokenAccountBalance de RPC retorna
accrued_fees        = protocol_fees_token{0,1} + fund_fees_token{0,1} + creator_fees_token{0,1}
curve_balance       = raw_vault_balance − accrued_fees
invariant           = curve_balance0 * curve_balance1

Consequências para integradores:

Não cite de saldos brutos. Subtraia os campos de taxa acumulada primeiro, ou chame SwapBaseInput como uma simulação e pegue seu retorno.
CollectProtocolFee move tokens para fora do vault. Após coleta, raw_vault_balance cai mas curve_balance permanece inalterado; o preço do pool não se move. Isso é deliberado.

Precisão e overflow

Toda aritmética de curva usa intermediários u128 para prevenir overflow em x * y.
Divisão arredonda para zero exceto para Δx_net de SwapBaseOutput, que arredonda para cima, e computação de taxa, que arredonda para cima em trade_fee e para baixo nas sub-divisões. Essas direções de arredondamento são escolhidas para que o invariante nunca diminua devido a truncamento inteiro.
Pools com proporções de vault extremas (bilhões : 1) podem atingir pisos de precisão em pequenos trades; o programa retorna ZeroTradingTokens nesse caso. Veja reference/error-codes.

Próximos passos

products/cpmm/fees — a semântica completa de tier de taxa e coleta.
products/cpmm/instructions — as instruções que invocam essa matemática.
algorithms/constant-product — a derivação e casos extremos de x · y = k compartilhados entre AMM v4 e CPMM.

Fontes:

raydium-io/raydium-cp-swap — matemática de swap em states/curve.rs
Relatórios de auditoria do Raydium vinculados em security/audits

Products

Algorithms

O invariante

Modelo de taxa no caminho de swap

SwapBaseInput (entrada exata)

Token-2022 no lado de entrada

Token-2022 no lado de saída

Verificação de slippage

SwapBaseOutput (saída exata)

Verificação de slippage

Exemplo trabalhado

Regra de atualização de observação

Taxas na curva

Precisão e overflow

Próximos passos

​O invariante

​Modelo de taxa no caminho de swap

​SwapBaseInput (entrada exata)

​Token-2022 no lado de entrada

​Token-2022 no lado de saída

​Verificação de slippage

​SwapBaseOutput (saída exata)

​Verificação de slippage

​Exemplo trabalhado

​Regra de atualização de observação

​Taxas na curva

​Precisão e overflow

​Próximos passos

O invariante

Modelo de taxa no caminho de swap

SwapBaseInput (entrada exata)

Token-2022 no lado de entrada

Token-2022 no lado de saída

Verificação de slippage

SwapBaseOutput (saída exata)

Verificação de slippage

Exemplo trabalhado

Regra de atualização de observação

Taxas na curva

Precisão e overflow

Próximos passos