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.

Fee Ordering & Settlement

This page defines the deterministic ordering and settlement semantics of fee surfaces in LBAMM.

It separates:

1. Execution-level adjustments
2. Hop-level pool mechanics
3. Hook-level fee accrual
4. Final settlement

This separation is critical for reasoning about multi-hop swaps and composability.

---

Swap Execution Ordering

Swap execution consists of distinct phases.

Execution-Level Adjustments (Applied Once)

Execution-level adjustments apply once per singleSwap or multiSwap call, regardless of hop count.

These include:

• Fee-on-top (flat input adjustment)
• Exchange fee (BPS-based)

Swap-by-Input

Given an input amount X:

1. Fee-on-top is removed from X
2. Exchange fee is computed on the remaining input
3. The resulting net input proceeds into hop execution

Swap-by-Output

Given a target output amount:

1. Pool math determines required net input
2. Exchange fee scales input upward
3. Fee-on-top is added to the required input

These adjustments:

• Do not apply per hop
• Do not compound across route segments
• Apply only at the execution boundary

---

Hop-Level Pool Mechanics (Per Hop)

After execution-level adjustments:

• Swap proceeds hop-by-hop
• Each hop:
  • Applies its LP fee
  • Updates reserves
  • Emits Swap event
  • Produces an output used as the next hop’s input

Execution-level exchange fee and fee-on-top do not reapply at this layer.

---

Token Hook Fees (Per Hop)

For each hop:

1. beforeSwap (if enabled)
2. Pool swap logic
3. afterSwap (if enabled)

Token hook fees:

• Are computed per hop
• May cause swap to revert
• Are accrued in core
• Are not transferred immediately during hook execution

There is no explicit max parameter for swap hook fees, but:

• Hooks cannot overconsume the trade
• Excessive fees may trigger swap limit validation reverts

---

Liquidity Operation Ordering

Liquidity operations (addLiquidity, removeLiquidity, collectFees) follow a deterministic sequence.

Hook Validation Order

1. Token hooks (token0, token1 sides if enabled)
2. Position hook (if provided)
3. Pool hook (if configured)

Each hook may:

• Revert
• Return hook fees

---

Hook Fee Aggregation

For liquidity operations:

• All hook fees for token0 are summed
• All hook fees for token1 are summed
• Final totals are compared against:
  • maxHookFee0
  • maxHookFee1

Hooks are unaware of each other’s fee returns.

Enforcement occurs on the aggregated totals.

---

Netting Semantics

Hook fees may:

• Increase required deposit
• Reduce withdrawal amount

In edge cases:

• A withdrawal may be reduced enough that the provider must supply additional funds

---

Flashloan Ordering

Flashloan execution:

1. Loan token hook beforeFlashloan
   • Returns (feeToken, feeAmount)
2. Optional validation if feeToken differs from loan token
3. Loan is issued
4. Loan is repaid
5. Fee is accounted

Flashloan fee:

• Is accrued using the token-hook fee accounting model
• Emitted via Flashloan event
• Is not subject to explicit protocol cap

---

Settlement Model

LBAMM separates:

• Calculation
• Accrual
• Transfer

Execution Atomicity

All operations are atomic:

• If any hook reverts, the entire operation reverts
• No fee surface partially commits

---

Exchange Fee and Fee-on-Top Settlement

For swaps:

• Exchange fee and fee-on-top are transferred by core
• If a transfer handler is used:
  • Handler must supply total input (including fees)
• If no handler:
  • Input tokens are collected from executor directly

Exchange fee and fee-on-top are not emitted in swap events today.

---

Hook Fee Accrual

Hook fees:

• Are accrued in core balances
• May be collected by the hook later
• May be queued for collection during execution depending on hook configuration

Queued transfers:

• Execute after primary operation finalizes
• Process FIFO
• Cannot interfere with swap/liquidity accounting

---

Protocol Fee Settlement

Protocol fees:

• Are taken according to configured rates
• May apply to:
  • Hop-level token fees
  • LP fees
  • Exchange fee
  • Fee-on-top
• Are emitted via:

event ProtocolFeeTaken(address indexed token, uint256 amount);

Protocol fee accounting is internal but fee rates are queryable.

---

Multi-Hop Invariants

For multiSwap:

• Exchange fee applies once
• Fee-on-top applies once
• Transfer handler (if any) cannot change mid-route
• LP fees apply per hop
• Token hook swap fees apply per hop
• Protocol hop minimum fees (if configured) apply per hop

These invariants prevent compounding of execution-level fees.

---

Key Invariants Summary

• Execution-level fees are applied once.
• LP fees are hop-scoped.
• Hook fees are accrued and settled post-operation.
• Liquidity hook fees are bounded by aggregated max limits.
• Flashloan fees are governed by token hook logic.
• All operations are atomic.