This describes a pre-release version of LBAMM. Interfaces and behavior may change.
Verify the exact repository commit before building production integrations.
Custom Pool Types
Custom pool types define the liquidity model, pricing logic, and position accounting rules for a pool.
LBAMM separates responsibilities clearly:
Core:
- Holds reserves and fee balances
- Executes hooks
- Transfers tokens
- Enforces invariants
- Validates protocol fees
Pool Types:
- Implement swap math
- Implement liquidity math
- Manage pool-specific state
- Derive position identifiers
Pool types never custody reserves. Core is always the balance authority.
Pool Type Interface
All pool types must implement ILimitBreakAMMPoolType.
Core vs Pool Type Responsibilities
Core Guarantees
Core exclusively manages:
- reserve0 / reserve1
- feeBalance0 / feeBalance1
- Protocol fee storage
- Hook execution ordering
- Token transfers
- Partial fill rules
- Swap invariant validation
Pool types must never attempt to transfer tokens or maintain shadow reserve balances.
Pool Type Responsibilities
Pool types are responsible for:
- Deterministic swap calculation
- Deterministic liquidity accounting
- Position ID derivation
- Internal state management
- Optional dynamic pricing logic
- Returning correct LP and protocol fee amounts
Pool types are stateful contracts. They may:
- Store internal liquidity model state
- Store oracle observations
- Adjust pricing based on volatility
- Decode and use swapExtraData
- Read view functions from the AMM core
They may not mutate core storage.
Pool ID Encoding
poolId is a packed value:
- Bits 0 – 15 → Pool fee in BPS
- Bits 16 – 143 → Creation details hash
- Bits 144 – 255 → Pool type address (must have 6 leading zero bytes)
Requirements:
- Pool type address must be encoded in upper 112 bits
- Fee must be encoded in lower 16 bits
- Creation hash must ensure deterministic uniqueness
Multiple pools may share the same token pair but differ by:
- Pool type
- Fee
- Pool parameters
Swap Model
Core determines swap direction and applies hook logic.
Pool types compute swap outputs.
Input Swap:
- May partially fill only on first hop
- Must return actualAmountIn, amountOut, feeOfAmountIn, protocolFees
- Must ensure total fees do not exceed amountIn
Output Swap:
- Must return actualAmountOut, amountIn, feeOfAmountIn, protocolFees
- Requires poolFeeBPS < 10000
- 10000 BPS would zero the effective input and break reverse calculation
Core validates:
- Total fee bounds
- Protocol minimum enforcement
- Reserve safety
- Dynamic fee bounds
SwapContext
Pool types receive contextual information including:
- Executor identity
- Transfer handler
- Exchange fee configuration
- Fee-on-top configuration
- Final recipient
- Hop count
Pool types may use this for:
- Context-aware pricing
- Compliance-aware liquidity
- Oracle adjustments
- Executor-dependent logic
Or ignore it entirely.
Liquidity & Position Model
Core derives a stable base position ID from: provider, liquidityHook, and poolId.
Pool types must deterministically derive positionId from:
- ammBasePositionId
- poolParams
- Internal rules
The same derivation must succeed for:
- addLiquidity
- removeLiquidity
- collectFees
Dynamic Fees
If pool fee equals the dynamic sentinel value,
Core queries the pool hook for the fee.
Dynamic fee must:
- Be deterministic relative to state
- Be strictly less than 10000 BPS
- Preserve swap invariants
Protocol Fee Storage
Single swap:
- Accumulates protocol fee in memory
- Stored once at finalization
Multi-hop:
- Stored per hop
- Required because input token changes
getCurrentPriceX96
Allows integrations to query price without reproducing pool logic.
The pool type may:
- Compute from internal state
- Derive from reserves
- Incorporate oracle adjustments
poolTypeManifestUri
Each pool type exposes a manifest URI describing:
- Liquidity model
- Swap model
- Required poolParams
- Required swapExtraData
- Dynamic fee behavior
- Position derivation rules
If the URI changes, the pool type must emit: PoolTypeManifestUriUpdated(string uri)
Design Philosophy
LBAMM separates:
- Execution math (pool type)
- Settlement authority (core)
Core is the settlement layer.
Pool types are deterministic execution modules.