Instruções AMM v4

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

A partir da atualização do programa 2026-07, a dependência OpenBook / Serum do AMM v4 foi removida. As instruções legadas v1 SwapBaseIn / SwapBaseOut, Deposit e Withdraw mantêm seus layouts de conta antigos para compatibilidade com versões anteriores: as contas de mercado ainda são aceitas em suas posições antigas, mas não são mais validadas ou usadas (nenhum CPI é emitido). Novas integrações devem usar os pontos de entrada de swap V2, que omitem completamente as contas de mercado. Várias instruções foram removidas e agora revertidas — veja a entrada do changelog. As listas de contas abaixo usam os nomes de campo do SDK Raydium; o IDL subjacente às vezes usa prefixos serum_*.A atualização do programa 2026-09 adiciona uma instrução de admin, WithdrawExcessLamports (tag 18), e remove a sysvar de rent de CreateConfigAccount. Tudo o que um trader ou LP chama permanece inalterado. Veja a entrada do changelog 2026-09-09.

Inventário de instruções

Grupo	Instrução	tag	Notas
Ciclo de vida do pool	`Initialize2`	1	Única instrução de criação de pool (UI padrão para CPMM em novos pools).
Liquidez	`Deposit`	3	Adicionar liquidez, receber LP. Layout inalterado (contas de mercado ignoradas).
Liquidez	`Withdraw`	4	Queimar LP, receber ambos os lados pro-rata. Layout inalterado (contas de mercado ignoradas).
Swap	`SwapBaseIn`	9	Swap de entrada exata. Layout v1 inalterado; contas de mercado aceitas mas ignoradas.
Swap	`SwapBaseOut`	11	Swap de saída exata. Igual ao anterior.
Swap	`SwapBaseInV2`	16	Recomendado. Swap de entrada exata sem as contas de mercado.
Swap	`SwapBaseOutV2`	17	Recomendado. Swap de saída exata sem as contas de mercado.
Manutenção	`SetParams`	6	Admin: alterar parâmetros do pool. Layout + valores de `param` alterados (quebra compatibilidade).
Manutenção	`WithdrawPnl`	7	Varrer PnL de protocolo acumulado. Layout de conta alterado (quebra compatibilidade).
Manutenção	`CreateConfigAccount`	14	Admin: inicializar o PDA `AmmConfig` em nível de programa.
Manutenção	`UpdateConfigAccount`	15	Admin: alterar parâmetros de config em nível de programa.
Manutenção	`WithdrawExcessLamports`	18	Admin: varrer lamports acima do mínimo isento de rent de contas controladas pelo programa. Adicionado em 2026-09.

O SDK expõe builders apenas para as instruções voltadas ao usuário. Instruções de manutenção são tipicamente invocadas pelo keeper Raydium. Removidas / não mais chamáveis (seus builders de cliente foram deletados): Initialize (tag 0, use Initialize2), MonitorStep (2), MigrateToOpenBook (5), WithdrawSrm (8), PreInitialize (10, use Initialize2), SimulateInfo (12), AdminCancelOrders (13). Uma transação carregando uma dessas tags falha; o programa nunca executa a instrução. Trate todos os sete como desaparecidos em vez de caminhos de erro a serem tratados.

`Initialize2`

Inicializar um novo pool AMM v4 vinculado a um mercado OpenBook existente. Argumentos

nonce:        u8
open_time:    u64
init_pc_amount:   u64
init_coin_amount: u64

Contas (gravável W, signatário S)

