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.

Token Hooks

Token hooks are the mechanism LBAMM uses to enforce token-level policy across all venues, pool types, and execution paths.

A token hook is a single contract configured per token. When enabled, LBAMM invokes the hook at well-defined points (swaps, liquidity operations, pool creation, flash loans, and transfer-handler order validation).

This page documents:

• How token hooks are configured
• Which hook functions can be invoked and when
• What context token hooks receive
• What token hooks are allowed to do (and what they are not)

For the exact invocation ordering relative to pool/position hooks, see the call-order reference.

---

Configuration: setTokenSettings

Token hooks are configured per token via:

setTokenSettings(address token, address tokenHook, uint32 packedSettings)

Authorization

setTokenSettings may only be called by an authorized party for the token:

• The token owner
• A role-based admin
• An account holding LBAMM_TOKEN_SETTINGS_MANAGER_ROLE

Enabling and disabling

• Tokens default to tokenHook = address(0) (no token hook).
• A token hook may be removed by setting tokenHook = address(0).
• When tokenHook is zero, packedSettings must be zero.

Flag negotiation: hookFlags()

A token hook declares its required and supported behavior via:

function hookFlags() external view returns (uint32 requiredFlags, uint32 supportedFlags);

• requiredFlags are flags the token owner must enable for the hook to function correctly.
• supportedFlags are flags the token owner may enable.
• All required flags must be supported.

LBAMM validates the configuration at setTokenSettings time:

• If the token owner enables an unsupported flag → the call reverts.
• If the token owner fails to enable a required flag → the call reverts.

Only 10 bits of the 32-bit packedSettings value are currently consumed by LBAMM for hook gating. The remaining 22 bits are stored by core and may be used by hook developers for token-specific semantics.

The core stores packedSettings and makes it retrievable to hooks (e.g. via getTokenSettings(token)).

---

Hook gating flags

The protocol uses the following flag bits in packedSettings to determine which token hook functions are invoked:

Bit	Constant	Enables
0	TOKEN_SETTINGS_BEFORE_SWAP_HOOK_FLAG	Enables beforeSwap hook validation
1	TOKEN_SETTINGS_AFTER_SWAP_HOOK_FLAG	Enables afterSwap hook validation
2	TOKEN_SETTINGS_ADD_LIQUIDITY_HOOK_FLAG	Enables hook validation during addLiquidity
3	TOKEN_SETTINGS_REMOVE_LIQUIDITY_HOOK_FLAG	Enables hook validation during removeLiquidity
4	TOKEN_SETTINGS_COLLECT_FEES_HOOK_FLAG	Enables hook validation during collectFees
5	TOKEN_SETTINGS_POOL_CREATION_HOOK_FLAG	Enables hook validation during createPool
6	TOKEN_SETTINGS_HOOK_MANAGES_FEES_FLAG	Indicates hook contract manages its own fee collection
7	TOKEN_SETTINGS_FLASHLOANS_FLAG	Enables flash loan operations for the token
8	TOKEN_SETTINGS_FLASHLOANS_VALIDATE_FEE_FLAG	Enables validation when flash loan fees are paid in a different token
9	TOKEN_SETTINGS_HANDLER_ORDER_VALIDATE_FLAG	Enables transfer handler order validation

These flags are evaluated by the core AMM before invoking the corresponding hook functions.

---

Token hook interface

A token hook implements ILimitBreakAMMTokenHook and may receive calls for the following operations:

• Pool creation validation
• Swap validation and per-swap fee assessment
• Liquidity operation validation and per-operation fee assessment
• Transfer-handler order validation
• Flash loan validation and optional cross-token fee validation

The hook must revert to block an operation.

---

When token hooks run

Token hooks run for any token involved in the operation, subject to flags.

Pool creation

For pool creation, token hooks may be called for:

• token0
• token1

Hook function:

• validatePoolCreation(...)

The hook receives:

• creator (the account calling the AMM to create the pool)
• hookForToken0 indicating whether the invocation is for the token0 or token1 side
• PoolCreationDetails containing pool type, fee, token pair, pool hook, and pool params

