@eco-incorp/sauce 0.99.0

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

@@ -0,0 +1,142 @@
+/**
+ * `@eco-incorp/sauce`'s `deposit` module — E4.2, the universal deposit/stake/wrap adapter.
+ *
+ * Types + the per-protocol template registry shape. See `sdk/src/deposit/index.ts` for the
+ * module-level overview, and `sdk/src/swap/types.ts` (E4.1) for the sibling module this one mirrors
+ * — `Address`/`AddressInput`/`AmountInput` are re-used from there, not re-declared.
+ */
+export type { Address, AddressInput, AmountInput, Hex } from "../swap/types.js";
+import type { AddressInput, AmountInput } from "../swap/types.js";
+/**
+ * How a template's protocol call pulls in the token amount being deposited.
+ *
+ * - `"erc20-approve"` — an ERC20 asset; `depositCallStatement` emits `IERC20.approve(target,
+ *   amount)` immediately before the protocol call (see {@link ApprovalPolicy}).
+ * - `"native-value"` — no ERC20 leg at all; the amount rides as `msg.value` on a raw
+ *   `evm.call(target, value, calldata)` (a typed ABI binding can never attach value — see
+ *   `sdk/src/deposit/index.ts`'s "native vs ERC20" note). No approve is ever emitted.
+ * - `"none"` — a redeem/withdraw leg that burns a balance this contract already holds (e.g. Aave's
+ *   `withdraw`, which burns aTokens). No approve, no value.
+ */
+export type Funding = "erc20-approve" | "native-value" | "none";
+/** Whether a template's protocol call accepts a caller-chosen beneficiary/recipient address. */
+export type BeneficiarySupport = "supported" | "unsupported";
+/** How much of `spec.amount` to approve, when `funding === "erc20-approve"`. */
+export type ApprovalPolicy = "exact" | "max" | "none";
+/** A single extra, protocol-specific field a template accepts beyond the common shape. */
+export interface ExtraFieldSpec {
+    /** Default value used when the caller omits this field entirely. */
+    readonly defaultValue: bigint;
+    /** Normalizes + range-checks a caller-supplied value; throws (naming the field) on violation. */
+    normalize(value: AmountInput, fieldName: string): bigint;
+}
+/**
+ * The chain-agnostic deposit SPEC a caller builds — the input to {@link toDeposit} /
+ * `depositCallStatement` / `depositSource`.
+ *
+ * `token` is required for an `"erc20-approve"`/`"none"` template (the asset being approved/
+ * supplied/withdrawn) and must be omitted for a `"native-value"` template (there is no ERC20 leg).
+ * `beneficiary` defaults to `ctx.self()` and must be omitted on a `beneficiary: "unsupported"`
+ * template (every such protocol credits `msg.sender` unconditionally — accepting one would silently
+ * send the position to the wrong account).
+ */
+export interface DepositSpec {
+    /** SDK protocol slug (`"aave-v3"`, `"spark"`, …), or `"weth"` — see `skippedProtocols` in the
+     *  module doc for why WETH has no SDK protocol entry but is still supported here. */
+    protocol: string;
+    /** `"supply" | "withdraw" | "deposit" | "wrap" | "unwrap" | "stake"`, per the registered template. */
+    action: string;
+    /** The contract this deposit calls into (the Aave Pool, the Comet, the vault, WETH9, stETH, …). */
+    target: AddressInput;
+    /** Required for an ERC20-funded template; must be omitted for a native-value one. */
+    token?: AddressInput;
+    amount: AmountInput;
+    /** Defaults to `ctx.self()`. Must be omitted on a `beneficiary: "unsupported"` template. */
+    beneficiary?: AddressInput;
+    /** Defaults to `"exact"`. See {@link ApprovalPolicy}. */
+    approvalPolicy?: ApprovalPolicy;
+    /** Extra, protocol-specific fields (e.g. Aave/Spark `referralCode`). */
+    extra?: Readonly<Record<string, AmountInput>>;
+}
+/**
+ * The extra shapes `depositCallStatement`/`depositSource` accept beyond a concrete
+ * {@link DepositSpec}:
+ *
+ * - `amount: "balance"` — emit a RUNTIME balance read instead of a baked-in literal (`IERC20.
+ *   balanceOf(ctx.self())` for an ERC20 template, `ctx.selfBalance()` for a native one) — the shape
+ *   a swap-then-deposit program needs when the deposit amount is an earlier leg's (unknown at
+ *   compile time) output.
+ * - `amount: "delta"` — only meaningful inside `swapThenDepositSource` (it needs a pre-swap balance
+ *   snapshot to compute against); `depositCallStatement`/`depositSource` alone reject it.
+ * - `amount: "max"` — only accepted on a template with `allowsMaxAmount: true` (Aave/Spark
+ *   `withdraw`'s documented `type(uint256).max` withdraw-all sentinel); rejected everywhere else.
+ */
+export type DepositSourceSpec = DepositSpec | (Omit<DepositSpec, "amount"> & {
+    amount: "balance" | "delta" | "max";
+});
+/**
+ * A {@link DepositSpec}, fully normalized — bigint scalars (+ the `"self"` sentinel for a defaulted
+ * `beneficiary`, matching `SwapParams`'s own convention), plus the resolved {@link DepositTemplate}.
+ * `amount` stays a passthrough of whatever `toDeposit` was handed for the runtime-amount shapes
+ * (`"balance"` etc.) so a caller can tell a concrete deposit from a source-only one apart.
+ */
+export interface NormalizedDeposit {
+    template: DepositTemplate;
+    target: bigint;
+    token: bigint | null;
+    amount: bigint | "balance" | "delta" | "max";
+    beneficiary: bigint | "self" | null;
+    approvalPolicy: ApprovalPolicy;
+    extra: Readonly<Record<string, bigint>>;
+}
+/**
+ * One per-protocol call template — data + a small pure emitter, deliberately not a class
+ * hierarchy. See `sdk/src/deposit/templates.ts` for the concrete registry and
+ * `sdk/src/deposit/index.ts` for which protocols are included/skipped and why.
+ */
+export interface DepositTemplate {
+    /** SDK protocol slug this template is keyed under, or `"weth"` (no SDK protocol entry — see the
+     *  module doc's `skippedProtocols` note). */
+    readonly protocol: string;
+    readonly action: string;
+    /** Provenance: which vendored ABI backs this template. `null` only for the two WETH9 templates,
+     *  which have no SDK ABI at all. */
+    readonly source: {
+        readonly module: string;
+        readonly exportName: string;
+    } | null;
+    /** The exact method signature, transcribed from the vendored ABI (or WETH9's well-known one). */
+    readonly signature: string;
+    /** `toFunctionSelector(signature)`, pinned by a drift test. */
+    readonly selector: `0x${string}`;
+    readonly funding: Funding;
+    readonly beneficiary: BeneficiarySupport;
+    /** True only where the protocol documents a `uint256` max-amount sentinel (Aave/Spark withdraw). */
+    readonly allowsMaxAmount: boolean;
+    /** SauceScript import lines this template needs (empty for the two raw-call WETH templates,
+     *  which use no typed ABI binding at all). */
+    readonly imports: readonly string[];
+    /** The SauceScript identifier the import binds the ABI to (e.g. `"IAavePool"`); `null` for a
+     *  raw-call template. */
+    readonly binding: string | null;
+    /** Extra spec fields this template accepts (e.g. Aave/Spark `referralCode`). */
+    readonly extras: Readonly<Record<string, ExtraFieldSpec>>;
+    /**
+     * Pure: the normalized deposit + the already-resolved amount EXPRESSION (a SauceScript literal
+     * like `"1000n"` or a bound identifier like `"depositAmt0"`/`"ctx.selfBalance()"`) -> the
+     * protocol-call statement line(s). The approve line is NOT emitted here — `depositCallStatement`
+     * prepends it from `funding`/`approvalPolicy`, so the approve rule lives in exactly one place
+     * across every template.
+     *
+     * `varSuffix` is the emitting spec's own index within the program (the same one
+     * `depositCallStatement` uses for `depositAmtN`), so a template that BINDS a local must suffix it
+     * — two deposits of the same kind in one `main` would otherwise redeclare one name.
+     */
+    emit(d: NormalizedDeposit, amountExpr: string, varSuffix: string): readonly string[];
+}
+/** A short, human-readable note on a protocol considered but not registered as a template. */
+export interface SkippedProtocolNote {
+    readonly protocol: string;
+    readonly reason: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/sdk/dist/deposit/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/deposit/types.ts"],"names":[],"mappings":""}

package/sdk/dist/descriptors/accessors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The E2.3 native accessor tree: `chainContracts(chainRef)` builds the lazy
+ * `Chain -> Protocol -> Contract -> method` object a chain global (`Base`)
+ * or `contracts.on(ref)` exposes. A walk over `describeContract`/
+ * `requireContract` (query.ts) and `DESCRIPTORS` (registry.ts) — not a
+ * reimplementation of either.
+ *
+ * Every namespace and leaf is a memoising GETTER (`Object.defineProperty`,
+ * never eager construction/spread) so nothing is built until touched — see
+ * the design doc's laziness note for why that matters (39 chains x ~29
+ * contracts eagerly built on the SDK's import path would be real cost).
+ */
+import type { Address, Abi } from "viem";
+import { type CanonicalChain, type ChainRef, type ChainSlug } from "../chains/canonical.js";
+import type { ContractCoverage, ContractDescriptor, DescriptorMethod } from "./types.js";
+import type { FamilyContracts, FamilyKey, ContractNameOf, PascalOf, ProtocolSlug } from "./names.js";
+/**
+ * One leaf: a bound (protocol, contract) on a specific chain, plus every
+ * real ABI method as a callable producing a `ContractCall`. Method names are
+ * NOT part of the static type (kept loose as `unknown` via the index
+ * signature below) — they are derived from the descriptor's real ABI at
+ * BUILD time, so `Base.UniswapV4.UniversalRouter.execute(...)` resolves a
+ * real method and `.exactIn` is `undefined`, matching E2.2's "surface what
+ * exists, invent nothing" stance.
+ */
+export interface ContractAccessor {
+    readonly descriptor: ContractDescriptor;
+    readonly chain: CanonicalChain;
+    /** `undefined` when this contract has no address on `chain` (a hole), or for an unbound `kind:"interface"`. */
+    readonly address: Address | undefined;
+    readonly available: boolean;
+    readonly chains: readonly ChainSlug[];
+    readonly coverage: ContractCoverage;
+    readonly abi: Abi;
+    readonly methods: readonly DescriptorMethod[];
+    /** Rebinds this accessor to a specific instance address — REQUIRED for `kind:"interface"`, an optional override otherwise. */
+    at(address: Address): ContractAccessor;
+    readonly [method: string]: unknown;
+}
+/**
+ * The whole typed tree `chainContracts(...)` returns — chain-INDEPENDENT by
+ * design (per-chain address presence is runtime data, not literally typed;
+ * see the design doc's `ChainContracts` note), so it instantiates once
+ * regardless of how many chain globals intersect it.
+ */
+export type ChainContracts = {
+    readonly [P in ProtocolSlug as PascalOf<P>]: {
+        readonly [C in ContractNameOf<P>]: ContractAccessor;
+    };
+} & {
+    readonly [F in FamilyKey]: {
+        readonly [C in FamilyContracts<F>]: ContractAccessor;
+    };
+};
+/**
+ * Builds the whole lazy tree for one resolved chain. Every canonical
+ * protocol namespace is memoised once per `chainContracts` call, so a family
+ * alias resolving a non-ambiguous name (`Base.Uniswap.UniversalRouter`)
+ * forwards to the EXACT SAME accessor object as the canonical path
+ * (`Base.UniswapV4.UniversalRouter`) — verified by identity in
+ * `test/descriptors-accessors.test.ts`.
+ */
+export declare function chainContracts(chainRef: ChainRef): ChainContracts;
+/** Import-based front door (option-b): `contracts.on('base').Uniswap.UniversalRouter.execute(...)`.
+ *  Escape hatch for `__ECO_ROUTES_NO_GLOBALS__` hosts and for the TS2451 own-`const Base` caveat. */
+export declare function on(chainRef: ChainRef): ChainContracts;
+//# sourceMappingURL=accessors.d.ts.map

package/sdk/dist/descriptors/accessors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessors.d.ts","sourceRoot":"","sources":["../../src/descriptors/accessors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,wBAAwB,CAAC;AAKhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,8HAA8H;IAC9H,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,CAAC,IAAI,YAAY,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;QAC3C,QAAQ,EAAE,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG,gBAAgB;KACpD;CACF,GAAG;IACF,QAAQ,EAAE,CAAC,IAAI,SAAS,GAAG;QAAE,QAAQ,EAAE,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,gBAAgB;KAAE;CACpF,CAAC;AAqFF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CA4FjE;AAED;qGACqG;AACrG,wBAAgB,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAErD"}

package/sdk/dist/descriptors/accessors.js

@@ -0,0 +1,176 @@
+import { requireChain, } from "../chains/canonical.js";
+import { pascalOfSlug } from "../routes/builder.js";
+import { makeContractCall } from "./call.js";
+import { addressOn, requireContract } from "./query.js";
+import { DESCRIPTORS } from "./registry.js";
+function buildAccessor(descriptor, chain, addressOverride) {
+    const isInterface = descriptor.kind === "interface";
+    const resolvedAddress = addressOverride ?? (isInterface ? undefined : addressOn(descriptor, chain));
+    const available = isInterface ? addressOverride !== undefined : resolvedAddress !== undefined;
+    const base = {
+        descriptor,
+        chain,
+        address: resolvedAddress,
+        available,
+        chains: descriptor.chains,
+        coverage: descriptor.coverage,
+        abi: descriptor.abi,
+        methods: descriptor.methods,
+        at(newAddress) {
+            return buildAccessor(descriptor, chain, newAddress);
+        },
+    };
+    for (const method of descriptor.methods) {
+        base[method.name] = (...args) => {
+            let address = resolvedAddress;
+            if (address === undefined) {
+                if (isInterface) {
+                    throw new Error(`${descriptor.protocol}.${descriptor.contract} is an interface descriptor (no fixed address) — bind an instance first: .at('0x…').${method.name}(...)`);
+                }
+                // Reuses requireContract's exact, established hole-error message
+                // rather than re-deriving it here.
+                const resolved = requireContract(chain, descriptor.protocol, descriptor.contract);
+                address = resolved.address;
+            }
+            if (address === undefined) {
+                throw new Error(`${descriptor.protocol}.${descriptor.contract}: no address resolved on '${chain.slug}'`);
+            }
+            return makeContractCall(descriptor, chain, address, method, args);
+        };
+    }
+    return base;
+}
+/** protocol slug (exact, as declared in CONTRACT_LINKS) -> its descriptors, insertion order. */
+const protocolGroups = (() => {
+    const map = new Map();
+    for (const d of DESCRIPTORS) {
+        const list = map.get(d.protocol);
+        if (list)
+            list.push(d);
+        else
+            map.set(d.protocol, [d]);
+    }
+    return map;
+})();
+const protocolSlugs = [...protocolGroups.keys()];
+/** `"uniswap-v4"` -> `"uniswap"`; a slug with no trailing `-v<N>` yields `undefined` (no family alias). */
+function familyStem(slug) {
+    const m = /^(.+)-v\d+$/.exec(slug);
+    return m ? m[1] : undefined;
+}
+/** family alias key (PascalCase) -> member protocol slugs, insertion order. */
+const familyMembers = (() => {
+    const map = new Map();
+    for (const slug of protocolSlugs) {
+        const stem = familyStem(slug);
+        if (stem === undefined)
+            continue;
+        const key = pascalOfSlug(stem);
+        const list = map.get(key);
+        if (list)
+            list.push(slug);
+        else
+            map.set(key, [slug]);
+    }
+    return map;
+})();
+/**
+ * Builds the whole lazy tree for one resolved chain. Every canonical
+ * protocol namespace is memoised once per `chainContracts` call, so a family
+ * alias resolving a non-ambiguous name (`Base.Uniswap.UniversalRouter`)
+ * forwards to the EXACT SAME accessor object as the canonical path
+ * (`Base.UniswapV4.UniversalRouter`) — verified by identity in
+ * `test/descriptors-accessors.test.ts`.
+ */
+export function chainContracts(chainRef) {
+    const chain = requireChain(chainRef);
+    const protocolNamespaceCache = new Map();
+    function protocolNamespace(slug) {
+        const cached = protocolNamespaceCache.get(slug);
+        if (cached !== undefined)
+            return cached;
+        const ns = {};
+        for (const d of protocolGroups.get(slug) ?? []) {
+            let memo;
+            Object.defineProperty(ns, d.contract, {
+                enumerable: true,
+                configurable: true,
+                get() {
+                    if (memo === undefined)
+                        memo = buildAccessor(d, chain);
+                    return memo;
+                },
+            });
+        }
+        protocolNamespaceCache.set(slug, ns);
+        return ns;
+    }
+    function buildFamilyNamespace(familyKey, members) {
+        const ownersByContract = new Map();
+        for (const slug of members) {
+            for (const d of protocolGroups.get(slug) ?? []) {
+                const owners = ownersByContract.get(d.contract);
+                if (owners)
+                    owners.push(slug);
+                else
+                    ownersByContract.set(d.contract, [slug]);
+            }
+        }
+        const out = {};
+        for (const [contractName, owners] of ownersByContract) {
+            if (owners.length === 1) {
+                const owner = owners[0];
+                Object.defineProperty(out, contractName, {
+                    enumerable: true,
+                    configurable: true,
+                    get: () => protocolNamespace(owner)[contractName],
+                });
+            }
+            else {
+                Object.defineProperty(out, contractName, {
+                    enumerable: true,
+                    configurable: true,
+                    get() {
+                        const candidates = owners.map((s) => `${pascalOfSlug(s)}.${contractName}`).join(" or ");
+                        throw new Error(`"${contractName}" is ambiguous under ${familyKey} (${owners.join(", ")}) — use ${candidates}`);
+                    },
+                });
+            }
+        }
+        return out;
+    }
+    const out = {};
+    for (const slug of protocolSlugs) {
+        const key = pascalOfSlug(slug);
+        if (key in out) {
+            throw new Error(`descriptors: duplicate protocol namespace '${key}' (from slug '${slug}')`);
+        }
+        Object.defineProperty(out, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => protocolNamespace(slug),
+        });
+    }
+    for (const [familyKey, members] of familyMembers) {
+        if (familyKey in out) {
+            throw new Error(`descriptors: family alias '${familyKey}' collides with a canonical protocol namespace`);
+        }
+        let memo;
+        Object.defineProperty(out, familyKey, {
+            enumerable: true,
+            configurable: true,
+            get: () => {
+                if (memo === undefined)
+                    memo = buildFamilyNamespace(familyKey, members);
+                return memo;
+            },
+        });
+    }
+    return out;
+}
+/** Import-based front door (option-b): `contracts.on('base').Uniswap.UniversalRouter.execute(...)`.
+ *  Escape hatch for `__ECO_ROUTES_NO_GLOBALS__` hosts and for the TS2451 own-`const Base` caveat. */
+export function on(chainRef) {
+    return chainContracts(chainRef);
+}
+//# sourceMappingURL=accessors.js.map