#	Nome	W	S	Notas
1	`token_program`			Verificado `== spl_token::id()`.
2	`associated_token_program`			Usado para criar a ATA de LP do criador.
3	`system_program`
4	`rent`			Ainda encaminhada para os CPIs `initialize_account` / `initialize_mint` — não a remova.
5	`amm`	W		PDA `AmmInfo` `[programId, market, "amm_associated_seed"]`; criada aqui.
6	`amm_authority`			PDA `["amm authority"]`; o argumento `nonce` deve ser igual ao seu bump.
7	`lp_mint`	W		PDA `[programId, market, "lp_mint_associated_seed"]`; criado aqui.
8	`coin_mint`			Deve ser diferente de `pc_mint` (`InvalidCoinMint`).
9	`pc_mint`
10	`pool_coin_token_account`	W		PDA `[programId, market, "coin_vault_associated_seed"]`.
11	`pool_pc_token_account`	W		PDA `[programId, market, "pc_vault_associated_seed"]`.
12	`pool_target_orders_account`	W		PDA `[programId, market, "target_associated_seed"]`.
13	`amm_config`			PDA de configuração de nível de programa `["amm_config_account_seed"]`; `InvalidConfigAccount` em caso de incompatibilidade.
14	`create_fee_destination`	W		Deve ser igual a `config_feature::create_pool_fee_address`; `InvalidFee` caso contrário.
15	`market`			Não validado — usado apenas como a seed variável para cada PDA acima, e armazenado como campo de referência.
16	`user_wallet`	W	S	Criador. Paga rent, a taxa de criação de pool e o depósito inicial.
17	`user_token_coin`	W
18	`user_token_pc`	W
19	`user_token_lp`	W		ATA de LP do criador; criada pelo programa.

Dois layouts aceitos. A lista de 19 contas acima é a recomendada. Por compatibilidade retroativa o programa também lê um layout legado de 21 contas, que insere um amm_open_orders ignorado na posição 7 e um market_program ignorado na posição 16 — é isso que o construtor de instruções initialize2 no repositório ainda emite. Qualquer outro comprimento é analisado posicionalmente contra o layout legado e vai falhar.

Pós-condições

LP mintado para o criador = sqrt(init_coin_amount × init_pc_amount) − 10^coin_mint.decimals. Os decimais de LP são iguais a coin_mint.decimals, portanto a quantia subtraída é exatamente um token LP inteiro; ele nunca é mintado e fica permanentemente fora de circulação. Se sqrt(...) for menor que isso, a instrução reverte com InitLpAmountTooLess.
AmmInfo.lp_amount armazena o sqrt(...) completo, não a quantia mintada — portanto lp_mint.supply fica permanentemente um token LP inteiro abaixo de amm.lp_amount. Toda a matemática pro-rata usa amm.lp_amount.
Nenhuma ordem OpenBook é postada (a grade de livro de ordens foi removida). AmmInfo.market registra a conta passada no slot 15, mas AmmInfo.open_orders e AmmInfo.market_program são ambos escritos como Pubkey::default(), e coin_lot_size / pc_lot_size / min_size são inicializados para 0. No layout legado de 21 contas, as contas extras amm_open_orders e market_program são lidas e descartadas.

Erros comuns — InvalidCoinMint (mints coin e pc idênticos), InvalidConfigAccount (PDA amm_config errado), InvalidFee (destino errado da taxa de criação de pool), InvalidProgramAddress (amm_authority errado ou nonce errado), RepeatCreateAmm (já existe um pool para este mercado), InitLpAmountTooLess, InvalidSupply (uma das quantias iniciais é 0, ou o mint de LP já tem suprimento), AlreadyInUse.

`Deposit`

Adicionar liquidez. Argumentos

max_coin_amount: u64
max_pc_amount:   u64
base_side:       u64    // 0 = base em coin, 1 = base em pc
// (algumas variantes do SDK também aceitam other_amount_min)

Contas (abreviado)

#	Nome	W	S
1	`token_program`
2	`amm`	W
3	`amm_authority`
4	`amm_target_orders`	W
5	`lp_mint`	W
6	`pool_coin_token_account`	W
7	`pool_pc_token_account`	W
8	`user_coin_token_account`	W
9	`user_pc_token_account`	W
10	`user_lp_token_account`	W
11	`user_owner`		S

As contagens aceitas são 11, 14 ou 15 — nada mais. O layout legado tem 14 contas (ou 15 com uma conta ignorada ao final): a mesma lista com um amm_open_orders ignorado na posição 4, um market ignorado na posição 9, e um market_event_queue ignorado acrescentado na posição 14. Qualquer outra contagem reverte com WrongAccountsNumber.

