Swap Instruction

Overview

The swap instruction is the core trading operation of the Multiliquid Program, enabling atomic swaps between Real World Asset (RWA) tokens and stablecoins. It supports both swap directions and both exact-in and exact-out modes.

Key Responsibilities

Execute bidirectional swaps between RWAs and stablecoins
Calculate swap amounts using NAV-based pricing
Apply protocol fees and capital provider fees
Validate all pause states before execution
Emit comprehensive swap events

Function Signature

pub fn swap(
    ctx: Context<Swap>,
    amount: u64,
    min_amount_out: Option<u64>,
    max_amount_in: Option<u64>,
    swap_direction: SwapDirection,
    swap_type: SwapType,
    treasury_nav_account_count: u8,
    treasury_apy_account_count: u8,
) -> Result<()>

Parameters

Parameter	Type	Description
`amount`	`u64`	Primary amount (input for ExactIn, output for ExactOut)
`min_amount_out`	`Option<u64>`	Minimum output (slippage protection for ExactIn)
`max_amount_in`	`Option<u64>`	Maximum input (slippage protection for ExactOut)
`swap_direction`	`SwapDirection`	Direction of the swap
`swap_type`	`SwapType`	ExactIn or ExactOut mode
`treasury_nav_account_count`	`u8`	Treasury NAV accounts following the fixed Treasury account bundle
`treasury_apy_account_count`	`u8`	Treasury APY accounts following the NAV prefix

Swap Direction

pub enum SwapDirection {
    QuoteToBase,  // Quote token → Base token
    BaseToQuote,  // Base token → Quote token
}

Swap Type

pub enum SwapType {
    ExactIn,   // User specifies exact input amount
    ExactOut,  // User specifies exact output amount
}

Required Accounts

#[derive(Accounts)]
pub struct Swap<'info> {
    #[account(mut)]
    pub user: Signer<'info>,

    #[account(
        seeds = [PAIR_PREFIX, liquidity_provider.key().as_ref(), quote_token_mint_address.key().as_ref(), base_token_mint_address.key().as_ref()],
        bump = pair.bump,
    )]
    pub pair: Box<Account<'info, Pair>>,

    #[account(
        seeds = [PROGRAM_AUTHORITY_PREFIX],
        bump,
    )]
    pub program_authority: UncheckedAccount<'info>,

    pub liquidity_provider: UncheckedAccount<'info>,

    #[account(
        mut,
        seeds = [VAULT_AUTHORITY_PREFIX, liquidity_provider.key().as_ref()],
        bump,
    )]
    pub lp_vault_authority: UncheckedAccount<'info>,

    #[account(
        seeds = [LP_FEE_VAULT_AUTHORITY_PREFIX, liquidity_provider.key().as_ref()],
        bump,
    )]
    pub lp_fee_vault_authority: UncheckedAccount<'info>,

    pub quote_token_mint_address: Box<InterfaceAccount<'info, Mint>>,

    pub base_token_mint_address: Box<InterfaceAccount<'info, Mint>>,

    #[account(
        mut,
        token::mint = base_token_mint_address,
        token::authority = user,
        token::token_program = token_program_base,
    )]
    pub base_token_user_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        mut,
        token::mint = quote_token_mint_address,
        token::authority = user,
        token::token_program = token_program_quote,
    )]
    pub quote_token_user_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        mut,
        associated_token::mint = quote_token_mint_address,
        associated_token::authority = lp_vault_authority,
        associated_token::token_program = token_program_quote,
    )]
    pub quote_token_vault_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        mut,
        associated_token::mint = base_token_mint_address,
        associated_token::authority = lp_vault_authority,
        associated_token::token_program = token_program_base,
    )]
    pub base_token_vault_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        seeds = [GLOBAL_CONFIG_PREFIX],
        bump = global_config.bump
    )]
    pub global_config: Box<Account<'info, GlobalConfig>>,

    #[account(
        constraint = fee_token_mint_address.key() == global_config.fee_token_mint @ ErrorCode::InvalidAccountPublicKey,
    )]
    pub fee_token_mint_address: Box<InterfaceAccount<'info, Mint>>,

    #[account(
        mut,
        associated_token::mint = fee_token_mint_address,
        associated_token::authority = lp_fee_vault_authority,
        associated_token::token_program = token_program_fee,
    )]
    pub lp_fee_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        mut,
        associated_token::mint = fee_token_mint_address,
        associated_token::authority = program_authority,
        associated_token::token_program = token_program_fee,
    )]
    pub fee_token_account: Box<InterfaceAccount<'info, TokenAccount>>,

    #[account(
        seeds = [ASSET_CONFIG_PREFIX, base_token_mint_address.key().as_ref()],
        bump = base_config.bump
    )]
    pub base_config: Box<Account<'info, AssetConfig>>,

    #[account(
        seeds = [ASSET_CONFIG_PREFIX, quote_token_mint_address.key().as_ref()],
        bump = quote_config.bump
    )]
    pub quote_config: Box<Account<'info, AssetConfig>>,

    #[account(
        seeds = [ASSET_CONFIG_PREFIX, fee_token_mint_address.key().as_ref()],
        bump = fee_config.bump
    )]
    pub fee_config: Box<Account<'info, AssetConfig>>,

    #[account(
        seeds = [LP_STABLE_CONFIG_PREFIX, quote_token_mint_address.key().as_ref(), liquidity_provider.key().as_ref()],
        bump
    )]
    pub lp_stable_config_quote: Option<Box<Account<'info, LpStableConfig>>>,

    #[account(
        seeds = [LP_STABLE_CONFIG_PREFIX, base_token_mint_address.key().as_ref(), liquidity_provider.key().as_ref()],
        bump
    )]
    pub lp_stable_config_base: Option<Box<Account<'info, LpStableConfig>>>,

    #[account(
        seeds = [LP_PROTOCOL_FEE_CONFIG_PREFIX, liquidity_provider.key().as_ref()],
        bump
    )]
    pub lp_protocol_fee_config: UncheckedAccount<'info>,

    pub token_program_quote: Interface<'info, TokenInterface>,

    pub token_program_base: Interface<'info, TokenInterface>,

    pub token_program_fee: Interface<'info, TokenInterface>,
}

