Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.raydium.io/llms.txt

Use this file to discover all available pages before exploring further.

Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.Ver versión en inglés →
AMM v4 es significativamente más pesado en cuentas que CPMM o CLMM porque cada operación toca el estado de OpenBook. Esta página agrupa las cuentas en secciones “propiedad del pool” y “propiedad de OpenBook” para que un integrador pueda ver rápidamente cuál es cuál.

Inventario

Un pool de AMM v4 se vincula a exactamente un mercado de OpenBook al momento de su creación. El panorama completo actual es:
CategoríaCuentaPropietarioRol
PoolAmmInfoPrograma AMM v4Estado del pool: comisiones acumuladas, estado, referencias a bóvedas y mercado de OpenBook.
Poolamm_authorityPrograma AMM v4PDA propiedad del programa que firma los movimientos de bóvedas. Compartida entre todos los pools de AMM v4.
Poolamm_open_ordersOpenBookLa cuenta OpenOrders del pool en OpenBook para este mercado.
Poolamm_target_ordersPrograma AMM v4Cuadrícula de órdenes límite objetivo del lado del pool para publicar en OpenBook.
Poolpool_coin_token_accountSPL TokenBóveda del lado coin del pool (ATA de amm_authority).
Poolpool_pc_token_accountSPL TokenBóveda del lado pc del pool.
Poollp_mintSPL TokenMint de LP fungible.
Poolpool_withdraw_queuePrograma AMM v4Cola heredada para retiros retrasados; se mantiene con longitud cero.
Poolpool_temp_lpPrograma AMM v4Cuenta LP auxiliar utilizada durante Initialize.
Mercado (OpenBook)serum_marketOpenBookEl mercado en sí (mints base/quote, vault signer, etc.).
Mercadoserum_bids, serum_asksOpenBookLas colas de ofertas y demandas.
Mercadoserum_event_queueOpenBookEventos pendientes (ejecuciones, cancelaciones).
Mercadoserum_coin_vault, serum_pc_vaultSPL TokenBóvedas a nivel de mercado de OpenBook.
Mercadoserum_vault_signerOpenBookPDA a nivel de mercado que firma los movimientos de serum_*_vault.
Nota: El prefijo “serum” se mantiene en el IDL y nombres de campos de AMM v4 por compatibilidad hacia atrás. Se refiere al mercado de OpenBook actual.

AmmInfo

La cuenta de estado raíz del pool. Grande (≈ 752 bytes) porque contiene referencias de pool y OpenBook en línea.
// programs/amm/src/state.rs (abreviado; el orden de campos / nombres sigue el IDL)
pub struct AmmInfo {
    pub status: u64,           // máscara de bits: swap/deposit/withdraw/crank habilitado
    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,    // refleja el mercado de OpenBook
    pub pc_lot_size:   u64,
    pub min_price_multiplier: u64,
    pub max_price_multiplier: u64,
    pub sys_decimal_value: u64,

    pub fees: Fees,            // tasas de comisión comercial/protocolo/fondo
    pub state_data: StateData,

    // Cuentas propiedad del 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 del pool en OpenBook
    pub market: Pubkey,        // Mercado de OpenBook
    pub market_program: Pubkey, // ID del programa OpenBook
    pub target_orders: Pubkey,
    pub withdraw_queue: Pubkey,
    pub lp_vault:       Pubkey, // = pool_temp_lp
    pub owner: Pubkey,          // administrador (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  → utilizado por integración de OpenBook
    pub trade_fee_denominator:    u64,     // 10_000
    pub pnl_numerator:            u64,     // 12  → participación del protocolo DE la comisión de swap
    pub pnl_denominator:          u64,     // 100 → así 12/100 = 12% de la comisión, = 0.03% del volumen
    pub swap_fee_numerator:       u64,     // 25  → comisión de swap bruta 0.25%
    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 relevantes para integradores:
  • coin_vault, pc_vault — las bóvedas SPL Token del pool. coin es token_0 por convención de Serum/OpenBook (base), pc es token_1 (quote).
  • coin_decimals, pc_decimals — coincidiendo con los mints.
  • open_orders, target_orders, market — deben pasarse a cada instrucción de swap/deposit/withdraw.
  • fees.swap_fee_numerator / swap_fee_denominator — la comisión comercial combinada. Por defecto 25 / 10_000 = 0.25%.
  • status — máscara de bits que controla operaciones. Configurable por administrador mediante AdminSetStatus.
  • state_data.need_take_pnl_* — diferencia entre las comisiones acumuladas brutas y las que se han recopilado. TakePnl pone estas a cero.

El cableado de OpenBook

Ya no está activo. Los pools de AMM v4 ya no comparten liquidez en OpenBook — la cuadrícula de órdenes límite ha sido desactivada. Las cuentas de OpenBook descritas en esta sección siguen estando en AmmInfo de cada pool y siguen siendo validadas por los puntos de entrada de swap V1 (y por Initialize, Deposit, Withdraw) por compatibilidad hacia atrás, pero el estado en libro que referencia está vacío en la práctica. Usa los puntos de entrada de swap V2 (SwapBaseInV2 / SwapBaseOutV2) que no requieren estas cuentas en absoluto y representan la ruta de ejecución canónica hoy.
Cuando llamas a cualquier instrucción V1 de lectura o escritura en un pool de AMM v4, debes pasar las cuentas de OpenBook. El programa las re-deriva y valida, por lo que pasar un conjunto no coincidente revierte. (Las variantes de swap V2 no requieren estas cuentas en absoluto.)
const market = ...;  // PublicKey del mercado de OpenBook

// Campos que OpenBook expone en su cuenta 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,
);
amm_open_orders del AMM es una cuenta propiedad de OpenBook que contiene el estado de órdenes límite del pool en este mercado: órdenes activas, saldos liquidados, referentes, etc. amm_target_orders es del lado del AMM: contiene la cuadrícula pretendida del AMM (precio/tamaño para cada ranura de orden) para que el programa pueda comparar barato contra lo que está actualmente publicado y colocar / cancelar la diferencia.

