Comptes AMM v4

Cette page est traduite automatiquement par IA. La version anglaise fait foi.Voir la version anglaise →

AMM v4 est nettement plus « consommateur de comptes » que CPMM ou CLMM, car chaque opération touche l’état OpenBook. Cette page regroupe les comptes en sections « pool-owned » et « OpenBook-owned » pour permettre à un intégrateur de voir rapidement qui possède quoi.

Inventaire

Un pool AMM v4 se lie à exactement un marché OpenBook à la création. L’image complète en direct est :

Catégorie	Compte	Propriétaire	Rôle
Pool	`AmmInfo`	Programme AMM v4	État du pool : frais accumulés, statut, références aux vaults et au marché OpenBook.
Pool	`amm_authority`	Programme AMM v4	PDA détenu par le programme qui signe les mouvements de vault. Partagé entre tous les pools AMM v4.
Pool	`amm_open_orders`	OpenBook	Le compte `OpenOrders` OpenBook du pool pour ce marché.
Pool	`amm_target_orders`	Programme AMM v4	Grille côté pool d’ordres à cours limité cible à poster sur OpenBook.
Pool	`pool_coin_token_account`	SPL Token	Vault côté coin du pool (ATA de `amm_authority`).
Pool	`pool_pc_token_account`	SPL Token	Vault côté pc du pool.
Pool	`lp_mint`	SPL Token	Mint LP fongible.
Pool	`pool_withdraw_queue`	Programme AMM v4	Queue héritée pour les retraits différés ; maintenue à longueur zéro.
Pool	`pool_temp_lp`	Programme AMM v4	Compte LP auxiliaire utilisé lors de `Initialize`.
Marché (OpenBook)	`serum_market`	OpenBook	Le marché lui-même (mints base/quote, vault signer, etc.).
Marché	`serum_bids`, `serum_asks`	OpenBook	Les files d’enchères et les demandes.
Marché	`serum_event_queue`	OpenBook	Événements en attente (remplissages, annulations).
Marché	`serum_coin_vault`, `serum_pc_vault`	SPL Token	Vaults au niveau du marché OpenBook.
Marché	`serum_vault_signer`	OpenBook	PDA au niveau du marché qui signe les mouvements de `serum_*_vault`.

Remarque : le préfixe « serum » est conservé dans l’IDL et les noms de champs d’AMM v4 pour la compatibilité ascendante. Il fait référence au marché OpenBook aujourd’hui.

`AmmInfo`

Le compte d’état racine du pool. Large (≈ 752 octets) car il porte à la fois les références du pool et d’OpenBook en ligne.

// programs/amm/src/state.rs (abrégé ; l'ordre des champs / noms suit l'IDL)
pub struct AmmInfo {
    pub status: u64,           // bitmask: swap/deposit/withdraw/crank enabled
    pub nonce:  u64,           // bump used to derive amm_authority
    pub order_num: u64,
    pub depth: u64,
    pub coin_decimals: u64,
    pub pc_decimals:   u64,
    pub state:         u64,    // internal state machine
    pub reset_flag:    u64,
    pub min_size:      u64,
    pub vol_max_cut_ratio: u64,
    pub amount_wave: u64,
    pub coin_lot_size: u64,    // mirrors OpenBook market
    pub pc_lot_size:   u64,
    pub min_price_multiplier: u64,
    pub max_price_multiplier: u64,
    pub sys_decimal_value: u64,

    pub fees: Fees,            // trade/protocol/fund fee rates
    pub state_data: StateData,

    // Pool-owned accounts:
    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,   // pool's OpenOrders on OpenBook
    pub market: Pubkey,        // OpenBook market
    pub market_program: Pubkey, // OpenBook program ID
    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  → used by OpenBook integration
    pub trade_fee_denominator:    u64,     // 10_000
    pub pnl_numerator:            u64,     // 12  → protocol's share OF the swap fee
    pub pnl_denominator:          u64,     // 100 → so 12/100 = 12% of fee, = 0.03% of volume
    pub swap_fee_numerator:       u64,     // 25  → 0.25% gross swap fee
    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,
}

