@rhinestone/sdk 2.5.0 → 2.6.0

package/dist/src/modules/validators/smart-sessions/swap/rules.js

@@ -0,0 +1,105 @@
+/**
+ * Shared rule builders for swap-venue scoping.
+ *
+ * Venue modules describe *what* to pin; these turn that into policy rules with
+ * the security-relevant details (cumulative accumulation, zero native value)
+ * decided in exactly one place.
+ */
+/**
+ * Pin a calldata word to an exact numeric value.
+ *
+ * Used for ABI *shape* words — array pointers, lengths, element offsets. Pinning
+ * those is what makes pinning anything inside a dynamic tail sound: without
+ * them a caller can re-lay-out the encoding so a fixed offset lands on a
+ * different word, and the rule silently validates the wrong bytes.
+ */
+export function pinValue(calldataOffset, referenceValue) {
+    return { condition: 'equal', calldataOffset, referenceValue };
+}
+/** Pin a calldata word to an exact 32-byte value. */
+export function pinWord(calldataOffset, referenceValue) {
+    return { condition: 'equal', calldataOffset, referenceValue };
+}
+/** Pin a calldata word to an exact address. */
+export function pin(calldataOffset, referenceValue) {
+    return { condition: 'equal', calldataOffset, referenceValue };
+}
+/**
+ * Cap a swap's own sell amount, cumulatively across every call.
+ *
+ * `usageLimit` is what makes this cumulative: it sets `isLimited` + `usage.limit`
+ * on-chain, so the policy accumulates the observed value and reverts once the
+ * running total would exceed the cap.
+ *
+ * A bare comparison would be per-call, which is not enough. A reusable session
+ * could then run N swaps of `cap` each, and any allowance that already existed
+ * before the session was created is spent without the approve's spending-limit
+ * ever observing it.
+ */
+export function cumulativeCap(calldataOffset, cap) {
+    return {
+        condition: 'lessThanOrEqual',
+        calldataOffset,
+        referenceValue: cap,
+        usageLimit: cap,
+    };
+}
+/**
+ * Wrap rules into the action's policy.
+ *
+ * `valueLimitPerUse: 0n` because the approve cap only bounds ERC-20 pulls —
+ * without it, a payable swap selector could still carry arbitrary native value
+ * through the router.
+ */
+/** Every rule must hold, as a right-folded AND over the expression tree. */
+function allOf(rules) {
+    return rules
+        .map((rule) => ({ type: 'rule', rule }))
+        .reduceRight((right, left) => ({ type: 'and', left, right }));
+}
+/**
+ * Wrap rules into the action's policy.
+ *
+ * `valueLimitPerUse: 0n` because the approve cap only bounds ERC-20 pulls —
+ * without it, a payable swap selector could still carry arbitrary native value
+ * through the router.
+ *
+ * UniversalActionPolicy while the rules fit its fixed 16-slot array, which is
+ * every venue except a fully-pinned wrapped route — those pin the shape words,
+ * both call targets, the approve and the nested exec, and run past 16. ArgPolicy
+ * takes a dynamic rule list, so it carries the overflow rather than forcing a
+ * pin to be dropped. Preferring the simpler policy keeps the common case on the
+ * contract it has always used.
+ */
+const UNIVERSAL_ACTION_MAX_RULES = 16;
+export function swapAction(target, selector, rules, 
+/**
+ * Mutually exclusive rule sets, at least one of which must hold — used when
+ * several venues authorise the SAME call but pin its tail to different
+ * aggregators. One on-chain action id cannot carry two policies, and dropping
+ * the pins to share it would authorise a tail neither venue named, so the
+ * alternatives become an OR instead.
+ */
+alternatives = []) {
+    const usable = alternatives.filter((set) => set.length > 0);
+    const policy = usable.length > 0
+        ? {
+            type: 'arg-policy',
+            valueLimitPerUse: 0n,
+            expression: {
+                type: 'and',
+                left: allOf(rules),
+                right: usable
+                    .map(allOf)
+                    .reduce((left, right) => ({ type: 'or', left, right })),
+            },
+        }
+        : rules.length <= UNIVERSAL_ACTION_MAX_RULES
+            ? {
+                type: 'universal-action',
+                valueLimitPerUse: 0n,
+                rules: rules,
+            }
+            : { type: 'arg-policy', valueLimitPerUse: 0n, expression: allOf(rules) };
+    return { target, selector, policies: [policy] };
+}

