@eco-incorp/sauce 0.99.0

package/sdk/dist/routes/sauce-calls.js

@@ -0,0 +1,237 @@
+/**
+ * eco-routes Sauce-bytecode `route.calls[]` builders — E3.3.
+ *
+ * Turns compiled Sauce bytecode (the compiler's output) into the `CallInput`(s) that slot straight
+ * into a `RouteInput.calls` (E3.1's fluent builder) and flow unchanged through `normalizeRoute` /
+ * `encodeRouteEvm` / `encodeRouteSvm` (E3.2). This module does not re-implement either of those —
+ * it only decides WHAT the `target`/`data`/`value` of a Sauce-executing call are, forking on chain
+ * kind (`../chains/canonical.js` `isEvm`/`isSvm`, via `encode.js#kindOf` — bigint-aware, so a native
+ * `Intent.destination` passes through with no silent evm mis-classification).
+ *
+ * EVM: `target = pot`, `data = v12Pot.encodeCook(engine, program)` (`../evm/engine.js`, reused verbatim
+ * — no re-encoding), `value` defaults to `0n`. The Pot address is deliberately NOT defaulted: it is
+ * a per-OWNER CREATE2 address (`v12Kitchen.deployPot(owner, salt)`) and `cook()` is `onlyOwner`, so
+ * only the caller (who knows the fulfilling executor) can supply it — see
+ * `sauceEvmDeployPotCall`/`v12Kitchen.encodePredictPot` for how to derive one.
+ *
+ * SVM: multi-KB Sauce bytecode cannot fit in a single ~1,232-byte transaction, so it must already
+ * be STAGED in a buffer PDA before any route call can reference it. **This module never stages
+ * anything** — see the "SVM STAGING IS A PREREQUISITE" section below. Given an already-staged
+ * buffer address, it builds an `execute_from_account` instruction
+ * (`../svm/instructions.js#buildExecuteFromAccountInstruction`, the `/svm/engine` kit surface) and
+ * wraps it in the Portal `CalldataWithAccounts` Borsh envelope (`../svm/intent.js
+ * #encodePortalCalldataWithAccounts`) — that envelope IS the SVM route call's `data`.
+ *
+ * WHY THIS FILE IMPORTS `@solana/kit` BUT NEVER `@solana/web3.js`: `sdk/src/index.ts` re-exports
+ * `routes` from the main SDK barrel, and `@solana/web3.js` is not a dependency of this package at
+ * all. Hard-requiring it here would make the main barrel fail
+ * to load for any consumer who did not install it. So every SVM address parameter accepts a plain
+ * base58 string, a kit `Address`, or anything duck-typed like a web3.js `PublicKey`
+ * (`{ toBase58(): string }`) — see `SvmAddressInput`/`toSvmAddress` — never an imported `PublicKey`
+ * type. A web3.js consumer passes its `PublicKey`s straight in; nothing here imports the package.
+ *
+ * ── SVM STAGING IS A PREREQUISITE (solver-side, NOT performed here) ──
+ *
+ * Before any `buildSauceSvmCall`/`buildSauceSvmCalls` output is submittable, the referenced buffer
+ * must already be created, written, and FINALIZED through the KITCHEN — the engine itself holds no
+ * staging. All of it is on `@eco-incorp/sauce/svm` (`../svm/kitchen.js`):
+ *   1. `deriveCodeBufferPda(kitchen, owner, nonce)` for the metadata account, then
+ *      `deriveCodePda(kitchen, codeBuffer)` for the bytes account — seeded on the metadata
+ *      address, so the pair is bound by derivation. The second is the one a call names.
+ *   2. `buildCreateCodeBufferInstruction` / `buildWriteCodeBufferInstruction` /
+ *      `buildFinalizeCodeBufferInstruction` to create, fill and finalize it, plus
+ *      `Math.ceil(capacity / GROWTH_STEP) - 1` `buildGrowCodeBufferInstruction` calls, because a
+ *      create allocates at most one `GROWTH_STEP`. Finalize takes the 32-byte `expectedSha256`
+ *      the caller computes over the bytecode; that same hash is the pin below.
+ *   3. Only THEN does a `StagedBufferRef.buffer` naming that address produce a call that will
+ *      actually execute — an unstaged, half-written, or unfinalized buffer fails at FULFILL time
+ *      (the engine dispatches on the account's own header, not on anything this module can see), not
+ *      at build time here.
+ *
+ * `StagedBufferRef` deliberately carries no `bytecode`/`seed`/`authority`/`payer` field: accepting
+ * any of those would imply this module can perform the staging above. It cannot — it only accepts
+ * the RESOLVED buffer address a solver-side process already produced.
+ *
+ * `buildExecuteAndCloseInstruction` (the buffer-reaping variant) is deliberately never used here: it
+ * needs the buffer WRITABLE and drains its rent, a lifecycle action; a route call only ever executes
+ * a staged program (buffer READONLY) via `execute_from_account`. Writability is a transaction-level
+ * property, so the two can never share a transaction anyway.
+ */
+import { AccountRole, address, getAddressEncoder, isSignerRole, isWritableRole } from "@solana/kit";
+import { bytesToHex } from "viem";
+import { v12Kitchen, v12Pot } from "../evm/engine.js";
+import { requireV12Deployment, v12SvmProgramId } from "../deployments/index.js";
+import { encodePortalCalldataWithAccounts } from "../svm/intent.js";
+import { assertNoExecutePin, buildExecuteFromAccountInstruction } from "../svm/instructions.js";
+import { kindOf, denormalizeToEvm } from "./encode.js";
+import { toBigInt, toUniversalAddress } from "./normalize.js";
+/** One `cook(engine, program)` call on `pot`. `data` is produced by `v12Pot.encodeCook` — the exact
+ *  EVM engine encoder, not re-implemented here. */
+export function buildSauceEvmCall(params) {
+    return {
+        target: toUniversalAddress(params.pot),
+        data: v12Pot.encodeCook(denormalizeToEvm(toUniversalAddress(params.engine)), params.program),
+        value: params.value ?? 0n,
+    };
+}
+/** One `Call` per element of `cooks`, in the given order, all targeting the same `pot`. */
+export function buildSauceEvmCalls(params) {
+    return params.cooks.map((program) => buildSauceEvmCall({ pot: params.pot, engine: params.engine, program, value: params.value }));
+}
+/**
+ * The leading `deployPot(owner, salt)` call a solver issues before its first `cook()` on a Pot that
+ * may not exist yet.
+ *
+ * One of `kitchen` / `chainId` is required. The ungated `V12_EVM_CONTRACTS.v12Kitchen` is NOT a
+ * fallback: those addresses are CREATE2 over the initcode that produced them, so they name the
+ * stack deployed before the engine became a `cook` argument (see `deployments/v12.generated.ts`).
+ * Silently deploying a Pot through an older-lineage Kitchen gives a Pot at an address the caller did
+ * not predict, whose `cook` takes the old signature. `chainId` still reaches the record — through
+ * the liveness gate, which is the part that makes it answerable.
+ */
+export function sauceEvmDeployPotCall(params) {
+    if (params.kitchen === undefined && params.chainId === undefined) {
+        throw new Error("sauceEvmDeployPotCall: pass `kitchen`, or a `chainId` to take it from the gated deployment " +
+            "record — there is no ungated default Kitchen address.");
+    }
+    const kitchen = params.kitchen ?? requireV12Deployment(params.chainId).v12Kitchen;
+    const ownerAddress = denormalizeToEvm(toUniversalAddress(params.owner));
+    return {
+        target: kitchen,
+        data: v12Kitchen.encodeDeployPot(ownerAddress, params.salt),
+        value: 0n,
+    };
+}
+/** Thin delegate to `requireV12Deployment` — throws with the reason when the v12 stack is not live
+ *  on `chainId` (e.g. ronin/2020, whose deploy did not land). */
+export function assertSauceEvmLive(chainId) {
+    return requireV12Deployment(chainId);
+}
+function toSvmAddress(input, label) {
+    if (typeof input === "string")
+        return address(input);
+    if (input !== null &&
+        typeof input === "object" &&
+        typeof input.toBase58 === "function") {
+        return address(input.toBase58());
+    }
+    throw new Error(`${label}: expected a base58 string, an Address, or a { toBase58() } (e.g. a web3.js PublicKey), got ${String(input)}`);
+}
+/** Canonical string key for de-duplicating/matching an `SvmAddressInput` (its resolved base58 form). */
+function svmAddressKey(input, label) {
+    return String(toSvmAddress(input, label));
+}
+function toRole(isSigner, isWritable) {
+    return isWritable
+        ? isSigner
+            ? AccountRole.WRITABLE_SIGNER
+            : AccountRole.WRITABLE
+        : isSigner
+            ? AccountRole.READONLY_SIGNER
+            : AccountRole.READONLY;
+}
+/**
+ * Cross-call OR-merge of `isSigner`/`isWritable` per pubkey across every given instruction's
+ * accounts — the Solana runtime dedupes a repeated pubkey in one transaction to the union of its
+ * flags, so a leg's own two staged calls (e.g. swap half + settle half) sharing an account must
+ * agree on the more-permissive flags before either is built, not just within itself.
+ */
+export function mergeSvmAccountFlags(instructions) {
+    const merged = new Map();
+    for (const ix of instructions) {
+        for (const acc of ix.accounts) {
+            const key = svmAddressKey(acc.pubkey, "account.pubkey");
+            const prev = merged.get(key) ?? { isSigner: false, isWritable: false };
+            merged.set(key, {
+                isSigner: prev.isSigner || acc.isSigner,
+                isWritable: prev.isWritable || acc.isWritable,
+            });
+        }
+    }
+    return merged;
+}
+function applyMergedFlags(accounts, merged) {
+    return accounts.map((a) => {
+        const flags = merged.get(svmAddressKey(a.pubkey, "account.pubkey"));
+        return flags === undefined
+            ? a
+            : { ...a, isSigner: flags.isSigner, isWritable: flags.isWritable };
+    });
+}
+function forceExecutorNonSigner(accounts, executor) {
+    if (executor === undefined)
+        return accounts.slice();
+    const key = svmAddressKey(executor, "executor");
+    return accounts.map((a) => svmAddressKey(a.pubkey, "account.pubkey") === key ? { ...a, isSigner: false } : a);
+}
+function assertSvmValue(value) {
+    if (value !== undefined && toBigInt(value) !== 0n) {
+        throw new Error("buildSauceSvmCall: SVM Call has no value field (nonzero value cannot be encoded)");
+    }
+}
+/** Builds one `execute_from_account` CPI, wrapped in the Portal `CalldataWithAccounts` envelope, for
+ *  an ALREADY-staged buffer. `merged`, when given, overrides each account's flags per the cross-call
+ *  merge (`mergeSvmAccountFlags`); executor-flattening always runs after the merge, so it wins. */
+function buildOneSauceSvmCall(programId, execution, executor, merged) {
+    assertSvmValue(execution.value);
+    let accounts = execution.accounts;
+    if (merged !== undefined)
+        accounts = applyMergedFlags(accounts, merged);
+    accounts = forceExecutorNonSigner(accounts, executor);
+    const resolvedAccounts = accounts.map((a) => ({
+        address: toSvmAddress(a.pubkey, "account.pubkey"),
+        role: toRole(a.isSigner, a.isWritable),
+    }));
+    assertNoExecutePin(execution.expectedSha256);
+    const ix = buildExecuteFromAccountInstruction({
+        programId,
+        code: toSvmAddress(execution.code, "code"),
+        accounts: resolvedAccounts,
+    });
+    // Buffer rides FIRST (READONLY) — buildExecuteFromAccountInstruction already puts it there; this
+    // just re-derives isSigner/isWritable from the role kit's own way (isSignerRole/isWritableRole),
+    // mirroring engine-web3js.ts#toWeb3JsInstruction, so the envelope's account metas track kit's
+    // AccountRole encoding rather than assuming a bit layout.
+    const envelopeAccounts = (ix.accounts ?? []).map((a) => ({
+        pubkey: a.address,
+        isSigner: isSignerRole(a.role),
+        isWritable: isWritableRole(a.role),
+    }));
+    const data = encodePortalCalldataWithAccounts({
+        instructionData: (ix.data ?? new Uint8Array()),
+        accounts: envelopeAccounts,
+    });
+    const target = bytesToHex(getAddressEncoder().encode(programId));
+    return { target, data, value: 0n };
+}
+/** Builds ONE staged SVM route call. Merges account flags within its own instruction only — use
+ *  `buildSauceSvmCalls` for the cross-call merge over a whole leg. */
+export function buildSauceSvmCall(params) {
+    const programId = toSvmAddress(params.programId ?? v12SvmProgramId, "programId");
+    const merged = mergeSvmAccountFlags([params]);
+    return buildOneSauceSvmCall(programId, params, params.executor, merged);
+}
+/** RECOMMENDED entry point: builds one staged route call per `executions` element, with account
+ *  flags OR-merged across the whole leg by default. */
+export function buildSauceSvmCalls(params) {
+    const programId = toSvmAddress(params.programId ?? v12SvmProgramId, "programId");
+    const merged = (params.mergeAccountFlags ?? true) ? mergeSvmAccountFlags(params.executions) : undefined;
+    return params.executions.map((execution) => buildOneSauceSvmCall(programId, execution, params.executor, merged));
+}
+// ---------------------------------------------------------------------------
+// Chain-kind fork
+// ---------------------------------------------------------------------------
+/** Forks on `kindOf(chain)` (bigint-aware; throws for an unregistered chain id rather than
+ *  defaulting to evm) to build one Sauce-executing `Call` for either engine. */
+export function buildSauceCall(chain, params) {
+    return kindOf(chain) === "svm"
+        ? buildSauceSvmCall(params)
+        : buildSauceEvmCall(params);
+}
+/** Plural fork of {@link buildSauceCall}. */
+export function buildSauceCalls(chain, params) {
+    return kindOf(chain) === "svm"
+        ? buildSauceSvmCalls(params)
+        : buildSauceEvmCalls(params);
+}
+//# sourceMappingURL=sauce-calls.js.map