package/sdk/dist/descriptors/accessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessors.js","sourceRoot":"","sources":["../../src/descriptors/accessors.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,YAAY,GAIb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAqB,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAgD5C,SAAS,aAAa,CACpB,UAA8B,EAC9B,KAAqB,EACrB,eAAyB;IAEzB,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,KAAK,WAAW,CAAC;IACpD,MAAM,eAAe,GACnB,eAAe,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9E,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC;IAE9F,MAAM,IAAI,GAA4B;QACpC,UAAU;QACV,KAAK;QACL,OAAO,EAAE,eAAe;QACxB,SAAS;QACT,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,GAAG,EAAE,UAAU,CAAC,GAAG;QACnB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,EAAE,CAAC,UAAmB;YACpB,OAAO,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;IAEF,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAe,EAAgB,EAAE;YACvD,IAAI,OAAO,GAAG,eAAe,CAAC;YAC9B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,WAAW,EAAE,CAAC;oBAChB,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ,uFAAuF,MAAM,CAAC,IAAI,OAAO,CACvJ,CAAC;gBACJ,CAAC;gBACD,iEAAiE;gBACjE,mCAAmC;gBACnC,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAClF,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC7B,CAAC;YACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ,6BAA6B,KAAK,CAAC,IAAI,GAAG,CACxF,CAAC;YACJ,CAAC;YACD,OAAO,gBAAgB,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,IAAwB,CAAC;AAClC,CAAC;AAED,gGAAgG;AAChG,MAAM,cAAc,GAAuD,CAAC,GAAG,EAAE;IAC/E,MAAM,GAAG,GAAG,IAAI,GAAG,EAAgC,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;;YAClB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,aAAa,GAAsB,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;AAEpE,2GAA2G;AAC3G,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9B,CAAC;AAED,+EAA+E;AAC/E,MAAM,aAAa,GAA2C,CAAC,GAAG,EAAE;IAClE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YACrB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC,EAAE,CAAC;AAEL;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,sBAAsB,GAAG,IAAI,GAAG,EAA4C,CAAC;IAEnF,SAAS,iBAAiB,CAAC,IAAY;QACrC,MAAM,MAAM,GAAG,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,MAAM,EAAE,GAAqC,EAAE,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/C,IAAI,IAAkC,CAAC;YACvC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;gBACpC,UAAU,EAAE,IAAI;gBAChB,YAAY,EAAE,IAAI;gBAClB,GAAG;oBACD,IAAI,IAAI,KAAK,SAAS;wBAAE,IAAI,GAAG,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;oBACvD,OAAO,IAAI,CAAC;gBACd,CAAC;aACF,CAAC,CAAC;QACL,CAAC;QACD,sBAAsB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,oBAAoB,CAC3B,SAAiB,EACjB,OAA0B;QAE1B,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAoB,CAAC;QACrD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC/C,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAChD,IAAI,MAAM;oBAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;oBACzB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;YACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;gBACzB,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE;oBACvC,UAAU,EAAE,IAAI;oBAChB,YAAY,EAAE,IAAI;oBAClB,GAAG,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC;iBAClD,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE;oBACvC,UAAU,EAAE,IAAI;oBAChB,YAAY,EAAE,IAAI;oBAClB,GAAG;wBACD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;wBACxF,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,wBAAwB,SAAS,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,UAAU,EAAE,CAC/F,CAAC;oBACJ,CAAC;iBACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,GAAG,GAA4B,EAAE,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,iBAAiB,IAAI,IAAI,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE;YAC9B,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,GAAG,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,aAAa,EAAE,CAAC;QACjD,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,8BAA8B,SAAS,gDAAgD,CACxF,CAAC;QACJ,CAAC;QACD,IAAI,IAAyC,CAAC;QAC9C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE;YACpC,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,GAAG,EAAE,GAAG,EAAE;gBACR,IAAI,IAAI,KAAK,SAAS;oBAAE,IAAI,GAAG,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxE,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAgC,CAAC;AAC1C,CAAC;AAED;qGACqG;AACrG,MAAM,UAAU,EAAE,CAAC,QAAkB;IACnC,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/sdk/dist/descriptors/call.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `ContractCall` — the inert value a `Base.<Proto>.<Contract>.<method>(...)`
+ * leaf produces. Synchronous, no RPC, no compiler import: the same posture
+ * as `swap/source.ts`/`deposit/source.ts`'s pure param-templating call
+ * builders, which `toSauceScript` below deliberately mirrors.
+ *
+ * The `typeFidelity: "widened"` gate lives here, not in accessors.ts: every
+ * production path (`data`, `encode`, `toCall`, `toSauceScript`) funnels
+ * through `assertFidelity`, so a widened descriptor (three uniswap-v3
+ * entries, uniswap-v4's PoolManager) can never silently hand out calldata
+ * that will not hit the deployed contract — see links.ts's own caveats for
+ * why each one is widened.
+ */
+import { type Address, type Hex } from "viem";
+import type { CanonicalChain } from "../chains/canonical.js";
+import type { ContractDescriptor, DescriptorMethod } from "./types.js";
+/**
+ * `baseDirs` for compiling a `toSauceScript()` program — same two-entry
+ * shape (dist root + shipped `sdk/src`) and rationale as
+ * `deposit/source.ts`'s `DEPOSIT_BASE_DIRS`: a contract's `.json` import
+ * resolves against the SDK's protocol registry, not the engine-vendored
+ * `dist/artifacts`.
+ */
+export declare const CONTRACT_BASE_DIRS: readonly string[];
+export interface EncodeOptions {
+    /** Opts past the widened-selector refusal — see the module doc comment. */
+    readonly allowWidened?: boolean;
+    /** Defaults to 0n. */
+    readonly value?: bigint;
+}
+export interface SauceScriptOptions {
+    /** Local binding name for the `.json` import. Defaults to the descriptor's `contract` name. */
+    readonly binding?: string;
+}
+export interface ContractCall {
+    readonly chain: CanonicalChain;
+    readonly protocol: string;
+    readonly contract: string;
+    readonly address: Address;
+    readonly method: DescriptorMethod;
+    readonly args: readonly unknown[];
+    readonly fidelity: "exact" | "widened";
+    readonly caveats: readonly string[];
+    /** `encode()` with no options — throws under the same widened gate. */
+    readonly data: Hex;
+    encode(opts?: EncodeOptions): Hex;
+    toCall(opts?: EncodeOptions): {
+        readonly target: Address;
+        readonly data: Hex;
+        readonly value: bigint;
+    };
+    toSauceScript(opts?: SauceScriptOptions): {
+        readonly imports: readonly string[];
+        readonly statement: string;
+        readonly source: string;
+        readonly baseDirs: readonly string[];
+    };
+}
+export declare function makeContractCall(descriptor: ContractDescriptor, chain: CanonicalChain, address: Address, method: DescriptorMethod, args: readonly unknown[]): ContractCall;
+//# sourceMappingURL=call.d.ts.map

package/sdk/dist/descriptors/call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/descriptors/call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAIlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIvE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAG/C,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,sBAAsB;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,GAAG,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG;QAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,aAAa,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG;QACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KACtC,CAAC;CACH;AA4DD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,YAAY,CAgDd"}

package/sdk/dist/descriptors/call.js

@@ -0,0 +1,118 @@
+/**
+ * `ContractCall` — the inert value a `Base.<Proto>.<Contract>.<method>(...)`
+ * leaf produces. Synchronous, no RPC, no compiler import: the same posture
+ * as `swap/source.ts`/`deposit/source.ts`'s pure param-templating call
+ * builders, which `toSauceScript` below deliberately mirrors.
+ *
+ * The `typeFidelity: "widened"` gate lives here, not in accessors.ts: every
+ * production path (`data`, `encode`, `toCall`, `toSauceScript`) funnels
+ * through `assertFidelity`, so a widened descriptor (three uniswap-v3
+ * entries, uniswap-v4's PoolManager) can never silently hand out calldata
+ * that will not hit the deployed contract — see links.ts's own caveats for
+ * why each one is widened.
+ */
+import { encodeFunctionData } from "viem";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toExactBigInt } from "../numeric.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * `baseDirs` for compiling a `toSauceScript()` program — same two-entry
+ * shape (dist root + shipped `sdk/src`) and rationale as
+ * `deposit/source.ts`'s `DEPOSIT_BASE_DIRS`: a contract's `.json` import
+ * resolves against the SDK's protocol registry, not the engine-vendored
+ * `dist/artifacts`.
+ */
+export const CONTRACT_BASE_DIRS = [
+    join(__dirname, ".."),
+    join(__dirname, "..", "..", "src"),
+];
+function widenedRealSelectorHint(descriptor) {
+    return descriptor.coverage.caveats.length > 0
+        ? descriptor.coverage.caveats.join("; ")
+        : "vendored types differ from the deployed contract";
+}
+function assertFidelity(descriptor, method, allowWidened) {
+    if (descriptor.coverage.typeFidelity !== "widened")
+        return;
+    if (allowWidened)
+        return;
+    throw new Error(`${descriptor.protocol}.${descriptor.contract}.${method.name}: this descriptor's ABI is WIDENED (${widenedRealSelectorHint(descriptor)}) — ` +
+        `selector ${method.selector} will NOT match the deployed contract. Pass { allowWidened: true } to encode anyway.`);
+}
+const renderBigintArg = (value) => `${value.toString()}n`;
+/** Renders one JS value as a SauceScript literal expression, or throws a named error for a shape
+ *  `toSauceScript` can't spell yet (a caller should reach for `encode()`/`toCall()` instead).
+ *
+ *  Every numeric literal is rendered from a `bigint`: a `number` past 2^53-1 would stringify to a
+ *  DIFFERENT rounded value than `BigInt()` gives it, and this text becomes compiled bytecode. A
+ *  non-integer is rejected here rather than by `toExactBigInt` because the fix is a different call
+ *  (`encode()`), not a different literal type. */
+function renderSauceArg(value, methodName) {
+    if (typeof value === "bigint")
+        return renderBigintArg(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new Error(`toSauceScript: cannot render non-integer number argument for ${methodName} — use encode()/toCall() instead`);
+        }
+        return renderBigintArg(toExactBigInt(value, `toSauceScript: number argument for ${methodName}`));
+    }
+    if (typeof value === "string") {
+        if (/^0x[0-9a-fA-F]{40}$/.test(value))
+            return renderBigintArg(BigInt(value));
+        throw new Error(`toSauceScript: cannot render string argument "${value}" for ${methodName} (only a 20-byte address literal is supported) — use encode()/toCall() instead`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => renderSauceArg(v, methodName)).join(", ")}]`;
+    }
+    if (value instanceof Uint8Array) {
+        return `Uint8Array.from([${Array.from(value).join(", ")}])`;
+    }
+    throw new Error(`toSauceScript: cannot render argument of type ${typeof value} for ${methodName} — use encode()/toCall() instead`);
+}
+export function makeContractCall(descriptor, chain, address, method, args) {
+    const fidelity = descriptor.coverage.typeFidelity;
+    const caveats = descriptor.coverage.caveats;
+    function encode(opts = {}) {
+        assertFidelity(descriptor, method, opts.allowWidened);
+        return encodeFunctionData({
+            abi: descriptor.abi,
+            functionName: method.name,
+            args: args,
+        });
+    }
+    function toCall(opts = {}) {
+        return { target: address, data: encode(opts), value: opts.value ?? 0n };
+    }
+    function toSauceScript(opts = {}) {
+        assertFidelity(descriptor, method, undefined);
+        if (descriptor.abiExport === undefined) {
+            throw new Error(`toSauceScript: ${descriptor.protocol}.${descriptor.contract} has no vendored abiExport — use encode()/toCall() instead`);
+        }
+        const binding = opts.binding ?? descriptor.contract;
+        const importLine = `import { ${binding} } from "./protocols/${descriptor.protocol}/${descriptor.abiExport}.json";`;
+        const renderedArgs = args.map((a) => renderSauceArg(a, method.name)).join(", ");
+        const statement = `${binding}.at(${address.length > 0 ? `${BigInt(address).toString()}n` : "0n"}).${method.name}(${renderedArgs});`;
+        const source = [importLine, "", "function main() {", `  ${statement}`, "}", ""].join("\n");
+        return { imports: [importLine], statement, source, baseDirs: CONTRACT_BASE_DIRS };
+    }
+    return {
+        chain,
+        protocol: descriptor.protocol,
+        contract: descriptor.contract,
+        address,
+        method,
+        args,
+        fidelity,
+        caveats,
+        get data() {
+            return encode();
+        },
+        encode,
+        toCall,
+        toSauceScript,
+    };
+}
+//# sourceMappingURL=call.js.map

package/sdk/dist/descriptors/call.js.map

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

package/sdk/dist/descriptors/derive.d.ts

@@ -0,0 +1,23 @@
+import { type Abi, type Address } from "viem";
+import type { ChainDeployment, ProtocolInfo } from "../core/types.js";
+import { type ChainSlug } from "../chains/canonical.js";
+import type { ContractLink } from "./links.js";
+import type { ContractCoverage, ContractDescriptor, DescriptorMethod } from "./types.js";
+/**
+ * Default contract-name derivation: `abiExport` minus its trailing "ABI"
+ * minus the protocol-name prefix, e.g. "UniswapV4UniversalRouterABI" with
+ * protocol name "Uniswap V4" -> "UniversalRouter". Only used when the link
+ * carries no explicit `contract` override (see links.ts's module comment for
+ * why 6 of the 29 starter entries need one).
+ */
+export declare function deriveContractName(protocolName: string, abiExport: string): string;
+/** ABI -> ordered DescriptorMethod[] (no name-collapse — an overloaded name would appear twice, see the linkage test's zero-overload invariant). */
+export declare function buildMethods(abi: Abi): DescriptorMethod[];
+/** role key -> sparse, EIP-55-checksummed per-chain address map. `undefined` roleKey (kind:"interface") -> {}. */
+export declare function buildPerChainAddress(chains: readonly ChainDeployment[], roleKey: string | undefined): Record<number, Address>;
+/** Sparse per-chain address map -> the chain slugs it resolves to, id-ascending. Fails closed (throws) on an id the canonical registry doesn't know — see test invariant #6. */
+export declare function deriveChainSlugs(perChainAddress: Readonly<Record<number, Address>>): ChainSlug[];
+export declare function buildCoverage(methods: readonly DescriptorMethod[], link: ContractLink): ContractCoverage;
+/** Assembles one full ContractDescriptor from a link entry plus the protocol's already-resolved data. */
+export declare function buildDescriptor(link: ContractLink, protocolInfo: ProtocolInfo, abi: Abi | undefined): ContractDescriptor;
+//# sourceMappingURL=derive.d.ts.map

package/sdk/dist/descriptors/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/descriptors/derive.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,GAAG,EAER,KAAK,OAAO,EACb,MAAM,MAAM,CAAC;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUlF;AASD,oJAAoJ;AACpJ,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,EAAE,CAezD;AAED,kHAAkH;AAClH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,gLAAgL;AAChL,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,CAKhG;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,IAAI,EAAE,YAAY,GACjB,gBAAgB,CAQlB;AAED,yGAAyG;AACzG,wBAAgB,eAAe,CAC7B,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,GAAG,GAAG,SAAS,GACnB,kBAAkB,CAuBpB"}