Zap Formulas and Limits

Zap uses integer arithmetic and delegates most AMM math to DAMM v2 or DLMM. This page covers the calculations Zap performs directly.

​

Zap Out Amount

Zap Out starts from the increase in the user’s input token account: $$\text{balance increase} = \text{post balance} - \text{pre balance}$$ If pre_user_token_balance >= post balance, Zap returns successfully and does not invoke a swap. The swap amount is: $$\text{swap amount} = \min\left( \left\lfloor\frac{\text{balance increase} \times \text{percentage}}{100}\right\rfloor, \text{max swap amount} \right)$$ For percentage = 100, Zap uses the full balance increase before applying the max-swap cap. Zap writes the final swap amount into payload_data as a little-endian u64.

​

Ledger Delta Updates

When Zap updates a ledger after a balance-changing CPI, it applies the token account delta to the current ledger amount: $$\text{new ledger amount} = \text{old ledger amount} + \text{post token balance} - \text{pre token balance}$$ For update_ledger_balance_after_swap, the recorded amount is capped: $$\text{recorded amount} = \min(\text{post token balance} - \text{pre token balance}, \text{max transfer amount})$$ The balance delta uses saturating subtraction, so if the current token balance is below the supplied pre-balance, the delta is 0.

​

Transfer-Fee-Excluded Amounts

Zap In uses transfer-fee-excluded token amounts when calculating DAMM v2 liquidity and DLMM strategy parameters: $$\text{net amount} = \text{gross amount} - \text{transfer fee}$$ For SPL Token mints and Token 2022 mints without a transfer fee extension, the transfer fee is treated as 0. For Token 2022 transfer-fee mints, Zap uses the current epoch’s configured fee.

​

DAMM v2 Price Slippage

DAMM v2 Zap In checks the pool sqrt price after the optional balancing swap: $$\text{sqrt price change bps} = \left\lceil \frac{|\text{post sqrt price} - \text{pre sqrt price}| \times 10{,}000} {\text{pre sqrt price}} \right\rceil$$ The instruction fails if: $$\text{sqrt price change bps} > \text{max sqrt price change bps}$$ max_sqrt_price_change_bps is supplied by the caller as a u32.

​

DAMM v2 Surplus-Side Swap

DAMM v2 Zap In compares how much liquidity the ledger’s token A and token B amounts can provide. The side that can provide more liquidity is considered surplus: Zap then uses a binary search of up to 20 iterations to estimate an exact-in swap amount that makes the remaining user amounts closer to the pool ratio. The search accounts for DAMM v2 fee mode, dynamic fee, reserves, compounding fee behavior, and transfer-fee-excluded token amounts. The internal DAMM v2 fee simulation supports these base fee modes:

• FeeTimeSchedulerLinear
• FeeTimeSchedulerExponential
• FeeMarketCapSchedulerLinear
• FeeMarketCapSchedulerExponential
• RateLimiter

If the calculation fails or produces a zero input or output amount, Zap skips the swap and returns successfully.

​

DLMM Range

DLMM Zap In receives min_delta_id and max_delta_id relative to the current active bin. The program requires: $$\text{min delta id} \le \text{max delta id}$$ For a new position, Zap initializes the DLMM position with: $$\text{lower bin id} = \text{current active id} + \text{min delta id}$$ $$\text{width} = \text{max delta id} - \text{min delta id} + 1$$ The strategy math uses the pair’s current active_id and bin_step.

​

Active Bin Side Selection

favor_x_in_active_id controls which side receives the active bin when a range crosses the active bin. This matters because bins below the active area use token Y, bins above it use token X, and the active bin can be assigned to either side.

​

DLMM Strategy Shapes

Zap computes DLMM AddLiquidityParams for three strategy types: The computed signed parameters are stored as absolute u64 values plus a bit flag that marks which of x0, y0, delta_x, or delta_y was negative.

​

Error Conditions