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.

AMM Standard Token Hook

The AMM Standard Token Hook is a first-party token hook intended for token issuers who want simple, issuer-controlled constraints on how their token can be used inside LBAMM (swaps, pool creation, liquidity adds).

It is composed of two contracts:

1. Creator Hook Settings Registry — the source of truth and issuer-facing configuration surface.
2. AMM Standard Hook — the token hook address set on LBAMM core, which enforces settings during execution and maintains local caches updated by the registry.

This page documents how to use the hook and what it enforces. For ABI-level details, see:

• Reference → Core Interfaces (Registry + Hook)
• Reference → Contract Registry (canonical addresses)

---

Mental model

LBAMM core is hook-agnostic

LBAMM core does not “understand” issuer settings beyond:

• which token hook to call, and
• which hook flags are enabled for that token.

All issuer policy lives in the AMM Standard Hook (enforcement) and the Settings Registry (configuration).

Registry is the configuration system of record

Token issuers set policy in the registry. The registry then pushes updates to one or more hook implementations (including the AMM Standard Hook) via explicit sync calls.

Hook switching is a first-class workflow

Issuers can switch token hooks in the future. The intended path is:

1. configure settings in the registry (and sync them to the new hook),
2. then point LBAMM core at the new token hook.

---

Who can administer settings?

A caller may update a token’s registry settings if they are:

• the token contract itself, or
• the token contract owner() (ERC-173/Ownable-style), or
• the token’s DEFAULT_ADMIN_ROLE (AccessControl-style)

The registry is canonical (one per chain).

---

Setup and lifecycle

Initial setup (enable the AMM Standard Hook)

Step A — configure the registry Call the registry to set your HookTokenSettings and push them to the AMM Standard Hook.

Conceptually:

• registry.setTokenSettings(token, settings, ..., hooksToSync=[ammStandardHook])

Step B — enable on LBAMM core Call setTokenSettings on LBAMM core to set:

• the token hook address = AMM Standard Hook
• the token’s packed settings bits (hook flags you want enabled)

Important: if no relevant hook flags are enabled for a token, the hook is effectively inert (none of its enforcement runs).

Updating settings after launch

To update issuer policy:

1. update settings in the registry, and push updates to the AMM Standard Hook via hooksToSync
2. if you need to change which hook callbacks run, update LBAMM core token settings bits (hook flags)

Switching hooks safely

Recommended order:

1. Update registry settings and push/sync them to the new hook implementation
2. Call LBAMM core setTokenSettings to switch tokenHook to the new hook address

---

What the hook enforces

The AMM Standard Hook enforces different constraints depending on which hook functions are enabled via core flags.

beforeSwap

beforeSwap may:

• Block swaps when:

  • the pool is disabled (per-pool disable flag is set by either token)
  • trading is paused (global pause for the token)
  • direct swaps are blocked (blockDirectSwaps = true)
  • a direct swap uses a pairing token not on the paired-token whitelist (if configured)
  • the pool price is outside the configured price bounds (if set), unless the swap “heals” the price (see Price Bounds)

• Apply token-imposed swap fees Fees are computed from the hook’s settings using the swap direction and whether the hook is being invoked for the input token or output token side.

afterSwap

afterSwap repeats many of the same validity checks and may also apply fees.

Why both? Two reasons:

• some constraints depend on post-swap price (“did the swap move price back into bounds?”)
• fee logic may depend on amounts that are only final after swap fill

validateHandlerOrder (handler-controlled)

This function is not called by LBAMM core. A transfer handler may call it (e.g., at order creation time) if it wants the token’s hook to validate an order’s implied price.

AMM Standard Hook behavior:

• If price bounds are configured, it validates the order is within bounds using amountIn/amountOut by deriving the implied sqrtPriceX96.

validateAddLiquidity

May block add-liquidity when:

• the pool is disabled
• an LP whitelist is configured and provider is not whitelisted
• the pool price is outside bounds (with the same “healing” behavior where applicable)

validatePoolCreation

May block pool creation when:

• a pool type whitelist is configured and the pool type is not allowed
• the LP fee rate is outside [minFeeAmount, maxFeeAmount]
• the paired token is not allowed (paired-token whitelist)
• initial pool price is outside configured bounds (if bounds are set)
• an LP whitelist is configured and the pool creator is not whitelisted

beforeFlashloan

If enabled, this hook always reverts. Practically:

• enabling the beforeFlashloan flag = “disable flashloans for this token”

validateFlashloanFee

If enabled, this hook always reverts. Practically:

• enabling validateFlashloanFee = “disallow using this token as the fee-payment token for flashloans”

---

Swap fee semantics

The AMM Standard Hook’s swap fee selection uses two axes:

• Mode: inputSwap (swap-by-input) vs output-based
• Side: whether the hook is invoked for the input token (hookForInputToken = true) or the other side

It selects one of four fee settings:

• tokenFeeBuyBPS: Fee rate assessed on token when buying (paired token in, token out)
• tokenFeeSellBPS: Fee rate assessed on token when selling (token in, paired token out)
• pairedFeeBuyBPS: Fee rate assessed on paired token when buying (paired token in, token out)
• pairedFeeSellBPS: Fee rate assessed on paired token when selling (token in, paired token out)

Where fees accrue and how they are collected

AMM Standard Hook does not manage fees itself.

Fees accrue to the token and are claimable via LBAMM core:

• collectHookFeesByToken(tokenFor, tokenFee, recipient, amount)

Parameters:

• tokenFor - Address of the token that fees belong to.
• tokenFee - Address of the token the fees are denominated in.
• recipient - Address to receive the fees.
• amount - Amount of fees to transfer to recipient.

Only the token contract, owner, admin, or an account assigned the LBAMM_TOKEN_FEE_COLLECTOR_ROLE may collect.

---

Pool disabling vs trading pause

These are different controls with different blast radius:

Disable a specific pool

Registry: setPoolDisabled(token, poolId, disable)

• Either token in the pool can disable it.
• A pool is treated as disabled if either token has disabled it.
• If both tokens disable, both must re-enable.

Effect:

• trading in that pool is blocked
• liquidity withdrawal remains possible (so “disable pool” is not a hostage mechanism)

The registry verifies token is one of the pool’s tokens by checking pool state in LBAMM core.

Pause trading globally for a token

Registry: set tradingIsPaused = true in HookTokenSettings

Effect:

• blocks trading across all pools involving this token
• still allows liquidity add/remove/fee collection (i.e., it is a trading pause, not a full freeze)

---

Price bounds

Price bounds are configured per (token, pairToken):

• (minSqrtPriceX96, maxSqrtPriceX96) in Q96 sqrt price space
• bounds may be unset by setting both min/max to 0

Enforcement phases

The hook checks bounds:

• pre-swap and post-swap
• during pool creation (initial price)
• during add-liquidity validation
• for handler order validation (derived from amountIn/amountOut)

“Healing” behavior

If the current price is out of bounds, the hook may still allow a swap if it moves price toward the configured range (i.e., a swap that “heals” an out-of-range market).

Multiple allowed pair tokens

If you allow multiple pair tokens, bounds are configured independently per pair token. Issuers should set bounds for every pair token they want enforced.

---

Whitelists and cache synchronization

The registry manages list ownership + membership. Lists are referenced from HookTokenSettings by ID:

• poolTypeWhitelistId
• pairedTokenWhitelistId
• lpWhitelistId

0 means “no restriction”.

Important: settings sync vs membership sync

When you call setTokenSettings(..., hooksToSync=...), the registry syncs the HookTokenSettings struct (including list IDs) to the hook, but it does not necessarily sync the full membership content of referenced lists.

Membership updates are synced to hooks via explicit calls when you update lists. For example:

• updatePairTokenWhitelist(...) calls hook.registryUpdateWhitelistPairToken(listId, tokens, add)
• updatePoolTypeWhitelist(...) calls hook.registryUpdateWhitelistPoolType(listId, poolTypes, add)
• updateLpWhitelist(...) calls hook.registryUpdateWhitelistLpAddress(listId, accounts, add)

Behavior on stale caches

The hook enforces based on its known whitelist state. If you depend on strict allow/deny behavior, make list updates and hook sync part of your operational playbook.

---

Settings reference (HookTokenSettings)

• initialized: registry has initialized settings for this token
• tradingIsPaused: block trading for this token across pools
• blockDirectSwaps: prevent directSwap paths involving this token
• checkDisabledPools: enforce per-pool disable checks against registry state
• tokenFeeBuyBPS / tokenFeeSellBPS: fees applied depending on direction/side
• pairedFeeBuyBPS / pairedFeeSellBPS: fees applied depending on direction/side
• minFeeAmount / maxFeeAmount: bounds on LP fee rate at pool creation
• poolTypeWhitelistId: restrict pool types allowed for this token
• pairedTokenWhitelistId: restrict pairing tokens allowed
• lpWhitelistId: restrict liquidity providers / pool creators (where enforced)

---

Common integration implications

Routers become the executor

If a router calls LBAMM, hooks see the router as executor. Tokens may restrict execution based on that identity. Design your integration accordingly.

Direct swaps are not “always available”

If blockDirectSwaps is enabled, directSwap paths will revert for this token.

Bounds are in sqrtPriceX96 (Q96)

Bounds are expressed in sqrt price format; ensure your issuer tooling and UI present this safely.