Matemática — pro-rata padrão. Usando as reservas efetivas do pool (vaults + em livro), o SDK calcula o par coin/pc que produz a quantidade de LP fornecida e verifica contra max_*. Reverte com ExceededSlippage se qualquer lado exceder o limite.

`Withdraw`

Queimar LP, receber ambos os lados. Argumentos

amount: u64    // LP a queimar

Contas — layout recomendado de 11 contas

#	Nome	W	S
1	`token_program`
2	`amm`	W
3	`amm_authority`
4	`amm_target_orders`	W
5	`lp_mint`	W
6	`pool_coin_token_account`	W
7	`pool_pc_token_account`	W
8	`user_lp_token_account`	W
9	`user_coin_token_account`	W
10	`user_pc_token_account`	W
11	`user_owner`		S

Withdraw não é Deposit invertido. As contagens aceitas são 11, ou de 20 a 23. O layout legado de 20 contas coloca a conta de LP do usuário antes das duas ATAs receptoras e intercala cinco contas de mercado ignoradas:

token_program, amm(W), amm_authority, amm_open_orders(W), amm_target_orders(W), lp_mint(W), pool_coin_token_account(W), pool_pc_token_account(W), market_program, market(W), market_coin_vault(W), market_pc_vault(W), market_vault_signer, user_lp_token_account(W), user_coin_token_account(W), user_pc_token_account(W), user_owner(S), market_event_queue(W), market_bids(W), market_asks(W)

. As formas de 22 e 23 contas inserem duas contas de padding ignoradas depois da posição 8. Qualquer outra contagem reverte com WrongAccountsNumber.

Não há mais nenhuma etapa de settle-from-OpenBook — a matemática pro-rata usa os saldos de vault diretamente.

`SwapBaseIn`

Swap de entrada exata. Sempre um swap de caminho AMM (não roteia através de matching OpenBook).

Use as variantes V2 para novo código. Como a dependência OpenBook do AMM v4 foi removida, os pontos de entrada V1 (SwapBaseIn, SwapBaseOut) ainda esperam a lista completa de 17 contas (ou 18 com a conta target-orders opcional), mas as contas OpenBook/market agora são aceitas posicionalmente e ignoradas — não são validadas e nenhum CPI é emitido. Passar uma contagem de conta errada ainda reverte com WrongAccountsNumber, mas o conteúdo das contas de mercado não é mais verificado. Novas integrações devem usar SwapBaseInV2 / SwapBaseOutV2, que usam uma lista de contas muito menor e representam o caminho de execução canônico hoje. Os formulários V1 são documentados aqui para completude e para ler transações on-chain existentes.

Argumentos

amount_in:            u64
minimum_amount_out:   u64

Contas (abreviado)

#	Nome	W	S
1	`token_program`
2	`amm`	W
3	`amm_authority`
4	`amm_open_orders`	W
5	`amm_target_orders`	W
6	`pool_coin_token_account`	W
7	`pool_pc_token_account`	W
8	`market_program`
9	`market`	W
10	`market_bids`	W
11	`market_asks`	W
12	`market_event_queue`	W
13	`market_coin_vault`	W
14	`market_pc_vault`	W
15	`market_vault_signer`
16	`user_source_token_account`	W
17	`user_dest_token_account`	W
18	`user_owner`		S

Matemática — veja products/amm-v4/math. Pré-condições

AmmStatus::from_u64(amm.status).swap_permission() é verdadeiro — isto é, status é 1 (Initialized), 6 (SwapOnly) ou 7 (WaitingTrade). status é um valor de enum, não uma bitmask; veja products/amm-v4/accounts.
amm.state_data.pool_open_time <= now.
amount_in > 0.
user_source_token_account contém pelo menos amount_in.

Pós-condições

Usuário perde amount_in do token de origem, ganha amount_out ≥ minimum_amount_out do token de destino.
A taxa de swap permanece nos vaults, elevando o invariante k. Os contadores need_take_pnl_* não são tocados pelos swaps — o PnL de protocolo é recalculado a partir do delta de k no próximo Deposit, Withdraw ou WithdrawPnl (Processor::calc_take_pnl).
Nota: os contadores de análise state_data.swap_*_in_amount / swap_*_out_amount não são mais atualizados — seus valores estão congelados. Use logs de trade para análise de volume.

