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.

Writing Safe Hooks

This page documents the engineering constraints hook authors must follow to remain safe and composable within LBAMM’s execution model.

Hooks execute inside a single atomic execution context. If a hook reverts, the entire execution reverts. Improper hook design can break integrations, cause unexpected reverts, or introduce economic inconsistencies.

Read Hook Call Order & Context before implementing a hook.

---

Understand what you are allowed to call

During hook execution, the only state-changing AMM call that hooks are intended to perform is:

• collectHookFeesByHook(...)

Hooks may call back into the AMM for view functions.

This constraint is intentional:

• It preserves execution atomicity
• It prevents hooks from mutating pool state mid-validation
• It reduces reentrancy and state-inconsistency risk

If you need additional stateful interactions, design them as part of the main execution flow rather than invoking them from inside hook callbacks.

---

Fee-side semantics for token swap hooks

Token swap hooks (beforeSwap and afterSwap) return a fee amount. The token the fee is denominated in depends on:

• whether the swap is input-based (swapByInput) or output-based (swapByOutput)
• whether the hook is beforeSwap or afterSwap

Fee denomination truth table

Swap type	beforeSwap fee is denominated in	afterSwap fee is denominated in
swapByInput	tokenIn	tokenOut
swapByOutput	tokenOut	tokenIn

This is a common source of mistakes. If a hook assumes the wrong side, it may:

• apply fees to an unintended token
• cause swaps to revert due to insufficient available amounts
• mis-estimate net settlement for the executor/recipient

---

Required vs supported flags

Token hooks declare configuration capabilities via:

• requiredFlags — flags that must be enabled
• supportedFlags — flags that may be enabled

A practical pattern:

• Mark before/after swap hooks as supported but not required when your logic needs both in some cases, but can safely operate with only one in others.

This avoids forcing token owners into enabling callbacks they do not need, while still allowing advanced enforcement when desired.

---

Avoid fee overconsumption across hooks

Multiple hooks can assess fees during a single execution (token hooks, pool hooks, and position hooks).

If fees collectively overconsume the available input/output amounts, operations may revert.

Guidelines:

• Keep hook fees bounded and predictable

• Use user-supplied bounds where available (e.g., maxHookFee0/maxHookFee1 on liquidity ops)

• Consider how fees stack across:

  • token hook swap fees
  • pool/position hook liquidity fees
  • queued hook-fee transfer requests

---

Liquidity operations and transfer failures

For liquidity operations, LBAMM may record failed token transfers as debt rather than reverting.

Important boundaries:

• This applies only when a token transfer fails during a liquidity operation.

• It is distinct from hook reverts:

  • If a hook reverts, the entire operation reverts.

Hook authors should avoid assuming that passing validation implies transfers will succeed for non-standard ERC-20s.

(Details of the debt mechanism and its accounting are documented in the liquidity operation reference.)

---

Keep hooks cheap and deterministic

The protocol does not force a specific gas budget for hooks, but hook authors should assume:

• Hooks run on the hot path of swaps and liquidity operations
• Expensive hooks will degrade UX and can become a practical DoS vector

Practical guidance:

• Avoid unbounded loops and dynamic per-user iteration
• Treat external calls as potentially fragile and expensive
• Prefer constant-time checks and compact calldata formats