Contas 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 →

O AMM v4 é significativamente mais pesado em contas do que CPMM ou CLMM, pois toda operação toca no estado do OpenBook. Esta página agrupa as contas em seções “de propriedade do pool” e “de propriedade do OpenBook” para que um integrador veja rapidamente qual lado é qual.

Inventário

Um pool AMM v4 se vincula a exatamente um mercado OpenBook na criação. O quadro completo atual é:

Categoria	Conta	Proprietário	Função
Pool	`AmmInfo`	Programa AMM v4	Estado do pool: taxas acumuladas, status, referências para vaults e mercado OpenBook.
Pool	`amm_authority`	Programa AMM v4	PDA de propriedade do programa que assina movimentos de vault. Compartilhado entre todos os pools AMM v4.
Pool	`amm_open_orders`	OpenBook	A conta `OpenOrders` do pool no OpenBook para este mercado.
Pool	`amm_target_orders`	Programa AMM v4	Grid de ordens limite alvo do lado do pool para postar no OpenBook.
Pool	`pool_coin_token_account`	SPL Token	Vault do lado coin do pool (ATA de `amm_authority`).
Pool	`pool_pc_token_account`	SPL Token	Vault do lado pc do pool.
Pool	`lp_mint`	SPL Token	Mint de LP fungível.
Pool	`pool_withdraw_queue`	Programa AMM v4	Fila legada para saques atrasados; mantida com comprimento zero.
Pool	`pool_temp_lp`	Programa AMM v4	Conta LP auxiliar usada durante `Initialize`.
Mercado (OpenBook)	`serum_market`	OpenBook	O mercado em si (mints de base/quote, vault signer, etc.).
Mercado	`serum_bids`, `serum_asks`	OpenBook	As filas de ofertas e pedidos.
Mercado	`serum_event_queue`	OpenBook	Eventos pendentes (preenchimentos, cancelamentos).
Mercado	`serum_coin_vault`, `serum_pc_vault`	SPL Token	Vaults do nível de mercado do OpenBook.
Mercado	`serum_vault_signer`	OpenBook	PDA de nível de mercado que assina movimentos de `serum_*_vault`.

Nota: o prefixo “serum” é mantido no IDL e nomes de campos do AMM v4 para compatibilidade com versões anteriores. Ele se refere ao mercado OpenBook atualmente.

`AmmInfo`

A conta de estado raiz do pool. Grande (≈ 752 bytes) porque carrega referências de pool e OpenBook inline.

// programs/amm/src/state.rs (abreviado; ordem de campos / nomes seguem o IDL)
pub struct AmmInfo {
    pub status: u64,           // bitmask: swap/deposit/withdraw/crank enabled
    pub nonce:  u64,           // bump usado para derivar amm_authority
    pub order_num: u64,
    pub depth: u64,
    pub coin_decimals: u64,
    pub pc_decimals:   u64,
    pub state:         u64,    // máquina de estado interna
    pub reset_flag:    u64,
    pub min_size:      u64,
    pub vol_max_cut_ratio: u64,
    pub amount_wave: u64,
    pub coin_lot_size: u64,    // espelha mercado OpenBook
    pub pc_lot_size:   u64,
    pub min_price_multiplier: u64,
    pub max_price_multiplier: u64,
    pub sys_decimal_value: u64,

    pub fees: Fees,            // taxas de negociação/protocolo/fundo
    pub state_data: StateData,

    // Contas de propriedade do pool:
    pub coin_vault: Pubkey,
    pub pc_vault:   Pubkey,
    pub coin_vault_mint: Pubkey,
    pub pc_vault_mint:   Pubkey,
    pub lp_mint:  Pubkey,
    pub open_orders: Pubkey,   // OpenOrders do pool no OpenBook
    pub market: Pubkey,        // mercado OpenBook
    pub market_program: Pubkey, // ID do programa OpenBook
    pub target_orders: Pubkey,
    pub withdraw_queue: Pubkey,
    pub lp_vault:       Pubkey, // = pool_temp_lp
    pub owner: Pubkey,          // admin (multisig)
    pub lp_reserve: u64,
    pub padding: [u64; 3],
}

pub struct Fees {
    pub min_separate_numerator:   u64,     // 5
    pub min_separate_denominator: u64,     // 10_000
    pub trade_fee_numerator:      u64,     // 25  → usado pela integração OpenBook
    pub trade_fee_denominator:    u64,     // 10_000
    pub pnl_numerator:            u64,     // 12  → participação do protocolo DA taxa de swap
    pub pnl_denominator:          u64,     // 100 → então 12/100 = 12% da taxa, = 0.03% do volume
    pub swap_fee_numerator:       u64,     // 25  → 0.25% taxa de swap bruta
    pub swap_fee_denominator:     u64,     // 10_000
}