Erros comuns — ExceededSlippage, InvalidInput, InvalidStatus, NotAllowed (mint coin/pc idêntico).

`SwapBaseOut`

Saída exata, inverso de SwapBaseIn. Mesmas contas. Argumentos

max_amount_in: u64
amount_out:    u64

`SwapBaseInV2` / `SwapBaseOutV2`

Pontos de entrada de swap variantes (tags 16 / 17) que pulam completamente as contas OpenBook. A matemática é idêntica ao caminho V1, mas a lista de contas encolhe para apenas o lado AMM e o usuário — 8 contas, e amm_open_orders não é passado:

#	Nome	W	S
1	`token_program`
2	`amm`	W
3	`amm_authority`
4	`pool_coin_token_account`	W
5	`pool_pc_token_account`	W
6	`user_source_token_account`	W
7	`user_dest_token_account`	W
8	`user_owner`		S

As reservas do pool agora são os saldos de vault (menos PnL pendente), então a matemática de quote é direta e idêntica ao caminho v1. Use V2 para economizar compute e evitar passar as contas de mercado (agora ignoradas). O roteador Raydium sempre usa a forma V2 ao rotear através do AMM v4. Os argumentos são os mesmos dos formulários V1 (amount_in / minimum_amount_out para SwapBaseInV2; max_amount_in / amount_out para SwapBaseOutV2).

`MonitorStep` e outras instruções removidas

Removidas — não mais chamáveis. A partir da atualização 2026-07, MonitorStep (tag 2) foi removida do programa e agora reverte (unimplemented!) se invocada. Seu builder de cliente também foi deletado. O mesmo se aplica a MigrateToOpenBook (5), WithdrawSrm (8), SimulateInfo (12), AdminCancelOrders (13), e os pontos de entrada legados de criação de pool Initialize (0) / PreInitialize (10) — use Initialize2 em vez disso.

Historicamente, MonitorStep acionava a interação OpenBook do pool: liquidava ordens preenchidas (movendo receitas dos vaults de mercado para os vaults de pool via CPI OpenBook), cancelava ordens obsoletas e postava novas ordens para fechar a lacuna entre target_orders e amm_open_orders. Com a dependência OpenBook removida, não há nada a acionar e a instrução desapareceu. Qualquer keeper ou integração que ainda a chame deve remover a chamada.

`WithdrawPnl` / `TakePnl`

Varredura de admin de taxas de protocolo acumuladas. Argumentos

WithdrawPnl não recebe argumentos; lê need_take_pnl_* e move exatamente esses valores.

