Fee

Fee instructions are applied to amountIn. All are wrapping instructions: they call ctx.runLoop() internally to execute the nested swap formula, then adjust amounts around the result.

Source: src/instructions/Fee.sol (part of the SwapVM instruction set on the Aqua router).

Fee scale: BPS = 1e9 (1e9 = 100%). A fee of 3000000 (3e6) = 0.3%. In the app, the swap fee is displayed to two decimals (for example, 0.30%).

Constraint shared by all instructions

Must be placed before swap amounts are computed. That is, both amountIn and amountOut must be zero when this instruction executes. Violating this reverts with FeeShouldBeAppliedBeforeSwapAmountsComputation.

Quote/swap divergence: All instructions compute fee amounts in quote mode but skip the actual token transfer or Aqua pull. A quote may succeed while the swap reverts due to insufficient maker balance or missing ERC-20 approval. Do not use backward jumps to any of these instructions.

Instructions

_flatFeeAmountInXD

function _flatFeeAmountInXD(Context memory ctx, bytes calldata args) internal

Applies a flat proportional fee on amountIn. There is no token transfer; it adjusts amounts only. This is the instruction behind the non-zero LP swap fee.

_protocolFeeAmountInXD

function _protocolFeeAmountInXD(Context memory ctx, bytes calldata args) internal

Flat fee on amountIn with a live ERC-20 transfer from maker to a recipient.

The transfer (safeTransferFrom(maker, to, feeAmount)) occurs during program execution, before SwapVM's final taker-to-maker tokenIn transfer. The maker must hold sufficient tokenIn balance and have granted ERC-20 approval before swap execution.

_aquaProtocolFeeAmountInXD

function _aquaProtocolFeeAmountInXD(Context memory ctx, bytes calldata args) internal

Same as _protocolFeeAmountInXD but pulls fee from the maker's Aqua virtual balance via IAqua.pull(maker, orderHash, tokenIn, feeAmount, to) instead of a direct ERC-20 transfer. Increments ctx.swap.amountNetPulled by the fee.

_dynamicProtocolFeeAmountInXD

function _dynamicProtocolFeeAmountInXD(Context memory ctx, bytes calldata args) internal

Fee rate and recipient are determined at execution time by calling IProtocolFeeProvider.getFeeBpsAndRecipient(...) on an external contract via staticcall. Transfers fee via safeTransferFrom.

Security: Uses staticcall, so the fee provider cannot mutate state. Protected by TransientLock at the orderHash level. A malicious provider can return large data causing high gas consumption; takers should verify provider trustworthiness.

Errors: FeeDynamicProtocolInvalidRecipient() if feeBps != 0 but to == address(0). FeeProtocolProviderFailedCall() if staticcall fails or returns unexpected data. FeeBpsOutOfRange(feeBps) if returned fee exceeds BPS.

_aquaDynamicProtocolFeeAmountInXD

function _aquaDynamicProtocolFeeAmountInXD(Context memory ctx, bytes calldata args) internal

Same as _dynamicProtocolFeeAmountInXD but uses IAqua.pull for the transfer instead of safeTransferFrom.

Related

• FeeExperimental: experimental fee variants applied to amountOut. Not part of the shipped v1 opcode set.
• XYCSwap: a typical swap formula nested inside fee instructions.
• LimitSwap: another common nested swap formula.