This describes a pre-release version of LBAMM. Interfaces and behavior may change.
Verify the exact repository commit before building production integrations.
Concepts & Terminology
This page is the canonical vocabulary for the LBAMM docs. If a term is unclear later, refer back here.
Core objects
LBAMM core
The protocol contract that:
- Owns reserves and fee balances (pool types never custody reserves)
- Constructs execution context
- Invokes hooks in deterministic order
- Performs token transfers and settlement
- Enforces protocol-level bounds and invariants (fees, limits, atomicity)
Pool
A market between two tokens (token0, token1) with a specific pool type and optional pool hook. Pools are identified by a poolId.
Pool type
A contract that defines the liquidity and pricing mechanics for a pool, including:
- Swap math
- Liquidity accounting math
- Position identifier derivation
Pool types conform to a shared interface and execute under LBAMM core. Core remains the balance authority and settlement layer.
Position
A pool-type-defined representation of liquidity ownership/claims.
- Every position belongs to exactly one pool.
- The economic meaning of a position (ranges, bands, buckets, “height intervals”, etc.) is defined by the pool type.
- Core treats positions as identifiers and enforces standardized settlement + hook validation.
poolId
A bytes32 identifier for a pool. It is derived deterministically by the pool type (conceptually from PoolCreationDetails).
positionId
A bytes32 identifier for a position. Pool types may derive it from core’s base ID plus pool-type-specific parameters.
Base position identifier (AMM base position ID)
A bytes32 derived by core from:
provider(liquidity provider address),liquidityHook(position hook address),poolId.
Because the liquidity hook address is part of the identity, integrators must persist and reuse it for subsequent operations on “the same” position.
Execution model terms
Execution
A single top-level call into LBAMM core (e.g. singleSwap, multiSwap, addLiquidity, removeLiquidity, collectFees, flash loan).
An execution:
- Begins when the external call enters LBAMM core
- Ends when that call returns (successfully or via revert)
- Is atomic: if any required validation or hook invocation reverts, the entire execution reverts
Execution context
The non-spoofable metadata constructed by LBAMM core at the start of an execution and made available to hooks and pool types.
Execution context explicitly encodes:
- The executor (
msg.sender) - The optional recipient (where relevant)
- The hop index (for multi-hop swaps)
- Operation-specific metadata required by the current action
Execution context is shared across the entire execution and cannot be modified by hooks.
Executor
The LBAMM caller (msg.sender) for the current execution.
- The executor is the authoritative identity exposed in execution context.
- There is no
tx.originor “true initiator” concept in core semantics.
Integration implication: if an external router calls LBAMM, that router is the executor for hook-policy purposes.
Recipient
An address specified by certain operations (e.g. swaps) that receives assets as part of the execution.
- May differ from the executor
- Is surfaced in execution context where applicable
Route, hop, and hopIndex
- A route is an ordered sequence of hops (pools) in a
multiSwap. - A hop is one pool interaction inside a route.
hopIndexis zero-based and increments per hop.
Single-hop vs multi-hop
singleSwap: exactly one hop.multiSwap: multiple hops with per-hop fees (LP + token hook swap fees), while execution-level fees apply once.
Hook terminology
Hook
A contract invoked by LBAMM core at defined execution points to enforce or extend behavior.
Hooks may be attached at different scopes:
- Token hooks (token-global policy)
- Pool hooks (pool-wide constraints)
- Position hooks (position-scoped constraints)
Hooks execute within the same execution context as core logic and may revert to block an operation.
Hooks do not:
- transfer tokens on behalf of core,
- mutate core accounting directly,
- partially commit an execution.
Token hook
A single hook configured per token via token settings. Token hooks can run on swaps, pool creation, liquidity ops, transfer-handler order validation, and flash loans (gated by flags).
Pool hook
A hook configured per pool at creation time. Pool hooks:
- validate pool creation / liquidity ops,
- may select dynamic LP fee at swap-time when dynamic fees are enabled.
Position hook (liquidity hook)
A hook configured per position identity (supplied in liquidity operation params). Used for position-scoped constraints like lockups/vesting/permissioning and for liquidity-operation hook fees.
Hook flags / token settings
A token’s hook behavior is gated by a compact bitmask in packedSettings set alongside tokenHook.
- “Required” vs “supported” flags are negotiated via
hookFlags()on the hook contract. - Only a subset of bits are consumed by core; remaining bits may be interpreted by the hook.
hookForToken0 / hookForInputToken
Boolean indicators used in hook calls to disambiguate whether a hook is being invoked for:
- the token0 vs token1 side (liquidity + pool creation), or
- the input-token vs output-token side (swap hooks).
Hook fees (general)
Fees assessed by hooks (token/pool/position) that are:
- accrued in core accounting,
- typically collected later by the hook,
- and may be queued for settlement after the primary operation finalizes.
Swap and order terminology
Swap order (taker intent)
A struct describing “trade X for Y subject to limits” (deadline, tokens, amountSpecified, limitAmount, recipient, etc.). A swap order is executed either against pools or via direct settlement mechanisms.
Swap-by-input vs swap-by-output
- Swap-by-input: user specifies input amount; output is computed and bounded by a minimum/limit.
- Swap-by-output: user specifies desired output amount; required input is computed and bounded by a maximum/limit.
These modes affect fee ordering and caps.
Direct swap
A swap execution that does not interact with a pool. (Token swap hooks may still run; pool hooks do not, because no pool is touched.)
Maker / taker
- Taker: the party submitting an execution against existing liquidity/quotes.
- Maker: the party providing liquidity or posting orders that takers consume.
LBAMM supports both continuous maker liquidity (pools) and discrete maker liquidity (order/handler systems).
Transfer handler terminology
Transfer handler
A settlement module invoked by LBAMM core during swap finalization to supply the swap’s input tokens to the AMM.
- A handler is not a router.
- It receives full swap context and can implement custom settlement flows (e.g., order books).
transferData / transferExtraData
Opaque bytes passed to a handler for handler-specific decoding/logic.
validateHandlerOrder
A token-hook validation function that is not called by core. Handlers may choose to call it during order creation/opening if token policy requires handler-level validation.
Fee terminology (canonical)
LBAMM has multiple fee surfaces. The key vocabulary is:
Execution-level fees
Fees passed to the top-level swap call and applied once per execution, not per hop:
- Exchange fee: BPS-based fee on
tokenIn, paid to an explicit recipient. - Fee-on-top: flat amount in
tokenIn, paid to an explicit recipient. - Executor fee: represented as fee-on-top (no hidden executor reward surface).
Hop-level fees
Fees applied per hop inside a route:
- LP fee: pool-level fee taken by the pool type (fixed or dynamically selected by pool hook).
- Token hook swap fees: token-level fees assessed in
beforeSwap/afterSwapper hop. - Protocol hop minimum fees (if configured): protocol-defined per-hop minimums.
Fee ordering and settlement (high-level)
- Execution-level fees apply once; hop-level fees apply per hop. In
multiSwap, execution-level fees cannot compound across hops. - Hook-requested fee transfers are deferred/queued and settle after the primary operation finalizes.
Fee bounds (terminology)
maxHookFee0/maxHookFee1: caller-supplied bounds that cap how much hook fees may be charged in liquidity operations.- Mode-specific fee caps exist for exchange fee BPS and (in swap-by-input) fee-on-top amount.
Liquidity-operation terminology
Add liquidity / remove liquidity / collect fees
The three core liquidity operations. Core standardizes:
- hook invocation ordering,
- fee bounds enforcement,
- settlement and accounting, while the pool type defines the mechanics and parameters.
Provider
The account performing the liquidity operation (the liquidity “actor” from core’s perspective).
poolParams
Pool-type-specific encoded parameters used to define the meaning of a liquidity operation (e.g., range bounds, “height interval” selection, etc.). Core does not interpret these.
Failure and boundary terminology
Revert vs “tokens owed” (debt)
- If a hook reverts, the entire operation reverts (atomic policy enforcement).
- Separately, some failed token transfers during liquidity settlement may be recorded as tokens owed rather than reverting (non-standard token behavior). This is distinct from hook failures and affects settlement/claim flows.
Determinism
A protocol goal for hook call ordering and context propagation: hooks and integrators should be able to reason about what runs, when, and with what metadata—especially across multi-hop execution.