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.

Hook Call Ordering & Context

This page defines the deterministic hook invocation model for LBAMM.

For each top-level execution type, it specifies:

• Which hooks are invoked
• In what order they are invoked
• What execution context is visible at each stage
• How reverts propagate

All hook invocation occurs within a single execution context constructed by LBAMM core. If any required hook invocation reverts, the entire execution reverts.

---

Shared execution context principles

All hook calls occur within a single LBAMM execution (a single top-level AMM call).

• The authoritative identity is the executor (msg.sender of the AMM call).
• There is no tx.origin / initiator field.
• Hooks may observe a recipient where applicable (e.g. swaps).
• Hook-triggered fee transfers are queued during execution and settled after the primary operation finalizes.

---

Ordering: high-level phases

Hook calls are grouped into phases depending on the operation:

• Pool creation
• Swaps (single-hop, multi-hop)
• Liquidity operations (add/remove/collect)
• Flash loans

Within each operation, LBAMM uses a consistent ordering across hook categories.

---

Pool creation ordering

When creating a pool, the core may invoke:

• Token hooks for token0 and token1 (if TOKEN_SETTINGS_POOL_CREATION_HOOK_FLAG is enabled for the token)
• The pool hook specified by PoolCreationDetails.poolHook (if non-zero)

Canonical order:

1. Token0 hook: validatePoolCreation(..., hookForToken0=true, ...)
2. Token1 hook: validatePoolCreation(..., hookForToken0=false, ...)
3. Pool hook: validatePoolCreation(...)

If any hook reverts, pool creation reverts.

---

Swap ordering

Swaps may be:

• Single-hop (one pool)
• Multi-hop (multiple pools)
• Direct swap (no pool)

Direct swaps

A direct swap has no pool interaction.

• Token swap hooks may run (subject to token settings flags)
• Pool hooks do not run
• Position hooks do not run

Pool-based swaps

For each hop in a swap, token hooks may be invoked for both the hop’s input and output token (subject to flags).

Token hooks are invoked in two phases:

• beforeSwap (if TOKEN_SETTINGS_BEFORE_SWAP_HOOK_FLAG enabled)
• afterSwap (if TOKEN_SETTINGS_AFTER_SWAP_HOOK_FLAG enabled)

Per-hop canonical order:

1. Token hook(s) — beforeSwap

   • Token In hook: beforeSwap(... hookForInputToken=true ...)
   • Token Out hook: beforeSwap(... hookForInputToken=false ...)

2. (Optional) Pool hook dynamic fee selection

   • Only if the pool was created with DYNAMIC_POOL_FEE_BPS (55_555)
   • Calls getPoolFeeForSwap(context, poolFeeParams, hookData)

3. Pool-type swap execution (pricing + reserve/fee accounting)

4. Token hook(s) — afterSwap

   • Token In hook: afterSwap(... hookForInputToken=true ...)
   • Token Out hook: afterSwap(... hookForInputToken=false ...)

If any hook reverts, the swap reverts.

Note: HookSwapParams.hopIndex is zero-based. It increments monotonically for multiSwap and is 0 for a single-hop swap.

Fee settlement during swaps

Token hooks may request hook-fee transfers during beforeSwap/afterSwap.

• Requests are queued during execution
• Swap hops complete
• Input/output token movements finalize
• Queued fee requests settle afterward (FIFO)

---

Liquidity operation ordering

Liquidity operations include:

• addLiquidity
• removeLiquidity
• collectFees

All three operations share the same high-level ordering across hook categories.

Canonical order:

1. Pool type execution of liquidity operation
2. Token hook for token0 then token1
3. Position hook (liquidity hook), if non-zero
4. Pool hook, if non-zero

Token hook invocation

For liquidity operations, token hooks may be invoked for both token0 and token1 of the pool (subject to flags):

• Add liquidity: TOKEN_SETTINGS_ADD_LIQUIDITY_HOOK_FLAG
• Remove liquidity: TOKEN_SETTINGS_REMOVE_LIQUIDITY_HOOK_FLAG
• Collect fees: TOKEN_SETTINGS_COLLECT_FEES_HOOK_FLAG

Token hook functions:

• validateAddLiquidity(...)
• validateRemoveLiquidity(...)
• validateCollectFees(...)

Token hook invocations include a hookForToken0 boolean to indicate whether the call is being performed for the token0 or token1 side.

Position hook invocation

If liquidityHook != address(0), the AMM invokes the position hook:

• validatePositionAddLiquidity(...)
• validatePositionRemoveLiquidity(...)
• validatePositionCollectFees(...)

Pool hook invocation

If poolHook != address(0), the AMM invokes the pool hook:

• validatePoolAddLiquidity(...)
• validatePoolRemoveLiquidity(...)
• validatePoolCollectFees(...)

Fee settlement during liquidity operations

Token, position, and pool hooks may request hook-fee transfers during validation.

• Requests are queued during execution
• The liquidity operation finalizes (reserves/fee balances updated; provider net amounts processed)
• Queued fee requests settle afterward (FIFO)

---

Flash loan ordering

Flash loans are token-hook-governed:

1. Loan-token hook beforeFlashloan(...) (gated by TOKEN_SETTINGS_FLASHLOANS_FLAG)
2. (Optional) Fee-token hook validateFlashloanFee(...) if a different fee currency is specified (gated by TOKEN_SETTINGS_FLASHLOANS_VALIDATE_FEE_FLAG)

Pool and position hooks do not participate in flash loans.

---

Context objects

This section summarizes the primary context objects used by hooks.

SwapContext

SwapContext includes:

• executor
• transferHandler
• exchange-fee recipient and BPS
• fee-on-top recipient and amount
• recipient
• tokenIn, tokenOut
• numberOfHops

HookSwapParams

HookSwapParams includes:

• inputSwap (true for input-based swaps, false for output-based swaps)
• hopIndex
• poolId
• tokenIn, tokenOut
• amount (interpreted based on inputSwap)
• hookForInputToken

LiquidityContext

LiquidityContext includes:

• provider (the account performing the liquidity operation)
• token0, token1
• positionId (final, pool-type-defined)

LiquidityModificationParams and LiquidityCollectFeesParams

Liquidity parameter structs include:

• poolId
• liquidityHook
• bounds for net amounts and hook fees (e.g., maxHookFee0, maxHookFee1)
• pool-type-specific poolParams

---

Notes for integrators

• Hook calls are part of execution atomicity: a revert in any hook reverts the operation.
• Hooks do not move value directly; any hook-fee transfers requested during execution are settled after the primary operation finalizes.
• The executor is always the AMM caller. If you insert an external router, it becomes the executor for hook purposes.

---

Related pages

• Hooks Overview
• Token Hooks
• Pool Hooks
• Position Hooks
• Protocol Fundamentals
• Writing Safe Hooks