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.

Economic Design Patterns

This page describes compositional economic patterns enabled by LBAMM’s fee surfaces.

These are not recommendations.
They are examples of how different fee surfaces can be combined to produce specific economic behavior.

Each pattern is described in terms of:

• Fee surfaces used
• Value flow
• Enforcement boundary
• Risks / invariants

---

Executor-Compensated Routing

Goal

Allow third-party executors (solvers, searchers, relayers) to route orders and be paid deterministically at execution time.

Surfaces Used

• Fee-on-top (execution-level)
• Optional exchange fee
• Token hooks (optional restrictions)

Structure

The executor fee is encoded as:

FlatFeeWithRecipient({
  amount: executorFee,
  recipient: executor
})

This ensures:

• Executor compensation is explicit
• Compensation is paid in tokenIn
• No hidden reward surface exists

Invariants

• Fee-on-top must satisfy swap bounds.
• Execution-level fee applies once (not per hop).
• If a transfer handler enforces signature integrity (e.g., permit-based handler), fee parameters may be constrained by signed order data.

---

Exchange Revenue Model

Goal

Capture a proportional fee for a DEX frontend or routing layer.

Surfaces Used

• Exchange fee (BPS-based)

Structure

BPSFeeWithRecipient({
  BPS: exchangeBps,
  recipient: exchangeTreasury
})

Exchange fee:

• Is applied to execution-level input
• Scales automatically in swap-by-output mode
• Is independent of LP fees

Invariants

• recipient == address(0) requires BPS == 0
• BPS must satisfy mode-specific bounds
• Does not compound across hops

---

Token-Controlled Markets

Goal

Allow a token issuer to enforce economic policy across all swaps.

Surfaces Used

• Token hook swap fees
• Token hook liquidity validation
• Optional minimum protocol hop fees

Structure

Token hook may:

• Charge dynamic swap fees via beforeSwap / afterSwap
• Restrict swap direction or participants
• Enforce liquidity hook usage

Because token hooks observe:

• Executor
• Recipient
• Hop index
• PoolId

They can implement:

• Tiered fee models
• Loyalty pricing
• Whitelist discounts
• Cross-pool invariants

Invariants

• Hook fees accrue in core.
• Excessive hook fees may cause swap limit reverts.
• Enforcement applies per hop.

---

Liquidity Lock + Performance Fee

Goal

Lock liquidity and assess performance-based extraction.

Surfaces Used

• Position hook
• Liquidity operation hook fees

Structure

Position hook:

• Prevents removal before unlock condition
• Assesses fee during removeLiquidity or collectFees

Hook fees are bounded by:

• maxHookFee0
• maxHookFee1

Total hook fees are aggregated across all hooks before enforcement.

Invariants

• Hooks are unaware of each other’s returns.
• Enforcement applies to aggregated totals.
• Withdrawal may be reduced by hook fees.

---

Pool-Specific Access Markets

Goal

Create a pool that restricts who may provide liquidity or access swaps.

Surfaces Used

• Pool hook validation
• Dynamic LP fee selection

Structure

Pool hook may:

• Revert unauthorized liquidity additions
• Select LP fee dynamically based on execution context
• Charge liquidity operation hook fees

Because dynamic LP fee selection occurs at swap-time:

• Pool can express price discrimination
• Fees may vary per executor or route

Invariants

• Dynamic LP fee must satisfy core bounds.
• Pool hook cannot modify reserves directly.
• Execution remains atomic.

---

Protocol Revenue Capture

Goal

Allow protocol-level capture of revenue from multiple surfaces.

Surfaces Used

• Protocol fee on LP fees
• Protocol fee on exchange fee
• Protocol fee on fee-on-top
• Minimum hop fee configuration

Protocol fee configuration may be:

• Global
• Overridden per poolId
• Overridden per exchange fee recipient
• Overridden per fee-on-top recipient

Invariants

• Defaults may be zero.
• Protocol fee rates are queryable.
• Protocol fee events are emitted when taken.
• Protocol fee does not alter ordering semantics.

---

Affiliate Routing Model

Goal

Reward referrers or affiliates without altering pool math.

Surfaces Used

• Fee-on-top
• Exchange fee (split via multiple routes)
• Token hook contextual logic

Structure options:

1. Affiliate as feeOnTop.recipient
2. Affiliate as exchange fee recipient
3. Affiliate logic embedded in token hook

This allows:

• Explicit affiliate compensation
• No changes to pool-level pricing
• Deterministic visibility of payout

---

Compliance-Gated Liquidity

Goal

Allow liquidity provision or swaps only under specific compliance conditions.

Surfaces Used

• Token hooks
• Position hooks
• Pool hooks

Hooks may:

• Revert on unauthorized executor
• Enforce use of a specific liquidity hook
• Charge additional fees for non-compliant actors

Economic control becomes programmable policy.

---

Multi-Hop Controlled Markets

Goal

Ensure fee behavior is stable across routes.

Surfaces Used

• Execution-level fees (once)
• Per-hop LP fees
• Per-hop token hook fees

Design principle:

• Exchange fee and fee-on-top apply once
• LP and token hook swap fees apply per hop

This separation ensures:

• No compounding of execution-level fees
• Predictable total cost modeling
• Safe route simulation

---

Anti-MEV or Route-Specific Pricing

Goal

Charge different economics based on executor identity or route characteristics.

Surfaces Used

• Token hook swap logic
• Pool hook dynamic LP fee

Hooks observe:

• Executor
• Hop index
• PoolId
• Recipient

This allows:

• MEV-aware fee structures
• Route-based pricing adjustments
• Contextual rebates

---

Design Principles Across Patterns

Across all patterns:

1. Execution-level fees are applied once.
2. LP fees are hop-scoped.
3. Hook fees accrue and settle post-operation.
4. Liquidity hook fees are bounded by aggregated max limits.
5. All operations remain atomic.
6. No fee surface is implicit.

---

What This Page Does Not Do

This page does not:

• Prescribe recommended fee values
• Suggest governance structures
• Define economic policy

It demonstrates composability enabled by the protocol.