package/dist/src/modules/validators/smart-sessions/swap/scope.d.ts

@@ -0,0 +1,31 @@
+import type { FyndVenue, Permission, RhinestoneSwapVenue, ScopedAction, SwapScopeInput, SwapVenue, ZeroExVenue } from '../types.js';
+import { type FyndChainId } from './fynd.js';
+import { type ZeroExChainId } from './zero-ex.js';
+/**
+ * Venue-scoped swap sessions (RHI-6286).
+ *
+ * A session scoped with `swap` may do exactly two things: approve the sell token
+ * to a listed venue's spender, and call that venue's swap entrypoint with the
+ * sell token, buy token and recipient pinned. Everything else reverts.
+ *
+ * Callers name venues (`zeroEx(...)`, `fynd()`); routers, selectors and calldata
+ * offsets live in the per-venue modules and never reach the public surface, so
+ * they stay patchable without a breaking change.
+ */
+/**
+ * Venues valid on a given chain.
+ *
+ * Narrows `swap.via` by the session's chain id, so naming a venue that is not
+ * deployed there is a compile error rather than a revert at swap time.
+ */
+export type SwapVenueFor<TChainId extends number> = number extends TChainId ? SwapVenue : RhinestoneSwapVenue | (TChainId extends ZeroExChainId ? ZeroExVenue : never) | (TChainId extends FyndChainId ? FyndVenue : never);
+export interface ResolvedSwapScope {
+    readonly permissions: Permission[];
+    readonly actions: ScopedAction[];
+}
+/**
+ * Compile a `swap` scope into one merged approve permission plus one scoped
+ * action per venue.
+ */
+export declare function resolveSwapScope(scope: SwapScopeInput, chainId: number, environment?: 'production' | 'development'): ResolvedSwapScope;
+//# sourceMappingURL=scope.d.ts.map

package/dist/src/modules/validators/smart-sessions/swap/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../../../modules/validators/smart-sessions/swap/scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EAEnB,YAAY,EACZ,cAAc,EACd,SAAS,EACT,WAAW,EACZ,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,QAAQ,CAAA;AAGpD,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAE3D;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,QAAQ,SAAS,MAAM,IAAI,MAAM,SAAS,QAAQ,GAMvE,SAAS,GAGL,mBAAmB,GACnB,CAAC,QAAQ,SAAS,aAAa,GAAG,WAAW,GAAG,KAAK,CAAC,GACtD,CAAC,QAAQ,SAAS,WAAW,GAAG,SAAS,GAAG,KAAK,CAAC,CAAA;AAE1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CACjC;AAuDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,YAAY,GAAG,aAA4B,GACvD,iBAAiB,CAqGnB"}

package/dist/src/modules/validators/smart-sessions/swap/scope.js

