Учётные записи AMM v4

Эта страница переведена с помощью ИИ. За эталон принимается английская версия.Открыть английскую версию →

AMM v4 требует значительно больше учётных записей, чем CPMM или CLMM, поскольку каждая операция касается состояния OpenBook. На этой странице учётные записи разделены на секции “принадлежащие пулу” и “принадлежащие OpenBook”, чтобы интегратор мог быстро ориентироваться.

Перечень

Пул AMM v4 привязывается ровно к одному рынку OpenBook при создании. Полная актуальная картина выглядит так:

Категория	Учётная запись	Владелец	Роль
Pool	`AmmInfo`	AMM v4 программа	Состояние пула: накопленные сборы, статус, ссылки на хранилища и рынок OpenBook.
Pool	`amm_authority`	AMM v4 программа	Принадлежащий программе PDA, подписывающий переводы из хранилищ. Общий для всех пулов AMM v4.
Pool	`amm_open_orders`	OpenBook	Учётная запись `OpenOrders` пула на этом рынке OpenBook.
Pool	`amm_target_orders`	AMM v4 программа	Сетка целевых лимитных ордеров пула для размещения на OpenBook.
Pool	`pool_coin_token_account`	SPL Token	Хранилище пула на стороне монеты (ATA `amm_authority`).
Pool	`pool_pc_token_account`	SPL Token	Хранилище пула на стороне pc.
Pool	`lp_mint`	SPL Token	Взаимозаменяемый LP-минт.
Pool	`pool_withdraw_queue`	AMM v4 программа	Унаследованная очередь для отложенных выводов; сохраняется нулевой длины.
Pool	`pool_temp_lp`	AMM v4 программа	Вспомогательная LP-учётная запись, используемая при `Initialize`.
Market (OpenBook)	`serum_market`	OpenBook	Сам рынок (минты base/quote, vault signer и т. д.).
Market	`serum_bids`, `serum_asks`	OpenBook	Очереди заявок на покупку и продажу.
Market	`serum_event_queue`	OpenBook	Очередь событий (заполнения, отмены).
Market	`serum_coin_vault`, `serum_pc_vault`	SPL Token	Хранилища рынка на уровне OpenBook.
Market	`serum_vault_signer`	OpenBook	PDA уровня рынка, подписывающий переводы из `serum_*_vault`.

Примечание: префикс “serum” сохранён в IDL и именах полей AMM v4 для обратной совместимости. Он относится к рынку OpenBook.

`AmmInfo`

Корневая учётная запись состояния пула. Большого размера (≈ 752 байта), так как содержит ссылки на пул и OpenBook встроенными.

// programs/amm/src/state.rs (сокращённо; порядок полей / имена соответствуют 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,
}

Поля для интеграторов:

coin_vault, pc_vault — хранилища SPL Token пула. coin — это token_0 по соглашению Serum/OpenBook (base), pc — это token_1 (quote).
coin_decimals, pc_decimals — соответствуют минтам.
open_orders, target_orders, market — должны передаваться в каждую инструкцию swap/deposit/withdraw.
fees.swap_fee_numerator / swap_fee_denominator — объединённая торговая комиссия. По умолчанию 25 / 10_000 = 0.25%.
status — bitmask, управляющий операциями. Может быть установлен администратором через AdminSetStatus.
state_data.need_take_pnl_* — разница между накопленными брутто-сборами и тем, что уже снято. TakePnl обнуляет эти значения.

Связь с OpenBook

Больше не активно. Пулы AMM v4 больше не делят ликвидность с OpenBook — сетка лимитных ордеров деактивирована. Учётные записи OpenBook, описанные в этом разделе, остаются в AmmInfo каждого пула и по-прежнему проверяются конечными точками V1 swap (а также Initialize, Deposit, Withdraw) для обратной совместимости, но состояние на книге ордеров остаётся пустым на практике. Используйте конечные точки V2 swap (SwapBaseInV2 / SwapBaseOutV2), которые полностью пропускают эти учётные записи и представляют канонический путь выполнения сегодня.

При вызове любой инструкции V1 на пуле AMM v4 вы должны передать учётные записи OpenBook. Программа переоценивает и проверяет их, поэтому передача несоответствующего набора откатывает операцию. (Варианты V2 swap вообще не требуют эти учётные записи.)

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,
);

amm_open_orders — это учётная запись, принадлежащая OpenBook, содержащая состояние лимитных ордеров пула на этом рынке: активные ордера, выплаченные балансы, рефереры и т. д. amm_target_orders — сторона AMM: содержит намеченную сетку пула (цена/размер для каждого слота ордера), чтобы программа могла дёшево сравнить с тем, что в данный момент размещено, и разместить / отменить разницу.

PDA Authority

Существует ровно один PDA amm_authority для всей программы AMM v4. Его seed тривиален (["amm authority"]) и его bump сохранён в каждой AmmInfo. Этот authority подписывает все перемещения токенов для всех пулов AMM v4.

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