PDAs de autoridad

Hay exactamente un PDA amm_authority para todo el programa AMM v4. Su semilla es trivial (["amm authority"]) y su bump se almacena en cada AmmInfo. Esta autoridad firma todos los movimientos de token para todos los pools de AMM v4.
const AMM_V4_PROGRAM_ID = new PublicKey(
  "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
);
const [ammAuthority] = PublicKey.findProgramAddressSync(
  [Buffer.from("amm authority")],
  AMM_V4_PROGRAM_ID,
);
Hay una autoridad de ámbito del pool separada derivada por pool para firmar operaciones de OpenBook (amm_authority arriba realmente cubre ambas en el diseño de este programa; versiones diferentes usaron derivación diferente, así que verifica el AmmInfo.nonce específico del pool en el código).

Bóvedas

Las bóvedas SPL Token del pool son cuentas de token estándar cuyo owner es amm_authority. No son ATAs — sus direcciones son PDAs específicas derivadas en Initialize con semillas ["amm_associated_seed", coin_mint_or_pc_mint, market, amm_id]. Las direcciones se almacenan en AmmInfo; la derivación es una curiosidad única. Token-2022 no es compatible. El programa codifica el ID del programa SPL Token para todos los movimientos de bóvedas. Intentar vincular un pool de AMM v4 a un mint de Token-2022 falla en Initialize.

Mint de LP

Un mint SPL Token clásico cuya autoridad es amm_authority. El suministro total rastrea la propiedad de LP del pool; quemar LP devuelve tokens de ambas bóvedas de forma prorrateada. Porque AMM v4 es anterior a CPMM, no hay un espejo lp_supply en el estado del pool — lee directamente el suministro del mint en cadena.

Máscara de estado

AmmInfo.status controla operaciones. Bits (la posición puede diferir entre versiones del programa — confirma mediante la fuente):
BitBanderaEfecto
0SWAP_DISABLEDSwap* rechaza.
1DEPOSIT_DISABLEDDeposit rechaza.
2WITHDRAW_DISABLEDWithdraw rechaza.
3CLMM_LIKE_MIGRATEBandera de puerta de migración utilizada por operaciones.
El multisig de Raydium establece estos mediante AdminCancelOrders, AdminSetParams, etc.

Observación / oráculo

AMM v4 no tiene una cuenta de observación dedicada. Otros protocolos que necesitan un TWAP en cadena típicamente consumen los cruces de libro de OpenBook indirectamente o leen fuera de cadena. Si necesitas un TWAP de Raydium con soporte de programa, usa CPMM o CLMM.

Derivar cuentas de un pool desde cero

Porque AMM v4 no fue diseñado para PDAs deterministas por par (predataba esa convención de Solana), el amm_id canónico es un keypair semillado derivado con:
ammId = createWithSeed(
  owner: ammAuthority,
  seed:  marketPubkey.toBase58().slice(0, 32),
  programId: AMM_V4_PROGRAM_ID,
)
El mismo patrón de clave semillada se aplica a amm_open_orders, amm_target_orders, amm_withdraw_queue, pool_temp_lp, pool_coin_token_account, pool_pc_token_account, y lp_mint. El SDK y API precomputan estos para ti; ver raydium-sdk-v2’s Liquidity.getAssociatedPoolKeys. En la práctica, los integradores leen el conjunto completo de cuentas del pool desde GET https://api-v3.raydium.io/pools/info/ids?ids=<POOL_ID> o desde el SDK. La derivación manual es raramente necesaria.

Referencia rápida del ciclo de vida

EventoCuentas creadasCuentas destruidas
Initialize2amm_info, amm_open_orders, amm_target_orders, bóvedas, lp_mint, pool_withdraw_queue, pool_temp_lp
Deposit— (puede crear ATA de LP del usuario)
Withdraw
SwapBaseIn / SwapBaseOut— (puede crear ATA del usuario)
TakePnl
MonitorStep (crank)
Los pools y sus cuentas persisten indefinidamente. Incluso si la liquidez se retira completamente, AmmInfo permanece.

Qué leer dónde

Fuentes: