@eco-incorp/sauce 0.99.6 → 0.99.8

package/actions/dist/names.js

@@ -0,0 +1,334 @@
+/**
+ * Tokens and protocol contracts by name, as a Sauce program names them.
+ *
+ * A token field takes a registry symbol (`"USDC"`) and a contract field a namespace reference
+ * (`"UniswapV3.Factory"`), beside an address. The generated program carries the NAME — the program
+ * global it is — so the compile for a chain resolves it there, exactly as a hand-written program's
+ * `USDC` resolves: an action document that names everything is chain-agnostic. This module is the
+ * check made first, on the chain being compiled for, so a name that chain lacks is reported with
+ * its path, the chain and the name, rather than as the compiler's "not a declared variable".
+ *
+ * The names come from `routes.sourceGlobals(chain)` — the SDK's own list of what a program compiled
+ * for the chain may use, read from the same registries the compile reads — never a second table.
+ * The same pass also yields each name's address, for the checks that compare tokens (a swap of a
+ * token for itself) and for the quote calls, which are built here rather than compiled.
+ */
+import { CANONICAL_CHAINS } from "../../sdk/dist/chains/canonical.js";
+import { getChain, nativeErc20 } from "../../sdk/dist/chains/index.js";
+import { sourceGlobals, SVM_TOKEN_REGISTRY, TOKEN_REGISTRY } from "../../sdk/dist/routes/index.js";
+import { NAMESPACE_KEYS } from "../../sdk/dist/routes/accessor-index.js";
+import { ACTION_SPECS } from "./spec.js";
+/** A registry token symbol: the registry's own ticker rule (`token-registry.ts`). */
+export const TOKEN_SYMBOL_RE = /^[A-Z][A-Z0-9]{1,10}$/;
+/**
+ * The shape of a symbol, stocks' included: an identifier with a capital letter in it, as an
+ * issuer's ticker is ("SPCXc", "TSLAon", "bTSLA", "BRK_Bx") and `"native"` and `"usdc"` are not.
+ * What the JSON Schema accepts, since it lists no names; the parser takes only the uppercase
+ * ticker shape and the stock symbols the registry has (`isTokenSymbol`).
+ */
+export const STOCK_SYMBOL_RE = /^(?=[^A-Z]*[A-Z])[A-Za-z][A-Za-z0-9_]{1,15}$/;
+/** Every tokenized stock's symbol the registry has, on any chain: which chain is the compile's. */
+const STOCK_SYMBOLS = new Set([...Object.values(TOKEN_REGISTRY), SVM_TOKEN_REGISTRY["mainnet-beta"]].flatMap((rows) => rows.filter((row) => row.stock !== undefined).map((row) => row.symbol)));
+/** Solana's stock symbols: a document cannot use one, since action programs run on EVM chains. */
+const SOLANA_STOCK_SYMBOLS = new Set(SVM_TOKEN_REGISTRY["mainnet-beta"]
+    .filter((row) => row.stock !== undefined)
+    .map((row) => row.symbol));
+/** True for a token symbol: the uppercase ticker shape, or a tokenized stock's own symbol. */
+export function isTokenSymbol(value) {
+    return TOKEN_SYMBOL_RE.test(value) || STOCK_SYMBOLS.has(value);
+}
+/** The registry's spelling of `value` written in another case (`spcxc` is `SPCXc`), if any. */
+export function registrySpelling(value) {
+    const wanted = value.toUpperCase();
+    for (const rows of [...Object.values(TOKEN_REGISTRY), SVM_TOKEN_REGISTRY["mainnet-beta"]]) {
+        const row = rows.find((candidate) => candidate.symbol.toUpperCase() === wanted);
+        if (row !== undefined)
+            return row.symbol;
+    }
+    return undefined;
+}
+/** A protocol contract by namespace: `Namespace.Contract`, as a program writes it. */
+export const CONTRACT_NAME_RE = /^[A-Z][A-Za-z0-9]*\.[A-Za-z][A-Za-z0-9]*$/;
+/** The native currency, where a venue trades it itself: the zero address it keys it as. */
+export const NATIVE = "native";
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** True for a token symbol or a namespace reference — anything but an address or `"native"`. */
+export function isName(value) {
+    return isTokenSymbol(value) || CONTRACT_NAME_RE.test(value);
+}
+const cache = new Map();
+/** The names a program compiled for `chain` resolves, from `routes.sourceGlobals`. */
+export function chainNames(chain) {
+    const cached = cache.get(chain.id);
+    if (cached !== undefined)
+        return cached;
+    const globals = sourceGlobals(chain);
+    const contracts = new Map();
+    const namespaces = new Map();
+    for (const ns of globals.protocols) {
+        namespaces.set(ns.namespace, ns.contracts.map((c) => c.name));
+        for (const contract of ns.contracts) {
+            contracts.set(`${ns.namespace}.${contract.name}`, {
+                address: contract.address,
+                signatures: new Set(contract.methods.map((m) => m.signature)),
+            });
+        }
+    }
+    // The tokens and, among them, the stocks, in one pass: once per chain, as the whole listing is.
+    const tokens = new Map();
+    const stocks = new Set();
+    for (const token of globals.tokens) {
+        tokens.set(token.symbol, token.address);
+        if (token.stock !== undefined)
+            stocks.add(token.symbol);
+    }
+    const names = { chain, tokens, stocks, contracts, namespaces };
+    cache.set(chain.id, names);
+    return names;
+}
+/**
+ * Every EVM chain on which `namespace` has a contract, for a name the compiled chain lacks. Only a
+ * refusal asks, and each chain's listing is built once (`chainNames`' cache), so a service that
+ * checks many documents pays for it at most once per chain.
+ */
+function chainsWith(namespace) {
+    return CANONICAL_CHAINS.filter((chain) => chain.kind === "evm" && chainNames(chain).namespaces.has(namespace));
+}
+/**
+ * Every namespace the registry has on any chain, for a suggestion when a name matches none: the
+ * accessor index's own keys, so the suggestion builds no chain's listing.
+ */
+const allNamespaces = () => [...NAMESPACE_KEYS].sort();
+/** `Base (base, chain 8453)`. */
+export function chainLabel(chain) {
+    return `${chain.name} (${chain.slug}, chain ${chain.id})`;
+}
+/** `Base (chain 8453)`: the chain in an issue, under a heading that already gives its slug. */
+const onChain = (chain) => `${chain.name} (chain ${chain.id})`;
+const list = (names) => names.length <= 12 ? names.join(", ") : `${names.slice(0, 12).join(", ")}, …`;
+/** The closest of `candidates` to `word`, ignoring case, when it is close enough to be a typo. */
+function closest(word, candidates) {
+    const distance = (a, b) => {
+        const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+        for (let i = 1; i <= a.length; i++) {
+            let prev = row[0];
+            row[0] = i;
+            for (let j = 1; j <= b.length; j++) {
+                const next = row[j];
+                row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+                prev = next;
+            }
+        }
+        return row[b.length];
+    };
+    let best;
+    let bestDistance = Infinity;
+    for (const candidate of candidates) {
+        const d = distance(word.toLowerCase(), candidate.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = candidate;
+        }
+    }
+    return bestDistance <= Math.max(2, Math.floor(word.length / 4)) ? best : undefined;
+}
+/** Why `symbol` is not a token on `names.chain`. */
+function missingToken(symbol, names) {
+    // Its other tokens by name, its stock tokens by count: Ethereum has over a thousand.
+    const known = [...names.tokens.keys()].filter((name) => !names.stocks.has(name)).sort();
+    const stocks = names.stocks.size > 0 ? ` and ${names.stocks.size} stock tokens` : "";
+    const listed = names.tokens.size === 0
+        ? "which registers no token symbols"
+        : `whose tokens are ${list(known)}${stocks}`;
+    // A stock token is on a chain or a few: say which, for a document compiled for another. Solana's
+    // are named too, though no action program runs there.
+    const on = [
+        ...CANONICAL_CHAINS
+            .filter((chain) => chain.kind === "evm" && STOCK_SYMBOLS.has(symbol) && chainNames(chain).tokens.has(symbol))
+            .map((chain) => chain.name),
+        ...(SOLANA_STOCK_SYMBOLS.has(symbol) ? ["Solana, where action programs do not run"] : []),
+    ];
+    const hint = symbol === "ETH"
+        ? '; the native currency is "native" where an action trades it, and wrapped ETH is "WETH"'
+        : on.length > 0
+            ? `; ${symbol} is a token on ${on.join(" and ")}`
+            : "";
+    return (`no token "${symbol}" on ${onChain(names.chain)}, ${listed}${hint} — give its address there ` +
+        "instead");
+}
+/** Why `name` (`Namespace.Contract`) is not a contract a program on `names.chain` can name. */
+function missingContract(name, names) {
+    const where = onChain(names.chain);
+    const [namespace, contract] = name.split(".");
+    const here = names.namespaces.get(namespace);
+    if (here !== undefined) {
+        return `${namespace} on ${where} has no contract "${contract}"; it has ${list(here)}`;
+    }
+    const elsewhere = chainsWith(namespace);
+    if (elsewhere.length > 0) {
+        return (`no "${name}" on ${where}: ${namespace} is not deployed there (it is on ` +
+            `${list(elsewhere.map((c) => c.slug))}) — give the contract's address there instead`);
+    }
+    const hint = closest(namespace, allNamespaces());
+    return (`no protocol namespace "${namespace}"${hint === undefined ? "" : ` — did you mean ${hint}?`}` +
+        " (`sauce globals --chain <chain> --protocols` lists them)");
+}
+/** One named field's value on the compiled chain: its address, or why it has none. */
+function resolveValue(value, names) {
+    if (value === NATIVE)
+        return { address: ZERO_ADDRESS };
+    if (!isName(value))
+        return { address: value };
+    if (CONTRACT_NAME_RE.test(value)) {
+        const found = names.contracts.get(value);
+        return found === undefined
+            ? { problem: missingContract(value, names) }
+            : { address: found.address };
+    }
+    const token = names.tokens.get(value);
+    return token === undefined ? { problem: missingToken(value, names) } : { address: token };
+}
+/** Walks `value` of `kind`, replacing every name with its address and reporting the missing. */
+function walk(path, value, kind, names, issues) {
+    switch (kind.k) {
+        case "token":
+        case "contract":
+        case "tokenContract": {
+            const found = resolveValue(value, names);
+            if ("problem" in found) {
+                issues.push({ path, message: found.problem });
+                return value;
+            }
+            return found.address;
+        }
+        case "array":
+            return value.map((item, i) => walk(`${path}[${i}]`, item, kind.of, names, issues));
+        case "tuple":
+            return value.map((item, i) => walk(`${path}[${i}]`, item, kind.of[i], names, issues));
+        case "object": {
+            const out = { ...value };
+            for (const [key, def] of Object.entries(kind.fields)) {
+                if (out[key] !== undefined)
+                    out[key] = walk(`${path}.${key}`, out[key], def.kind, names, issues);
+            }
+            return out;
+        }
+        default:
+            return value;
+    }
+}
+/**
+ * The method a pool key reads from its factory, by action and key: what a `factory` given by name
+ * must declare, so a factory of the wrong kind is refused before it is called.
+ */
+export function poolLookup(action) {
+    const factory = action.factory;
+    if (factory === undefined)
+        return undefined;
+    switch (action.type) {
+        case "uniswapV2Swap":
+            return { signature: "getPair(address,address)", kind: "a Uniswap V2-style factory" };
+        case "uniswapV3Swap":
+            return action.fee !== undefined
+                ? {
+                    signature: "getPool(address,address,uint24)",
+                    kind: "a Uniswap V3-style factory, which `fee` keys",
+                }
+                : {
+                    signature: "getPool(address,address,int24)",
+                    kind: "a Slipstream factory, which `tickSpacing` keys",
+                };
+        case "traderJoeLBSwap":
+            return { signature: "getLBPairInformation(address,address,uint256)", kind: "an LBFactory" };
+        default:
+            return undefined;
+    }
+}
+/** A named `factory` that lacks the method its pool key reads. */
+function factoryIssue(action, path, names) {
+    const lookup = poolLookup(action);
+    const factory = action.factory;
+    if (lookup === undefined || factory === undefined || !CONTRACT_NAME_RE.test(factory)) {
+        return undefined;
+    }
+    const contract = names.contracts.get(factory);
+    if (contract === undefined || contract.signatures.has(lookup.signature))
+        return undefined;
+    const fitting = [...names.contracts.entries()]
+        .filter(([, c]) => c.signatures.has(lookup.signature))
+        .map(([name]) => name)
+        .sort();
+    return {
+        path: `${path}.factory`,
+        message: `"${factory}" has no ${lookup.signature}: this action's factory is ${lookup.kind}` +
+            (fitting.length === 0
+                ? ` — ${onChain(names.chain)} has none by name; give its address`
+                : ` (on ${onChain(names.chain)}: ${list(fitting)})`),
+    };
+}
+/**
+ * Every name in `actions` checked on `chain`: the issues for the ones it lacks, each with its path,
+ * and a copy of the actions with every name replaced by its address on that chain.
+ */
+export function resolveNames(actions, chain, path = "actions") {
+    const names = chainNames(chain);
+    const issues = [];
+    const resolved = actions.map((action, i) => {
+        const at = `${path}[${i}]`;
+        const spec = ACTION_SPECS[action.type];
+        const out = walk(at, action, { k: "object", fields: spec.fields }, names, issues);
+        const factory = factoryIssue(action, at, names);
+        if (factory !== undefined)
+            issues.push(factory);
+        return out;
+    });
+    return { resolved, issues };
+}
+/**
+ * A name whose MEANING depends on the chain, refused where it means something else: `"WETH"` is
+ * the wrapped native coin only where the native coin is ETH. On Polygon the registry's WETH is
+ * bridged ETH beside the native POL, so a `wrapETH` or `unwrapETH` of `"WETH"` there would call a
+ * token that wraps nothing. (Arc, whose native coin is itself an ERC-20, refuses wrapping outright:
+ * `semantics.ts`.) An address is taken as given: it says which contract is meant.
+ */
+export function wrappedNativeIssues(actions, chain, path = "actions") {
+    const native = getChain(chain.id)?.nativeCurrency.symbol;
+    if (native === undefined || native === "ETH" || nativeErc20(chain.id) !== undefined)
+        return [];
+    return actions.flatMap((action, i) => (action.type === "wrapETH" || action.type === "unwrapETH") && action.weth === "WETH"
+        ? [
+            {
+                path: `${path}[${i}].weth`,
+                message: `on ${onChain(chain)} the native coin is ${native}, and the registry's "WETH" is ` +
+                    `bridged ETH, not its wrapped native: ${action.type} would call a token that wraps ` +
+                    "nothing. Give the wrapped native's symbol or address",
+            },
+        ]
+        : []);
+}
+/** True when any action names a token or a contract rather than giving its address. */
+export function usesNames(actions) {
+    let found = false;
+    const visit = (value, kind) => {
+        if (found || value === undefined)
+            return;
+        if (kind.k === "token" || kind.k === "contract" || kind.k === "tokenContract") {
+            found = isName(value);
+        }
+        else if (kind.k === "array") {
+            for (const item of value)
+                visit(item, kind.of);
+        }
+        else if (kind.k === "tuple") {
+            value.forEach((item, i) => visit(item, kind.of[i]));
+        }
+        else if (kind.k === "object") {
+            for (const [key, def] of Object.entries(kind.fields)) {
+                visit(value[key], def.kind);
+            }
+        }
+    };
+    for (const action of actions)
+        visit(action, { k: "object", fields: ACTION_SPECS[action.type].fields });
+    return found;
+}

package/actions/dist/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAc,MAAM,YAAY,CAAC;AAEpE,uEAAuE;AACvE,eAAO,MAAM,eAAe,IAAI,CAAC;AA0NjC,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAQrD;AA4FD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/E;AAqED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAK1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAExF"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,WAAW,CAAC;AASnB,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAc,MAAM,YAAY,CAAC;AAEpE,uEAAuE;AACvE,eAAO,MAAM,eAAe,IAAI,CAAC;AAuSjC,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAQrD;AAwJD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/E;AAwED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAK1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAExF"}

package/actions/dist/program.js

@@ -12,6 +12,7 @@
  */
 import { getAddress } from "viem";
 import { ACTION_SPECS, ACTION_TYPES, } from "./spec.js";
+import { CONTRACT_NAME_RE, isTokenSymbol, NATIVE, registrySpelling, TOKEN_SYMBOL_RE, } from "./names.js";
 import { IDENTIFIER_RE, ProgramError, programIssues } from "./semantics.js";
 /** The action-program format version this package reads and writes. */
 export const PROGRAM_VERSION = 1;
@@ -76,6 +77,11 @@ class Checker {
             case "address":
                 this.address(path, value);
                 break;
+            case "token":
+            case "contract":
+            case "tokenContract":
+                this.named(path, value, kind);
+                break;
             case "recipient":
                 if (value !== "self")
                     this.address(path, value, ' or "self"');
@@ -152,6 +158,63 @@ class Checker {
         }
         return this.issues.length === start;
     }
+    /**
+     * A token or contract field: an address, or a name in the spelling a program uses — a registry
+     * token symbol, a `Namespace.Contract` reference, or `"native"` where the field takes it. Only
+     * the spelling is checked here; whether the name exists is the compiled chain's question.
+     */
+    named(path, value, kind) {
+        const symbols = kind.k !== "contract";
+        const contracts = kind.k !== "token";
+        const native = kind.k === "token" && kind.native === true;
+        const expected = [
+            symbols ? 'a registry token symbol ("USDC")' : undefined,
+            contracts ? 'a protocol contract ("UniswapV3.Factory")' : undefined,
+            native ? '"native"' : undefined,
+            "an address (0x + 40 hex digits)",
+        ].filter((part) => part !== undefined);
+        const wanted = `expected ${expected.slice(0, -1).join(", ")} or ${expected.at(-1)}`;
+        if (typeof value === "string" && /^0x/i.test(value)) {
+            this.address(path, value);
+            return;
+        }
+        if (typeof value !== "string") {
+            this.fail(path, `${wanted}, got ${describe(value)}`);
+            return;
+        }
+        if (value === NATIVE) {
+            if (!native) {
+                this.fail(path, `"native" is not a token this field takes — only a venue that trades the native ` +
+                    `currency itself takes it (uniswapV4Swap, ambientSwap, balancerV2BatchSwap); ${wanted}`);
+            }
+            return;
+        }
+        if (isTokenSymbol(value)) {
+            if (!symbols) {
+                this.fail(path, `${JSON.stringify(value)} is a token symbol, and this field is a protocol contract: ` +
+                    `name it as "Namespace.Contract" ("UniswapV3.Factory"), or give its address`);
+            }
+            return;
+        }
+        if (CONTRACT_NAME_RE.test(value)) {
+            if (!contracts) {
+                this.fail(path, `${JSON.stringify(value)} is a protocol contract, and this field is a token: give its ` +
+                    'registry symbol ("USDC") or its address');
+            }
+            return;
+        }
+        const upper = value.toUpperCase();
+        // A stock's symbol is its issuer's ticker, not upper case: `spcxc` is `SPCXc`.
+        const spelled = symbols ? registrySpelling(value) : undefined;
+        const hint = native && (upper === "ETH" || upper === "NATIVE")
+            ? ' — the native currency is "native"'
+            : spelled !== undefined && spelled !== upper
+                ? ` — a stock token's symbol is its issuer's ticker: did you mean ${JSON.stringify(spelled)}?`
+                : symbols && TOKEN_SYMBOL_RE.test(upper)
+                    ? ` — symbols are upper case: did you mean ${JSON.stringify(upper)}?`
+                    : "";
+        this.fail(path, `${wanted}, got ${describe(value)}${hint}`);
+    }
     address(path, value, alternative = "") {
         if (typeof value !== "string" || !ADDRESS_RE.test(value)) {
             this.fail(path, `expected an address (0x + 40 hex digits)${alternative}, got ${describe(value)}`);
@@ -229,6 +292,7 @@ function checkAction(c, path, value) {
     const before = c.issues.length;
     if (!c.object(path, value, spec.fields, extra))
         return undefined;
+    alternatives(c, path, value, spec);
     if (spec.spends && has(value, "amount"))
         c.value(`${path}.amount`, value.amount, { k: "uint", bits: 256 });
     for (const key of ["saveOutputAs", "amountRef"]) {
@@ -254,6 +318,48 @@ function checkAction(c, path, value) {
     const copy = JSON.parse(JSON.stringify(value));
     return ordered(copy, actionKeys(spec), spec.fields);
 }
+/** `fields` as a person reads them: `pool`, `factory + fee`. */
+const spelled = (fields) => fields.map((f) => `\`${f}\``).join(" + ");
+/**
+ * The action's `oneOf` and `together` rules: it carries exactly the fields of one alternative (a
+ * pool by its address, or by its key), and fields that go together are given together.
+ */
+function alternatives(c, path, value, spec) {
+    for (const group of spec.together ?? []) {
+        const given = group.filter((key) => has(value, key));
+        if (given.length > 0 && given.length < group.length) {
+            const missing = group.filter((key) => !has(value, key));
+            c.fail(`${path}.${missing[0]}`, `missing: ${spelled(group)} go together — give ${missing.length === 1 ? "it" : "them"} ` +
+                `too, or leave ${spelled(given)} out`);
+        }
+    }
+    const options = spec.oneOf;
+    if (options === undefined)
+        return;
+    const named = [...new Set(options.flat())];
+    const given = named.filter((key) => has(value, key));
+    if (options.some((option) => sameSet(option, given)))
+        return;
+    const ways = options.map(spelled).join(", or ");
+    if (given.length === 0) {
+        c.fail(`${path}.${options[0][0]}`, `missing: give ${ways}`);
+        return;
+    }
+    // The alternative the action came closest to, to name what is extra or missing from it.
+    const nearest = [...options].sort((a, b) => distanceTo(a, given) - distanceTo(b, given) || a.length - b.length)[0];
+    const extra = given.filter((key) => !nearest.includes(key));
+    const missing = nearest.filter((key) => !given.includes(key));
+    if (extra.length > 0) {
+        c.fail(`${path}.${extra[0]}`, `${spelled(extra)} cannot go with ${spelled(given.filter((key) => !extra.includes(key)))}: ` +
+            `give exactly one of ${ways}`);
+        return;
+    }
+    c.fail(`${path}.${missing[0]}`, `missing: with ${spelled(given)}, give ${spelled(missing)} too`);
+}
+const sameSet = (a, b) => a.length === b.length && a.every((key) => b.includes(key));
+/** How many fields `given` would add or drop to become `option`. */
+const distanceTo = (option, given) => option.filter((key) => !given.includes(key)).length +
+    given.filter((key) => !option.includes(key)).length;
 /** `value` rebuilt with its keys in `keys` order (nested objects follow their field order too). */
 function ordered(value, keys, fields) {
     const out = {};
@@ -295,7 +401,7 @@ function check(input) {
         }
     }
     if (!isPlainObject(value)) {
-        c.fail("$", `expected an action program object ({ version, chainId, actions }), got ${describe(value)}`);
+        c.fail("$", `expected an action program object ({ version, actions }), got ${describe(value)}`);
         return { issues: c.issues };
     }
     for (const key of Object.keys(value)) {
@@ -311,10 +417,9 @@ function check(input) {
             ? `missing — set it to ${PROGRAM_VERSION}`
             : `unsupported version ${describe(value.version)}; this package reads version ${PROGRAM_VERSION}`);
     }
+    // Optional: a document that names its tokens and contracts is for any chain that has them.
     if (has(value, "chainId"))
         c.value("chainId", value.chainId, { k: "int", min: 1, max: Number.MAX_SAFE_INTEGER });
-    else
-        c.fail("chainId", "missing — the chain every action executes on");
     const actions = [];
     if (!Array.isArray(value.actions)) {
         c.fail("actions", value.actions === undefined
@@ -332,11 +437,16 @@ function check(input) {
         });
     }
     // The chaining rules read every action, so they run only once every action is well formed.
+    const chainId = has(value, "chainId") ? value.chainId : undefined;
     if (c.issues.length === 0)
-        c.issues.push(...programIssues(actions, value.chainId));
+        c.issues.push(...programIssues(actions, chainId));
     if (c.issues.length > 0)
         return { issues: c.issues };
-    return { program: { version: PROGRAM_VERSION, chainId: value.chainId, actions } };
+    return {
+        program: chainId === undefined
+            ? { version: PROGRAM_VERSION, actions }
+            : { version: PROGRAM_VERSION, chainId, actions },
+    };
 }
 /**
  * Parses and validates an action program — JSON text, or an already-parsed value. Returns a fresh

package/actions/dist/registry.d.ts

@@ -1,6 +1,6 @@
 /**
- * The SDK modules the actions build on: protocol-registry ABIs for the bindings and the quotes, and
- * the SDK's `SafeERC20` ERC-20 write lowering.
+ * The SDK modules the actions build on: protocol-registry ABIs for the bindings and the quotes, the
+ * SDK's `SafeERC20` ERC-20 write lowering, and the resolver that serves `@sauce/router`.
  *
  * Imported by RELATIVE path into the SDK's build output, not by package name, and that is the one
  * spelling that resolves in both layouts this code runs in: in the repository `actions/src/` and
@@ -13,7 +13,9 @@
  * Each registry module is a protocol's public entry (`@eco-incorp/sauce/protocols/<slug>`), not a
  * file inside it. `token/safe` is the SDK's own lowering of `approve`/`transfer` with OpenZeppelin
  * `SafeERC20` semantics (a USDT `approve` returns no `bool`, and a stale allowance is reset first);
- * every SDK token write uses the same one, so the SDK has one ERC-20 write path.
+ * every SDK token write uses the same one, so the SDK has one ERC-20 write path. `embedded/resolve`
+ * serves the SDK's standard library from memory: a swap action at one of `@sauce/router`'s venues
+ * is a call into that library, which a program imports by name.
  */
 export { ERC20ABI } from "../../sdk/dist/protocols/erc20/index.js";
 export { PoolABI as AaveV3PoolABI } from "../../sdk/dist/protocols/aave-v3/index.js";
@@ -22,16 +24,16 @@ export { AcrossSpokePoolABI } from "../../sdk/dist/protocols/across/index.js";
 export { CrocSwapDexABI } from "../../sdk/dist/protocols/ambient/index.js";
 export { BalancerV2VaultABI } from "../../sdk/dist/protocols/balancer-v2/index.js";
 export { CurveRouterNGABI, CurveThreePoolABI } from "../../sdk/dist/protocols/curve/index.js";
-export { DODOV2ProxyABI } from "../../sdk/dist/protocols/dodo/index.js";
 export { LidoABI, WstETHABI } from "../../sdk/dist/protocols/lido/index.js";
 export { LiquidityPoolABI } from "../../sdk/dist/protocols/etherfi/index.js";
-export { MaverickV2RouterABI } from "../../sdk/dist/protocols/maverick/index.js";
 export { Permit2ABI } from "../../sdk/dist/protocols/permit2/index.js";
 export { RETHABI, RocketDepositPoolABI } from "../../sdk/dist/protocols/rocket-pool/index.js";
 export { StargatePoolABI } from "../../sdk/dist/protocols/stargate/index.js";
 export { TokenMessengerABI } from "../../sdk/dist/protocols/cctp/index.js";
-export { UniswapV2RouterABI } from "../../sdk/dist/protocols/uniswap-v2/index.js";
-export { UniswapV3QuoterV2ABI, UniswapV3SwapRouter02ABI, } from "../../sdk/dist/protocols/uniswap-v3/index.js";
-export { UniswapV4UniversalRouterABI } from "../../sdk/dist/protocols/uniswap-v4/index.js";
+export { UniswapV2FactoryABI, UniswapV2RouterABI, } from "../../sdk/dist/protocols/uniswap-v2/index.js";
+export { UniswapV3FactoryABI } from "../../sdk/dist/protocols/uniswap-v3/index.js";
+export { SlipstreamCLFactoryABI } from "../../sdk/dist/protocols/aerodrome-slipstream/index.js";
+export { LBFactoryABI } from "../../sdk/dist/protocols/trader-joe/index.js";
 export { safeApproveStatements, safeTransferStatements, type WordArg, } from "../../sdk/dist/token/safe.js";
+export { resolveSdkModule, resolveSdkPackage } from "../../sdk/dist/embedded/resolve.js";
 //# sourceMappingURL=registry.d.ts.map

package/actions/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+CAA+C,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAClF,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,OAAO,GACb,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC9F,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+CAA+C,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAC3E,OAAO,EACL,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wDAAwD,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAC5E,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,OAAO,GACb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC"}

package/actions/dist/registry.js

@@ -1,6 +1,6 @@
 /**
- * The SDK modules the actions build on: protocol-registry ABIs for the bindings and the quotes, and
- * the SDK's `SafeERC20` ERC-20 write lowering.
+ * The SDK modules the actions build on: protocol-registry ABIs for the bindings and the quotes, the
+ * SDK's `SafeERC20` ERC-20 write lowering, and the resolver that serves `@sauce/router`.
  *
  * Imported by RELATIVE path into the SDK's build output, not by package name, and that is the one
  * spelling that resolves in both layouts this code runs in: in the repository `actions/src/` and
@@ -13,7 +13,9 @@
  * Each registry module is a protocol's public entry (`@eco-incorp/sauce/protocols/<slug>`), not a
  * file inside it. `token/safe` is the SDK's own lowering of `approve`/`transfer` with OpenZeppelin
  * `SafeERC20` semantics (a USDT `approve` returns no `bool`, and a stale allowance is reset first);
- * every SDK token write uses the same one, so the SDK has one ERC-20 write path.
+ * every SDK token write uses the same one, so the SDK has one ERC-20 write path. `embedded/resolve`
+ * serves the SDK's standard library from memory: a swap action at one of `@sauce/router`'s venues
+ * is a call into that library, which a program imports by name.
  */
 export { ERC20ABI } from "../../sdk/dist/protocols/erc20/index.js";
 export { PoolABI as AaveV3PoolABI } from "../../sdk/dist/protocols/aave-v3/index.js";
@@ -22,15 +24,15 @@ export { AcrossSpokePoolABI } from "../../sdk/dist/protocols/across/index.js";
 export { CrocSwapDexABI } from "../../sdk/dist/protocols/ambient/index.js";
 export { BalancerV2VaultABI } from "../../sdk/dist/protocols/balancer-v2/index.js";
 export { CurveRouterNGABI, CurveThreePoolABI } from "../../sdk/dist/protocols/curve/index.js";
-export { DODOV2ProxyABI } from "../../sdk/dist/protocols/dodo/index.js";
 export { LidoABI, WstETHABI } from "../../sdk/dist/protocols/lido/index.js";
 export { LiquidityPoolABI } from "../../sdk/dist/protocols/etherfi/index.js";
-export { MaverickV2RouterABI } from "../../sdk/dist/protocols/maverick/index.js";
 export { Permit2ABI } from "../../sdk/dist/protocols/permit2/index.js";
 export { RETHABI, RocketDepositPoolABI } from "../../sdk/dist/protocols/rocket-pool/index.js";
 export { StargatePoolABI } from "../../sdk/dist/protocols/stargate/index.js";
 export { TokenMessengerABI } from "../../sdk/dist/protocols/cctp/index.js";
-export { UniswapV2RouterABI } from "../../sdk/dist/protocols/uniswap-v2/index.js";
-export { UniswapV3QuoterV2ABI, UniswapV3SwapRouter02ABI, } from "../../sdk/dist/protocols/uniswap-v3/index.js";
-export { UniswapV4UniversalRouterABI } from "../../sdk/dist/protocols/uniswap-v4/index.js";
+export { UniswapV2FactoryABI, UniswapV2RouterABI, } from "../../sdk/dist/protocols/uniswap-v2/index.js";
+export { UniswapV3FactoryABI } from "../../sdk/dist/protocols/uniswap-v3/index.js";
+export { SlipstreamCLFactoryABI } from "../../sdk/dist/protocols/aerodrome-slipstream/index.js";
+export { LBFactoryABI } from "../../sdk/dist/protocols/trader-joe/index.js";
 export { safeApproveStatements, safeTransferStatements, } from "../../sdk/dist/token/safe.js";
+export { resolveSdkModule, resolveSdkPackage } from "../../sdk/dist/embedded/resolve.js";

package/actions/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAmI7D,sDAAsD;AACtD,wBAAgB,aAAa,IAAI,UAAU,CAoC1C"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AA2N7D,sDAAsD;AACtD,wBAAgB,aAAa,IAAI,UAAU,CA+C1C"}