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 Policy Enforcement

LBAMM externalizes liquidity policy to hooks and pool types.

Core provides deterministic execution, identity guarantees, and bounded fee surfaces.
Hooks and pool types provide compliance logic and participation rules.

This page explains how compliance and policy compose across:

• Token hooks
• Position hooks
• Pool hooks

For hook interfaces and execution order, see:

• hooks/hook-types/position-hooks
• liquidity/adding-removing-liquidity

---

Core Guarantees

LBAMM core guarantees:

• provider = msg.sender for liquidity operations
• Deterministic hook ordering (token → position → pool)
• Hook fee bounding via maxHookFee0 / maxHookFee1
• Atomic execution (hook revert = full revert)
• Deferred payout support via tokensOwed when transfers fail

Core does not define compliance rules.
It provides the execution framework within which policy is enforced.

---

Policy Surfaces and Responsibilities

Token Hooks — Token-Global Compliance

Token hooks are the canonical surface for:

• Token-wide compliance guarantees
• Eligibility validation
• Required authorization flows
• Mandatory integration constraints

If a token requires compliance, it should enforce that policy in its token hook so that guarantees remain consistent across all pools and venues.

Token hooks may also require specific liquidity hooks to be used when creating positions.

This requirement can be dynamic.
For example, a token hook may enforce different liquidityHook addresses depending on the provider creating the position. This enables:

• Different compliance programs for different participant classes
• Distinct policy modules for institutional vs. retail providers
• Position-scoped policy variation without altering pool semantics

In this model, the token defines which position-level policy must be bound to each provider.

---

Position Hooks — Position-Scoped Compliance

Position hooks bind policy directly to a specific liquidity position identity:

• Program- or tranche-scoped requirements
• Time-based enablement (e.g., vesting schedules)
• Operator- or custodian-scoped workflows
• Position-specific fee logic

Because liquidityHook is part of the position identity:

• Policy becomes cryptographically bound to that position.
• Supplying a different hook resolves a different position.

Position hooks allow compliant positions to coexist with unrestricted positions for the same token.

---

Pool Hooks — Pool-Level Compliance Isolation

Pool hooks provide pool-wide policy surfaces.

They are well suited for:

• Venue-scoped participation requirements
• Compliance isolation for LPs
• Pools integrating tokens without token hooks
• Application-specific integration guarantees

Pool hooks enable compliant liquidity environments without requiring token-level changes.

---

Composability Model

A liquidity operation may invoke:

• token0 hook
• token1 hook
• position hook
• pool hook

Each layer may:

• Validate eligibility
• Enforce policy
• Return hook fees

Hook fees are bounded by the caller via maxHookFee0 and maxHookFee1.

If bounds are exceeded, the operation reverts.

This preserves predictable economics for liquidity providers.

---

Settlement Considerations

Policy validation and settlement are distinct phases.

If outbound transfers fail during removeLiquidity or collectFees,
the amount is recorded as tokensOwed rather than reverting.

This ensures:

• Policy enforcement remains atomic
• Settlement remains reliable
• Providers can claim owed balances later

Compliance guarantees are preserved even if payout is deferred.

---

Design Guidance for Integrators

When designing compliant liquidity systems:

• Enforce token-global requirements in token hooks.
• Bind program- or position-specific logic in position hooks.
• Use pool hooks for venue-scoped compliance isolation.
• Persist and reuse liquidityHook for each position.
• Bound hook fees.
• Handle potential tokensOwed claims.

Policy in LBAMM is explicit, composable, and opt-in through hooks.

---

Summary

LBAMM separates execution from policy.

Core provides:

• Identity stability
• Deterministic ordering
• Bounded fee surfaces
• Reliable settlement semantics

Hooks and pool types provide:

• Compliance guarantees
• Eligibility validation
• Programmatic participation rules
• Isolation where needed

Liquidity policy is enabled — not imposed — through composable hook architecture.