@@ -0,0 +1,168 @@
+import { scopeFynd } from './fynd.js';
+import { rhinestoneSwap, scopeRhinestone } from './rhinestone.js';
+import { scopeZeroEx } from './zero-ex.js';
+const erc20ApproveAbi = [
+    {
+        type: 'function',
+        name: 'approve',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'spender', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+/**
+ * One approve permission covering every venue's spender.
+ *
+ * Merged rather than one-per-venue because all venues pull the same sell token;
+ * a single action with a spender allowlist is cheaper to install and keeps the
+ * spending-limit a single shared counter instead of one budget per venue.
+ */
+function approvePermission(scope, scopings) {
+    const spenders = [
+        ...new Set(scopings.flatMap((s) => s.approveSpenders.map((a) => a.toLowerCase()))),
+    ].map((s) => s);
+    return {
+        abi: erc20ApproveAbi,
+        address: scope.sell.token,
+        functions: {
+            approve: {
+                ...(scope.sell.maxTotal !== undefined
+                    ? {
+                        spendingLimit: {
+                            token: scope.sell.token,
+                            amount: scope.sell.maxTotal,
+                        },
+                    }
+                    : {}),
+                params: {
+                    spender: spenders.length === 1
+                        ? { condition: 'equal', value: spenders[0] }
+                        : { anyOf: spenders },
+                },
+            },
+        },
+    };
+}
+/**
+ * Compile a `swap` scope into one merged approve permission plus one scoped
+ * action per venue.
+ */
+export function resolveSwapScope(scope, chainId, environment = 'production') {
+    // Default to the Swapper: it is the route the orchestrator emits for
+    // same-chain smart-account swaps, so a caller who just says "let this key
+    // swap A for B" gets a scope that actually matches the resulting ops.
+    const via = scope.via ?? [rhinestoneSwap()];
+    if (via.length === 0) {
+        throw new Error('swap.via must list at least one venue — an empty list would authorise nothing');
+    }
+    if (scope.sell.token.toLowerCase() === scope.buy.token.toLowerCase()) {
+        throw new Error(`swap.sell.token and swap.buy.token are the same address (${scope.sell.token})`);
+    }
+    const ctxFor = (venue) => ({
+        chainId,
+        environment,
+        sellToken: scope.sell.token,
+        buyToken: scope.buy.token,
+        recipient: scope.to,
+        // A venue-level cap wins over the scope-level one: `anySettler` demands its
+        // own `maxSpend` precisely because that venue needs a tighter bound than the
+        // session as a whole might carry.
+        cap: venue.maxSpend ?? scope.sell.maxTotal,
+    });
+    // Every aggregator venue is reachable two ways and the orchestrator picks:
+    // it wraps a route in the Swapper only when the Swapper can capture surplus,
+    // which depends on the direction AND the winning quoter, and that eligibility
+    // is orchestrator-side config that changes without the session knowing. So
+    // each venue authorises its direct call AND the wrapped one; authorising a
+    // single shape is how a session rejects the swap it was created for.
+    //
+    // The wrapped shape pins which aggregator may sit in the Swapper's `calls[]`.
+    // Two venues pinning DIFFERENT aggregators cannot share one Swapper action —
+    // so with more than one aggregator authorised the tail is left unpinned,
+    // which is the honest reading: either aggregator may fill it. The swap stays
+    // bound by the Swapper's own top-level tokenIn/tokenOut/recipient pins and
+    // the sell cap either way.
+    const routes = new Set(via.flatMap((venue) => venue.id === 'fynd'
+        ? ['fynd']
+        : venue.id === '0x'
+            ? ['zeroEx']
+            : []));
+    // A bare `rhinestoneSwap()` authorises any aggregator in the tail, so pinning
+    // it for the others would both contradict that venue and collide with it on
+    // the same Swapper action.
+    // A caller-written Swapper venue carries no route by construction — the
+    // routed shape is internal — so naming one authorises any aggregator.
+    const anyAggregatorAllowed = via.some((venue) => venue.id === 'rhinestone');
+    const sharedRoute = routes.size === 1 && !anyAggregatorAllowed ? [...routes][0] : undefined;
+    // More than one aggregator authorised: pin the tail to ANY ONE of them rather
+    // than to none. Sharing the Swapper action by dropping its route pins would
+    // authorise a tail neither venue named, which is broader than the scope.
+    const sharedRoutes = routes.size > 1 && !anyAggregatorAllowed ? [...routes] : undefined;
+    // The Settler the 0x venue already carries, so the wrapped half can pin the
+    // nested exec instead of dropping the one address that makes it bindable.
+    const zeroExSettler = via.flatMap((venue) => venue.id === '0x' && venue.settler !== undefined ? [venue.settler] : [])[0];
+    const wrappedVenue = () => {
+        const settler = zeroExSettler !== undefined ? { settler: zeroExSettler } : {};
+        if (sharedRoutes)
+            return { id: 'rhinestone', routes: sharedRoutes, ...settler };
+        if (sharedRoute) {
+            return {
+                id: 'rhinestone',
+                route: sharedRoute,
+                ...(sharedRoute === 'zeroEx' ? settler : {}),
+            };
+        }
+        return { id: 'rhinestone' };
+    };
+    const scopings = via.map((venue) => {
+        const ctx = ctxFor(venue);
+        if (venue.id === 'rhinestone')
+            return scopeRhinestone(venue, ctx);
+        const parts = [
+            venue.id === 'fynd' ? scopeFynd(ctx) : scopeZeroEx(venue, ctx),
+            scopeRhinestone(wrappedVenue(), ctx),
+        ];
+        return {
+            approveSpenders: parts.flatMap((p) => [...p.approveSpenders]),
+            actions: parts.flatMap((p) => [...p.actions]),
+        };
+    });
+    return {
+        permissions: [approvePermission(scope, scopings)],
+        actions: dedupeActions(scopings.flatMap((s) => [...s.actions])),
+    };
+}
+/**
+ * Collapse actions that different venues both authorise.
+ *
+ * Every aggregator venue covers the Swapper-wrapped shape as well as its direct
+ * one, so listing two of them yields the same (target, selector) twice. Those map to one on-chain action id, and the resolver rejects
+ * duplicates — reasonably, since two entries would silently overwrite each
+ * other's policies. Identical entries are safe to collapse; genuinely
+ * conflicting ones still throw, because picking a winner would silently
+ * loosen or tighten a rule the caller wrote.
+ */
+function dedupeActions(actions) {
+    const byKey = new Map();
+    for (const action of actions) {
+        const key = `${action.target.toLowerCase()}|${action.selector.toLowerCase()}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, action);
+            continue;
+        }
+        if (JSON.stringify(existing, replaceBigInt) !==
+            JSON.stringify(action, replaceBigInt)) {
+            throw new Error(`Conflicting swap actions for ${action.target} ${action.selector}: ` +
+                'two venues authorise the same call with different policies. Give ' +
+                'them the same cap, or list only one.');
+        }
+    }
+    return [...byKey.values()];
+}
+function replaceBigInt(_key, value) {
+    return typeof value === 'bigint' ? value.toString() : value;
+}

package/dist/src/modules/validators/smart-sessions/swap/zero-ex.d.ts

@@ -0,0 +1,143 @@
+import { type Address } from 'viem';
+import type { ZeroExVenue } from '../types.js';
+import type { VenueContext, VenueScoping } from './rules.js';
+/**
+ * 0x — Swap API v2, AllowanceHolder flow.
+ *
+ * Two calls per swap:
+ *   1. `approve(AllowanceHolder, amount)` on the sell token
+ *   2. `AllowanceHolder.exec(operator, token, amount, target, data)` — pulls the
+ *      approved sell token and forwards `data` to the Settler.
+ *
+ * The split matters for scoping. `token` and `amount` are consumed by the
+ * AllowanceHolder itself, so pinning them is meaningful no matter what `target`
+ * is. `operator` and `target` decide who receives the pulled funds, and nothing
+ * on-chain requires them to be a Settler — leave them free and a compromised
+ * session key names its own contract.
+ */
+/** Permanent across chains — 0x never rotates this. Verified deployed on Plasma. */
+export declare const ZEROX_ALLOWANCE_HOLDER: Address;
+/** Chains where 0x is an enabled quoter with a whitelisted Settler. */
+export declare const ZEROX_CHAIN_IDS: readonly [1, 10, 56, 130, 137, 143, 146, 999, 4663, 8453, 9745, 42161, 43114, 57073];
+export type ZeroExChainId = (typeof ZEROX_CHAIN_IDS)[number];
+export declare const allowanceHolderAbi: readonly [{
+    readonly type: "function";
+    readonly name: "exec";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "result";
+        readonly type: "bytes";
+    }];
+}];
+export declare const ALLOWANCE_HOLDER_EXEC_SELECTOR: `0x${string}`;
+/**
+ * 0x's Settler registry — an ERC-721 whose token owner IS the current Settler
+ * for that feature slot. Slot 2 is the taker-submitted Settler used by ordinary
+ * swaps.
+ *
+ * 0x redeploys the Settler every few weeks and moves the token, so there is no
+ * safe constant to bundle: any address baked into a release is correct only
+ * until the next rotation. Resolve with {@link resolveZeroExSettler} and pin the
+ * result, or use `anySettler` to trade the pin for longevity.
+ */
+export declare const ZEROX_SETTLER_REGISTRY: Address;
+export declare const ZEROX_SETTLER_FEATURE_ID = 2n;
+export declare const zeroExSettlerRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "ownerOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}];
+/** Minimal structural client — avoids coupling this module to a viem client type. */
+interface SettlerRegistryReader {
+    readContract(args: {
+        address: Address;
+        abi: typeof zeroExSettlerRegistryAbi;
+        functionName: 'ownerOf';
+        args: readonly [bigint];
+    }): Promise<Address>;
+}
+/**
+ * Read 0x's current Settler for this chain from the on-chain registry.
+ *
+ * Pin the result at session-enable time; do NOT re-resolve per swap. A session
+ * that looked the address up at use time would follow 0x's registry wherever it
+ * points, so a compromise of 0x's upgrade multisig could redirect every live
+ * session's approved funds. Pinned, the worst case of a rotation is that the
+ * session stops working until it is re-enabled.
+ *
+ * @param client - Any viem public client for the target chain.
+ */
+export declare function resolveZeroExSettler(client: SettlerRegistryReader): Promise<Address>;
+/**
+ * Pin 0x's Settler to a specific address.
+ *
+ * Pinning the inner `buyToken` / `recipient` is not a substitute for pinning
+ * `target`: those bytes only mean what their names say when the callee is
+ * genuinely a Settler.
+ */
+export interface ZeroExPinnedOptions {
+    /** The Settler to pin. Get the current one with {@link resolveZeroExSettler}. */
+    settler: Address;
+    anySettler?: never;
+    maxSpend?: never;
+}
+/**
+ * Leave 0x's Settler unpinned so the session survives 0x's rotations.
+ *
+ * A deliberate security downgrade, which is why `maxSpend` is mandatory here:
+ * with `target` free, a compromised session key can redirect the AllowanceHolder
+ * pull to its own contract, and `maxSpend` is then the ONLY bound on what it
+ * takes. The blast radius becomes exactly `maxSpend`, never the account's whole
+ * balance.
+ *
+ * Prefer {@link ZeroExPinnedOptions} unless the session must outlive 0x's
+ * upgrade cadence (roughly every few weeks).
+ */
+export interface ZeroExAnySettlerOptions {
+    anySettler: true;
+    /** Cumulative cap on sell-token spend across every swap in this session. */
+    maxSpend: bigint;
+    settler?: never;
+}
+/**
+ * Scope a session to 0x swaps, in whichever shape the orchestrator produces.
+ *
+ * Authorises BOTH the direct `AllowanceHolder.exec` call and the
+ * Swapper-wrapped one, and there is no way to narrow that. Whether a swap is
+ * wrapped is decided by `ENABLE_SWAPPER`, the account type, and whether the
+ * Swapper resolves on the chain — state that is read when the intent executes,
+ * not when the session is signed. Authorising one shape is how a session ends
+ * up rejecting the swap it was created for.
+ *
+ * Takes either a pinned `settler` or `anySettler` + `maxSpend`. There is
+ * deliberately no zero-argument form: a bundled Settler constant would be stale
+ * within weeks of the release that shipped it.
+ */
+export declare function zeroEx(options: ZeroExPinnedOptions | ZeroExAnySettlerOptions): ZeroExVenue;
+export declare function scopeZeroEx(venue: ZeroExVenue, ctx: VenueContext): VenueScoping;
+export {};
+//# sourceMappingURL=zero-ex.d.ts.map

package/dist/src/modules/validators/smart-sessions/swap/zero-ex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-ex.d.ts","sourceRoot":"","sources":["../../../../../../modules/validators/smart-sessions/swap/zero-ex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAsB,MAAM,MAAM,CAAA;AAEjE,OAAO,KAAK,EAAkC,WAAW,EAAE,MAAM,UAAU,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGzD;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,OACS,CAAA;AAE9C,uEAAuE;AACvE,eAAO,MAAM,eAAe,sFAElB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;EAcP,CAAA;AAExB,eAAO,MAAM,8BAA8B,eAE1C,CAAA;AAiCD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,OACS,CAAA;AAE9C,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAQb,CAAA;AAExB,qFAAqF;AACrF,UAAU,qBAAqB;IAC7B,YAAY,CAAC,IAAI,EAAE;QACjB,OAAO,EAAE,OAAO,CAAA;QAChB,GAAG,EAAE,OAAO,wBAAwB,CAAA;QACpC,YAAY,EAAE,SAAS,CAAA;QACvB,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;KACxB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,IAAI,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,mBAAmB,GAAG,uBAAuB,GACrD,WAAW,CAOb;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,YAAY,GAChB,YAAY,CAsCd"}

package/dist/src/modules/validators/smart-sessions/swap/zero-ex.js

@@ -0,0 +1,164 @@
+import { toFunctionSelector } from 'viem';
+import { namedParamOffsets } from '../../permissions.js';
+import { cumulativeCap, pin, pinValue, swapAction } from './rules.js';
+/**
+ * 0x — Swap API v2, AllowanceHolder flow.
+ *
+ * Two calls per swap:
+ *   1. `approve(AllowanceHolder, amount)` on the sell token
+ *   2. `AllowanceHolder.exec(operator, token, amount, target, data)` — pulls the
+ *      approved sell token and forwards `data` to the Settler.
+ *
+ * The split matters for scoping. `token` and `amount` are consumed by the
+ * AllowanceHolder itself, so pinning them is meaningful no matter what `target`
+ * is. `operator` and `target` decide who receives the pulled funds, and nothing
+ * on-chain requires them to be a Settler — leave them free and a compromised
+ * session key names its own contract.
+ */
+/** Permanent across chains — 0x never rotates this. Verified deployed on Plasma. */
+export const ZEROX_ALLOWANCE_HOLDER = '0x0000000000001fF3684f28c67538d4D072C22734';
+/** Chains where 0x is an enabled quoter with a whitelisted Settler. */
+export const ZEROX_CHAIN_IDS = [
+    1, 10, 56, 130, 137, 143, 146, 999, 4663, 8453, 9745, 42161, 43114, 57073,
+];
+export const allowanceHolderAbi = [
+    {
+        type: 'function',
+        name: 'exec',
+        stateMutability: 'payable',
+        inputs: [
+            { name: 'operator', type: 'address' },
+            { name: 'token', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+            { name: 'target', type: 'address' },
+            { name: 'data', type: 'bytes' },
+        ],
+        outputs: [{ name: 'result', type: 'bytes' }],
+    },
+];
+export const ALLOWANCE_HOLDER_EXEC_SELECTOR = toFunctionSelector(allowanceHolderAbi[0]);
+/** exec's own head offsets, derived from the ABI. */
+const EXEC = namedParamOffsets(allowanceHolderAbi, 'exec');
+/**
+ * Offsets of the Settler's slippage fields, measured in EXEC's calldata.
+ *
+ * These cannot come from an ABI: they live inside `exec.data`, which is opaque
+ * `bytes` as far as exec's own signature is concerned. They are stable anyway
+ * because the Settler's
+ * `execute((recipient, buyToken, minAmountOut) slippage, bytes[] actions, bytes32)`
+ * places the fixed-size slippage struct BEFORE the variable-length `actions`.
+ *
+ * Derivation: exec's `data` content begins at 192 (five head words + the length
+ * word), +4 for the inner selector = 196 for `recipient`, +32 = 228 for
+ * `buyToken`. Re-derive against a live 0x exec if 0x revs the Settler ABI.
+ */
+/**
+ * `exec`'s `data` head word, and the canonical tail it must point at.
+ *
+ * The Settler offsets below are derived from `data` starting at 192, which only
+ * holds while this pointer says 160. Unpinned, a session key can aim `data`
+ * elsewhere and leave matching decoy words at 196/228 for the policy to read
+ * while the Settler decodes a different recipient. `rhinestone.ts` pins the
+ * equivalent `calls[]` shape words for the same reason.
+ */
+const EXEC_DATA_POINTER_OFFSET = 128n;
+const EXEC_DATA_POINTER = 160n;
+const SETTLER_RECIPIENT_OFFSET = 196n;
+const SETTLER_BUY_TOKEN_OFFSET = 228n;
+/**
+ * 0x's Settler registry — an ERC-721 whose token owner IS the current Settler
+ * for that feature slot. Slot 2 is the taker-submitted Settler used by ordinary
+ * swaps.
+ *
+ * 0x redeploys the Settler every few weeks and moves the token, so there is no
+ * safe constant to bundle: any address baked into a release is correct only
+ * until the next rotation. Resolve with {@link resolveZeroExSettler} and pin the
+ * result, or use `anySettler` to trade the pin for longevity.
+ */
+export const ZEROX_SETTLER_REGISTRY = '0x00000000000004533Fe15556B1E086BB1A72cEae';
+export const ZEROX_SETTLER_FEATURE_ID = 2n;
+export const zeroExSettlerRegistryAbi = [
+    {
+        type: 'function',
+        name: 'ownerOf',
+        stateMutability: 'view',
+        inputs: [{ name: 'tokenId', type: 'uint256' }],
+        outputs: [{ name: '', type: 'address' }],
+    },
+];
+/**
+ * Read 0x's current Settler for this chain from the on-chain registry.
+ *
+ * Pin the result at session-enable time; do NOT re-resolve per swap. A session
+ * that looked the address up at use time would follow 0x's registry wherever it
+ * points, so a compromise of 0x's upgrade multisig could redirect every live
+ * session's approved funds. Pinned, the worst case of a rotation is that the
+ * session stops working until it is re-enabled.
+ *
+ * @param client - Any viem public client for the target chain.
+ */
+export async function resolveZeroExSettler(client) {
+    return client.readContract({
+        address: ZEROX_SETTLER_REGISTRY,
+        abi: zeroExSettlerRegistryAbi,
+        functionName: 'ownerOf',
+        args: [ZEROX_SETTLER_FEATURE_ID],
+    });
+}
+/**
+ * Scope a session to 0x swaps, in whichever shape the orchestrator produces.
+ *
+ * Authorises BOTH the direct `AllowanceHolder.exec` call and the
+ * Swapper-wrapped one, and there is no way to narrow that. Whether a swap is
+ * wrapped is decided by `ENABLE_SWAPPER`, the account type, and whether the
+ * Swapper resolves on the chain — state that is read when the intent executes,
+ * not when the session is signed. Authorising one shape is how a session ends
+ * up rejecting the swap it was created for.
+ *
+ * Takes either a pinned `settler` or `anySettler` + `maxSpend`. There is
+ * deliberately no zero-argument form: a bundled Settler constant would be stale
+ * within weeks of the release that shipped it.
+ */
+export function zeroEx(options) {
+    return {
+        id: '0x',
+        ...(options.settler !== undefined ? { settler: options.settler } : {}),
+        ...(options.anySettler ? { anySettler: true } : {}),
+        ...(options.maxSpend !== undefined ? { maxSpend: options.maxSpend } : {}),
+    };
+}
+export function scopeZeroEx(venue, ctx) {
+    // The union type rejects this at compile time, but a plain-JS caller or an
+    // `as any` reaches here with neither, and the rules below would then pin only
+    // the sell token — an unbounded AllowanceHolder path.
+    if (venue.settler === undefined && !venue.anySettler) {
+        throw new Error('zeroEx() requires either a pinned settler or anySettler + maxSpend: ' +
+            'with neither, nothing bounds the operator, target or amount');
+    }
+    if (venue.anySettler && ctx.cap === undefined) {
+        throw new Error('zeroEx({ anySettler: true }) requires maxSpend: with the Settler ' +
+            'unpinned it is the only bound on what a compromised session key can pull');
+    }
+    // Pinned from the scope, never from venue options — the sell token is a
+    // scope-level guarantee and must not depend on the caller restating it.
+    const rules = [
+        pin(EXEC.token, ctx.sellToken),
+    ];
+    if (venue.settler !== undefined) {
+        rules.push(pin(EXEC.operator, venue.settler));
+        rules.push(pin(EXEC.target, venue.settler));
+        // Before any offset inside `exec.data` can be trusted.
+        rules.push(pinValue(EXEC_DATA_POINTER_OFFSET, EXEC_DATA_POINTER));
+        rules.push(pin(SETTLER_BUY_TOKEN_OFFSET, ctx.buyToken));
+        rules.push(pin(SETTLER_RECIPIENT_OFFSET, ctx.recipient));
+    }
+    if (ctx.cap !== undefined) {
+        rules.push(cumulativeCap(EXEC.amount, ctx.cap));
+    }
+    return {
+        approveSpenders: [ZEROX_ALLOWANCE_HOLDER],
+        actions: [
+            swapAction(ZEROX_ALLOWANCE_HOLDER, ALLOWANCE_HOLDER_EXEC_SELECTOR, rules),
+        ],
+    };
+}