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.

Position Hooks

Position hooks (liquidity hooks) allow position-scoped policy to be enforced for liquidity operations.

Unlike token hooks (global per token) and pool hooks (scoped per pool), a position hook is part of the identity of a position and is applied to:

• Adding liquidity
• Removing liquidity
• Collecting LP fees

This page documents:

• How position hooks attach to positions
• Which functions can be invoked and when
• What context position hooks receive
• What position hooks are allowed to do (and what they are not)

---

What is a position hook?

A position hook is a contract implementing ILimitBreakAMMLiquidityHook that validates liquidity operations for a position.

Position hooks are designed for constraints such as:

• Lockups / vesting / time-based restrictions
• Enforcing that liquidity providers use a specific hook implementation
• Additional fee logic scoped to a position

Position hooks do not change who owns a position.

---

Attachment and identity

Supplied via liquidity operation params

A position hook is specified via:

• LiquidityModificationParams.liquidityHook (add/remove liquidity)
• LiquidityCollectFeesParams.liquidityHook (collect fees)

A zero address indicates no position hook.

Part of the base position identifier

The core AMM derives a base position identifier that includes the position hook address.

Conceptually:

bytes32 basePositionId = keccak256(
    abi.encode(
        provider,
        liquidityHook,
        poolId
    )
);

Because liquidityHook is included:

• The hook is bound to the position’s identity.
• Liquidity operations for that position must use the same hook address to resolve the same base position.

Pool types may derive a final positionId from the base ID and pool-type parameters.

Position hooks observe only the final positionId, not the base position ID.

---

When position hooks run

Position hooks are invoked once per liquidity operation:

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

Position hooks are not invoked for:

• swaps
• pool creation
• flash loans

---

Position hook interface

A position hook implements the following validation functions:

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

Each function:

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

---

Context available to position hooks

Position hooks receive:

• LiquidityContext with:

  • provider
  • token0, token1
  • positionId (final, pool-type-defined)

• Liquidity operation parameters:

  • LiquidityModificationParams or LiquidityCollectFeesParams

Key points:

• provider is the account performing the liquidity operation (the msg.sender of the AMM call).
• Position hooks receive poolId (via liquidity params), but do not receive the pool hook address directly.
• Position hooks can observe fee bounds such as maxHookFee0 and maxHookFee1 from liquidity params.

---

Fees and fee requests

Per-operation hook fees

Position hooks may charge additional fees by returning:

• hookFee0 (denominated in token0)
• hookFee1 (denominated in token1)

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

Requesting fee transfers (queued)

During hook execution, position hooks may call into the AMM to request fee transfers (e.g., collectHookFeesByHook).

Fee transfer requests are:

• queued during execution
• settled after the liquidity operation finalizes
• processed FIFO

---

What position hooks can do

Position hooks are intended for position-scoped constraints, such as:

• Locking liquidity until a timestamp or vesting condition is met
• Enforcing that only certain providers may modify a position
• Enforcing that a specific hook implementation is used for a class of positions

Token hooks may also require that liquidity providers use specific position hooks for a token.

---

What position hooks cannot do

Position hooks do not replace core accounting or pool-type position semantics.

Position hooks must not assume they can:

• Change position ownership
• Modify pool reserves or fee balances directly
• Perform token transfers on behalf of the AMM
• Change liquidity operation parameters
• Partially commit execution (operations remain atomic)

---

Failure semantics

Position hook calls are atomic with the liquidity operation:

• If any position hook reverts, the entire liquidity operation reverts.