Существует отдельный authority в области пула, производная для каждого пула, чтобы подписывать операции OpenBook (amm_authority выше фактически охватывает оба в дизайне этой программы; разные версии использовали разные выводы, поэтому проверьте конкретную AmmInfo.nonce пула в коде).

Хранилища

Хранилища SPL Token пула — это стандартные учётные записи токенов, чей owner — это amm_authority. Не ATA — их адреса — это специфичные PDA, производные при Initialize с seeds ["amm_associated_seed", coin_mint_or_pc_mint, market, amm_id]. Адреса хранятся в AmmInfo; выведение — это одноразовое любопытство. Token-2022 не поддерживается. Программа жёстко кодирует идентификатор программы SPL Token для всех перемещений хранилищ. Попытка привязать пул AMM v4 к минту Token-2022 откатывается на Initialize.

LP-минт

Классический минт SPL Token, чьим authority является amm_authority. Общий объём предложения отслеживает владение LP пулом; сжигание LP возвращает токены из обоих хранилищ пропорционально. Поскольку AMM v4 предшествует CPMM, в состояние пула нет зеркала lp_supply — читайте предложение минта на цепи напрямую.

Bitmask статуса

AmmInfo.status управляет операциями. Биты (позиция может различаться в разных версиях программы — подтвердите через исходный код):

Бит	Флаг	Эффект
0	`SWAP_DISABLED`	`Swap*` отклоняет.
1	`DEPOSIT_DISABLED`	`Deposit` отклоняет.
2	`WITHDRAW_DISABLED`	`Withdraw` отклоняет.
3	`CLMM_LIKE_MIGRATE`	Флаг миграции, используемый операциями.

Multisig Raydium устанавливает эти значения через AdminCancelOrders, AdminSetParams и т. д.

Observation / oracle

AMM v4 не имеет выделённой учётной записи observation. Другие протоколы, которым нужен on-chain TWAP, обычно косвенно потребляют пересечения книги ордеров OpenBook или читают off-chain. Если вам нужен Raydium TWAP с поддержкой программы, используйте CPMM или CLMM.

Выведение учётных записей пула с нуля

Поскольку AMM v4 не был разработан для детерминированных per-pair PDA (он предшествует этому соглашению Solana), каноничный amm_id — это seeded keypair, производная с:

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

Тот же шаблон seeded-key применяется к amm_open_orders, amm_target_orders, amm_withdraw_queue, pool_temp_lp, pool_coin_token_account, pool_pc_token_account и lp_mint. SDK и API предварительно вычисляют эти значения; см. raydium-sdk-v2’s Liquidity.getAssociatedPoolKeys. На практике интеграторы читают полный набор учётных записей пула из GET https://api-v3.raydium.io/pools/info/ids?ids=<POOL_ID> или из SDK. Ручное выведение редко требуется.

Краткая справка жизненного цикла

Событие	Созданные учётные записи	Удалённые учётные записи
`Initialize2`	`amm_info`, `amm_open_orders`, `amm_target_orders`, хранилища, `lp_mint`, `pool_withdraw_queue`, `pool_temp_lp`	—
`Deposit`	— (может создать пользовательскую LP ATA)	—
`Withdraw`	—	—
`SwapBaseIn` / `SwapBaseOut`	— (может создать пользовательскую ATA)	—
`TakePnl`	—	—
`MonitorStep` (crank)	—	—

Пулы и их учётные записи сохраняются неопределённо долго. Даже если ликвидность полностью выведена, AmmInfo остаётся.

Что читать где

Математика и арифметика сборов: products/amm-v4/math.
Распределение сборов и сравнение с CPMM/CLMM: products/amm-v4/fees.
Списки учётных записей инструкций: products/amm-v4/instructions.
Выведение учётных записей OpenBook: документация программы OpenBook (github.com/openbook-dex/program).

Источники:

Программа Raydium AMM — raydium-io/raydium-amm
reference/program-addresses для канонических идентификаторов программ
Протокол OpenBook / Serum для учётных записей контрагента

Продукты

Алгоритмы

Учётные записи AMM v4

Перечень

`AmmInfo`

Связь с OpenBook

PDA Authority

Хранилища

LP-минт

Bitmask статуса

Observation / oracle

Выведение учётных записей пула с нуля

Краткая справка жизненного цикла

Что читать где

Продукты

Алгоритмы

Documentation Index

​Перечень

​AmmInfo

​Связь с OpenBook

​PDA Authority

​Хранилища

​LP-минт

​Bitmask статуса

​Observation / oracle

​Выведение учётных записей пула с нуля

​Краткая справка жизненного цикла

​Что читать где

Перечень

`AmmInfo`

Связь с OpenBook

PDA Authority

Хранилища

LP-минт

Bitmask статуса

Observation / oracle

Выведение учётных записей пула с нуля

Краткая справка жизненного цикла

Что читать где