@eco-incorp/sauce 0.99.0

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

@@ -0,0 +1,37 @@
+import { type SwapSourceSpec } from "./types.js";
+/**
+ * `baseDirs` for compiling any program `swapSource`/`swapCallStatement` produces — resolves the
+ * generated `import { ISauceRouter } from "./artifacts/ISauceRouter.json"` (and, for a `"balance"`
+ * leg, `./artifacts/IERC20.json`) against this installed package's dist root. Same value/pattern as
+ * `sdk/src/recipes/index.ts`'s `SAUCE_BASE_DIRS`.
+ */
+export declare const SWAP_BASE_DIRS: readonly string[];
+/**
+ * One `ISauceRouter.at(ctx.self()).swap({...})` statement for `spec` — for splicing into a
+ * larger, hand-written program. Runs the FULL `toSwapParams` normalization/guard pass (a
+ * `"balance"` `amountIn` reuses every other field's normalization, only the amount itself is
+ * emitted as a runtime expression instead of a literal).
+ */
+export declare function swapCallStatement(spec: SwapSourceSpec): string;
+export interface SwapSourceOptions {
+    /** Defaults to `"main"`. */
+    functionName?: string;
+    /** Extra import lines spliced in verbatim, ahead of the generated `main`/`functionName` body. */
+    imports?: readonly string[];
+}
+/**
+ * The import lines a `swapSource(specs)` program needs — `ISauceRouter` always, plus `IERC20` iff
+ * any spec uses `amountIn: "balance"`. Extracted so `swapThenDepositSource` (E4.2's composition
+ * seam) can union these with the deposit side's own import lines instead of duplicating this rule;
+ * `swapSource` itself just calls this, so its own output is unaffected byte-for-byte.
+ */
+export declare function swapImportLines(specs: SwapSourceSpec | readonly SwapSourceSpec[]): readonly string[];
+/**
+ * A complete, compilable `function main() { ... }` program: one `ISauceRouter.swap(...)` statement
+ * per spec, in the given order, inside ONE function — because `V12Pot.cook` takes exactly one
+ * program (its own doc), a multi-hop route is ONE program with N swap statements, not N separate
+ * cooks. See `sdk/src/swap/index.ts` for the full compile → `routes.buildSauceEvmCall`
+ * seam.
+ */
+export declare function swapSource(spec: SwapSourceSpec | readonly SwapSourceSpec[], opts?: SwapSourceOptions): string;
+//# sourceMappingURL=source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/swap/source.ts"],"names":[],"mappings":"AAUA,OAAO,EAA0B,KAAK,cAAc,EAAiB,MAAM,YAAY,CAAC;AAKxF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA4B,CAAC;AAgCzE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA4B9D;AAED,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,GAChD,SAAS,MAAM,EAAE,CAOnB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,EAChD,IAAI,GAAE,iBAAsB,GAC3B,MAAM,CAiBR"}

package/sdk/dist/swap/source.js