Mudança quebra-compatibilidade (admin apenas). A lista de contas caiu de 17 (+1 opcional) para 10 — amm_open_orders e todas as seis contas de mercado foram removidas — sem nenhuma análise de compatibilidade. O layout antigo desalinha (antigo #5 era amm_open_orders, agora pool_coin_token_account) e falha com erros como InvalidCoinVault. Ferramentas de admin devem ser atualizadas.

Contas (novo layout de 10 contas)

#	Nome	W	S	Notas
1	`token_program`
2	`amm`	W
3	`amm_config`
4	`amm_authority`
5	`pool_coin_token_account`	W
6	`pool_pc_token_account`	W
7	`pnl_coin_token_account`	W		Destinatário.
8	`pnl_pc_token_account`	W
9	`pnl_owner`		S	Multisig de admin.
10	`amm_target_orders`	W

Efeito

Transfere need_take_pnl_coin de pool_coin_token_account para pnl_coin_token_account.
Mesmo para pc.
Zera need_take_pnl_coin e need_take_pnl_pc.
Mudança de lógica: se o saldo de vault for insuficiente para cobrir PnL acumulado, a instrução retorna TakePnlError diretamente (não manipula mais o estado do livro de ordens).

Nenhuma mudança nas reservas já que PnL acumulado já foi excluído do invariante.

`SetParams`

Mudanças de parâmetros de admin, chamadas pelo multisig Raydium. Os argumentos são uma tag param: u8 + payload.

Mudança quebra-compatibilidade (admin apenas). A lista de contas foi reduzida para apenas [amm (W), admin (S)] (a autoridade, open-orders, target-orders, vault e todas as contas de mercado foram removidas). O enum param foi renumerado e reduzido: Status = 0, State = 1, Fees = 2 (era 9), SetOpenTime = 3 (era 11). Todos os parâmetros de grade de livro de ordens e AmmOwner, LastOrderDistance, UpdateOpenOrder foram removidos, e a struct SetParamsInstruction removeu new_pubkey e last_order_distance. Ferramentas de admin devem ser atualizadas.

`CreateConfigAccount` / `UpdateConfigAccount`

Gerenciamento de admin do PDA AmmConfig em nível de programa (seed ["amm_config_account_seed"]). A conta contém exatamente três campos significativos — pnl_owner, cancel_owner e create_pool_fee — mais duas regiões reservadas de padding; não existe flag de criação de pool. UpdateConfigAccount define pnl_owner com param = 0, cancel_owner com param = 1, e create_pool_fee com param = 2.

Alterado em 2026-09, e compatível com versões anteriores. CreateConfigAccount não lê mais a sysvar de rent. Sua lista de contas agora é 4 contas, reduzida de 5:

#	Nome	W	S
1	`admin`	W	S
2	`amm_config`	W
3	`pnl_owner`
4	`system_program`

O programa lê parâmetros de rent de Rent::get() em vez de desserializar uma conta sysvar passada — o que a atualização de dependência Solana 3.0 tornou natural.A conta removida estava por último na lista, e o handler lê suas contas posicionalmente através de next_account_info sem verificação de comprimento. Uma ferramenta de admin existente que ainda passa a lista antiga de 5 contas portanto continua funcionando: a conta de rent à direita simplesmente nunca é lida. Atualize quando conveniente, não urgentemente. UpdateConfigAccount é inalterado.

Initialize2 mantém a sysvar de rent na posição 3, e ainda a usa: o programa parou de chamar Rent::from_account_info nela, mas ela ainda é encaminhada para os CPIs spl_token::initialize_account e initialize_mint que criam os vaults e mint de LP do pool. Não a remova da lista de contas.

`WithdrawExcessLamports`

Varredura de admin de lamports sentados acima do mínimo isento de rent em contas que o programa controla. Adicionado na atualização 2026-09 para recuperar o over-funding que a redução de rent SIMD-0437 deixa para trás em contas criadas antes de cada etapa. Move apenas o excesso. Saldos de token, dados de conta, proprietários e estado do pool não são tocados, e a instrução é um no-op em uma conta já em seu mínimo — então é seguro disparar repetidamente e novamente após cada etapa de rollout. Argumentos — nenhum. O payload é o byte de tag único 18. Contas

#	Nome	W	S	Notas
1	`collect_lamports`	W	S	Destino para cada lamport varrido. Deve ser igual à carteira collect-lamports do cluster — veja `reference/program-addresses`. Qualquer outro signatário falha com `InvalidSignAccount`.
2	`amm_authority`			O único PDA de autoridade AMM v4, re-derivado pelo programa de `["amm authority"]` com um nonce fixo de `254`. Assina os CPIs do programa de token.
3	`token_program`			SPL Token. Verificado contra `spl_token::id()`; um valor errado falha com `InvalidSplTokenProgram`.
4..	contas de origem	W		`M` contas a varrer, qualquer número, qualquer ordem.

Como cada conta de origem é tratada O programa despacha no owner da conta de origem:

Proprietário da conta de origem	Tratamento
SPL Token, `data_len == 165` (uma conta de token), não-nativa	CPI `WithdrawExcessLamports` (discriminante do programa de token `38`), assinado por `amm_authority`.
SPL Token, `data_len == 165`, nativa (wSOL)	`WithdrawExcessLamports` não pode ser usado em uma conta nativa. O programa faz CPI `SyncNative`, mede quanto o `amount` envolvido cresceu, `UnwrapLamports` (discriminante `45`) para exatamente esse delta, então afirma que o saldo envolvido volta ao seu valor pré-sync — caso contrário `LamportsCalculateError`. A liquidez SOL do pool portanto nunca é tocada.
SPL Token, qualquer outro tamanho (um mint de LP)	CPI `WithdrawExcessLamports`, assinado por `amm_authority`.
O próprio programa AMM v4 (`AmmInfo`, `TargetOrders`, `AmmConfig`)	O programa debita a conta diretamente até `rent.minimum_balance(data_len)`.
Qualquer outra coisa	Pulado silenciosamente. Sem erro, sem lamports movidos.

Erros comuns — InvalidSignAccount (signatário errado), InvalidSplTokenProgram (programa errado no slot 3), InvalidProgramAddress (amm_authority errado), LamportsCalculateError (código customizado 60; a volta redonda wSOL não resultou em zero), e InsufficientFunds do caminho controlado pelo programa quando uma conta contém menos que seu próprio mínimo de rent. Sem builder SDK. @raydium-io/raydium-sdk-v2 não fornece um builder para essa instrução, nem o repositório raydium-sdk-V2-demo — é um caminho de admin. Codifique manualmente, da forma que a varredura do lado da carteira em solana-fundamentals/rent-and-reclaimable-rent faz para a instrução do programa de token.

Matriz de mudança de estado

A coluna OpenBook desapareceu — nenhuma instrução toca um livro de ordens mais.

Instrução	Fornecimento de `lp_mint`	Vaults	Contadores de PnL
`Initialize2`	fornecimento init cunhado para criador	`+ init_coin_amount`, `+ init_pc_amount`	0
`Deposit`	+	+ ambos	—
`Withdraw`	−	− ambos	—
`SwapBaseIn` / `SwapBaseInV2`	—	+ entrada, − saída	— (realizado depois)
`SwapBaseOut` / `SwapBaseOutV2`	—	+ entrada, − saída	— (realizado depois)
`WithdrawPnl`	—	− (pnl varrido)	0
`SetParams`	—	—	—
`WithdrawExcessLamports`	—	— (saldos de token inalterados)	—

Próximos passos

products/amm-v4/code-demos — Exemplos TypeScript para fluxos de swap e LP.
products/amm-v4/fees — Detalhes de WithdrawPnl e a divisão de taxa.
reference/error-codes — Tabela de referência direta (erros AMM v4 estão listados nessa página).

Fontes:

Programa Raydium AMM — raydium-io/raydium-amm
Módulo Liquidity do Raydium SDK v2
Programa OpenBook — validações de conta no lado do mercado

Products

Algorithms

Inventário de instruções

`Initialize2`

`Deposit`

`Withdraw`

`SwapBaseIn`

`SwapBaseOut`

`SwapBaseInV2` / `SwapBaseOutV2`

`MonitorStep` e outras instruções removidas

`WithdrawPnl` / `TakePnl`

`SetParams`

`CreateConfigAccount` / `UpdateConfigAccount`

`WithdrawExcessLamports`

Matriz de mudança de estado

Próximos passos

​Inventário de instruções

​Initialize2

​Deposit

​Withdraw

​SwapBaseIn

​SwapBaseOut

​SwapBaseInV2 / SwapBaseOutV2

​MonitorStep e outras instruções removidas

​WithdrawPnl / TakePnl

​SetParams

​CreateConfigAccount / UpdateConfigAccount

​WithdrawExcessLamports

​Matriz de mudança de estado

​Próximos passos

Inventário de instruções

`Initialize2`

`Deposit`

`Withdraw`

`SwapBaseIn`

`SwapBaseOut`

`SwapBaseInV2` / `SwapBaseOutV2`

`MonitorStep` e outras instruções removidas

`WithdrawPnl` / `TakePnl`

`SetParams`

`CreateConfigAccount` / `UpdateConfigAccount`

`WithdrawExcessLamports`

Matriz de mudança de estado

Próximos passos