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.

Fundamentals

This page defines what an execution is in LBAMM, how execution context is constructed, and what guarantees hooks, pools, and integrators can rely on.

It builds directly on the canonical vocabulary defined in Concepts & Terminology. Everything else in the protocol—hooks, pools, routing semantics, and integrations—builds on this execution model.

---

What is an execution?

An execution is a single top-level call into LBAMM core via one of its external entrypoints, such as:

• Pool creation
• Swaps (single-hop, multi-hop, or direct)
• Liquidity addition or removal
• Fee collection
• Flash loans
• Token settings updates by issuers

An execution:

• Begins at the start of the external call to LBAMM
• Ends when that call completes (successfully or via revert)
• May span multiple pools and tokens
• Shares a single execution context throughout its lifetime

There is exactly one active execution context at a time.

---

Execution context

The execution context is the shared, non-spoofable state constructed by LBAMM core that describes who is acting and how an operation is being performed.

It is:

• Created at the beginning of the external LBAMM call
• Destroyed at the end of that call
• Immutable for the duration of the execution (except for explicitly scoped, protocol-defined fields)

All hooks, pool types, and internal protocol logic observe the same execution context.

Canonical actors

LBAMM deliberately keeps the set of actors small and explicit.

• Executor

  • The msg.sender calling into LBAMM
  • The primary identity hooks should rely on
  • Always present and reliable

• Recipient (optional)

  • An address specified by certain actions (e.g. swaps)
  • May differ from the executor
  • Included so hooks can allow or restrict specific execution–recipient combinations

Non-actor: tx.origin is intentionally irrelevant and must not be used for authorization or logic.

---

Routing and hops

LBAMM itself is the first-class router.

There is no protocol-level router abstraction. If third parties introduce routing contracts, they are simply executors calling into LBAMM, and hooks may restrict or block execution based on executor identity.

Multi-hop swaps

For multi-hop swaps:

• A single execution may traverse multiple pools
• The output of one hop becomes the input of the next
• The execution context is shared across all hops

LBAMM exposes a hop index in execution context with the following properties:

• Zero-based
• Increments monotonically for each hop within a multi-hop swap

This allows hooks to reason about where in a multi-hop route an interaction occurs without introducing an external router abstraction.

---

Nested operations

Some protocol flows are logically nested but do not create new executions.

Examples include:

• Pool creation that immediately adds initial liquidity
• Swaps or liquidity modifications that trigger fee collection

These operations:

• Occur within the same execution context
• Do not reset or replace execution metadata
• Must obey all execution guarantees

Deferred fee collection

Hooks may request fee collection during execution.

Such requests are:

• Queued during execution
• Settled after the primary operation completes

For example:

1. A hook on the second hop of a three-hop swap requests fee collection
2. The second and third hops complete
3. Input tokens are collected from the executor
4. Output tokens are sent to the recipient
5. The queued fee request is settled

This ensures fee settlement observes the finalized execution outcome while remaining bound to the same execution context.

---

Direct swaps

A direct swap is an execution with no pool interaction.

• Tokens are exchanged directly between two parties
• No AMM pricing logic is involved
• A transfer handler is typically used

Despite the absence of pools:

• Token hooks fire exactly as they do in pooled swaps
• Execution context semantics are identical

---

Flash loans

Flash loans use the same execution model and context as all other LBAMM operations.

During a flash loan:

• Token hooks fire to authorize the loan
• If the loaned token specifies an alternate fee currency, hooks validate that the fee currency is permitted

Repayment and fee settlement occur within the same execution context and are subject to the same revert semantics.

---

Failure semantics

Execution-level failure rules are intentionally simple:

• If any hook reverts, the entire execution reverts
• Partial effects are not committed across execution boundaries

Partial fills

Some pool types may support bounded partial fills:

• For example, a partial fill on the first hop of a swap
• Always constrained by user-specified parameters (e.g. minimum output)

Partial fills do not weaken execution atomicity; they are an explicit outcome of pool logic.

---

What the execution model guarantees

You can rely on the following invariants:

• Executor identity is reliable and non-spoofable
• Execution context is shared across all pools and tokens in an execution
• Hooks observe consistent execution metadata
• Execution context persists across token transfers triggered by the execution

What it does not guarantee

• The existence of routers or routing abstractions
• That executors are permissionless across all hooks
• That all pool types behave identically

These distinctions are intentional and enable policy to be expressed explicitly rather than implicitly.

---

Why this matters

By making execution explicit and first-class, LBAMM enables:

• Token-level enforcement across venues
• Reliable hook behavior without guesswork
• Composable pool and liquidity designs
• Clear security boundaries for integrators and hook authors

Subsequent sections build directly on these guarantees.