https://apptokens.com/assets/js/ace26a2a.b4fc3868.js

1"use strict";(self.webpackChunkapptokens=self.webpackChunkapptokens||[]).push([[4602],{2424:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>c});const t=JSON.parse('{"id":"integration-guide/limit-break-amm/protocol-fundamentals","title":"Protocol Fundamentals","description":"This describes a pre-release version of LBAMM. Interfaces and behavior may change.","source":"@site/docs/integration-guide/limit-break-amm/protocol-fundamentals.md","sourceDirName":"integration-guide/limit-break-amm","slug":"/integration-guide/limit-break-amm/protocol-fundamentals","permalink":"/docs/integration-guide/limit-break-amm/protocol-fundamentals","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"Protocol Fundamentals","sidebar_label":"Protocol Fundamentals","sidebar_position":2},"sidebar":"tutorialSidebar","previous":{"title":"Design Goals & Guarantees","permalink":"/docs/integration-guide/limit-break-amm/intro/design-goals-guarantees"},"next":{"title":"Hooks","permalink":"/docs/integration-guide/limit-break-amm/hooks/"}}');var s=i(4848),l=i(8453);const o={title:"Protocol Fundamentals",sidebar_label:"Protocol Fundamentals",sidebar_position:2},r="Fundamentals",a={},c=[{value:"What is an execution?",id:"what-is-an-execution",level:2},{value:"Execution context",id:"execution-context",level:2},{value:"Canonical actors",id:"canonical-actors",level:3},{value:"Routing and hops",id:"routing-and-hops",level:2},{value:"Multi-hop swaps",id:"multi-hop-swaps",level:3},{value:"Nested operations",id:"nested-operations",level:2},{value:"Deferred fee collection",id:"deferred-fee-collection",level:3},{value:"Direct swaps",id:"direct-swaps",level:2},{value:"Flash loans",id:"flash-loans",level:2},{value:"Failure semantics",id:"failure-semantics",level:2},{value:"Partial fills",id:"partial-fills",level:3},{value:"What the execution model guarantees",id:"what-the-execution-model-guarantees",level:2},{value:"What it does not guarantee",id:"what-it-does-not-guarantee",level:2}

1,{value:"Why this matters",id:"why-this-matters",level:2}];function d(e){const n={a:"a",admonition:"admonition",blockquote:"blockquote",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",strong:"strong",ul:"ul",...(0,l.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.admonition,{title:"Pre-Release Documentation",type:"warning",children:[(0,s.jsx)(n.p,{children:"This describes a pre-release version of LBAMM. Interfaces and behavior may change."}),(0,s.jsx)(n.p,{children:"Verify the exact repository commit before building production integrations."})]}),"\n",(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"fundamentals",children:"Fundamentals"})}),"\n",(0,s.jsxs)(n.p,{children:["This page defines what an ",(0,s.jsx)(n.strong,{children:"execution"})," is in LBAMM, how execution context is constructed, and what guarantees hooks, pools, and integrators can rely on."]}),"\n",(0,s.jsxs)(n.p,{children:["It builds directly on the canonical vocabulary defined in ",(0,s.jsx)(n.a,{href:"./intro/concepts-terminology",children:"Concepts & Terminology"}),". Everything else in the protocol\u2014hooks, pools, routing semantics, and integrations\u2014builds on this execution model."]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"what-is-an-execution",children:"What is an execution?"}),"\n",(0,s.jsxs)(n.p,{children:["An ",(0,s.jsx)(n.strong,{children:"execution"})," is a single top-level call into LBAMM core via one of its external entrypoints, such as:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Pool creation"}),"\n",(0,s.jsx)(n.li,{children:"Swaps (single-hop, multi-hop, or direct)"}),"\n",(0,s.jsx)(n.li,{children:"Liquidity addition or removal"}),"\n",(0,s.jsx)(n.li,{children:"Fee collection"}),"\n",(0,s.jsx)(n.li,{children:"Flash loans"}),"\n",(0,s.jsx)(n.li,{children:"Token settings updates by issuers"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"An execution:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Begins at the start of the external call to LBAMM"}),"\n",(0,s.jsx)(n.li,{children:"Ends when that call completes (successfully or via revert)"}),"\n",(0,s.jsxs)(n.li,{children:["May span ",(0,s.jsx)(n.strong,{children:"multiple pools and tokens"})]}),"\n",(0,s.jsxs)(n.li,{children:["Shares a ",(0,s.jsx)(n.strong,{children:"single execution context"})," throughout its lifetime"]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["There is exactly ",(0,s.jsx)(n.strong,{children:"one active execution context"})," at a time."]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"execution-context",children:"Execution context"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.strong,{children:"execution context"})," is the shared, non-spoofable state constructed by LBAMM core that describes who is acting and how an operation is being performed."]}),"\n",(0,s.jsx)(n.p,{children:"It is:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Created at the beginning of the external LBAMM call"}),"\n",(0,s.jsx)(n.li,{children:"Destroyed at the end of that call"}),"\n",(0,s.jsx)(n.li,{children:"Immutable for the duration of the execution (except for explicitly scoped, protocol-defined fields)"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"All hooks, pool types, and internal protocol logic observe the same execution context."}),"\n",(0,s.jsx)(n.h3,{id:"canonical-actors",children:"Canonical actors"}),"\n",(0,s.jsx)(n.p,{children:"LBAMM deliberately keeps the set of actors small and explicit."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Executor"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["The ",(0,s.jsx)(n.code,{children:"msg.sender"})," calling into LBAMM"]}),"\n",(0,s.jsx)(n.li,{children:"The primary identity hooks should rely on"}),"\n",(0,s.jsx)(n.li,{children:"Always present and reliable"}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Recipient"})," (optional)"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"An address specified by certain actions (e.g. swaps)"}),"\n",(0,s.jsx)(n.li,{children:"May differ from the executor"}

1),"\n",(0,s.jsx)(n.li,{children:"Included so hooks can allow or restrict specific execution\u2013recipient combinations"}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Non-actor:"})," ",(0,s.jsx)(n.code,{children:"tx.origin"})," is intentionally irrelevant and must not be used for authorization or logic."]}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"routing-and-hops",children:"Routing and hops"}),"\n",(0,s.jsxs)(n.p,{children:["LBAMM itself is the ",(0,s.jsx)(n.strong,{children:"first-class router"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"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."}),"\n",(0,s.jsx)(n.h3,{id:"multi-hop-swaps",children:"Multi-hop swaps"}),"\n",(0,s.jsx)(n.p,{children:"For multi-hop swaps:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"A single execution may traverse multiple pools"}),"\n",(0,s.jsx)(n.li,{children:"The output of one hop becomes the input of the next"}),"\n",(0,s.jsx)(n.li,{children:"The execution context is shared across all hops"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"LBAMM exposes a hop index in execution context with the following properties:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Zero-based"}),"\n",(0,s.jsx)(n.li,{children:"Increments monotonically for each hop within a multi-hop swap"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"This allows hooks to reason about where in a multi-hop route an interaction occurs without introducing an external router abstraction."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"nested-operations",children:"Nested operations"}),"\n",(0,s.jsxs)(n.p,{children:["Some protocol flows are ",(0,s.jsx)(n.em,{children:"logically nested"})," but do ",(0,s.jsx)(n.strong,{children:"not"})," create new executions."]}),"\n",(0,s.jsx)(n.p,{children:"Examples include:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Pool creation that immediately adds initial liquidity"}),"\n",(0,s.jsx)(n.li,{children:"Swaps or liquidity modifications that trigger fee collection"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"These operations:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Occur within the same execution context"}),"\n",(0,s.jsx)(n.li,{children:"Do not reset or replace execution metadata"}),"\n",(0,s.jsx)(n.li,{children:"Must obey all execution guarantees"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"deferred-fee-collection",children:"Deferred fee collection"}),"\n",(0,s.jsx)(n.p,{children:"Hooks may request fee collection during execution."}),"\n",(0,s.jsx)(n.p,{children:"Such requests are:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Queued"})," during execution"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Settled after"})," the primary operation completes"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"For example:"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"A hook on the second hop of a three-hop swap requests fee collection"}),"\n",(0,s.jsx)(n.li,{children:"The second and third hops complete"}),"\n",(0,s.jsx)(n.li,{children:"Input tokens are collected from the executor"}),"\n",(0,s.jsx)(n.li,{children:"Output tokens are sent to the recipient"}),"\n",(0,s.jsx)(n.li,{children:"The queued fee request is settled"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"This ensures fee settlement observes the finalized execution outcome while remaining bound to the same execution context."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"direct-swaps",children:"Direct swaps"}),"\n",(0,s.jsxs)(n.p,{children:["A ",(0,s.jsx)(n.strong,{children:"direct swap"})," is an execution with ",(0,s.jsx)(n.strong,{children:"no pool interaction"}),"."]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Tokens are exchanged directly between two parties"}),"\n",(0,s.jsx)(n.li,{children:"No AMM pricing logic is involved"}),"\n",(0,s.jsx)(n.li,{children:"A transfer handler is typically used"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Despite the absence of pools:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Token hooks fire exactly as they do in pooled swaps"}),"\n",(0,s.jsx)(n.li,{children:"Execution context semantics are identical"}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"flash-loans",children:"Flash loans"}),"\n",(0,s.jsx)(n.p,{children:"Flash loans use the same execution model and context as all other LBAMM operations."}),"\n",(0,s.jsx)(n.p,{children:"During a flash loan:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Token hooks fire to authorize the loan"}),"\n",(0,s.jsx)(n.li,{children:"If the loaned token specifies an alternate fee currency, hooks validate that the fee currency is permitted"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Repayment and fee settlement occur within the same execution context and are subject to the same revert semantics."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"failure-semantics",children:"Failure semantics"}),"\n",(0,s.jsx)(n.p,{children:"Execution-level failure rules are intentionally simple:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["If any hook reverts, ",(0,s.jsx)(n.strong,{children:"the entire execution reverts"})]}),"\n",(0,s.jsx)(n.li,{children:"Partial effects are not committed across execution boundaries"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"partial-fills",children:"Partial fills"}),"\n",(0,s.jsx)(n.p,{children:"Some pool types may support bounded partial fills:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"For example, a partial fill on the first hop of a swap"}),"\n",(0,s.jsx)(n.li,{children:"Always constrained by user-specified parameters (e.g. minimum output)"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Partial fills do not weaken execution atomicity; they are an explicit outcome of pool logic."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"what-the-execution-model-guarantees",children:"What the execution model guarantees"}),"\n",(0,s.jsx)(n.p,{children:"You can rely on the following invariants:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Executor identity is reliable and non-s

1poofable"}),"\n",(0,s.jsx)(n.li,{children:"Execution context is shared across all pools and tokens in an execution"}),"\n",(0,s.jsx)(n.li,{children:"Hooks observe consistent execution metadata"}),"\n",(0,s.jsx)(n.li,{children:"Execution context persists across token transfers triggered by the execution"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"what-it-does-not-guarantee",children:"What it does not guarantee"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"The existence of routers or routing abstractions"}),"\n",(0,s.jsx)(n.li,{children:"That executors are permissionless across all hooks"}),"\n",(0,s.jsx)(n.li,{children:"That all pool types behave identically"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"These distinctions are intentional and enable policy to be expressed explicitly rather than implicitly."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h2,{id:"why-this-matters",children:"Why this matters"}),"\n",(0,s.jsx)(n.p,{children:"By making execution explicit and first-class, LBAMM enables:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Token-level enforcement across venues"}),"\n",(0,s.jsx)(n.li,{children:"Reliable hook behavior without guesswork"}),"\n",(0,s.jsx)(n.li,{children:"Composable pool and liquidity designs"}),"\n",(0,s.jsx)(n.li,{children:"Clear security boundaries for integrators and hook authors"}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Subsequent sections build directly on these guarantees."})]})}function h(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>r});var t=i(6540);const s={},l=t.createContext(s);function o(e){const n=t.useContext(l);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),t.createElement(l.Provider,{value:n},e.children)}}}]);