Champs visibles pour les intégrateurs :

coin_vault, pc_vault — les vaults SPL Token du pool. coin est token_0 par convention Serum/OpenBook (base), pc est token_1 (quote).
coin_decimals, pc_decimals — correspondant aux mints.
open_orders, target_orders, market — doivent être passés à chaque instruction de swap/deposit/withdraw.
fees.swap_fee_numerator / swap_fee_denominator — le frais commercial combiné. Par défaut 25 / 10_000 = 0,25%.
status — bitmask gating les opérations. Configurable par admin via AdminSetStatus.
state_data.need_take_pnl_* — delta entre les frais bruts accumulés et ce qui a été balayé. TakePnl remet ces valeurs à zéro.

Le câblage OpenBook

N’est plus actif. Les pools AMM v4 ne partagent plus la liquidité vers OpenBook — la grille des ordres à cours limité a été désactivée. Les comptes OpenBook décrits dans cette section restent sur le AmmInfo de chaque pool et sont toujours validés par les points d’entrée V1 swap (et par Initialize, Deposit, Withdraw) pour la compatibilité ascendante, mais l’état on-book auquel ils font référence est vide en pratique. Utilisez les points d’entrée V2 swap (SwapBaseInV2 / SwapBaseOutV2) qui ne nécessitent pas ces comptes du tout et représentent le chemin d’exécution canonique aujourd’hui.

Lorsque vous appelez une instruction de lecture ou d’écriture V1 sur un pool AMM v4, vous devez passer les comptes OpenBook. Le programme les re-dérive et les valide, donc passer un ensemble mal assorti revient en arrière. (Les variantes V2 swap ne nécessitent pas du tout ces comptes.)

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

// Fields OpenBook exposes on its market account:
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,
);

Le compte amm_open_orders du AMM est un compte détenu par OpenBook contenant l’état de l’ordre à cours limité du pool sur ce marché : ordres actifs, soldes réglés, références, etc. amm_target_orders est du côté AMM : il contient la grille intentionnelle du AMM (prix/taille pour chaque emplacement d’ordre) afin que le programme puisse facilement comparer par rapport à ce qui est actuellement posté et placer / annuler la différence.

PDAs d’autorité

Il y a exactement un PDA amm_authority pour l’ensemble du programme AMM v4. Sa seed est triviale (["amm authority"]) et son bump est stocké sur chaque AmmInfo. Cette autorité signe tous les mouvements de jetons pour tous les pools AMM v4.

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

Il y a une autorité limitée au pool séparée dérivée par pool pour signer les opérations OpenBook (amm_authority ci-dessus couvre en fait les deux dans la conception de ce programme ; différentes versions utilisaient une dérivation différente, vérifiez donc le AmmInfo.nonce spécifique du pool dans le code).

Vaults

Les vaults SPL Token du pool sont des comptes de jetons standard dont le propriétaire (owner) est amm_authority. Pas des ATAs — leurs adresses sont des PDAs spécifiques dérivés lors de Initialize avec les seeds ["amm_associated_seed", coin_mint_or_pc_mint, market, amm_id]. Les adresses sont stockées sur AmmInfo ; la dérivation est une curiosité purement une fois. Token-2022 n’est pas pris en charge. Le programme code en dur l’ID du programme SPL Token pour tous les mouvements de vault. Tenter de lier un pool AMM v4 à un mint Token-2022 échoue à Initialize.

LP mint

Un mint SPL Token classique dont l’autorité est amm_authority. L’offre totale suit la propriété du LP du pool ; la combustion du LP retourne les jetons des deux vaults au prorata. Parce qu’AMM v4 est antérieur à CPMM, il n’y a pas de miroir lp_supply dans l’état du pool — lisez directement l’offre on-chain du mint.