pub struct StateData {
    pub need_take_pnl_coin: u64,
    pub need_take_pnl_pc:   u64,
    pub total_pnl_pc:   u64,
    pub total_pnl_coin: u64,
    pub pool_open_time: u64,
    pub punish_pc_amount: u64,
    pub punish_coin_amount: u64,
    pub orderbook_to_init_time: u64,
    pub swap_coin_in_amount: u128,
    pub swap_pc_out_amount:  u128,
    pub swap_acc_pc_fee:    u64,
    pub swap_pc_in_amount:  u128,
    pub swap_coin_out_amount: u128,
    pub swap_acc_coin_fee:  u64,
}

Campos voltados para integradores:

coin_vault, pc_vault — os vaults SPL Token do pool. coin é token_0 por convenção Serum/OpenBook (base), pc é token_1 (quote).
coin_decimals, pc_decimals — correspondendo aos mints.
open_orders, target_orders, market — devem ser passados para toda instrução de swap/deposit/withdraw.
fees.swap_fee_numerator / swap_fee_denominator — a taxa de negociação combinada. Padrão 25 / 10_000 = 0.25%.
status — bitmask controlando operações. Configurável por admin via AdminSetStatus.
state_data.need_take_pnl_* — delta entre taxas brutas acumuladas e o que foi varrido. TakePnl zera estes.

A fiação OpenBook

Não está mais ativa. Pools AMM v4 não compartilham mais liquidez com OpenBook — a grid de ordens de limite foi desativada. As contas OpenBook descritas nesta seção permanecem no AmmInfo de cada pool e ainda são validadas pelos endpoints de swap V1 (e por Initialize, Deposit, Withdraw) para compatibilidade com versões anteriores, mas o estado on-book que elas referenciam está vazio na prática. Use os endpoints de swap V2 (SwapBaseInV2 / SwapBaseOutV2) que pulam completamente essas contas e representam o caminho de execução canônico atualmente.

Quando você chama qualquer instrução de leitura ou escrita V1 em um pool AMM v4, deve passar as contas OpenBook. O programa re-deriva e as valida, então passar um conjunto incompatível reverte. (As variantes de swap V2 não exigem essas contas de todo.)

const market = ...;  // PublicKey do mercado OpenBook

// Campos que OpenBook expõe em sua conta de mercado:
const marketDecoded = OpenBookMarket.decode(marketAccountData);
const {
  bids:           serumBids,
  asks:           serumAsks,
  eventQueue:     serumEventQueue,
  requestQueue:   serumRequestQueue,
  baseVault:      serumCoinVault,
  quoteVault:     serumPcVault,
  vaultSignerNonce,
} = marketDecoded;

const serumVaultSigner = PublicKey.createProgramAddressSync(
  [market.toBuffer(), u64ToBytes(vaultSignerNonce)],
  OPENBOOK_PROGRAM_ID,
);

O amm_open_orders do AMM é uma conta de propriedade do OpenBook contendo o estado de ordem limite do pool neste mercado: ordens ativas, saldos liquidados, referenciadores, etc. amm_target_orders é do lado do AMM: contém a grid pretendida do AMM (preço/tamanho para cada slot de ordem) para que o programa possa comparar barato com o que está atualmente postado e colocar/cancelar o diff.

PDAs de Autoridade

Há exatamente um PDA amm_authority para todo o programa AMM v4. Sua seed é trivial (["amm authority"]) e seu bump é armazenado em cada AmmInfo. Esta autoridade assina todos os movimentos de token para todos os pools AMM v4.

const AMM_V4_PROGRAM_ID = new PublicKey(
  "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
);
const [ammAuthority] = PublicKey.findProgramAddressSync(
  [Buffer.from("amm authority")],
  AMM_V4_PROGRAM_ID,
);

Há uma autoridade com escopo de pool separada derivada por pool para assinar operações OpenBook (amm_authority acima na verdade cobre ambas neste design de programa; versões diferentes usaram derivações diferentes, então verifique o AmmInfo.nonce do pool específico no código).

Vaults