Validation Checks

Before executing the swap, the instruction validates:

Pause States: Program, both assets, fee asset, pair, and applicable capital provider configs must be unpaused
Asset Types: Each Stable side requires its capital provider stable config; RWA/RWA pairs are also supported
Amount: Must be greater than zero
NAV Prices: Both assets and the configured fee token must return valid, non-zero NAV prices
Slippage: Calculated output/input must satisfy min/max constraints
Pair Fees: redemption_fee_bps + discount_rate_bps must be less than 10000

Treasury Remaining Accounts

When the capital provider enables Treasury routing, the first 14 remaining accounts are supplied in this order:

Index	Account
0	Treasury program
1	Treasury global config
2	Treasury quote asset config
3	Treasury base asset config
4	Capital provider Treasury user position
5	Treasury vault authority
6	Treasury mint
7	Capital provider Treasury receipt-token account
8	Treasury quote asset vault
9	Treasury base asset vault
10	Latest Treasury APY entry
11	Treasury token program
12	Associated token program
13	System program

The bundle is followed by the counted Treasury NAV accounts, the counted APY accounts, and then the remaining oracle and transfer-hook accounts. The Treasury program ID is fixed to the deployment listed on the Deployments page. Transfer-hook accounts must not introduce additional signers. The program uses idle vault liquidity first, redeems eligible Stable output shortfalls, and sweeps eligible Stable input balances after receiving the user’s tokens. The Treasury routing conditions apply; RWA inputs are not swept during swaps. The SDK resolves this account plan automatically.

Events

#[event]
pub struct SwapExecuted {
    pub requestor: Pubkey,          // User wallet
    pub amount_in: u64,             // Actual input amount
    pub protocol_fee_amount: u64,   // Protocol fees collected
    pub discount_bps: u16,          // Capital provider fee applied (redemption or discount)
    pub amount_out: u64,            // Actual output amount
    pub pair: Pubkey,               // Pair account address
    pub swap_direction: SwapDirection,
    pub swap_type: SwapType,
    pub redemption_fee_bps: u16,
    pub discount_rate_bps: u16,
}

Swap Calculation

NAV-Based Pricing

Deterministic Pricing: The Multiliquid Program uses NAV-based pricing, not AMM-style liquidity curves. Prices are determined by asset NAV values, not by liquidity depth. There is no price impact from trade size.

The swap amount is calculated using the exchange rate between asset NAVs:

output_amount = input_amount × input_nav / output_nav

Fee Application

Fees are applied in a specific order depending on swap direction. Protocol fees are paid from a separate capital provider fee-token ATA, using GlobalConfig.fee_token_mint; they are not transferred from the user’s input or the capital provider liquidity vault. The protocol’s spread share also affects the user-facing price.

QuoteToBase

Apply the pair redemption fee and protocol spread rate to the quote input.
Apply the NAV ratio to the remaining amount to calculate base output.

BaseToQuote

Apply the NAV ratio to calculate the quote-token equivalent.
Apply the pair discount fee and protocol spread rate to calculate quote output.

For RWA/RWA pairs, the pair fee is the sum of redemption and discount fees in either direction. The protocol spread rate is derived from both pair fee settings and the configured spread take; a nonzero spread take has a minimum one-basis-point effective rate. Base protocol fees are calculated separately on the quote-token fee basis and converted to fee-token units using NAV and token decimals.

Decimal Normalization

Calculations use checked 128-bit arithmetic and 256-bit intermediates for fee-token conversion:

NAV prices normalized to 9 decimals
Intermediate calculations use combined decimal precision
Final amounts rounded appropriately (ceil for fees, floor for outputs)

Usage Examples

These Anchor examples assume an existing pair with stablecoin as quote and RWA as base, with Treasury disabled. Direction follows the stored pair order; newly created pairs use canonical mint ordering. program is an Anchor client generated from the matching program IDL, separate from the Kit SDK.