@@ -0,0 +1,109 @@
+/**
+ * SauceScript SOURCE emission for E4.1's universal swap adapter — pure string templating over
+ * {@link toSwapParams}'s normalized output. Imports NO compiler (matches `sdk/src/recipes/index.ts`
+ * and `sdk/src/svm/recipes/index.ts`'s posture: every compile option stays explicit at the call
+ * site). See `sdk/src/swap/index.ts` for the full E3-composition example.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toSwapParams } from "./params.js";
+import { SwapPoolType } from "./types.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * `baseDirs` for compiling any program `swapSource`/`swapCallStatement` produces — resolves the
+ * generated `import { ISauceRouter } from "./artifacts/ISauceRouter.json"` (and, for a `"balance"`
+ * leg, `./artifacts/IERC20.json`) against this installed package's dist root. Same value/pattern as
+ * `sdk/src/recipes/index.ts`'s `SAUCE_BASE_DIRS`.
+ */
+export const SWAP_BASE_DIRS = [join(__dirname, "..")];
+function formatBigint(value) {
+    return `${value.toString()}n`;
+}
+/** `bigint` → its numeric literal; the `"self"` sentinel → the SauceScript `ctx.self()` global. */
+function formatAddressField(value) {
+    return value === "self" ? "ctx.self()" : formatBigint(value);
+}
+/** The bytes as a SauceScript `hex` literal; `"0x"` yields the empty one. */
+function formatCallback(callback) {
+    const digits = callback.slice(2);
+    if (digits.length % 2 !== 0)
+        throw new Error(`formatCallback: odd-length hex string ${callback}`);
+    return `hex\`${digits.toLowerCase()}\``;
+}
+function formatPoolKey(poolKey) {
+    return (`{ currency0: ${formatBigint(poolKey.currency0)}, currency1: ${formatBigint(poolKey.currency1)}, ` +
+        `fee: ${formatBigint(poolKey.fee)}, tickSpacing: ${formatBigint(poolKey.tickSpacing)}, ` +
+        `hooks: ${formatBigint(poolKey.hooks)} }`);
+}
+function fieldsFromParams(params) {
+    const { amountSpecified: _amountSpecified, ...rest } = params;
+    return rest;
+}
+/**
+ * One `ISauceRouter.at(ctx.self()).swap({...})` statement for `spec` — for splicing into a
+ * larger, hand-written program. Runs the FULL `toSwapParams` normalization/guard pass (a
+ * `"balance"` `amountIn` reuses every other field's normalization, only the amount itself is
+ * emitted as a runtime expression instead of a literal).
+ */
+export function swapCallStatement(spec) {
+    const concreteSpec = spec.amountIn === "balance" ? { ...spec, amountIn: 0n } : spec;
+    const params = toSwapParams(concreteSpec);
+    const fields = fieldsFromParams(params);
+    const tokenInLiteral = formatAddressField(fields.tokenIn);
+    const amountExpr = spec.amountIn === "balance"
+        ? spec.poolType === SwapPoolType.UniV4
+            ? `(0n - (IERC20.at(${tokenInLiteral}).balanceOf(ctx.self())))`
+            : `IERC20.at(${tokenInLiteral}).balanceOf(ctx.self())`
+        : formatBigint(params.amountSpecified);
+    const lines = [
+        "ISauceRouter.at(ctx.self()).swap({",
+        `  poolType: ${fields.poolType}n,`,
+        `  pool: ${formatAddressField(fields.pool)},`,
+        `  poolKey: ${formatPoolKey(fields.poolKey)},`,
+        `  tokenIn: ${tokenInLiteral},`,
+        `  tokenOut: ${formatAddressField(fields.tokenOut)},`,
+        `  amountSpecified: ${amountExpr},`,
+        `  sqrtPriceLimitX96: ${formatBigint(fields.sqrtPriceLimitX96)},`,
+        `  payer: ${formatAddressField(fields.payer)},`,
+        `  recipient: ${formatAddressField(fields.recipient)},`,
+        `  callback: ${formatCallback(fields.callback)},`,
+        "});",
+    ];
+    return lines.join("\n");
+}
+/**
+ * The import lines a `swapSource(specs)` program needs — `ISauceRouter` always, plus `IERC20` iff
+ * any spec uses `amountIn: "balance"`. Extracted so `swapThenDepositSource` (E4.2's composition
+ * seam) can union these with the deposit side's own import lines instead of duplicating this rule;
+ * `swapSource` itself just calls this, so its own output is unaffected byte-for-byte.
+ */
+export function swapImportLines(specs) {
+    const list = Array.isArray(specs) ? specs : [specs];
+    const needsBalanceImport = list.some((s) => s.amountIn === "balance");
+    return [
+        `import { ISauceRouter } from "./artifacts/ISauceRouter.json";`,
+        ...(needsBalanceImport ? [`import { IERC20 } from "./artifacts/IERC20.json";`] : []),
+    ];
+}
+/**
+ * A complete, compilable `function main() { ... }` program: one `ISauceRouter.swap(...)` statement
+ * per spec, in the given order, inside ONE function — because `V12Pot.cook` takes exactly one
+ * program (its own doc), a multi-hop route is ONE program with N swap statements, not N separate
+ * cooks. See `sdk/src/swap/index.ts` for the full compile → `routes.buildSauceEvmCall`
+ * seam.
+ */
+export function swapSource(spec, opts = {}) {
+    const specs = Array.isArray(spec) ? spec : [spec];
+    if (specs.length === 0)
+        throw new Error("swapSource: at least one swap spec is required");
+    const importLines = [...swapImportLines(specs), ...(opts.imports ?? [])];
+    const fnName = opts.functionName ?? "main";
+    const body = specs
+        .map((s) => swapCallStatement(s)
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n"))
+        .join("\n");
+    return [...importLines, "", `function ${fnName}() {`, body, "}", ""].join("\n");
+}
+//# sourceMappingURL=source.js.map

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

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

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

@@ -0,0 +1,160 @@
+/**
+ * `@eco-incorp/sauce`'s `swap` module — E4.1, the universal swap adapter.
+ *
+ * Types + pool-type registry for lowering a chain-agnostic swap SPEC into a `ISauceRouter.swap`
+ * call. See `sdk/src/swap/index.ts` for the module-level overview and the E3 composition example.
+ */
+/**
+ * `SwapPoolType` — pinned verbatim from the engine's `IRouter.sol` `enum SwapPoolType`, whose own
+ * doc says values are APPEND-ONLY (the enum rides `SwapParams.poolType` as `uint8`, so reordering
+ * breaks the ABI of every compiled recipe). Only 0..8 are dispatchable through the unified
+ * `swap()` entry point — see {@link UndispatchablePoolType} for 9/10.
+ */
+export declare const SwapPoolType: {
+    readonly UniV2: 0;
+    readonly UniV3: 1;
+    readonly UniV4: 2;
+    readonly Curve: 3;
+    readonly BalancerV2: 4;
+    readonly DODOV2: 5;
+    readonly TraderJoeLB: 6;
+    readonly MaverickV2: 7;
+    readonly WOOFi: 8;
+};
+export type SwapPoolType = (typeof SwapPoolType)[keyof typeof SwapPoolType];
+/**
+ * Pool types that exist on the engine's `SwapPoolType` enum but are NOT dispatchable through the
+ * unified `swap()` — `Router.sol`'s `swap()` dispatch chain covers only 0..8 and falls through to
+ * `revert SwapFailed()` for anything else. PancakeInfinity's CL/Bin pools need their own
+ * `swapInfinityCL`/`swapInfinityBin` entry points (a different, 6-field `InfinityPoolKey` that
+ * `SwapParams` cannot carry) — out of scope for this first cut. Exported so the value is nameable;
+ * {@link toSwapParams} throws when handed one of these, pointing at this follow-up.
+ */
+export declare const UndispatchablePoolType: {
+    readonly PancakeInfinityCL: 9;
+    readonly PancakeInfinityBin: 10;
+};
+export type UndispatchablePoolType = (typeof UndispatchablePoolType)[keyof typeof UndispatchablePoolType];
+/**
+ * True for the three pool types `Router.sol` (`~279-283`) allows a non-empty `callback` for — the
+ * pool re-enters the contract mid-swap to pull input, so servicing it requires the router's
+ * compiled code. NOT the same partition as {@link isCallbackFree}: MaverickV2 is callback-driven
+ * yet its handler still takes `abs(amountSpecified)` (see `amountSpecifiedFor`).
+ */
+export declare function isCallbackVenue(poolType: SwapPoolType): boolean;
+/**
+ * True for the pool types whose swap logic is callback-free (`Router.sol` reads reserves / calls a
+ * plain `pool.swap(...)`) and so MAY, as a follow-up, be replicated as direct
+ * `transfer` + `pool.swap` SauceScript instead of going through the Router. This module always
+ * routes through the unified `swap()` regardless — see `sdk/src/swap/index.ts`'s scope notes.
+ */
+export declare function isCallbackFree(poolType: SwapPoolType): boolean;
+/**
+ * True for the pool types where `SwapParams.poolKey` is actually consulted by the engine:
+ * UniV4 (all 5 fields, via `V4SwapParams`) and, less obviously, UniV2 (`Router.sol#_swapV2` reads
+ * `poolKey.fee` as the pair's LP fee in ppm — `0` defaults to 3000 / 0.30%, `>= 1_000_000` reverts).
+ * Every other pool type ignores `poolKey` entirely.
+ */
+export declare function usesPoolKey(poolType: SwapPoolType): boolean;
+/** A 20-byte EVM address, as an ordinary `0x`-prefixed hex string. */
+export type Address = `0x${string}`;
+/** A `0x`-prefixed hex byte string (used for `SwapParams.callback`). */
+export type Hex = `0x${string}`;
+/** Anything {@link toSwapParams} accepts for an address-shaped field. */
+export type AddressInput = Address | bigint;
+/** Anything {@link toSwapParams} accepts for a numeric-shaped field. */
+export type AmountInput = bigint | number | string;
+/**
+ * `SwapParams.poolKey` as the caller may supply it — every field optional; unset fields default to
+ * `0n` (see `toSwapParams`'s per-pool-type rules for which defaults are actually meaningful).
+ */
+export interface PoolKeyInput {
+    currency0?: AddressInput;
+    currency1?: AddressInput;
+    fee?: AmountInput;
+    tickSpacing?: AmountInput;
+    hooks?: AddressInput;
+}
+/** `SwapParams.poolKey`, fully normalized — 5 bigint fields, in ABI-declaration order. */
+export interface PoolKey {
+    currency0: bigint;
+    currency1: bigint;
+    fee: bigint;
+    tickSpacing: bigint;
+    hooks: bigint;
+}
+/** All-zero `poolKey`, used for any pool type that doesn't consult it (see {@link usesPoolKey}). */
+export declare const ZERO_POOL_KEY: PoolKey;
+/**
+ * The chain-agnostic swap SPEC a caller builds — the input to {@link toSwapParams} /
+ * `swapCallStatement` / `swapSource`. `amountIn` is always a single, unambiguous POSITIVE
+ * exact-input amount; {@link amountSpecifiedFor} does the per-path sign normalization.
+ *
+ * `payer`/`recipient` default to the SauceScript call `ctx.self()` (Router swap entries are
+ * `onlySelf`) — leave them unset unless you specifically need a different payer/recipient (which
+ * then disqualifies a non-empty `callback`, see `toSwapParams`'s guard).
+ */
+export interface SwapSpec {
+    poolType: SwapPoolType;
+    pool: AddressInput;
+    /** Required (all 5 fields) for UniV4; `fee` alone is meaningful for UniV2 (LP fee in ppm, `0` →
+     *  engine default 3000). Ignored for every other pool type. See {@link usesPoolKey}. */
+    poolKey?: PoolKeyInput;
+    tokenIn: AddressInput;
+    tokenOut: AddressInput;
+    /** A positive exact-input amount. See `amountSpecifiedFor` for the per-path sign this becomes. */
+    amountIn: AmountInput;
+    sqrtPriceLimitX96?: AmountInput;
+    /** Defaults to `ctx.self()`. Overriding this while also passing a non-empty `callback` is
+     *  rejected — see `toSwapParams`'s guard mirroring `Router.sol`'s own `payer == recipient ==
+     *  address(this)` check for a callback-driven swap. */
+    payer?: AddressInput;
+    /** Defaults to `ctx.self()`. See `payer`'s note. */
+    recipient?: AddressInput;
+    /** Opaque, already-compiled callback bytes for a Tier-1 flash fragment. Only valid for
+     *  {@link isCallbackVenue} pool types; building one is out of scope here — see
+     *  `sdk/src/swap/index.ts`'s scope notes. Defaults to empty (`"0x"`). */
+    callback?: Hex;
+}
+/**
+ * The one extra shape `swapCallStatement`/`swapSource` accept beyond {@link SwapSpec}:
+ * `amountIn: "balance"` emits a RUNTIME `IERC20.at(tokenIn).balanceOf(ctx.self())` read instead
+ * of a baked-in literal — the shape a multi-leg program needs when a later leg's input is an
+ * earlier leg's (unknown at compile time) output. `toSwapParams` does NOT accept this shape: it
+ * produces a concrete `SwapParams` object, which a runtime-derived amount cannot be.
+ */
+export type SwapSourceSpec = SwapSpec | (Omit<SwapSpec, "amountIn"> & {
+    amountIn: "balance";
+});
+/**
+ * `ISauceRouter.swap`'s `SwapParams`, fully normalized — every scalar a `bigint` (SauceScript- and
+ * viem-native), in exact ABI-declaration order (see `SWAP_PARAMS_FIELDS`, pinned against the
+ * vendored artifact in `sdk/test/swap.test.ts`). `payer`/`recipient` are `bigint | "self"`: `"self"`
+ * is the unresolved `ctx.self()` sentinel (this contract's own address, not knowable off-chain
+ * without the Pot address), preserved rather than eagerly resolved so a caller can tell the two
+ * cases apart.
+ *
+ * **Sign note (load-bearing, do not "fix" from the struct doc comment):** `IRouter.sol`'s own
+ * `SwapParams.amountSpecified` comment claims "Negative = exact input, Positive = exact output"
+ * universally. That is wrong for UniV3 — `Router.sol:431` passes it straight into Uniswap V3's
+ * pool, whose OWN convention is positive = exact input (fork-verified; see this repo's CLAUDE.md).
+ * `amountSpecifiedFor` follows the CODE, not the comment.
+ */
+export interface SwapParams {
+    poolType: SwapPoolType;
+    pool: bigint;
+    poolKey: PoolKey;
+    tokenIn: bigint;
+    tokenOut: bigint;
+    amountSpecified: bigint;
+    sqrtPriceLimitX96: bigint;
+    payer: bigint | "self";
+    recipient: bigint | "self";
+    callback: Hex;
+}
+/** `SwapParams`'s top-level field names, in exact ABI-declaration order (pinned against the
+ *  vendored `ISauceRouter.json` artifact in `sdk/test/swap.test.ts`). */
+export declare const SWAP_PARAMS_FIELDS: readonly (keyof SwapParams)[];
+/** `SwapParams.poolKey`'s field names, in exact ABI-declaration order. */
+export declare const POOL_KEY_FIELDS: readonly (keyof PoolKey)[];
+//# sourceMappingURL=types.d.ts.map

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

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

package/sdk/dist/swap/types.js

@@ -0,0 +1,106 @@
+/**
+ * `@eco-incorp/sauce`'s `swap` module — E4.1, the universal swap adapter.
+ *
+ * Types + pool-type registry for lowering a chain-agnostic swap SPEC into a `ISauceRouter.swap`
+ * call. See `sdk/src/swap/index.ts` for the module-level overview and the E3 composition example.
+ */
+/**
+ * `SwapPoolType` — pinned verbatim from the engine's `IRouter.sol` `enum SwapPoolType`, whose own
+ * doc says values are APPEND-ONLY (the enum rides `SwapParams.poolType` as `uint8`, so reordering
+ * breaks the ABI of every compiled recipe). Only 0..8 are dispatchable through the unified
+ * `swap()` entry point — see {@link UndispatchablePoolType} for 9/10.
+ */
+export const SwapPoolType = {
+    UniV2: 0,
+    UniV3: 1,
+    UniV4: 2,
+    Curve: 3,
+    BalancerV2: 4,
+    DODOV2: 5,
+    TraderJoeLB: 6,
+    MaverickV2: 7,
+    WOOFi: 8,
+};
+/**
+ * Pool types that exist on the engine's `SwapPoolType` enum but are NOT dispatchable through the
+ * unified `swap()` — `Router.sol`'s `swap()` dispatch chain covers only 0..8 and falls through to
+ * `revert SwapFailed()` for anything else. PancakeInfinity's CL/Bin pools need their own
+ * `swapInfinityCL`/`swapInfinityBin` entry points (a different, 6-field `InfinityPoolKey` that
+ * `SwapParams` cannot carry) — out of scope for this first cut. Exported so the value is nameable;
+ * {@link toSwapParams} throws when handed one of these, pointing at this follow-up.
+ */
+export const UndispatchablePoolType = {
+    PancakeInfinityCL: 9,
+    PancakeInfinityBin: 10,
+};
+const CALLBACK_VENUES = new Set([
+    SwapPoolType.UniV3,
+    SwapPoolType.UniV4,
+    SwapPoolType.MaverickV2,
+]);
+const CALLBACK_FREE_VENUES = new Set([
+    SwapPoolType.UniV2,
+    SwapPoolType.Curve,
+    SwapPoolType.BalancerV2,
+    SwapPoolType.DODOV2,
+    SwapPoolType.TraderJoeLB,
+    SwapPoolType.WOOFi,
+]);
+/**
+ * True for the three pool types `Router.sol` (`~279-283`) allows a non-empty `callback` for — the
+ * pool re-enters the contract mid-swap to pull input, so servicing it requires the router's
+ * compiled code. NOT the same partition as {@link isCallbackFree}: MaverickV2 is callback-driven
+ * yet its handler still takes `abs(amountSpecified)` (see `amountSpecifiedFor`).
+ */
+export function isCallbackVenue(poolType) {
+    return CALLBACK_VENUES.has(poolType);
+}
+/**
+ * True for the pool types whose swap logic is callback-free (`Router.sol` reads reserves / calls a
+ * plain `pool.swap(...)`) and so MAY, as a follow-up, be replicated as direct
+ * `transfer` + `pool.swap` SauceScript instead of going through the Router. This module always
+ * routes through the unified `swap()` regardless — see `sdk/src/swap/index.ts`'s scope notes.
+ */
+export function isCallbackFree(poolType) {
+    return CALLBACK_FREE_VENUES.has(poolType);
+}
+/**
+ * True for the pool types where `SwapParams.poolKey` is actually consulted by the engine:
+ * UniV4 (all 5 fields, via `V4SwapParams`) and, less obviously, UniV2 (`Router.sol#_swapV2` reads
+ * `poolKey.fee` as the pair's LP fee in ppm — `0` defaults to 3000 / 0.30%, `>= 1_000_000` reverts).
+ * Every other pool type ignores `poolKey` entirely.
+ */
+export function usesPoolKey(poolType) {
+    return poolType === SwapPoolType.UniV4 || poolType === SwapPoolType.UniV2;
+}
+/** All-zero `poolKey`, used for any pool type that doesn't consult it (see {@link usesPoolKey}). */
+export const ZERO_POOL_KEY = {
+    currency0: 0n,
+    currency1: 0n,
+    fee: 0n,
+    tickSpacing: 0n,
+    hooks: 0n,
+};
+/** `SwapParams`'s top-level field names, in exact ABI-declaration order (pinned against the
+ *  vendored `ISauceRouter.json` artifact in `sdk/test/swap.test.ts`). */
+export const SWAP_PARAMS_FIELDS = [
+    "poolType",
+    "pool",
+    "poolKey",
+    "tokenIn",
+    "tokenOut",
+    "amountSpecified",
+    "sqrtPriceLimitX96",
+    "payer",
+    "recipient",
+    "callback",
+];
+/** `SwapParams.poolKey`'s field names, in exact ABI-declaration order. */
+export const POOL_KEY_FIELDS = [
+    "currency0",
+    "currency1",
+    "fee",
+    "tickSpacing",
+    "hooks",
+];
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/swap/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,CAAC;IACb,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,UAAU,EAAE,CAAC;IACb,KAAK,EAAE,CAAC;CACA,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,iBAAiB,EAAE,CAAC;IACpB,kBAAkB,EAAE,EAAE;CACd,CAAC;AAKX,MAAM,eAAe,GAA8B,IAAI,GAAG,CAAC;IACzD,YAAY,CAAC,KAAK;IAClB,YAAY,CAAC,KAAK;IAClB,YAAY,CAAC,UAAU;CACxB,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAA8B,IAAI,GAAG,CAAC;IAC9D,YAAY,CAAC,KAAK;IAClB,YAAY,CAAC,KAAK;IAClB,YAAY,CAAC,UAAU;IACvB,YAAY,CAAC,MAAM;IACnB,YAAY,CAAC,WAAW;IACxB,YAAY,CAAC,KAAK;CACnB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAAsB;IACpD,OAAO,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB;IACnD,OAAO,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,QAAsB;IAChD,OAAO,QAAQ,KAAK,YAAY,CAAC,KAAK,IAAI,QAAQ,KAAK,YAAY,CAAC,KAAK,CAAC;AAC5E,CAAC;AAmCD,oGAAoG;AACpG,MAAM,CAAC,MAAM,aAAa,GAAY;IACpC,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,GAAG,EAAE,EAAE;IACP,WAAW,EAAE,EAAE;IACf,KAAK,EAAE,EAAE;CACV,CAAC;AAsEF;yEACyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAkC;IAC/D,UAAU;IACV,MAAM;IACN,SAAS;IACT,SAAS;IACT,UAAU;IACV,iBAAiB;IACjB,mBAAmB;IACnB,OAAO;IACP,WAAW;IACX,UAAU;CACX,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAA+B;IACzD,WAAW;IACX,WAAW;IACX,KAAK;IACL,aAAa;IACb,OAAO;CACR,CAAC"}

package/sdk/dist/token/api.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `Token` — the runtime value behind the DEFAULT GLOBAL `Token` (see `sdk/src/routes/globals.ts`).
+ * A plain, inert builder: `Token.transfer(spec)`/`.approve(spec)`/`.balanceOf(spec)` return a
+ * `TokenCall`, synchronous, no RPC, no compiler import — the same posture as
+ * `descriptors/call.ts`'s `ContractCall`.
+ */
+import { type Hex } from "viem";
+import { ERC20ABI } from "../protocols/erc20/abis.js";
+import { ata } from "../svm/venues/scale-common.js";
+import { type AddressInput, type TokenApproveSpec, type TokenBalanceSpec, type TokenSpec, type TokenTarget, type TokenTransferSpec } from "./types.js";
+export interface TokenSauceScript {
+    readonly imports: readonly string[];
+    readonly statement: string;
+    readonly source: string;
+    readonly baseDirs: readonly string[];
+    readonly accountRefs?: readonly string[];
+}
+export interface TokenCall {
+    readonly spec: TokenSpec;
+    /** A complete, compilable one-op `function main() { ... }` program. */
+    source(target: TokenTarget): string;
+    /** The bare statement (transfer/approve), for splicing into a larger program. Throws for `balanceOf`. */
+    statement(target: TokenTarget): string;
+    /** The bare expression (balanceOf only). Throws for transfer/approve. */
+    expression(target: TokenTarget): string;
+    toSauceScript(target: TokenTarget): TokenSauceScript;
+    /** EVM only: `{ target, data, value }` via `viem`'s `encodeFunctionData`. Throws for an svm spec. */
+    toCall(): {
+        readonly target: `0x${string}`;
+        readonly data: Hex;
+        readonly value: bigint;
+    };
+    /** SVM only: the AccountPlan refs this op interns, in order. Throws for an EVM-target spec. */
+    accountRefs(): readonly string[];
+}
+/**
+ * What `Token(<addr>)` yields **inside a route body** — the wrapper form, not the runtime API.
+ *
+ * Route-body calls are positional (`Token(a).approve(spender, amt)`) where the runtime
+ * [`TokenApi`] takes a spec object, because the body is compiled to Sauce bytecode rather than
+ * executed: `token-rewrite.ts#rewriteTokenFactory` replaces the callee with `IERC20.at` before the
+ * compiler sees it, and these signatures are what let a **typed closure** body typecheck on the way
+ * there. Nothing calls these at run time, which is why they live here rather than on `TokenApi`.
+ */
+export interface TokenBinding {
+    transfer(to: AddressInput, amount: bigint): void;
+    approve(spender: AddressInput, amount: bigint): void;
+    balanceOf(owner: AddressInput): bigint;
+}
+/**
+ * The call signature the **ambient** `Token` global carries, intersected onto [`TokenApi`] by
+ * `gen-route-globals.mjs` — the same way each chain global is `ChainGlobals[...] & ChainContracts`.
+ *
+ * Deliberately NOT on `TokenApi` itself: the runtime `Token` export is a frozen object and is not
+ * callable, so typing it as callable would promise something that throws. The ambient declaration
+ * describes what is legal in a route body, where the call never survives to run.
+ */
+export interface TokenFactory {
+    (address: AddressInput): TokenBinding;
+}
+export interface TokenApi {
+    transfer(spec: TokenTransferSpec): TokenCall;
+    approve(spec: TokenApproveSpec): TokenCall;
+    balanceOf(spec: TokenBalanceSpec): TokenCall;
+    /** N ops in ONE `main()` — because `V12Pot.cook`/an SVM program executes ONE program. */
+    program(specs: readonly TokenSpec[], opts: {
+        target: TokenTarget;
+    }): string;
+    readonly ata: typeof ata;
+    readonly TOKEN_PROGRAM: bigint;
+    readonly TOKEN_2022_PROGRAM: bigint;
+    readonly ERC20ABI: typeof ERC20ABI;
+    readonly SPL_TRANSFER_CHECKED: number;
+    readonly SPL_APPROVE_CHECKED: number;
+    readonly SPL_AMOUNT_OFFSET: number;
+    readonly MINT_DECIMALS_OFFSET: number;
+}
+/**
+ * The universal token interface — ERC20 on an EVM compile target, SPL Token on `svm`. See
+ * `sdk/src/token/index.ts` for the module overview. Installed as the DEFAULT GLOBAL `Token` (zero
+ * import) by `sdk/src/routes/globals.ts`; also available as the named export `token.Token`.
+ */
+export declare const Token: TokenApi;
+//# sourceMappingURL=api.d.ts.map

package/sdk/dist/token/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/token/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAsB,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAiBpD,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IACpC,yGAAyG;IACzG,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IACvC,yEAAyE;IACzE,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IACxC,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACrD,qGAAqG;IACrG,MAAM,IAAI;QAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,+FAA+F;IAC/F,WAAW,IAAI,SAAS,MAAM,EAAE,CAAC;CAClC;AA2FD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;CACvC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC7C,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC3C,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7C,yFAAyF;IACzF,OAAO,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5E,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IACnC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,QAclB,CAAC"}

package/sdk/dist/token/api.js

@@ -0,0 +1,116 @@
+/**
+ * `Token` — the runtime value behind the DEFAULT GLOBAL `Token` (see `sdk/src/routes/globals.ts`).
+ * A plain, inert builder: `Token.transfer(spec)`/`.approve(spec)`/`.balanceOf(spec)` return a
+ * `TokenCall`, synchronous, no RPC, no compiler import — the same posture as
+ * `descriptors/call.ts`'s `ContractCall`.
+ */
+import { encodeFunctionData } from "viem";
+import { ERC20ABI } from "../protocols/erc20/abis.js";
+import { ata } from "../svm/venues/scale-common.js";
+import { toAddressBigint, toAmountBigint, validateApproveSpec, validateBalanceSpec, validateTransferSpec, } from "./params.js";
+import { tokenAccountRefs, tokenExpression, TOKEN_BASE_DIRS, tokenCallStatement, tokenImportLines, tokenSource, } from "./source.js";
+import { TOKEN_PROGRAM_BIGINT, TOKEN_2022_PROGRAM_BIGINT } from "./svm.js";
+import { MINT_DECIMALS_OFFSET, SPL_AMOUNT_OFFSET, SPL_APPROVE_CHECKED, SPL_TRANSFER_CHECKED, } from "./types.js";
+function makeTokenCall(spec) {
+    return {
+        spec,
+        source: (target) => tokenSource(spec, target),
+        statement: (target) => tokenCallStatement(spec, target),
+        expression: (target) => tokenExpression(spec, target),
+        toSauceScript: (target) => {
+            const imports = tokenImportLines([spec], target);
+            const src = tokenSource(spec, target);
+            const isBalance = spec.op === "balanceOf";
+            const statement = isBalance
+                ? `${tokenExpression(spec, target)};`
+                : tokenCallStatement(spec, target);
+            return {
+                imports,
+                statement,
+                source: src,
+                baseDirs: TOKEN_BASE_DIRS,
+                ...(target === "svm" ? { accountRefs: tokenAccountRefsSafe(spec, target) } : {}),
+            };
+        },
+        toCall: () => {
+            if (spec.svm !== undefined) {
+                throw new Error(`TokenCall.toCall: Token.${spec.op} is an SVM spec — use accountRefs()/toSauceScript('svm') instead`);
+            }
+            if (spec.op === "balanceOf") {
+                validateBalanceSpec(spec, "evm");
+                if (spec.owner === "self") {
+                    throw new Error("TokenCall.toCall: Token.balanceOf('self') has no fixed calldata — compile it instead");
+                }
+                return {
+                    target: hexAddress(spec.token, "token"),
+                    data: encodeFunctionData({
+                        abi: ERC20ABI,
+                        functionName: "balanceOf",
+                        args: [hexAddress(spec.owner, "owner")],
+                    }),
+                    value: 0n,
+                };
+            }
+            if (spec.op === "transfer")
+                validateTransferSpec(spec, "evm");
+            else
+                validateApproveSpec(spec, "evm");
+            if (spec.amount === "balance") {
+                throw new Error(`TokenCall.toCall: Token.${spec.op} with amount: "balance" has no fixed calldata — compile it instead`);
+            }
+            if (spec.op === "transfer") {
+                return {
+                    target: hexAddress(spec.token, "token"),
+                    data: encodeFunctionData({
+                        abi: ERC20ABI,
+                        functionName: "transfer",
+                        args: [hexAddress(spec.to, "to"), toAmountBigint(spec.amount, "Token.transfer amount")],
+                    }),
+                    value: 0n,
+                };
+            }
+            return {
+                target: hexAddress(spec.token, "token"),
+                data: encodeFunctionData({
+                    abi: ERC20ABI,
+                    functionName: "approve",
+                    args: [
+                        hexAddress(spec.spender, "spender"),
+                        toAmountBigint(spec.amount, "Token.approve amount"),
+                    ],
+                }),
+                value: 0n,
+            };
+        },
+        accountRefs: () => tokenAccountRefsSafe(spec, "svm"),
+    };
+}
+function tokenAccountRefsSafe(spec, target) {
+    return tokenAccountRefs(spec, target);
+}
+function hexAddress(value, label) {
+    if (value === undefined)
+        throw new Error(`TokenCall.toCall: ${label} is required`);
+    const big = toAddressBigint(value, label);
+    return `0x${big.toString(16).padStart(40, "0")}`;
+}
+/**
+ * The universal token interface — ERC20 on an EVM compile target, SPL Token on `svm`. See
+ * `sdk/src/token/index.ts` for the module overview. Installed as the DEFAULT GLOBAL `Token` (zero
+ * import) by `sdk/src/routes/globals.ts`; also available as the named export `token.Token`.
+ */
+export const Token = Object.freeze({
+    transfer: (spec) => makeTokenCall({ op: "transfer", ...spec }),
+    approve: (spec) => makeTokenCall({ op: "approve", ...spec }),
+    balanceOf: (spec) => makeTokenCall({ op: "balanceOf", ...spec }),
+    program: (specs, opts) => tokenSource(specs, opts.target),
+    ata,
+    TOKEN_PROGRAM: TOKEN_PROGRAM_BIGINT,
+    TOKEN_2022_PROGRAM: TOKEN_2022_PROGRAM_BIGINT,
+    ERC20ABI,
+    SPL_TRANSFER_CHECKED,
+    SPL_APPROVE_CHECKED,
+    SPL_AMOUNT_OFFSET,
+    MINT_DECIMALS_OFFSET,
+});
+//# sourceMappingURL=api.js.map

package/sdk/dist/token/api.js.map

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