Os vaults SPL Token do pool são contas de token padrão cujo owner é amm_authority. Não ATAs — seus endereços são PDAs específicas derivadas em Initialize com seeds ["amm_associated_seed", coin_mint_or_pc_mint, market, amm_id]. Endereços são armazenados em AmmInfo; derivação é uma curiosidade única. Token-2022 não é suportado. O programa codifica o ID do programa SPL Token para todos os movimentos de vault. Tentar vincular um pool AMM v4 a um mint Token-2022 falha em Initialize.

Mint de LP

Um mint SPL Token clássico cuja autoridade é amm_authority. O fornecimento total rastreia a propriedade de LP do pool; queimar LP retorna tokens de ambos os vaults proporcionalmente. Como AMM v4 é anterior a CPMM, não há espelho lp_supply no estado do pool — leia o fornecimento on-chain do mint diretamente.

Bitmask de status

AmmInfo.status controla operações. Bits (a posição pode diferir entre versões de programa — confirme via a fonte):

Bit	Flag	Efeito
0	`SWAP_DISABLED`	`Swap*` rejeita.
1	`DEPOSIT_DISABLED`	`Deposit` rejeita.
2	`WITHDRAW_DISABLED`	`Withdraw` rejeita.
3	`CLMM_LIKE_MIGRATE`	Flag de gate de migração usado por ops.

O multisig Raydium define estes via AdminCancelOrders, AdminSetParams, etc.

Observação / oráculo

AMM v4 não possui conta de observação dedicada. Outros protocolos que precisam de um TWAP on-chain normalmente consomem travessias de livro do OpenBook indiretamente ou leem off-chain. Se você precisa de um TWAP Raydium com suporte de programa, use CPMM ou CLMM.

Derivando as contas de um pool do zero

Como AMM v4 não foi projetado para PDAs determinísticas por par (é anterior a essa convenção Solana), o amm_id canônico é um keypair seeded derivado com:

ammId = createWithSeed(
  owner: ammAuthority,
  seed:  marketPubkey.toBase58().slice(0, 32),
  programId: AMM_V4_PROGRAM_ID,
)

O mesmo padrão de chave seeded se aplica a amm_open_orders, amm_target_orders, amm_withdraw_queue, pool_temp_lp, pool_coin_token_account, pool_pc_token_account, e lp_mint. O SDK e API pré-computam estes para você; veja raydium-sdk-v2’s Liquidity.getAssociatedPoolKeys. Na prática, integradores leem o conjunto de contas completo do pool de GET https://api-v3.raydium.io/pools/info/ids?ids=<POOL_ID> ou do SDK. Derivar manualmente é raramente necessário.

Referência rápida de ciclo de vida

Evento	Contas criadas	Contas destruídas
`Initialize2`	`amm_info`, `amm_open_orders`, `amm_target_orders`, vaults, `lp_mint`, `pool_withdraw_queue`, `pool_temp_lp`	—
`Deposit`	— (pode criar ATA de LP do usuário)	—
`Withdraw`	—	—
`SwapBaseIn` / `SwapBaseOut`	— (pode criar ATA do usuário)	—
`TakePnl`	—	—
`MonitorStep` (crank)	—	—

Pools e suas contas persistem indefinidamente. Mesmo se a liquidez for completamente sacada, AmmInfo permanece.

O que ler onde

Matemática e aritmética de taxas: products/amm-v4/math.
Divisão de taxa e como se compara com CPMM/CLMM: products/amm-v4/fees.
Listas de contas de instrução: products/amm-v4/instructions.
Derivação de conta OpenBook: Documentação do programa OpenBook (github.com/openbook-dex/program).

Fontes:

Programa AMM Raydium — raydium-io/raydium-amm
reference/program-addresses para IDs de programa canônicos
Protocolo OpenBook / Serum para as contas de contraparte

Products

Algorithms

Inventário

`AmmInfo`

A fiação OpenBook

PDAs de Autoridade

Vaults

Mint de LP

Bitmask de status

Observação / oráculo

Derivando as contas de um pool do zero

Referência rápida de ciclo de vida

O que ler onde

Products

Algorithms

Documentation Index

​Inventário

​AmmInfo

​A fiação OpenBook

​PDAs de Autoridade

​Vaults

​Mint de LP

​Bitmask de status

​Observação / oráculo

​Derivando as contas de um pool do zero

​Referência rápida de ciclo de vida

​O que ler onde

Inventário

`AmmInfo`

A fiação OpenBook

PDAs de Autoridade

Vaults

Mint de LP

Bitmask de status

Observação / oráculo

Derivando as contas de um pool do zero

Referência rápida de ciclo de vida

O que ler onde