package/sdk/dist/routes/sauce-calls.js.map

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

package/sdk/dist/routes/sauce-route.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Cross-chain intent DSL — S1: compile a Sauce program for a route's DESTINATION chain and slot it
+ * into `route.calls`. Additive, compiler-untouching (see `docs/plans/2026-08-09-xchain-intent-dsl-v2.md`
+ * for the full staged design; this file implements stage 1 only).
+ *
+ * `compileSauceRoute` is the compile-and-slot seam: it never re-implements the EVM/SVM call
+ * builders (`buildSauceEvmCall`/`buildSauceSvmCall` in `sauce-calls.ts`) or the ABI/Borsh encoding —
+ * it only decides WHICH target to compile for (from the destination chain's `ChainKind`) and forks
+ * to the existing builder.
+ *
+ * SVM STAGING (unchanged prerequisite): a staged SVM route call executes bytecode that already
+ * lives in a buffer PDA — this module never stages anything, exactly like `sauce-calls.ts`'s own
+ * "SVM STAGING IS A PREREQUISITE" section documents. `compileSauceRoute` compiles the program (so
+ * the caller has the bytecode to stage) but requires `execution.code` to already name an
+ * already-staged buffer; omitting it is a build-time error pointing back at that section, not a
+ * silent no-op or a confusing later encode-time failure.
+ *
+ * ONE COOK = ONE PROGRAM: `V12Pot.cook` takes exactly one `bytes program`, so a route body is
+ * always compiled to exactly one bytecode blob (`compiled.bytecode[0]`) and slotted as exactly one
+ * `Call` — a multi-statement body is one program with N statements, never N cooks.
+ *
+ * THE SVM CALL DOES NOT COMMIT TO THE COMPILE. An EVM call carries the compiled bytecode itself, but
+ * a staged SVM call names only a CODE account, and the released engine's `execute_from_account` has
+ * no instruction payload — so there is nowhere to put a content pin and nothing here injects one.
+ * The returned calldata says which account to run, never which bytes are in it.
+ *
+ * The pin that IS enforced on chain is the kitchen's, supplied to
+ * `buildFinalizeCodeBufferInstruction` when the buffer is finalized. That binds the bytes at
+ * staging time, in another transaction, asserted by the party that already controlled them — so a
+ * consumer of this route is not protected by it. Treat `compiled.bytecode[0]` as the thing to
+ * compare the account's contents against yourself.
+ */
+import type { CompileResult, CompileTarget, ContractsConfig } from "./compile-types.js";
+import type { ChainRef } from "../chains/canonical.js";
+import { type SauceSvmCallParams } from "./sauce-calls.js";
+import { type ProtocolRewriteOptions } from "./protocol-rewrite.js";
+import type { AddressInput, CallInput } from "./types.js";
+export interface SauceCompileOptions {
+    /** Defaults by destination `ChainKind`: `'v12'` for evm, `'svm'` for svm. */
+    target?: CompileTarget;
+    baseDirs?: string[];
+    /**
+     * Compile-time parameters, injected into every module as a module-scope `const` — a define
+     * REPLACES the module's own `const` of that name and is constant-folded, so a given set of values
+     * yields fixed bytecode. This is how a standalone `.sauce.ts` asset (e.g.
+     * `recipes/cctp-split.sauce.ts`) is specialized for one intent. A value is one 256-bit word, so an
+     * array or a lookup table cannot be supplied this way — a program needing a variable-length list
+     * generates one declaration per element instead (see `svm/recipes/index.ts`).
+     */
+    defines?: Record<string, bigint | boolean | number>;
+    /** Caller token symbol -> address OVERRIDES, merged per-key on top of `token-registry.ts`'s
+     *  default per-chain registry (see `resolveTokenMap`) -- the merged map drives both `<Sym>.
+     *  transfer/.approve/.balanceOf(...)` (U4) and `<holder>.<Sym>` balance-sugar rewrites (see
+     *  `token-rewrite.ts`). A bare `USDC.transfer(...)` on a chain the registry covers now compiles
+     *  with NO entry here at all. EVM destinations only -- an svm destination throws if any site
+     *  actually rewrites, pointing at the SPL account-plan `Token` emitter instead. */
+    tokens?: Readonly<Record<string, AddressInput>>;
+    /** Forwarded directly to `compile()` -- merged with the bindings the protocol-accessor rewrite
+     *  (below) synthesizes. A same-named entry with a DIFFERENT abi throws (see `protocol-rewrite.ts`). */
+    contracts?: ContractsConfig;
+    /** The full protocol-accessor rewrite (`protocol-rewrite.ts`) -- `Uniswap.UniversalRouter.execute(...)`
+     *  -> `IUniswapV4_UniversalRouter.at(<addr>n).execute(...)`, plus bare `self` -> `ctx.self()`.
+     *  Default ON (`true`); pass `false` to opt out entirely, or an options object to tune it. Default-ON
+     *  is isolation-safe by measurement: the shapes it claims (a 1-3 segment member-chain call rooted at
+     *  a registry namespace or canonical-chain key) do not compile at all today, so this can only turn a
+     *  hard compile error into a success or a clearer error -- never break an already-compiling program.
+     *  EVM destinations only -- an svm destination with at least one rewritten accessor site throws. */
+    accessors?: boolean | ProtocolRewriteOptions;
+    /**
+     * Module specifiers whose exports are broadcast into every module with no `import` line: an
+     * ambient module's exported functions and consts become callable/readable with no import. Ambient
+     * always loses to user code — a name the module declares, imports or binds wins silently.
+     */
+    ambient?: string[];
+}
+export interface SauceEvmExecutionInput {
+    /** The Pot contract to `cook()` on — see `sauce-calls.ts#SauceEvmCallParams`, never defaulted. */
+    pot: AddressInput;
+    /**
+     * The interpreter this cook runs on, required for the same reason `pot` is: it is not something
+     * this module can guess correctly.
+     *
+     * It exists because a Pot holds no engine — the interpreter is a `cook` argument on both targets.
+     * There is deliberately no default. `V12_EVM_CONTRACTS.v12Runtime` is the obvious candidate and is
+     * the wrong one: those addresses are CREATE2 of the initcode that produced them, so they name the
+     * stack deployed BEFORE the engine moved into `cook`'s arguments — an interpreter of the older
+     * lineage. Defaulting to it would put the right program on the wrong engine silently, which is
+     * the one mistake a caller cannot see in the encoded call.
+     */
+    engine: AddressInput;
+    value?: bigint | number | string;
+}
+/**
+ * Verbatim the existing `sauce-calls.ts#SauceSvmCallParams` shape (`StagedBufferRef` + `accounts` +
+ * `programId?`/`executor?`) — a route's SVM execution input IS a staged-buffer execution, no new
+ * fields needed. `expectedSha256` must be left off: nothing fills it, the engine instruction cannot
+ * carry it, and passing it throws — see `svm/instructions.ts#assertNoExecutePin`.
+ */
+export type SauceSvmExecutionInput = SauceSvmCallParams;
+export interface CompiledSauceRoute {
+    readonly calls: readonly CallInput[];
+    readonly compiled: CompileResult;
+    /** The actual source text handed to `compile()` (after bare-body wrapping, if applied). */
+    readonly source: string;
+}
+export declare function wrapSauceBody(sauce: string): string;
+/**
+ * Compiles `sauce` (a complete `function main(){...}` program, or a bare body auto-wrapped by
+ * {@link wrapSauceBody}) for `destination`'s `ChainKind`, and slots the result into exactly one
+ * `CallInput` via the existing `buildSauceEvmCall`/`buildSauceSvmCall` fork — never a new encoder.
+ */
+export declare function compileSauceRoute(destination: ChainRef, sauce: string, execution: SauceEvmExecutionInput | SauceSvmExecutionInput, options?: SauceCompileOptions): CompiledSauceRoute;
+//# sourceMappingURL=sauce-route.d.ts.map

package/sdk/dist/routes/sauce-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sauce-route.d.ts","sourceRoot":"","sources":["../../src/routes/sauce-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGxF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAwC,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIjG,OAAO,EAA4B,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAG9F,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;IACpD;;;;;uFAKmF;IACnF,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAChD;2GACuG;IACvG,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;wGAMoG;IACpG,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,kGAAkG;IAClG,GAAG,EAAE,YAAY,CAAC;IAClB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,sBAAsB,GAAG,sBAAsB,EAC1D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAmIpB"}

package/sdk/dist/routes/sauce-route.js

@@ -0,0 +1,142 @@
+import { bytesToHex } from "viem";
+import { requireChain } from "../chains/canonical.js";
+import { buildSauceEvmCall, buildSauceSvmCall } from "./sauce-calls.js";
+import { compileWithRs } from "./rs-compile.js";
+import { rewriteTokenFactory, rewriteTokenMembers } from "./token-rewrite.js";
+import { resolveTokenMap } from "./token-registry.js";
+import { rewriteProtocolAccessors } from "./protocol-rewrite.js";
+import { TOKEN_BASE_DIRS } from "../token/source.js";
+import { ERC20_IMPORT_LINE } from "../token/evm.js";
+/**
+ * Deliberately dumb, documented rule (the acorn-based version arrives in stage 3 alongside the
+ * closure-sugar route-body form): a source is treated as "already a complete program" whenever it
+ * contains a top-level-looking `function main(` anywhere not immediately preceded by a word
+ * character or `.` (so `foo.main(` or `xmain(` don't false-positive); anything else is wrapped as a
+ * `function main() { ... }` body.
+ */
+const MAIN_FN_RE = /(^|[^.\w])function\s+main\s*\(/;
+export function wrapSauceBody(sauce) {
+    if (MAIN_FN_RE.test(sauce))
+        return sauce;
+    return `function main() {\n${sauce}\n}`;
+}
+function defaultTargetFor(kind) {
+    return kind === "svm" ? "svm" : "v12";
+}
+/**
+ * Compiles `sauce` (a complete `function main(){...}` program, or a bare body auto-wrapped by
+ * {@link wrapSauceBody}) for `destination`'s `ChainKind`, and slots the result into exactly one
+ * `CallInput` via the existing `buildSauceEvmCall`/`buildSauceSvmCall` fork — never a new encoder.
+ */
+export function compileSauceRoute(destination, sauce, execution, options = {}) {
+    const chain = requireChain(destination);
+    const target = options.target ?? defaultTargetFor(chain.kind);
+    if (chain.kind === "svm" && target !== "svm") {
+        throw new Error(`compileSauceRoute: destination '${chain.slug}' is svm but options.target is '${target}' — an svm destination requires target 'svm'`);
+    }
+    if (chain.kind === "evm" && target === "svm") {
+        throw new Error(`compileSauceRoute: destination '${chain.slug}' is evm but options.target is 'svm'`);
+    }
+    // The registry-resolved token map (registry defaults + options.tokens overrides, per-key -- see
+    // token-registry.ts#resolveTokenMap). Computed unconditionally: for an evm chain the registry may
+    // already supply symbols even with no caller options.tokens at all; for an svm chain/id the
+    // registry itself has no rows (no TOKEN_REGISTRY key is ever an svm chain id), so this reduces to
+    // "only options.tokens, if any" -- preserving the existing svm-throws-on-any-rewrite behavior.
+    const tokenMap = resolveTokenMap(chain, options.tokens);
+    let source = wrapSauceBody(sauce);
+    let baseDirs = options.baseDirs;
+    let contracts = options.contracts;
+    // Seed the resolved token map into defines UNDERNEATH the caller's own options.defines -- closes
+    // a latent gap where a direct compileSauceRoute(..., { tokens }) call emitted U4's bare
+    // `IERC20.at(USDC)` (the symbol, not a literal) with no `USDC` define at all. Idempotent with
+    // openRoute's own ambient-defines merge (ambient.ts#chainDefines resolves the SAME registry), so
+    // this is a no-op when reached via openRoute and a genuine fix for a direct caller.
+    const defines = tokenMap.size > 0 ? { ...Object.fromEntries(tokenMap), ...options.defines } : options.defines;
+    // ORDER IS LOAD-BEARING: the token pass (U4 + balance sugar) runs BEFORE the protocol-accessor
+    // pass. The accessor pass's `self` sugar rewrites a bare `self` Identifier -> `ctx.self()`
+    // textually; if it ran first, `self.USDC` would become `ctx.self().USDC` and the balance
+    // sugar's holder would no longer be a bare Identifier, silently losing the site. Safe in the
+    // other direction: the accessor pass cannot claim IERC20.at(...)'s output (neither a namespace
+    // nor a chain key, and its call sits mid-chain, which `decomposeMemberChain` declines), and its
+    // synthesized-binding collision check cannot trip on `IERC20` (`pascalOfSlug("erc20")` yields
+    // `IErc20_*`, not `IERC20`); the sugar's own `ctx.self()` output is immune to the accessor
+    // pass's self-sugar too (`self` there is a member PROPERTY, which its exclusion set already
+    // covers). See routes-token-rewrite.test.ts's composition test for the regression lock.
+    // Two ERC20 rewrites, both lowering to `IERC20.at(...)`: the `<Sym>.transfer(...)` symbol sugar
+    // (only when the chain has resolved token symbols) and the `Token(addr)` global wrapper (always —
+    // it takes an arbitrary address, not a registry symbol). Whichever fires, the `IERC20` import is
+    // injected ONCE and `TOKEN_BASE_DIRS` unioned in once; on svm either is the same EVM-only error.
+    let tokenRewrote = false;
+    if (tokenMap.size > 0) {
+        const rewritten = rewriteTokenMembers(source, tokenMap);
+        if (rewritten.rewrote) {
+            source = rewritten.source;
+            tokenRewrote = true;
+        }
+    }
+    const factory = rewriteTokenFactory(source);
+    if (factory.rewrote) {
+        source = factory.source;
+        tokenRewrote = true;
+    }
+    if (tokenRewrote) {
+        if (chain.kind === "svm") {
+            throw new Error(`compileSauceRoute: destination '${chain.slug}' is svm — the ERC20 token rewrite ` +
+                "(`Token(addr)` / `<Sym>.transfer(...)`) is EVM-only; an SVM route needs the SPL " +
+                "account-plan `Token` emitter (see token/api.ts) instead.");
+        }
+        source = `${ERC20_IMPORT_LINE}\n${source}`;
+        baseDirs = [...(options.baseDirs ?? []), ...TOKEN_BASE_DIRS];
+    }
+    if (options.accessors !== false) {
+        const accessorOpts = typeof options.accessors === "object" ? options.accessors : {};
+        const rewrittenAccessors = rewriteProtocolAccessors(source, chain, {
+            ...accessorOpts,
+            existingContracts: options.contracts,
+        });
+        if (rewrittenAccessors.rewrote) {
+            if (chain.kind === "svm") {
+                throw new Error(`compileSauceRoute: destination '${chain.slug}' is svm — the protocol-accessor rewrite ` +
+                    "(options.accessors) is EVM-only; contract bindings are not supported on target 'svm'.");
+            }
+            source = rewrittenAccessors.source;
+            contracts = { ...contracts, ...rewrittenAccessors.contracts };
+        }
+    }
+    const compiled = compileWithRs({
+        source,
+        target,
+        baseDirs,
+        defines,
+        contracts,
+        ambient: options.ambient,
+    });
+    if (compiled.bytecode.length === 0) {
+        throw new Error("compileSauceRoute: compile() produced zero bytecode segments");
+    }
+    const bytecodeHex = bytesToHex(compiled.bytecode[0]);
+    if (chain.kind === "svm") {
+        const svmExecution = execution;
+        if (svmExecution.code === undefined) {
+            throw new Error("compileSauceRoute: an svm route requires execution.code — a finalized code account this " +
+                "module did NOT stage. Stage it through the kitchen (create/grow/write/finalize) and pass " +
+                "the CODE account; see kitchen.ts. It must hold exactly the bytecode this call returns in " +
+                "`compiled.bytecode[0]`.");
+        }
+        // Passed through UNPINNED, and no route call can be otherwise: the released engine's
+        // `execute_from_account` has no payload to carry a pin. The kitchen's `cook_from_account` does
+        // enforce one, but the STAGING caller issues that — a different transaction, by the party that
+        // already controlled the bytes — so it is not a guarantee this call's consumer inherits.
+        const call = buildSauceSvmCall(svmExecution);
+        return { calls: [call], compiled, source };
+    }
+    const evmExecution = execution;
+    const call = buildSauceEvmCall({
+        pot: evmExecution.pot,
+        engine: evmExecution.engine,
+        program: bytecodeHex,
+        value: evmExecution.value,
+    });
+    return { calls: [call], compiled, source };
+}
+//# sourceMappingURL=sauce-route.js.map

package/sdk/dist/routes/sauce-route.js.map

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

package/sdk/dist/routes/token-registry.d.ts

@@ -0,0 +1,28 @@
+import type { CanonicalChain } from "../chains/canonical.js";
+import type { AddressInput } from "./types.js";
+export interface TokenRegistryRow {
+    /** The ticker `symbol()` itself returns on-chain -- uppercase, e.g. "USDC", "WPOL". */
+    readonly symbol: string;
+    /** EIP-55 checksummed 20-byte address. */
+    readonly address: `0x${string}`;
+    /** Verification metadata only -- NOT consumed by the rewrite (no decimals-aware amount sugar). */
+    readonly decimals: number;
+    /** Provenance: an in-repo pin, or `probe:<chain>@<date>` for a network-verified row. */
+    readonly source: string;
+}
+/** Keyed by canonical EVM chain id (`CanonicalChain.id`). */
+export declare const TOKEN_REGISTRY: Readonly<Record<number, readonly TokenRegistryRow[]>>;
+/** The registry's own address for `symbol` on `chain`, or `undefined` if unregistered. EVM-only --
+ *  an svm chain always returns `undefined` (no `TOKEN_REGISTRY` key exists for an svm chain id). */
+export declare function registryTokenAddress(chain: CanonicalChain, symbol: string): bigint | undefined;
+/** Every symbol this registry knows for `chain`, sorted for stable diagnostics/tests. */
+export declare function knownTokenSymbols(chain: CanonicalChain): readonly string[];
+/**
+ * THE one precedence resolver every token-address consumer goes through: registry rows for `chain`
+ * first (skipped entirely for a non-evm chain -- there are none to skip in practice, since no
+ * `TOKEN_REGISTRY` key is ever an svm chain id, but the `chain.kind` guard makes that explicit
+ * rather than incidental), then `callerTokens` merged PER KEY on top -- overriding one symbol (e.g.
+ * `USDC`) never drops an unrelated registry symbol (e.g. `WETH`) for the same chain.
+ */
+export declare function resolveTokenMap(chain: CanonicalChain, callerTokens?: Readonly<Record<string, AddressInput>>): ReadonlyMap<string, bigint>;
+//# sourceMappingURL=token-registry.d.ts.map

package/sdk/dist/routes/token-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-registry.d.ts","sourceRoot":"","sources":["../../src/routes/token-registry.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc/C,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IAChC,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6DAA6D;AAC7D,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC,CAkHhF,CAAC;AAmDF;oGACoG;AACpG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK9F;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAI1E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GACpD,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAa7B"}