Swaps (single, multi-hop, direct)

For each hop of a swap, token hooks may be called for:

• the hop’s input token
• the hop’s output token

Hook functions:

• beforeSwap(...) (if enabled)
• afterSwap(...) (if enabled)

Both hooks return a fee amount assessed by the AMM. The fee denomination depends on swap direction and whether the hook is executed before or after the swap.

Liquidity operations

For liquidity operations, token hooks may be called for:

• token0
• token1

Hook functions:

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

These validation functions may return hookFee0 and hookFee1, allowing a hook to charge fees in either or both pool tokens.

Transfer-handler orders

Token hooks may validate transfer-handler orders via:

• validateHandlerOrder(...)

This hook is not called by the AMM core directly. It is invoked by transfer handlers during order creation.

Flash loans

Flash loans involve two possible token-hook interactions:

• beforeFlashloan(...) on the loan token (gated by TOKEN_SETTINGS_FLASHLOANS_FLAG)

  • Authorizes the loan
  • Returns (feeToken, feeAmount)

• validateFlashloanFee(...) on the fee token when a different token is used to pay the fee (gated by TOKEN_SETTINGS_FLASHLOANS_VALIDATE_FEE_FLAG)

  • Validates whether the fee token may be used

---

Context available to token hooks

Token hooks receive rich, non-spoofable context from the AMM core.

Swap context

Swap hooks receive:

• SwapContext (who is executing, who receives output, fee recipients, transfer handler, and swap token pair)
• HookSwapParams (swap direction, hop index, poolId, amounts, and whether this call is for tokenIn vs tokenOut)

Key points:

• Executor is the authoritative identity (msg.sender of the AMM call). There is no tx.origin/initiator field.
• Recipient may differ from executor and is intentionally surfaced so hooks can restrict executor→recipient flows.
• Hop index is zero-based; for multiSwap it increments monotonically per hop (and will be zero for a single-hop swap).
• transferHandler may be present to settle a swap.

Liquidity context

Liquidity hooks receive:

• LiquidityContext including provider, the pool token pair, and the resolved positionId

Token hooks also observe the liquidity hook address via:

• LiquidityModificationParams.liquidityHook
• LiquidityCollectFeesParams.liquidityHook

This allows token hooks to validate which position hook is being used.

---

What token hooks can do

Token hooks are designed to express policy and dynamic behavior.

Enforce policy by reverting

All token hook validation functions must revert to block an operation.

Common uses include:

• Permissioning (who may trade, provide liquidity, or receive tokens)
• Execution-path restrictions (e.g., only certain executors)
• Slippage and parameter validation
• KYC/AML enforcement

Assess hook fees

Token hooks may assess additional fees:

• beforeSwap / afterSwap return a fee amount for swap flows
• Liquidity validation functions may return hookFee0 / hookFee1

Fee allocation depends on token settings. In particular, TOKEN_SETTINGS_HOOK_MANAGES_FEES_FLAG indicates that the hook contract manages its own fee collection.

Request fee transfers (queued)

Token hooks may call into the AMM during hook execution to request fee transfers via:

• collectHookFeesByHook

Fee transfer requests are:

• queued during execution
• settled after the primary operation finalizes
• processed in FIFO order

This prevents fee settlement from interfering with swap or liquidity finalization.

---

What token hooks cannot do

Token hooks are not a substitute for core accounting.

Token hooks must not assume they can:

• Perform or override token transfers performed by the AMM
• Modify pool reserves or fee balances directly
• Change swap parameters (path, recipient, amounts)
• Partially commit execution (all-or-nothing execution still applies)

Hooks can run arbitrary logic within the EVM (including interacting with other contracts), but transfer and accounting semantics remain controlled by the AMM core.

---

Failure semantics

Token hook calls are atomic with execution:

• If any token hook reverts, the entire operation reverts.

This is true for swaps, pool creation, liquidity operations, and flash loans.

---

Related pages

• Hook call ordering and execution context (reference)
• Hook economics (fees, settlement, and accounting)
• Pool hooks
• Position hooks