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.

Pool Hooks

Pool hooks allow pool-specific policy and dynamic behavior to be expressed per pool, without forking pool math or modifying the core AMM.

A pool hook is configured at pool creation time via PoolCreationDetails.poolHook and becomes part of the pool’s stored state.

This page documents:

• How pool hooks are configured
• Which pool hook functions can be invoked and when
• Dynamic LP fee selection via the pool hook
• What pool hooks are allowed to do (and what they are not)

For hook ordering relative to token and position hooks, see the call-order reference.

---

Configuration and lifecycle

Attachment

A pool hook is specified during pool creation:

• PoolCreationDetails.poolHook

The pool state stores the hook address:

struct PoolState {
    address token0;
    address token1;
    address poolHook;
    uint128 reserve0;
    uint128 reserve1;
    uint128 feeBalance0;
    uint128 feeBalance1;
}

Mutability

Pool hooks are configured once at creation time and are not updated afterward.

Scope

Pool hooks apply only to operations that interact with a pool:

• Pool creation
• Liquidity operations on that pool
• Swap fee selection for that pool when dynamic fees are enabled

Pool hooks are not invoked for directSwap (no pool interaction).

---

Pool hook interface

A pool hook implements ILimitBreakAMMPoolHook and may receive calls for:

• Pool creation validation
• Dynamic pool fee selection (optional, only for dynamic-fee pools)
• Liquidity operation validation and per-operation fee assessment

Notably, pool hooks are not used as general before/after swap validators. The only swap-time pool hook invocation is for dynamic pool fee selection.

---

When pool hooks run

Pool creation

A pool hook is validated when a pool is created with that hook address:

• validatePoolCreation(poolId, creator, details, hookData)

The hook must revert to block pool creation.

---

Swaps: dynamic LP fees only

Pool hooks participate in swaps only when the pool was created with the dynamic fee sentinel.

In that case, the AMM calls:

• getPoolFeeForSwap(context, poolFeeParams, hookData)

If a pool was created with a fixed LP fee, the pool hook is not invoked during swaps.

Dynamic fee sentinel

To opt into hook-driven dynamic LP fees, the pool must be created with a sentinel LP fee value:

uint16 constant DYNAMIC_POOL_FEE_BPS = 55_555;

When this sentinel value is used, the pool hook returns the effective fee rate (in basis points) for the swap.

Fee bounds enforced by core

The AMM enforces strict upper bounds on the returned fee:

• Input-based swaps: poolFeeBPS <= 10_000
• Output-based swaps: poolFeeBPS < 10_000

Pool hooks may compute fees based on any available context, including executor, recipient, hop index, tokens, pool, and swap direction.

---

Liquidity operations

Pool hooks may validate and assess fees during liquidity operations:

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

These functions:

• must revert to block the operation
• may return hookFee0 and hookFee1 to charge additional fees to the provider

Fees returned by pool hooks are allocated to the hook in the AMM and must be collected by the hook.

---

Context available to pool hooks

Pool hooks reuse the same core context types used across the protocol:

• LiquidityContext for liquidity operations (provider, token pair, positionId)
• LiquidityModificationParams / LiquidityCollectFeesParams for operation parameters
• SwapContext and HookPoolFeeParams for dynamic fee selection

Pool hooks therefore have enough information to:

• Restrict who may access a pool for liquidity provision
• Restrict or validate certain swap activity (when expressed via fee selection and/or pool creation / liquidity constraints)
• Implement dynamic fees conditioned on execution metadata

---

What pool hooks can do

Enforce pool-scoped policy

Pool hooks commonly enforce pool-scoped rules such as:

• Who may add/remove liquidity
• Pool access control (allow/deny specific providers)
• Constraints tied to pool parameters or pool identity

Pool hooks may also influence swap activity indirectly by:

• Rejecting pool creation for undesirable configurations
• Restricting liquidity provisioning
• Returning dynamic LP fees that depend on execution context

Assess hook fees on liquidity operations

Pool hooks may charge additional fees from the liquidity provider by returning hookFee0 and/or hookFee1 during liquidity operations.

Request fee transfers (queued)

During liquidity hook execution, pool hooks may call into the AMM to request fee transfers.

• Requests are queued during execution
• Settled after the liquidity operation finalizes
• Processed FIFO

---

What pool hooks cannot do

Pool hooks do not replace pool math or core accounting.

Pool hooks must not assume they can:

• Modify pool reserves or fee balances directly
• Perform token transfers on behalf of the AMM
• Change swap parameters (path, recipient, amounts)
• Validate arbitrary swap execution via before/after swap callbacks (except dynamic fee selection when enabled)

---

Failure semantics

Pool hook calls are atomic with the operation:

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

This applies to pool creation, liquidity operations, and dynamic fee selection.