@eco-incorp/sauce 0.99.0

package/sdk/dist/svm/verify.js

@@ -0,0 +1,303 @@
+// @eco-incorp/sauce/svm/verify — the SVM counterpart of `@eco-incorp/sauce/verify`, for a
+// compiled `settle` program.
+//
+// VERIFICATION IS BY RECOMPILE, on both VMs. A settle program's per-execution values
+// (`minOut`, `splCount`) are compile-time `defines`, constant-folded into the bytecode, and every
+// account identity is an attach slot that never appears in it. So there is nothing to decode OUT of
+// a program — and nothing that needs to be: a caller checking an execution already knows the values
+// it expects. What it needs is proof that the program it was handed IS the one those values produce.
+//
+// `verifySvmSettleProgram` is that proof: recompile `svmSettleSource(N)` with the expected defines
+// and byte-compare. A match establishes THREE things at once — the logic is the genuine settle
+// logic, `minOut` is the expected floor, and `splCount` is the expected token-program split —
+// because all three are folded into the same bytes. Under the older staged form the blob was a pure
+// function of N and the scalars rode the instruction payload, so they had to be decoded and checked
+// separately; binding them into the program is strictly stronger.
+//
+// The account identities are never in the bytecode on SVM in either form — Solana requires them
+// attached — so they come from the executed instruction's account list, matched positionally against
+// `svmSettleRefs(N)`. `decodeSvmSettleExecution` does that half; `verifySvmSettleExecution` adds the
+// recompile check and the pin↔bytecode tie.
+//
+// Unlike `@eco-incorp/sauce/verify`, this pulls the compiler in to recompile — a node-side check.
+import { createHash } from "node:crypto";
+import { compileWithRs } from "../routes/rs-compile.js";
+import { EXECUTE_DISCRIMINATOR, EXECUTE_FROM_ACCOUNT_DISCRIMINATOR } from "./engine.js";
+import { SVM_MAX_ESCROWS, svmSettleRefs, svmSettleSource } from "./recipes/index.js";
+// The intent-level surface (unwrap the Portal envelope + extract from an intent) is re-exported here so
+// the whole partner-facing decode/verify story lives under `@eco-incorp/sauce/svm/verify`, symmetric
+// with the EVM `/verify` barrel re-exporting its own `intent.ts`.
+export { decodePortalCalldataWithAccounts, encodePortalCalldataWithAccounts, extractSvmSettleFromCalls, extractSvmSettleFromIntent, } from "./intent.js";
+/** N escrows declare `3N + 3` accounts (2 token programs + 3 per escrow + the shared owner). */
+function escrowCountFromPlan(metaCount) {
+    if ((metaCount - 3) % 3 !== 0)
+        return null;
+    const n = (metaCount - 3) / 3;
+    return Number.isInteger(n) && n >= 1 && n <= SVM_MAX_ESCROWS ? n : null;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function sha256(bytes) {
+    return new Uint8Array(createHash("sha256").update(bytes).digest());
+}
+/** The canonical settle bytecode for `escrowCount` under `expected`, recompiled from the shipped
+ *  source with the shipped defines — a deterministic function of exactly those three values, and the
+ *  SDK's own ground truth for "what the genuine settle program's bytes are", derivable WITHOUT any
+ *  partner-supplied bytecode. */
+function compileCanonicalSettle(escrowCount, expected) {
+    return compileWithRs({
+        source: svmSettleSource(escrowCount),
+        target: "svm",
+        defines: { SETTLE_MIN_OUT: expected.minOut, SETTLE_SPL_COUNT: expected.splCount },
+    }).bytecode[0];
+}
+/**
+ * Verifies a compiled SVM settle program is genuine AND enforces `expected` — the SVM analogue of the
+ * EVM check, done by recompile. It:
+ *   1. takes the escrow count N (or infers it from the manifest's `3N + 3` slots),
+ *   2. recompiles `svmSettleSource(N)` with `expected` as defines, and
+ *   3. byte-compares the result, and asserts the manifest's slot names equal `svmSettleRefs(N)`.
+ *
+ * A genuine result means the bytecode IS the reusable settle logic for N escrows, compiled for
+ * exactly this floor and this split — all three are the same bytes, so one comparison pins them all.
+ * The resolved account identities (from the executed instruction) remain the caller's own check.
+ * Never throws for a non-genuine program; returns `{ genuine: false, mismatch }`.
+ */
+export function verifySvmSettleProgram(bytecode, manifest, expected) {
+    const slots = manifest.accounts.filter((entry) => entry.kind === "slot");
+    const escrowCount = escrowCountFromPlan(slots.length);
+    if (escrowCount === null) {
+        return {
+            genuine: false,
+            escrowCount: null,
+            refs: [],
+            mismatch: `account manifest has ${slots.length} slots, which is not 3N + 3 for any settle escrow count 1..${SVM_MAX_ESCROWS}`,
+        };
+    }
+    const refs = svmSettleRefs(escrowCount);
+    const slotNames = slots.map((slot) => slot.name);
+    if (slotNames.length !== refs.length || slotNames.some((name, i) => name !== refs[i])) {
+        return {
+            genuine: false,
+            escrowCount,
+            refs,
+            mismatch: `account manifest slots do not match svmSettleRefs(${escrowCount})`,
+        };
+    }
+    if (!bytesEqual(bytecode, compileCanonicalSettle(escrowCount, expected))) {
+        return {
+            genuine: false,
+            escrowCount,
+            refs,
+            mismatch: `bytecode does not byte-match svmSettleSource(${escrowCount}) at minOut=${expected.minOut}, splCount=${expected.splCount}`,
+        };
+    }
+    return { genuine: true, escrowCount, refs };
+}
+function accountAddress(a, i) {
+    const raw = typeof a === "string" ? a : (a.address ?? a.pubkey);
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new Error(`account ${i} is not an address (expected a base58 string, or an object with .address/.pubkey)`);
+    }
+    return raw;
+}
+/** Classifies an account-list length as a settle shape: `3N+3` is the user tail alone, `3N+4` is that
+ *  tail with the leading bytecode-buffer account. Returns null for any other length (the two never
+ *  collide — `3N+3 = 3M+4` has no integer solution). */
+function classifyAccountList(length) {
+    for (const hasBuffer of [false, true]) {
+        const userCount = hasBuffer ? length - 1 : length;
+        if ((userCount - 3) % 3 !== 0)
+            continue;
+        const escrowCount = (userCount - 3) / 3;
+        if (Number.isInteger(escrowCount) && escrowCount >= 1 && escrowCount <= SVM_MAX_ESCROWS) {
+            return { escrowCount, hasBuffer };
+        }
+    }
+    return null;
+}
+/**
+ * Names the engine instruction from its discriminator alone.
+ *
+ * Replaces a parser for the `[disc][flags][pin?][slice?]` grammar the pre-release engine took here;
+ * the released engine has no payload beyond the discriminator, so there is nothing left to parse.
+ */
+function classifyEngineInstruction(data) {
+    if (!(data instanceof Uint8Array))
+        throw new Error("instructionData must be a Uint8Array");
+    if (data.length < 8)
+        throw new Error(`instructionData is ${data.length} bytes — too short for an 8-byte discriminator`);
+    const disc = data.subarray(0, 8);
+    if (bytesEqual(disc, EXECUTE_FROM_ACCOUNT_DISCRIMINATOR))
+        return "execute_from_account";
+    if (bytesEqual(disc, EXECUTE_DISCRIMINATOR))
+        return "execute";
+    throw new Error("instructionData does not begin with a Sauce engine execute discriminator");
+}
+/**
+ * Decodes a full settle execution — the calldata AND the account list — into its staged-execute header
+ * and resolved account identities in one call. It parses the execute payload grammar off
+ * `instructionData`, infers the escrow count from the account-list length, and resolves each
+ * `svmSettleRefs(N)` slot to the attached pubkey. Consumes the sauce-recipes `split=1` settle sauce
+ * (`execution.instructionData` + `execution.accounts[]`) directly, and equally an executed engine
+ * instruction (full data + `[buffer, …user]` account list).
+ *
+ * `minOut`/`splCount` are NOT among the results, and cannot be: they are defines folded into the
+ * bytecode, so no amount of reading the calldata recovers them. `verifySvmSettleExecution` establishes
+ * them the only way available — by recompiling with the values a caller expects and byte-comparing.
+ *
+ * What IS here is not trusted either: the header comes from the raw calldata (not from a receipt), and
+ * the account identities are resolved positionally against the canonical refs, never from
+ * caller-supplied labels — `labeledRefsConsistent` only reports whether a label the caller happened to
+ * attach agreed with the slot it landed in.
+ *
+ * IMPORTANT — this is a STRUCTURAL decode, NOT a genuineness proof. A staged settle's calldata
+ * carries no structural signature: any staged Sauce execute with a `3N+3`/`3N+4` account count has
+ * this exact shape. So a non-settle execution (or an adversarial decoy) decodes here without error
+ * into any staged program at all. To prove the execution actually runs the genuine settle program,
+ * use `verifySvmSettleExecution` (or `extractSvmSettleFromIntent`), which ties the calldata to the
+ * SDK's own recompiled canonical settle bytecode.
+ *
+ * The EVM half splits the same two questions the same way — `decodeSettleProgram` is structural and
+ * accepts any 362-byte program, `validateSettleProgram` is the genuineness proof — but reaches the
+ * second one WITHOUT a compiler: an EVM settle's params ride the payload after the program, so the
+ * program is a constant and one `keccak256` settles it. Here they are `defines` folded into the
+ * bytecode, which is why this side recompiles.
+ */
+export function decodeSvmSettleExecution(input) {
+    const instruction = classifyEngineInstruction(input.instructionData);
+    const shape = classifyAccountList(input.accounts.length);
+    if (shape === null) {
+        throw new Error(`account list has ${input.accounts.length} accounts, which is neither 3N+3 (user tail) nor 3N+4 (with buffer) for any settle escrow count 1..${SVM_MAX_ESCROWS}`);
+    }
+    const { escrowCount, hasBuffer } = shape;
+    const refs = svmSettleRefs(escrowCount);
+    const userAccounts = hasBuffer ? input.accounts.slice(1) : input.accounts;
+    const accounts = {};
+    let labeledRefsConsistent = true;
+    refs.forEach((ref, i) => {
+        accounts[ref] = accountAddress(userAccounts[i], i);
+        const entry = userAccounts[i];
+        if (typeof entry === "object" && entry !== null && typeof entry.ref === "string") {
+            if (entry.ref !== ref)
+                labeledRefsConsistent = false;
+        }
+        else if (labeledRefsConsistent !== false) {
+            labeledRefsConsistent = null; // at least one entry carried no label → can't confirm
+        }
+    });
+    return {
+        instruction,
+        escrowCount,
+        refs,
+        accounts,
+        hadBufferAccount: hasBuffer,
+        labeledRefsConsistent,
+    };
+}
+/**
+ * The genuineness check for a settle execution — the crucial companion to `decodeSvmSettleExecution`,
+ * whose structural decode alone CANNOT tell a settle from any other staged Sauce execute (an account
+ * count is not a signature). This ties the calldata to the SDK's own recompiled canonical settle
+ * bytecode, in one of two ways, no partner bytecode required for either verdict:
+ *
+ *   - `bytecode` supplied → byte-compare it to `compileCanonicalSettle(escrowCount)` AND require the pin
+ *     to tie to it (`sha256(bytecode) === pin`). Proves the exact staged bytes ARE the settle and WILL run.
+ *     Both halves are load-bearing: calldata with no pin commits to no program at all, so bytes alone —
+ *     however genuine — prove nothing about what runs, and the verdict is not genuine.
+ *   - no bytecode, but a pin was supplied → check `pin === sha256(canonical settle)`. NOTHING ENFORCES
+ *     THIS ON CHAIN: the released engine's `execute_from_account` has no payload, so this is the
+ *     caller asserting the staged bytes hash to that value, and it is worth exactly what their
+ *     evidence is worth — hence `verifiedBy: 'caller-asserted-pin'`.
+ *   - neither → `genuine: false`, `verifiedBy: 'none'` (structure alone is not proof).
+ *
+ * An `execute` is handled separately and BEFORE any of the above: its program is inline in the
+ * calldata, so it is compared directly and a pin cannot make it genuine.
+ *
+ * Because `minOut`/`splCount` are folded into the bytecode, a `genuine` result also proves the program
+ * enforces the `minOut`/`splCount` passed in — leaving only the resolved account identities for the
+ * caller to check. Never throws beyond the shared structural decode; reports failures in `mismatch`.
+ */
+export function verifySvmSettleExecution(input) {
+    const decoded = decodeSvmSettleExecution(input);
+    const canonical = compileCanonicalSettle(decoded.escrowCount, input);
+    // The CALLER's pin. This instruction has no payload to carry one, and nothing on chain checks it
+    // at execute time, so it is an assertion by whoever supplied it — not a guarantee. On the staged
+    // path it is the only thing tying the bytes verified here to the bytes that run, which is exactly
+    // why the verdict it produces is named `caller-asserted-pin`.
+    const pin = input.pin;
+    const pinMatchesCanonical = pin === undefined ? null : bytesEqual(sha256(canonical), pin);
+    const bytecodeMatchesCanonical = input.bytecode === undefined ? null : bytesEqual(input.bytecode, canonical);
+    const pinMatchesBytecode = input.bytecode === undefined || pin === undefined
+        ? null
+        : bytesEqual(sha256(input.bytecode), pin);
+    let genuine;
+    let verifiedBy;
+    let mismatch;
+    // An inline `execute` carries its program in the calldata, so it is verifiable directly and a pin
+    // is irrelevant to it — the engine never reads one. Before this, the branch order below ignored
+    // `decoded.instruction` entirely, so an inline execute carrying ARBITRARY bytecode plus
+    // `pin = sha256(canonical)` returned `genuine: true`.
+    if (decoded.instruction === "execute") {
+        const inline = input.instructionData.subarray(8);
+        const inlineMatchesCanonical = bytesEqual(inline, canonical);
+        const suppliedMatchesInline = input.bytecode === undefined ? null : bytesEqual(input.bytecode, inline);
+        verifiedBy = "inline-bytecode";
+        genuine = inlineMatchesCanonical && suppliedMatchesInline !== false;
+        mismatch = !inlineMatchesCanonical
+            ? `inline execute bytecode does not byte-match svmSettleSource(${decoded.escrowCount})`
+            : suppliedMatchesInline === false
+                ? "supplied bytecode does not match the bytecode inline in this execute"
+                : undefined;
+        return {
+            ...decoded,
+            genuine,
+            verifiedBy,
+            pinMatchesCanonical,
+            pinMatchesBytecode,
+            bytecodeMatchesCanonical,
+            mismatch,
+        };
+    }
+    if (input.bytecode !== undefined) {
+        verifiedBy = "bytecode";
+        genuine = bytecodeMatchesCanonical === true && pinMatchesBytecode === true;
+        mismatch =
+            bytecodeMatchesCanonical !== true
+                ? `bytecode does not byte-match svmSettleSource(${decoded.escrowCount})`
+                : pinMatchesBytecode === false
+                    ? "calldata pin does not equal sha256(bytecode) — the calldata targets different bytecode"
+                    : pinMatchesBytecode === null
+                        ? "calldata carries no pin, so it does not commit to the supplied bytecode — the staged bytes verified here need not be the bytes that run"
+                        : undefined;
+    }
+    else if (pin !== undefined) {
+        verifiedBy = "caller-asserted-pin";
+        genuine = pinMatchesCanonical === true;
+        mismatch = genuine
+            ? undefined
+            : `pin does not match sha256(svmSettleSource(${decoded.escrowCount})) — not a genuine settle execution`;
+    }
+    else {
+        verifiedBy = "none";
+        genuine = false;
+        mismatch =
+            "no calldata pin and no bytecode supplied — a staged settle has no structural signature, so genuineness cannot be proven";
+    }
+    return {
+        ...decoded,
+        genuine,
+        verifiedBy,
+        pinMatchesCanonical,
+        pinMatchesBytecode,
+        bytecodeMatchesCanonical,
+        mismatch,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/sdk/dist/svm/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/svm/verify.ts"],"names":[],"mappings":"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"}

package/sdk/dist/swap/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `@eco-incorp/sauce`'s `swap` module — E4.1, the universal swap adapter.
+ *
+ * Lowers a chain-agnostic swap SPEC into the call(s) that execute it through the Sauce Router's
+ * unified `swap(SwapParams)` entry point, keyed by `SwapPoolType`. Two layers, both pure/sync, no
+ * compiler import (mirrors `sdk/src/recipes/index.ts`'s "every compile option stays explicit at the
+ * call site" posture):
+ *
+ *   1. {@link toSwapParams} — the whole normalization/sign/defaulting/guard decision, as a plain
+ *      `SwapParams` object (bigint scalars, exact ABI-declaration order). Independently useful for
+ *      an off-chain `viem.encodeFunctionData` call (e.g. a `quote()` simulation) or a test assertion.
+ *   2. {@link swapCallStatement} / {@link swapSource} — pure string templating over that object,
+ *      producing SauceScript source. `swapSource` returns a complete `function main() { ... }`
+ *      program; `swapCallStatement` returns one bare statement for splicing into a larger program.
+ *
+ * ## Composing with E3 (route.calls)
+ *
+ * ```ts
+ * import { routes, swap } from "@eco-incorp/sauce";
+ *
+ * // routes.compileSauceRoute, not the compiler directly: a generated `main` falls off the end and
+ * // a raw compile rejects it with "`main` does not return on every path".
+ * const { compiled } = routes.compileSauceRoute(
+ *   "base",
+ *   swap.swapSource({ poolType: swap.SwapPoolType.UniV3, pool, tokenIn, tokenOut, amountIn: 1_000n }),
+ *   { pot },
+ *   { baseDirs: swap.SWAP_BASE_DIRS },
+ * );
+ * // compiled.bytecode[0] -- 124 bytes for this spec
+ * ```
+ *
+ * A v12 program's `swap()` call self-targets `ctx.self()` (Router entries are `onlySelf`); the
+ * V12Pot's own `fallback` delegatecalls it into the v1 Router — see `V12Pot.sol`'s own header for
+ * that mechanism. This module never rebuilds any of that seam, only emits the SauceScript that
+ * exercises it.
+ *
+ * **One cook = one program** (`V12Pot.cook` takes exactly one): a multi-hop route is ONE
+ * `swapSource([legA, legB, ...])` program with N sequential `swap()` statements, not N cooks. A
+ * swap-then-settle composition is two separate `CallInput`s — `routes.buildSauceEvmCalls({ pot,
+ * engine, cooks: [swapBlob, settleBlob] })`.
+ *
+ * ## Scope (this is a minimal first cut)
+ *
+ * - **Unified `swap()` only — poolType 0..8.** PancakeInfinity's CL/Bin pools (9/10) are not
+ *   dispatchable through `swap()` at all (`Router.sol` falls through to `revert SwapFailed()`); they
+ *   need their own `swapInfinityCL`/`swapInfinityBin` emitters and their own (NEGATIVE-required)
+ *   sign rule. `toSwapParams` throws a named error pointing here rather than emitting a program that
+ *   reverts on-chain. See {@link UndispatchablePoolType}.
+ * - **No deposit/stake/wrap/bridge (E4.2).** Those lower to direct `approve` + per-protocol calls
+ *   against the SDK's protocol registry — a different shape (a registry, not one entry point).
+ * - **No callback-free direct-SauceScript alternative.** V2/Curve/BalancerV2/DODOV2/TraderJoeLB/
+ *   WOOFi (see {@link isCallbackFree}) MAY be replicated as `transfer` + `pool.swap` SauceScript,
+ *   bypassing the Router's fallback-delegatecall hop — this module always routes through the
+ *   unified `swap()` for all nine dispatchable types uniformly. Deferred; the predicate is exported
+ *   now so the follow-up has it.
+ * - **No Tier-1 flash-fragment construction.** `spec.callback` is accepted and guarded (see
+ *   {@link isCallbackVenue}) but never built — it is an opaque, already-compiled program the caller
+ *   supplies.
+ * - **No return-value decoding.** `swap()`'s `(int256 amount0, int256 amount1)` is emitted as a bare
+ *   discarded call; recovering `amountOut` needs direction-dependent delta selection. The intended
+ *   composition is `swap` cook → `settle.sauce.ts` cook, whose `minOut` floor is the real output
+ *   guard.
+ * - **EVM/v12 only**, same posture as `sdk/src/recipes/`. The Sauce Router itself is EVM-only.
+ *
+ * See `docs/plans/2026-08-08-universal-interfaces-epic.md` for the wider epic this is E4.1 of.
+ */
+export { SwapPoolType, UndispatchablePoolType, ZERO_POOL_KEY, SWAP_PARAMS_FIELDS, POOL_KEY_FIELDS, isCallbackVenue, isCallbackFree, usesPoolKey, } from "./types.js";
+export type { Address, Hex, AddressInput, AmountInput, PoolKey, PoolKeyInput, SwapSpec, SwapSourceSpec, SwapParams, } from "./types.js";
+export { toSwapParams, amountSpecifiedFor } from "./params.js";
+export { swapCallStatement, swapSource, swapImportLines, SWAP_BASE_DIRS } from "./source.js";
+export type { SwapSourceOptions } from "./source.js";
+//# sourceMappingURL=index.d.ts.map

package/sdk/dist/swap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/swap/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,OAAO,EACP,GAAG,EACH,YAAY,EACZ,WAAW,EACX,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7F,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/sdk/dist/swap/index.js

@@ -0,0 +1,70 @@
+/**
+ * `@eco-incorp/sauce`'s `swap` module — E4.1, the universal swap adapter.
+ *
+ * Lowers a chain-agnostic swap SPEC into the call(s) that execute it through the Sauce Router's
+ * unified `swap(SwapParams)` entry point, keyed by `SwapPoolType`. Two layers, both pure/sync, no
+ * compiler import (mirrors `sdk/src/recipes/index.ts`'s "every compile option stays explicit at the
+ * call site" posture):
+ *
+ *   1. {@link toSwapParams} — the whole normalization/sign/defaulting/guard decision, as a plain
+ *      `SwapParams` object (bigint scalars, exact ABI-declaration order). Independently useful for
+ *      an off-chain `viem.encodeFunctionData` call (e.g. a `quote()` simulation) or a test assertion.
+ *   2. {@link swapCallStatement} / {@link swapSource} — pure string templating over that object,
+ *      producing SauceScript source. `swapSource` returns a complete `function main() { ... }`
+ *      program; `swapCallStatement` returns one bare statement for splicing into a larger program.
+ *
+ * ## Composing with E3 (route.calls)
+ *
+ * ```ts
+ * import { routes, swap } from "@eco-incorp/sauce";
+ *
+ * // routes.compileSauceRoute, not the compiler directly: a generated `main` falls off the end and
+ * // a raw compile rejects it with "`main` does not return on every path".
+ * const { compiled } = routes.compileSauceRoute(
+ *   "base",
+ *   swap.swapSource({ poolType: swap.SwapPoolType.UniV3, pool, tokenIn, tokenOut, amountIn: 1_000n }),
+ *   { pot },
+ *   { baseDirs: swap.SWAP_BASE_DIRS },
+ * );
+ * // compiled.bytecode[0] -- 124 bytes for this spec
+ * ```
+ *
+ * A v12 program's `swap()` call self-targets `ctx.self()` (Router entries are `onlySelf`); the
+ * V12Pot's own `fallback` delegatecalls it into the v1 Router — see `V12Pot.sol`'s own header for
+ * that mechanism. This module never rebuilds any of that seam, only emits the SauceScript that
+ * exercises it.
+ *
+ * **One cook = one program** (`V12Pot.cook` takes exactly one): a multi-hop route is ONE
+ * `swapSource([legA, legB, ...])` program with N sequential `swap()` statements, not N cooks. A
+ * swap-then-settle composition is two separate `CallInput`s — `routes.buildSauceEvmCalls({ pot,
+ * engine, cooks: [swapBlob, settleBlob] })`.
+ *
+ * ## Scope (this is a minimal first cut)
+ *
+ * - **Unified `swap()` only — poolType 0..8.** PancakeInfinity's CL/Bin pools (9/10) are not
+ *   dispatchable through `swap()` at all (`Router.sol` falls through to `revert SwapFailed()`); they
+ *   need their own `swapInfinityCL`/`swapInfinityBin` emitters and their own (NEGATIVE-required)
+ *   sign rule. `toSwapParams` throws a named error pointing here rather than emitting a program that
+ *   reverts on-chain. See {@link UndispatchablePoolType}.
+ * - **No deposit/stake/wrap/bridge (E4.2).** Those lower to direct `approve` + per-protocol calls
+ *   against the SDK's protocol registry — a different shape (a registry, not one entry point).
+ * - **No callback-free direct-SauceScript alternative.** V2/Curve/BalancerV2/DODOV2/TraderJoeLB/
+ *   WOOFi (see {@link isCallbackFree}) MAY be replicated as `transfer` + `pool.swap` SauceScript,
+ *   bypassing the Router's fallback-delegatecall hop — this module always routes through the
+ *   unified `swap()` for all nine dispatchable types uniformly. Deferred; the predicate is exported
+ *   now so the follow-up has it.
+ * - **No Tier-1 flash-fragment construction.** `spec.callback` is accepted and guarded (see
+ *   {@link isCallbackVenue}) but never built — it is an opaque, already-compiled program the caller
+ *   supplies.
+ * - **No return-value decoding.** `swap()`'s `(int256 amount0, int256 amount1)` is emitted as a bare
+ *   discarded call; recovering `amountOut` needs direction-dependent delta selection. The intended
+ *   composition is `swap` cook → `settle.sauce.ts` cook, whose `minOut` floor is the real output
+ *   guard.
+ * - **EVM/v12 only**, same posture as `sdk/src/recipes/`. The Sauce Router itself is EVM-only.
+ *
+ * See `docs/plans/2026-08-08-universal-interfaces-epic.md` for the wider epic this is E4.1 of.
+ */
+export { SwapPoolType, UndispatchablePoolType, ZERO_POOL_KEY, SWAP_PARAMS_FIELDS, POOL_KEY_FIELDS, isCallbackVenue, isCallbackFree, usesPoolKey, } from "./types.js";
+export { toSwapParams, amountSpecifiedFor } from "./params.js";
+export { swapCallStatement, swapSource, swapImportLines, SWAP_BASE_DIRS } from "./source.js";
+//# sourceMappingURL=index.js.map

package/sdk/dist/swap/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/swap/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAapB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/sdk/dist/swap/params.d.ts

@@ -0,0 +1,29 @@
+import { SwapPoolType, type SwapParams, type SwapSpec } from "./types.js";
+/**
+ * The single, standalone sign rule (E4.3): given a POSITIVE exact-input amount, returns the
+ * `amountSpecified` value the given pool type's handler actually wants.
+ *
+ * - UniV3 (`Router.sol:431`, passthrough into Uniswap V3's own `pool.swap`): POSITIVE = exact
+ *   input (fork-verified; contradicts `IRouter.sol`'s own struct doc comment — see `SwapParams`).
+ * - UniV4 (`Router.sol`'s `unlockCallback` → `V4SwapParams`): NEGATIVE = exact input (Uniswap V4's
+ *   flipped convention). Encoded as the exact two's-complement `uint256` (`2**256 - amountIn`), not
+ *   `-amountIn` — see the module doc for why the compact spelling is deliberately deferred.
+ * - Every other pool type (0, 3, 4, 5, 6, 7, 8): the handler takes `abs(amountSpecified)`, so the
+ *   canonical positive form is used as-is.
+ */
+export declare function amountSpecifiedFor(poolType: SwapPoolType, amountIn: bigint): bigint;
+/**
+ * The whole normalization + sign + defaulting + guard decision: lowers a chain-agnostic
+ * {@link SwapSpec} into a fully normalized {@link SwapParams} — plain bigints (+ the `"self"`
+ * sentinel for a defaulted `payer`/`recipient`), in exact ABI-declaration order, so
+ * `Object.keys(toSwapParams(spec))` matches the vendored `ISauceRouter.json` component order.
+ *
+ * Throws (never emits a program that would revert on-chain) for: poolType 9/10 (Infinity — not
+ * dispatchable through `swap()`, see {@link UndispatchablePoolType}); any other out-of-range
+ * poolType; UniV4 missing `poolKey`; UniV2 `poolKey.fee >= 1_000_000`; a non-empty `callback` on a
+ * non-callback-driven pool type; a non-empty `callback` with an overridden `payer`/`recipient`; and
+ * any numeric field given as a `number` that is not a safe integer (past 2^53-1 pass a bigint or a
+ * string, since the double has already been rounded).
+ */
+export declare function toSwapParams(spec: SwapSpec): SwapParams;
+//# sourceMappingURL=params.d.ts.map

package/sdk/dist/swap/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/swap/params.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,YAAY,EASZ,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AAyDpB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUnF;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAoCvD"}

package/sdk/dist/swap/params.js

@@ -0,0 +1,123 @@
+/**
+ * Normalization core for E4.1's universal swap adapter — `toSwapParams` + `amountSpecifiedFor`.
+ * See `sdk/src/swap/index.ts` for the module overview.
+ */
+import { toExactBigInt } from "../numeric.js";
+import { isCallbackVenue, SwapPoolType, UndispatchablePoolType, usesPoolKey, ZERO_POOL_KEY, } from "./types.js";
+const DISPATCHABLE_POOL_TYPES = new Set(Object.values(SwapPoolType));
+const UNDISPATCHABLE_POOL_TYPES = new Set(Object.values(UndispatchablePoolType));
+/** UniV2's pair-fee ceiling — `Router.sol#_swapV2` reverts at/above this (ppm; 1_000_000 = 100%). */
+const MAX_UNIV2_FEE_PPM = 1000000n;
+function toBigIntStrict(value, label) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number")
+        return toExactBigInt(value, label);
+    // string: decimal or 0x-hex, either accepted by BigInt() directly.
+    return BigInt(value);
+}
+function toAddressBigint(value, _label) {
+    if (typeof value === "bigint")
+        return value;
+    return BigInt(value);
+}
+function normalizePoolKey(poolType, input) {
+    if (poolType === SwapPoolType.UniV4) {
+        if (input === undefined) {
+            throw new Error("toSwapParams: poolKey is required for UniV4 (currency0, currency1, fee, tickSpacing, hooks)");
+        }
+        return {
+            currency0: input.currency0 !== undefined ? toAddressBigint(input.currency0, "poolKey.currency0") : 0n,
+            currency1: input.currency1 !== undefined ? toAddressBigint(input.currency1, "poolKey.currency1") : 0n,
+            fee: input.fee !== undefined ? toBigIntStrict(input.fee, "poolKey.fee") : 0n,
+            tickSpacing: input.tickSpacing !== undefined
+                ? toBigIntStrict(input.tickSpacing, "poolKey.tickSpacing")
+                : 0n,
+            hooks: input.hooks !== undefined ? toAddressBigint(input.hooks, "poolKey.hooks") : 0n,
+        };
+    }
+    if (poolType === SwapPoolType.UniV2) {
+        const fee = input?.fee !== undefined ? toBigIntStrict(input.fee, "poolKey.fee") : 0n;
+        if (fee >= MAX_UNIV2_FEE_PPM) {
+            throw new Error(`toSwapParams: poolKey.fee (${fee}) must be < ${MAX_UNIV2_FEE_PPM} ppm for UniV2 (Router.sol reverts at/above it); 0 means the engine's default 3000 (0.30%)`);
+        }
+        return { ...ZERO_POOL_KEY, fee };
+    }
+    // Every other pool type ignores poolKey entirely — see usesPoolKey.
+    return ZERO_POOL_KEY;
+}
+/**
+ * The single, standalone sign rule (E4.3): given a POSITIVE exact-input amount, returns the
+ * `amountSpecified` value the given pool type's handler actually wants.
+ *
+ * - UniV3 (`Router.sol:431`, passthrough into Uniswap V3's own `pool.swap`): POSITIVE = exact
+ *   input (fork-verified; contradicts `IRouter.sol`'s own struct doc comment — see `SwapParams`).
+ * - UniV4 (`Router.sol`'s `unlockCallback` → `V4SwapParams`): NEGATIVE = exact input (Uniswap V4's
+ *   flipped convention). Encoded as the exact two's-complement `uint256` (`2**256 - amountIn`), not
+ *   `-amountIn` — see the module doc for why the compact spelling is deliberately deferred.
+ * - Every other pool type (0, 3, 4, 5, 6, 7, 8): the handler takes `abs(amountSpecified)`, so the
+ *   canonical positive form is used as-is.
+ */
+export function amountSpecifiedFor(poolType, amountIn) {
+    if (amountIn < 0n) {
+        throw new Error(`amountSpecifiedFor: amountIn must be a positive exact-input amount, got ${amountIn}`);
+    }
+    if (poolType === SwapPoolType.UniV4) {
+        return amountIn === 0n ? 0n : 2n ** 256n - amountIn;
+    }
+    return amountIn;
+}
+function normalizeCallback(poolType, callback, payerOverridden, recipientOverridden) {
+    const value = callback ?? "0x";
+    if (value === "0x")
+        return value;
+    if (!isCallbackVenue(poolType)) {
+        throw new Error(`toSwapParams: a non-empty callback is only valid for a callback-driven pool type (UniV3, UniV4, MaverickV2) — Router.sol's swap() rejects it for poolType ${poolType}`);
+    }
+    if (payerOverridden || recipientOverridden) {
+        throw new Error("toSwapParams: a non-empty callback requires payer and recipient to both stay ctx.self() — Router.sol's callback-driven handlers require payer == recipient == address(this)");
+    }
+    return value;
+}
+/**
+ * The whole normalization + sign + defaulting + guard decision: lowers a chain-agnostic
+ * {@link SwapSpec} into a fully normalized {@link SwapParams} — plain bigints (+ the `"self"`
+ * sentinel for a defaulted `payer`/`recipient`), in exact ABI-declaration order, so
+ * `Object.keys(toSwapParams(spec))` matches the vendored `ISauceRouter.json` component order.
+ *
+ * Throws (never emits a program that would revert on-chain) for: poolType 9/10 (Infinity — not
+ * dispatchable through `swap()`, see {@link UndispatchablePoolType}); any other out-of-range
+ * poolType; UniV4 missing `poolKey`; UniV2 `poolKey.fee >= 1_000_000`; a non-empty `callback` on a
+ * non-callback-driven pool type; a non-empty `callback` with an overridden `payer`/`recipient`; and
+ * any numeric field given as a `number` that is not a safe integer (past 2^53-1 pass a bigint or a
+ * string, since the double has already been rounded).
+ */
+export function toSwapParams(spec) {
+    const { poolType } = spec;
+    if (UNDISPATCHABLE_POOL_TYPES.has(poolType)) {
+        throw new Error(`toSwapParams: poolType ${poolType} (PancakeInfinity CL/Bin) is not dispatchable through the unified swap() — Router.sol falls through to revert SwapFailed(). Use the dedicated swapInfinityCL/swapInfinityBin entry points instead (a follow-up, not built by this module).`);
+    }
+    if (!DISPATCHABLE_POOL_TYPES.has(poolType)) {
+        throw new Error(`toSwapParams: unknown poolType ${poolType} (expected one of SwapPoolType's 0..8)`);
+    }
+    const payerOverridden = spec.payer !== undefined;
+    const recipientOverridden = spec.recipient !== undefined;
+    const params = {
+        poolType,
+        pool: toAddressBigint(spec.pool, "pool"),
+        poolKey: usesPoolKey(poolType) ? normalizePoolKey(poolType, spec.poolKey) : ZERO_POOL_KEY,
+        tokenIn: toAddressBigint(spec.tokenIn, "tokenIn"),
+        tokenOut: toAddressBigint(spec.tokenOut, "tokenOut"),
+        amountSpecified: amountSpecifiedFor(poolType, toBigIntStrict(spec.amountIn, "amountIn")),
+        sqrtPriceLimitX96: spec.sqrtPriceLimitX96 !== undefined
+            ? toBigIntStrict(spec.sqrtPriceLimitX96, "sqrtPriceLimitX96")
+            : 0n,
+        payer: payerOverridden ? toAddressBigint(spec.payer, "payer") : "self",
+        recipient: recipientOverridden
+            ? toAddressBigint(spec.recipient, "recipient")
+            : "self",
+        callback: normalizeCallback(poolType, spec.callback, payerOverridden, recipientOverridden),
+    };
+    return params;
+}
+//# sourceMappingURL=params.js.map

package/sdk/dist/swap/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../src/swap/params.ts"],"names":[],"mappings":"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"}