Pre-Release Documentation

This describes a pre-release version of LBAMM. Interfaces and behavior may change.

Verify the exact repository commit before building production integrations.

Fees & Economics

This section defines the fee surfaces and economic semantics of LBAMM: where fees can be assessed, how they are bounded, and how they settle.

LBAMM does not have a single “protocol fee.” Instead, it exposes multiple first-class fee surfaces spanning:

• Execution-level swap fees (exchange fee, fee-on-top)
• Pool-level fees (LP fees and protocol fee configurations)
• Hook-level fees (token/pool/position hooks)
• Flash loan fees

The goal of this section is to give integrators and auditors a deterministic, reference-grade model for value flow.

---

Fee surfaces vs. implementation details

LBAMM fee surfaces are defined in terms of:

• Scope (swap, liquidity operation, flash loan)
• Denomination (which token the fee is paid in)
• Recipient
• Bounds / caps
• Settlement semantics (immediate transfer vs. accrued balance vs. queued settlement)

This section intentionally separates:

• Execution-level fee adjustments (apply once per swap call), from
• Per-hop pool mechanics (apply within each hop), and from
• Hook fees (policy-driven and context-aware)

This avoids incorrect assumptions in multi-hop routes.

---

Execution-level swap fees

LBAMM supports two execution-level swap fee surfaces:

Exchange fee (BPS, proportional)

The exchange fee is a basis point fee applied to a swap’s execution-level input.

Key properties:

• Applies once per swap call (singleSwap / multiSwap), not per hop.
• Recipient and BPS are supplied as call parameters.
• Output-mode scaling: for swap-by-output, the required input is scaled up to cover the exchange fee.

Bounds (enforced by core):

• Swap-by-input: exchangeFee.BPS <= 10_000
• Swap-by-output: exchangeFee.BPS < 10_000
• If exchangeFee.recipient == address(0), then exchangeFee.BPS must be 0.

---

Fee-on-top (flat amount, additive)

Fee-on-top is a flat fee amount denominated in the input token.

Key properties:

• Applies once per swap call, not per hop.
• Supplied as call parameters (amount, recipient).
• Commonly used to implement executor fees (see below).
• Output-mode scaling: for swap-by-output, the required input is increased by the flat fee amount.

Bounds (enforced by core):

• Swap-by-input: feeOnTop.amount cannot exceed the specified input amount.
• Swap-by-output: no protocol-level cap on feeOnTop.amount (it is constrained by overall swap limits / feasibility).
• If feeOnTop.recipient == address(0), then feeOnTop.amount must be 0.

---

Ordering between exchange fee and fee-on-top

The exchange fee and fee-on-top have a deterministic relationship that differs by swap mode:

Swap-by-input

• Fee-on-top is removed from the provided input before exchange fee is applied.
• Exchange fee is applied to the remaining input before swap execution proceeds.

Swap-by-output

• Exchange fee is applied first (scaling up required input).
• Fee-on-top is added after exchange fee.

These ordering rules apply at the execution level and do not compound per hop in multiSwap.

---

Executor fees

Executor fees are represented as fee-on-top.

LBAMM does not introduce a hidden executor reward surface. If an executor is compensated at swap-time, it is explicitly encoded as feeOnTop.

---

Notes on transfer handlers (non-normative)

If a transfer handler is used, the handler receives the exchange fee and fee-on-top parameters as part of settlement.

Some handlers may impose additional constraints on fee fields. For example, a permit-based handler may require that the exchange fee recipient and BPS match what a user signed off-chain for an orderbook/UX flow.

This behavior is handler-specific and should not be treated as a global rule.

(Transfer handler mechanics are documented in the Orders → Transfer Handlers section.)

---

Hook-level fees

Hooks may assess fees during swaps and liquidity operations:

• Token hooks (beforeSwap / afterSwap, and liquidity validation hooks)
• Pool hooks (liquidity operation validation, and dynamic LP fee selection in swaps when enabled)
• Position hooks (liquidity operation validation)

General properties:

• Hook calls may revert and therefore block execution.
• Hook fees are generally accrued in core and later collected.
• Some token hook configurations allow fees to be attributed/managed differently (documented in the Hooks section).

This section does not redefine hook fee denomination tables; those are specified in the token hook docs.

---

Pool-level fees and protocol fee configurations

LBAMM supports protocol fee configurations that can apply at multiple levels, including:

• Minimum fee rates on specific token hops (configured per hop; default none)
• Global protocol fees on:
  • LP fees
  • Exchange fees
  • Fee-on-top fees (defaults 0)
• Overrides for specific:
  • poolId (LP fee protocol fee)
  • exchange fee recipient
  • fee-on-top recipient

Important: This protocol fee surface is likely to be defaulted to zero initially and may evolve. For now, this section describes it at a high level; details are captured in the Fee Surfaces reference page.

---

Flash loan fees

Flash loan fees are governed by the loan token’s flashloan hook, which returns:

• feeToken (may differ from the loan token)
• feeAmount

If the fee token differs from the loan token, the fee token must allow the loan token to use it as a fee currency (via hook validation).

Flash loan fees settle similarly to token hook fees (accrued/managed via the same hook fee accounting model).

---

Observability

The current event surface primarily exposes:

• LP fee amounts on swaps
• Flash loan fee details
• Liquidity add/remove/collect fee fields
• Protocol fee taken events

Notably, there are no events that directly log exchange fee or fee-on-top amounts/recipients today.

---

What’s next in this section

The remainder of this section provides reference pages:

• Fee Surfaces: an exhaustive breakdown of each fee surface (trigger, denomination, recipient, bounds, settlement, and visibility).
• Fee Ordering & Settlement: deterministic ordering rules and settlement semantics across swaps and liquidity operations, including multi-hop considerations.
• Economic Design Patterns: composition patterns enabled by these surfaces (kept separate from the reference spec).