ExactIn: Stable → RWA

Swap exactly 1000 USDC for RWA tokens with minimum output protection:

import { BN } from "@coral-xyz/anchor";

const amount = new BN(1000_000000);  // 1000 USDC (6 decimals)
const minAmountOut = new BN(990_000000);  // Minimum 990 RWA tokens

await program.methods
  .swap(
    amount,
    minAmountOut,    // min_amount_out
    null,            // max_amount_in (not used for ExactIn)
    { quoteToBase: {} },
    { exactIn: {} },
    0,  // treasury_nav_account_count (Treasury disabled)
    0   // treasury_apy_account_count
  )
  .accounts({
    user: wallet.publicKey,
    pair,
    programAuthority,
    liquidityProvider,
    lpVaultAuthority,
    lpFeeVaultAuthority,
    quoteTokenMintAddress,
    baseTokenMintAddress,
    baseTokenUserTokenAccount,
    quoteTokenUserTokenAccount,
    quoteTokenVaultTokenAccount,
    baseTokenVaultTokenAccount,
    globalConfig,
    feeTokenMintAddress,
    lpFeeTokenAccount,
    feeTokenAccount,
    baseConfig,
    quoteConfig,
    feeConfig,
    lpStableConfigQuote,
    lpStableConfigBase: null,
    lpProtocolFeeConfig,
    tokenProgramQuote: TOKEN_PROGRAM_ID,
    tokenProgramBase: TOKEN_PROGRAM_ID,
    tokenProgramFee,
  })
  .remainingAccounts(navAccounts)  // NAV source accounts
  .rpc();

ExactOut: Stable → RWA

Receive exactly 1000 RWA tokens, spending at most a specified USDC amount:

const amount = new BN(1000_000000);  // Exact 1000 RWA tokens out
const maxAmountIn = new BN(1010_000000);  // Maximum 1010 USDC in

await program.methods
  .swap(
    amount,
    null,            // min_amount_out (not used for ExactOut)
    maxAmountIn,     // max_amount_in
    { quoteToBase: {} },
    { exactOut: {} },
    0,  // treasury_nav_account_count (Treasury disabled)
    0   // treasury_apy_account_count
  )
  .accounts({
    // ... same accounts as above
  })
  .remainingAccounts(navAccounts)
  .rpc();

ExactIn: RWA → Stable

Swap exactly 1000 RWA tokens for stablecoins:

const amount = new BN(1000_000000);  // 1000 RWA tokens
const minAmountOut = new BN(995_000000);  // Minimum 995 USDC

await program.methods
  .swap(
    amount,
    minAmountOut,
    null,
    { baseToQuote: {} },
    { exactIn: {} },
    0,  // treasury_nav_account_count (Treasury disabled)
    0   // treasury_apy_account_count
  )
  .accounts({
    // ... accounts
  })
  .remainingAccounts(navAccounts)
  .rpc();

ExactOut: RWA → Stable

Receive exactly 1000 USDC, spending at most a specified RWA amount:

const amount = new BN(1000_000000);  // Exact 1000 USDC out
const maxAmountIn = new BN(1005_000000);  // Maximum 1005 RWA in

await program.methods
  .swap(
    amount,
    null,
    maxAmountIn,
    { baseToQuote: {} },
    { exactOut: {} },
    0,  // treasury_nav_account_count (Treasury disabled)
    0   // treasury_apy_account_count
  )
  .accounts({
    // ... accounts
  })
  .remainingAccounts(navAccounts)
  .rpc();

Error Codes

Error	Description
`ProgramPaused`	Program is paused
`RwaPaused`	Base asset is paused
`StablePaused`	Quote asset or a capital provider stable config is paused
`FeeAssetPaused`	Configured fee asset is paused
`PairPaused`	Trading pair is paused
`AmountMustBePositive`	Amount is zero
`MissingLpStableConfig`	A Stable side is missing its capital provider stable config
`AmountOutTooLow`	Output less than minimum
`AmountInTooHigh`	Input more than maximum
`FeesOutOfRange`	Pair redemption plus discount fees reach or exceed 10000 BPS
`SwapAmountTooSmall`	Nonzero configured protocol fee rounded to zero for the trade
`DiscountMustBePositive`	Nonzero configured capital provider fee rounded to zero for the trade
`AmountInMustBePositive`	Calculated vault input is zero
`AmountOutMustBePositive`	Calculated output is zero
`InvalidNav`	NAV sources returned invalid or divergent data
`MathOverflow`	Calculation overflow

Access Control

Access: Permissionless Any wallet can execute swaps provided:

All pause states are inactive
User has sufficient token balance
The capital provider’s fee-token account has sufficient balance to pay protocol fees
User signs the transaction and supplies the required token accounts
Valid NAV prices are available

Next: Global Configuration

Learn about program-wide configuration management

Overview

Instructions

Integration

Swap Instruction

Overview

Key Responsibilities