Bitmask de statut

AmmInfo.status gâte les opérations. Bits (la position peut différer selon les versions du programme — confirmez via la source) :

Bit	Drapeau	Effet
0	`SWAP_DISABLED`	`Swap*` rejette.
1	`DEPOSIT_DISABLED`	`Deposit` rejette.
2	`WITHDRAW_DISABLED`	`Withdraw` rejette.
3	`CLMM_LIKE_MIGRATE`	Drapeau de gâte de migration utilisé par les opérations.

Le multisig Raydium définit ceux-ci via AdminCancelOrders, AdminSetParams, etc.

Observation / oracle

AMM v4 n’a pas de compte d’observation dédié. Les autres protocoles qui ont besoin d’un TWAP on-chain consomment généralement les croisements de livre OpenBook indirectement ou lisent hors chaîne. Si vous avez besoin d’un TWAP Raydium avec prise en charge du programme, utilisez CPMM ou CLMM.

Dériver les comptes d’un pool à partir de zéro

Parce qu’AMM v4 n’a pas été conçu pour des PDAs déterministes par paire (il est antérieur à cette convention Solana), le amm_id canonique est un keypair ensemencé dérivé avec :

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

Le même modèle de clé ensemencée s’applique à amm_open_orders, amm_target_orders, amm_withdraw_queue, pool_temp_lp, pool_coin_token_account, pool_pc_token_account et lp_mint. Le SDK et l’API les pré-calculent pour vous ; consultez Liquidity.getAssociatedPoolKeys du raydium-sdk-v2. En pratique, les intégrateurs lisent l’ensemble complet des comptes du pool à partir de GET https://api-v3.raydium.io/pools/info/ids?ids=<POOL_ID> ou du SDK. La dérivation manuelle est rarement nécessaire.

Référence rapide du cycle de vie

Événement	Comptes créés	Comptes détruits
`Initialize2`	`amm_info`, `amm_open_orders`, `amm_target_orders`, vaults, `lp_mint`, `pool_withdraw_queue`, `pool_temp_lp`	—
`Deposit`	— (peut créer user LP ATA)	—
`Withdraw`	—	—
`SwapBaseIn` / `SwapBaseOut`	— (peut créer user ATA)	—
`TakePnl`	—	—
`MonitorStep` (crank)	—	—

Les pools et leurs comptes persistent indéfiniment. Même si la liquidité est entièrement retirée, AmmInfo reste.

Où lire quoi

Mathématiques et arithmétique des frais : products/amm-v4/math.
Répartition des frais et comparaison avec CPMM/CLMM : products/amm-v4/fees.
Listes de comptes d’instruction : products/amm-v4/instructions.
Dérivation de comptes OpenBook : Documentation du programme OpenBook (github.com/openbook-dex/program).

Sources :

Programme Raydium AMM — raydium-io/raydium-amm
reference/program-addresses pour les ID de programme canoniques
OpenBook / Protocole Serum pour les comptes de contrepartie

Produits

Algorithmes

Inventaire

`AmmInfo`

Le câblage OpenBook

PDAs d’autorité

Vaults

LP mint

Bitmask de statut

Observation / oracle

Dériver les comptes d’un pool à partir de zéro

Référence rapide du cycle de vie

Où lire quoi

Produits

Algorithmes

Documentation Index

​Inventaire

​AmmInfo

​Le câblage OpenBook

​PDAs d’autorité

​Vaults

​LP mint

​Bitmask de statut

​Observation / oracle

​Dériver les comptes d’un pool à partir de zéro

​Référence rapide du cycle de vie

​Où lire quoi

Inventaire

`AmmInfo`

Le câblage OpenBook

PDAs d’autorité

Vaults

LP mint

Bitmask de statut

Observation / oracle

Dériver les comptes d’un pool à partir de zéro

Référence rapide du cycle de vie

Où lire quoi