This describes a pre-release version of LBAMM. Interfaces and behavior may change.
Verify the exact repository commit before building production integrations.
Hooks
Hooks are contracts invoked by LBAMM core at defined execution points to enforce or extend behavior.
They execute within the same execution context as core logic and may revert to block an operation. Hooks do not own reserves or perform settlement; they operate within the execution framework enforced by LBAMM core.
Hooks are the primary extension mechanism in LBAMM. They allow token issuers, pool designers, and integrators to enforce policy and inject dynamic behavior without modifying core AMM logic.
Hooks are attached at defined scopes:
- Token scope (token-global guarantees)
- Pool scope (venue-level constraints)
- Position scope (liquidity-position constraints)
The scope determines when a hook runs and what invariants it may enforce.
Hook invocation timing and context details are specified in Hook Call Order & Context.
What is a hook?
A hook is a contract that is invoked by the LBAMM core at well-defined points during execution.
Hooks may:
- Validate whether an operation is allowed
- Enforce permissions or policy
- Supply dynamic attributes (such as fees or pricing)
- Request fee transfers
Hooks do not:
- Perform token transfers
- Update pool reserves directly
- Override execution atomicity
All value movement and accounting is handled by the LBAMM core.
Hook types
LBAMM supports multiple hook categories that attach at different layers of the protocol. Each category exists to scope responsibility and observability appropriately.
At a high level, hooks may attach at the token, pool, or position level. The precise interfaces, invocation rules, and validation semantics for each hook type are documented in the corresponding hook-type pages.
This page focuses only on the shared model and guarantees that apply to all hooks, regardless of category.
Pool hooks
Attachment: Per pool
Pool hooks are specified at pool creation time via:
PoolCreationDetails.poolHook
Pool hooks observe and validate pool-specific behavior, such as:
- Swap conditions
- Liquidity constraints
- Pool-specific invariants
Position hooks
Attachment: Per position
Position hooks are supplied during liquidity operations via:
LiquidityModificationParams.liquidityHookLiquidityCollectFeesParams.liquidityHook
Position hooks are optional. A zero address indicates no position hook.
They are primarily used to enforce rules around who may modify or collect from a given position.
Hook enablement model
Hooks are invoked only when explicitly enabled by configuration.
- Token-level hooks are gated by a compact settings bitmask supplied at configuration time
- Pool and position hooks are attached explicitly at pool creation or liquidity modification
The protocol enforces compatibility between hooks and their configuration so that unsupported or undefined hook behavior cannot be invoked.
Detailed flag definitions and per-operation behavior are documented in the token hook reference.
Execution context observability
All hooks are invoked with non-spoofable execution context supplied by the LBAMM core.
At a minimum, hooks can reliably observe:
- The executor of the execution
- The action being performed (swap, liquidity modification, fee collection, flash loan)
- Relevant token and pool identifiers
Additional context (such as hop index, recipients, or position identifiers) is provided where applicable and is documented per hook type.
Responsibilities and boundaries
Hooks exist to express policy and dynamic behavior, not to replace core protocol logic.
What hooks are for
Hooks are commonly used for:
- Permissioning and access control
- Validation of execution parameters
- Dynamic attributes such as fees or pricing inputs
What hooks are not for
Hooks must not assume responsibility for:
- Token transfers
- Reserve or fee accounting
- Partial or best-effort execution
All value movement and state updates are performed by the LBAMM core.
Hook-requested fees
Hooks may request fee transfers as part of execution.
- Fee requests are deferred and settled after the primary operation completes
- Fee settlement is performed by the LBAMM core
The mechanics and authorization rules for hook-requested fees are documented in the relevant hook-type sections.
Failure semantics
Hook execution is fully atomic with respect to execution:
- If any hook reverts, the entire execution reverts
- Hooks cannot partially succeed
This guarantees that validation and policy enforcement cannot be bypassed by downstream behavior.
Why hooks are central to LBAMM
By making hooks explicit, scoped, and declarative, LBAMM enables:
- Token-level enforcement across all liquidity venues
- Pool-agnostic policy and validation
- Clean separation between accounting, pricing, and control logic
Subsequent sections document each hook type and its interfaces in detail.
For hook authors
If you are implementing a hook contract, read: