@rhinestone/sdk 2.4.0 → 2.6.0

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

@@ -0,0 +1,147 @@
+import { type Address } from 'viem';
+import type { RhinestoneSwapVenue, RoutedRhinestoneSwapVenue } from '../types.js';
+import type { VenueContext, VenueScoping } from './rules.js';
+/**
+ * The Rhinestone Swapper — the route the orchestrator actually uses for
+ * same-chain smart-account swaps, and the right layer to scope a session at.
+ *
+ * Scoping an aggregator directly (see `zero-ex.ts`, `fynd.ts`) describes a call
+ * the account does not make on this route: the orchestrator wraps whichever
+ * quoter wins behind its own Swapper, so a session scoped to 0x's
+ * AllowanceHolder rejects its own intended swap with `InvalidSignature()`.
+ * Verified live on Plasma — the account's sell token moves to the Swapper, and
+ * the aggregator never appears in the account's ops.
+ *
+ * Scoping here is also strictly better:
+ *   - aggregator-agnostic, so whichever quoter wins is irrelevant
+ *   - no 0x Settler rotation problem, because this contract is ours
+ *   - one approve target per chain (the proxy) instead of one per venue
+ *   - the fields we care about are typed head args on a contract we control,
+ *     with the aggregator route demoted to an opaque `calls[]` tail
+ *
+ * What the Swapper guarantees (verified in compact-utils/src/swapper):
+ * at most `amountIn` of `tokenIn` is pulled, once, from `msg.sender`; the
+ * recipient's measured balance delta must be >= `minAmountOut` or it reverts;
+ * every refund and sweep goes to `msg.sender`. The account cannot be drained
+ * beyond the pulled amount: the tail runs as the Swapper, which holds no
+ * allowance from the account, and `SwapperLib.runRoute` forbids the tail from
+ * calling the proxy that does.
+ *
+ * Be precise about what that bounds, though. A capped `amountIn` bounds how
+ * much can LEAVE; it does not ensure anything comes back. `minAmountOut` is a
+ * caller-supplied argument this scoping does not pin, and the contract accepts
+ * zero — so with an unconstrained route a compromised key can spend up to the
+ * cap and receive nothing. Naming a venue closes that by pinning the
+ * route, leaving the pulled input nowhere to go but a real aggregator.
+ */
+/**
+ * Both entrypoints share a head layout, which is what lets one venue cover
+ * both: `tokenIn`@0, sell amount@32, `tokenOut`@64, `recipient`@160. The sell
+ * amount is `amountIn` for exact-in and `amountInMax` for exact-out — in both
+ * cases the ceiling on what leaves the account, which is exactly what to cap.
+ */
+export declare const swapperAbi: readonly [{
+    readonly type: "function";
+    readonly name: "swapExactIn";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "minAmountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "quotedAmountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "orderRef";
+        readonly type: "uint256";
+    }, {
+        readonly name: "calls";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "data";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "swapExactOut";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "amountInMax";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "quotedAmountIn";
+        readonly type: "uint256";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "orderRef";
+        readonly type: "uint256";
+    }, {
+        readonly name: "calls";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "data";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountSpent";
+        readonly type: "uint256";
+    }];
+}];
+export declare const SWAP_EXACT_IN_SELECTOR: `0x${string}`;
+export declare const SWAP_EXACT_OUT_SELECTOR: `0x${string}`;
+export declare function swapperAddresses(environment: 'production' | 'development'): {
+    swapper: Address;
+    proxy: Address;
+};
+/**
+ * Route swaps through the Rhinestone Swapper — the default, and the only venue
+ * that matches what the orchestrator emits for same-chain smart-account swaps.
+ *
+ * Takes no addresses and no aggregator: which quoter fills the swap is the
+ * orchestrator's decision, and this scoping holds whichever one wins.
+ */
+export declare function rhinestoneSwap(options?: {
+    maxSpend?: bigint;
+}): RhinestoneSwapVenue;
+export declare function scopeRhinestone(venue: RoutedRhinestoneSwapVenue, ctx: VenueContext): VenueScoping;
+//# sourceMappingURL=rhinestone.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rhinestone.d.ts","sourceRoot":"","sources":["../../../../../../modules/validators/smart-sessions/swap/rhinestone.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAgC,MAAM,MAAM,CAAA;AAE3E,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EAE1B,MAAM,UAAU,CAAA;AAEjB,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDC,CAAA;AAExB,eAAO,MAAM,sBAAsB,eAAoC,CAAA;AACvE,eAAO,MAAM,uBAAuB,eAAoC,CAAA;AAqBxE,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,YAAY,GAAG,aAAa,GAAG;IAC3E,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf,CAIA;AAkJD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,mBAAmB,CAKrB;AACD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,yBAAyB,EAChC,GAAG,EAAE,YAAY,GAChB,YAAY,CAgFd"}

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

@@ -0,0 +1,305 @@
+import { toFunctionSelector } from 'viem';
+import { namedParamOffsets } from '../../permissions.js';
+import { FYND_CHAIN_IDS, FYND_ROUTERS } from './fynd.js';
+import { cumulativeCap, pin, pinValue, pinWord, swapAction } from './rules.js';
+import { ZEROX_ALLOWANCE_HOLDER, ZEROX_CHAIN_IDS } from './zero-ex.js';
+/**
+ * The Rhinestone Swapper — the route the orchestrator actually uses for
+ * same-chain smart-account swaps, and the right layer to scope a session at.
+ *
+ * Scoping an aggregator directly (see `zero-ex.ts`, `fynd.ts`) describes a call
+ * the account does not make on this route: the orchestrator wraps whichever
+ * quoter wins behind its own Swapper, so a session scoped to 0x's
+ * AllowanceHolder rejects its own intended swap with `InvalidSignature()`.
+ * Verified live on Plasma — the account's sell token moves to the Swapper, and
+ * the aggregator never appears in the account's ops.
+ *
+ * Scoping here is also strictly better:
+ *   - aggregator-agnostic, so whichever quoter wins is irrelevant
+ *   - no 0x Settler rotation problem, because this contract is ours
+ *   - one approve target per chain (the proxy) instead of one per venue
+ *   - the fields we care about are typed head args on a contract we control,
+ *     with the aggregator route demoted to an opaque `calls[]` tail
+ *
+ * What the Swapper guarantees (verified in compact-utils/src/swapper):
+ * at most `amountIn` of `tokenIn` is pulled, once, from `msg.sender`; the
+ * recipient's measured balance delta must be >= `minAmountOut` or it reverts;
+ * every refund and sweep goes to `msg.sender`. The account cannot be drained
+ * beyond the pulled amount: the tail runs as the Swapper, which holds no
+ * allowance from the account, and `SwapperLib.runRoute` forbids the tail from
+ * calling the proxy that does.
+ *
+ * Be precise about what that bounds, though. A capped `amountIn` bounds how
+ * much can LEAVE; it does not ensure anything comes back. `minAmountOut` is a
+ * caller-supplied argument this scoping does not pin, and the contract accepts
+ * zero — so with an unconstrained route a compromised key can spend up to the
+ * cap and receive nothing. Naming a venue closes that by pinning the
+ * route, leaving the pulled input nowhere to go but a real aggregator.
+ */
+/**
+ * Both entrypoints share a head layout, which is what lets one venue cover
+ * both: `tokenIn`@0, sell amount@32, `tokenOut`@64, `recipient`@160. The sell
+ * amount is `amountIn` for exact-in and `amountInMax` for exact-out — in both
+ * cases the ceiling on what leaves the account, which is exactly what to cap.
+ */
+export const swapperAbi = [
+    {
+        type: 'function',
+        name: 'swapExactIn',
+        stateMutability: 'payable',
+        inputs: [
+            { name: 'tokenIn', type: 'address' },
+            { name: 'amountIn', type: 'uint256' },
+            { name: 'tokenOut', type: 'address' },
+            { name: 'minAmountOut', type: 'uint256' },
+            { name: 'quotedAmountOut', type: 'uint256' },
+            { name: 'recipient', type: 'address' },
+            { name: 'orderRef', type: 'uint256' },
+            {
+                name: 'calls',
+                type: 'tuple[]',
+                components: [
+                    { name: 'target', type: 'address' },
+                    { name: 'value', type: 'uint256' },
+                    { name: 'data', type: 'bytes' },
+                ],
+            },
+        ],
+        outputs: [{ name: 'amountOut', type: 'uint256' }],
+    },
+    {
+        type: 'function',
+        name: 'swapExactOut',
+        stateMutability: 'payable',
+        inputs: [
+            { name: 'tokenIn', type: 'address' },
+            { name: 'amountInMax', type: 'uint256' },
+            { name: 'tokenOut', type: 'address' },
+            { name: 'amountOut', type: 'uint256' },
+            { name: 'quotedAmountIn', type: 'uint256' },
+            { name: 'recipient', type: 'address' },
+            { name: 'orderRef', type: 'uint256' },
+            {
+                name: 'calls',
+                type: 'tuple[]',
+                components: [
+                    { name: 'target', type: 'address' },
+                    { name: 'value', type: 'uint256' },
+                    { name: 'data', type: 'bytes' },
+                ],
+            },
+        ],
+        outputs: [{ name: 'amountSpent', type: 'uint256' }],
+    },
+];
+export const SWAP_EXACT_IN_SELECTOR = toFunctionSelector(swapperAbi[0]);
+export const SWAP_EXACT_OUT_SELECTOR = toFunctionSelector(swapperAbi[1]);
+const EXACT_IN = namedParamOffsets(swapperAbi, 'swapExactIn');
+const EXACT_OUT = namedParamOffsets(swapperAbi, 'swapExactOut');
+/**
+ * Deployed via CREATE2, so one address covers every chain. The proxy is
+ * `new`'d in the Swapper's constructor and the binding is immutable both ways,
+ * so a Swapper redeploy also changes the proxy — verify both together.
+ *
+ * Confirmed on Plasma: `Swapper.PROXY()` returns the proxy below.
+ */
+const SWAPPER_PRODUCTION = '0x40CE38e0cbB8ec54a601256E4FacfED5679bccD0';
+const PROXY_PRODUCTION = '0x5afCe415B4370E5EfD8B9BE784d21C331bEAb965';
+const SWAPPER_DEVELOPMENT = '0x8206052a213AA7cafB18ec7898e8D1D421C02100';
+const PROXY_DEVELOPMENT = '0x21416a06e81fe115a5c8bf554b2b01383bd9b9f3';
+export function swapperAddresses(environment) {
+    return environment === 'development'
+        ? { swapper: SWAPPER_DEVELOPMENT, proxy: PROXY_DEVELOPMENT }
+        : { swapper: SWAPPER_PRODUCTION, proxy: PROXY_PRODUCTION };
+}
+/**
+ * Byte offsets of the `calls[]` ABI *shape* words, measured in the Swapper's
+ * calldata past the selector. Identical for `swapExactIn` and `swapExactOut`
+ * because both have the same eight-word head.
+ *
+ * Pinning a target inside a dynamic array is only sound if the layout is also
+ * pinned: a compromised session key controls the encoding and could otherwise
+ * relocate elements so a fixed offset reads an innocuous word. Pinning the array
+ * pointer, the length, and each element pointer fixes every position, making the
+ * target offsets exact.
+ *
+ * Derived from live Plasma calldata and reproduced by
+ * `zeroExRouteRules` in the test suite:
+ *   @224 array pointer  = 256   (tail begins right after the head)
+ *   @256 length         = 2     (approve + aggregator call)
+ *   @288 elem[0] pointer= 64    (element table is 2 words)
+ *   @320 elem[1] pointer= 288   (64 + elem[0] size: 4 words + a 68-byte approve)
+ *   @352 calls[0].target        (the sell-token approve)
+ *   @576 calls[1].target        (the aggregator)
+ *
+ * `calls[1].data` — the variable-length aggregator blob — is LAST in the
+ * encoding, so its length shifts nothing that is pinned. That is what makes
+ * these offsets stable across quotes rather than coincidental.
+ */
+const CALLS_POINTER_OFFSET = 224n;
+const CALLS_LENGTH_OFFSET = 256n;
+const CALLS_ELEM0_POINTER_OFFSET = 288n;
+const CALLS_ELEM1_POINTER_OFFSET = 320n;
+const CALLS_ELEM0_TARGET_OFFSET = 352n;
+const CALLS_ELEM1_TARGET_OFFSET = 576n;
+const CALLS_ELEM0_VALUE_OFFSET = 384n;
+const CALLS_ELEM1_VALUE_OFFSET = 608n;
+const NESTED_EXEC_TOKEN_OFFSET = 740n;
+/**
+ * The nested fynd call: `swap(amountIn, tokenIn, tokenOut, minOut, receiver)`.
+ * Verified against production calldata — the receiver is the Swapper itself,
+ * which collects the output and forwards it to the scope's recipient, so that
+ * is what gets pinned rather than the end recipient.
+ */
+const NESTED_FYND_TOKEN_IN_OFFSET = 740n;
+const NESTED_FYND_TOKEN_OUT_OFFSET = 772n;
+const NESTED_FYND_RECEIVER_OFFSET = 836n;
+const CALLS_ELEM1_DATA_POINTER_OFFSET = 640n;
+/** Head words of the `AllowanceHolder.exec` nested in `calls[1].data`. */
+const NESTED_EXEC_OPERATOR_OFFSET = 708n;
+const NESTED_EXEC_TARGET_OFFSET = 804n;
+const CALLS_ELEM1_DATA_POINTER = 96n;
+const CALLS_ELEM0_DATA_POINTER_OFFSET = 416n;
+const CALLS_ELEM0_DATA_LENGTH_OFFSET = 448n;
+/**
+ * The word straddling `calls[0].data`'s selector and the high bytes of its
+ * first argument. Pinning the spender alone leaves the selector free, so the
+ * same word layout also satisfies `transfer(aggregator, amount)` — which sends
+ * the pulled input to the aggregator instead of approving it, and with
+ * `minAmountOut` free to be zero the Swapper does not object.
+ */
+const CALLS_ELEM0_DATA_HEAD_OFFSET = 480n;
+const ERC20_APPROVE_SELECTOR = '095ea7b3';
+/** `approve` selector followed by the leading 28 bytes of the spender word. */
+function approveHeadWord(spender) {
+    return `0x${ERC20_APPROVE_SELECTOR}${'00'.repeat(12)}${spender
+        .slice(2, 34)
+        .toLowerCase()}`;
+}
+/** The `spender` argument of `calls[0]`'s `approve`, past its 4-byte selector. */
+const CALLS_ELEM0_SPENDER_OFFSET = 484n;
+const CALLS_ELEM0_DATA_POINTER = 96n;
+/** `approve(address,uint256)` — selector + two words. */
+const APPROVE_CALLDATA_LENGTH = 68n;
+const CALLS_POINTER = 256n;
+const CALLS_LENGTH = 2n;
+const CALLS_ELEM0_POINTER = 64n;
+const CALLS_ELEM1_POINTER = 288n;
+/**
+ * Pin the two-call `approve + aggregator` route inside the Swapper's `calls[]`.
+ *
+ * Without this the tail is unconstrained: the Swapper only requires that the
+ * recipient nets `minAmountOut`, and `minAmountOut` may be zero, so a
+ * compromised key could hand the pulled input to any address and satisfy the
+ * contract. Constraining every call target to a real aggregator removes the
+ * place those funds could go.
+ *
+ * Fails closed. A route that deviates from this shape — a different call count,
+ * an added permit or approval reset — reverts rather than slipping through, so
+ * the cost of the pin is availability, not safety.
+ */
+function routeRules(sellToken, aggregator, settler, 
+/** Set for the fynd route: pins the nested swap's tokens and receiver. */
+fyndNested) {
+    const nestedFynd = fyndNested
+        ? [
+            // Pinning calls[1].target to the Tycho router still leaves the swap it
+            // performs free to name any tokens and any receiver — so the output
+            // could land anywhere while the outer Swapper pins still hold.
+            pinValue(CALLS_ELEM1_DATA_POINTER_OFFSET, CALLS_ELEM1_DATA_POINTER),
+            pin(NESTED_FYND_TOKEN_IN_OFFSET, sellToken),
+            pin(NESTED_FYND_TOKEN_OUT_OFFSET, fyndNested.buyToken),
+            pin(NESTED_FYND_RECEIVER_OFFSET, fyndNested.swapper),
+        ]
+        : [];
+    const nested = settler
+        ? [
+            // Pinning calls[1]'s target to the AllowanceHolder still leaves the
+            // exec it forwards free to name any operator and target, which is where
+            // the pulled input would go. Pin those too when the Settler is known.
+            pinValue(CALLS_ELEM1_VALUE_OFFSET, 0n),
+            pinValue(CALLS_ELEM1_DATA_POINTER_OFFSET, CALLS_ELEM1_DATA_POINTER),
+            pin(NESTED_EXEC_OPERATOR_OFFSET, settler),
+            pin(NESTED_EXEC_TOKEN_OFFSET, sellToken),
+            pin(NESTED_EXEC_TARGET_OFFSET, settler),
+        ]
+        : [];
+    return [
+        ...nested,
+        ...nestedFynd,
+        pinValue(CALLS_POINTER_OFFSET, CALLS_POINTER),
+        pinValue(CALLS_LENGTH_OFFSET, CALLS_LENGTH),
+        pinValue(CALLS_ELEM0_POINTER_OFFSET, CALLS_ELEM0_POINTER),
+        pinValue(CALLS_ELEM1_POINTER_OFFSET, CALLS_ELEM1_POINTER),
+        pin(CALLS_ELEM0_TARGET_OFFSET, sellToken),
+        pin(CALLS_ELEM1_TARGET_OFFSET, aggregator),
+        // Pinning calls[0]'s target alone still lets it be any call to the sell
+        // token — `transfer(attacker, amountIn)` as easily as an approve. Fixing
+        // its length and the address it names leaves the aggregator as the only
+        // party the pulled input can reach.
+        pinValue(CALLS_ELEM0_VALUE_OFFSET, 0n),
+        pinValue(CALLS_ELEM0_DATA_POINTER_OFFSET, CALLS_ELEM0_DATA_POINTER),
+        pinValue(CALLS_ELEM0_DATA_LENGTH_OFFSET, APPROVE_CALLDATA_LENGTH),
+        pinWord(CALLS_ELEM0_DATA_HEAD_OFFSET, approveHeadWord(aggregator)),
+        pin(CALLS_ELEM0_SPENDER_OFFSET, aggregator),
+    ];
+}
+/**
+ * Route swaps through the Rhinestone Swapper — the default, and the only venue
+ * that matches what the orchestrator emits for same-chain smart-account swaps.
+ *
+ * Takes no addresses and no aggregator: which quoter fills the swap is the
+ * orchestrator's decision, and this scoping holds whichever one wins.
+ */
+export function rhinestoneSwap(options = {}) {
+    return {
+        id: 'rhinestone',
+        ...(options.maxSpend !== undefined ? { maxSpend: options.maxSpend } : {}),
+    };
+}
+export function scopeRhinestone(venue, ctx) {
+    const { swapper, proxy } = swapperAddresses(ctx.environment);
+    if (venue.route === 'zeroEx' && !ZEROX_CHAIN_IDS.includes(ctx.chainId)) {
+        throw new Error(`0x is not available on chain ${ctx.chainId}. ` +
+            `Supported: ${ZEROX_CHAIN_IDS.join(', ')}.`);
+    }
+    if (venue.route === 'fynd' && !FYND_CHAIN_IDS.includes(ctx.chainId)) {
+        throw new Error(`fynd is not available on chain ${ctx.chainId}. ` +
+            `Supported: ${FYND_CHAIN_IDS.join(', ')}.`);
+    }
+    // Which router the pinned tail must call. Undefined route = unconstrained.
+    const routeAggregator = venue.route === 'zeroEx'
+        ? ZEROX_ALLOWANCE_HOLDER
+        : venue.route === 'fynd'
+            ? FYND_ROUTERS[ctx.chainId]
+            : undefined;
+    const rulesFor = (offsets, sellAmountParam) => {
+        const rules = [
+            pin(offsets.tokenIn, ctx.sellToken),
+            pin(offsets.tokenOut, ctx.buyToken),
+            pin(offsets.recipient, ctx.recipient),
+        ];
+        if (ctx.cap !== undefined) {
+            rules.push(cumulativeCap(offsets[sellAmountParam], ctx.cap));
+        }
+        if (venue.routes === undefined && routeAggregator !== undefined) {
+            rules.push(...routeRules(ctx.sellToken, routeAggregator, venue.route === 'zeroEx' ? venue.settler : undefined, venue.route === 'fynd'
+                ? { buyToken: ctx.buyToken, swapper }
+                : undefined));
+        }
+        return rules;
+    };
+    /** One rule set per authorised aggregator; the policy requires any one. */
+    const routeAlternatives = (venue.routes ?? []).map((route) => routeRules(ctx.sellToken, route === 'zeroEx'
+        ? ZEROX_ALLOWANCE_HOLDER
+        : FYND_ROUTERS[ctx.chainId], route === 'zeroEx' ? venue.settler : undefined, route === 'fynd' ? { buyToken: ctx.buyToken, swapper } : undefined));
+    return {
+        // The account approves the proxy, never the Swapper and never a router —
+        // one fixed spender per chain, whichever aggregator ends up filling.
+        approveSpenders: [proxy],
+        actions: [
+            swapAction(swapper, SWAP_EXACT_IN_SELECTOR, rulesFor(EXACT_IN, 'amountIn'), routeAlternatives),
+            swapAction(swapper, SWAP_EXACT_OUT_SELECTOR, rulesFor(EXACT_OUT, 'amountInMax'), routeAlternatives),
+        ],
+    };
+}

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

@@ -0,0 +1,73 @@
+import type { Address, Hex } from 'viem';
+import type { ScopedAction, UniversalActionPolicyParamRule } from '../types.js';
+/**
+ * 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 declare function pinValue(calldataOffset: bigint, referenceValue: bigint): UniversalActionPolicyParamRule;
+/** Pin a calldata word to an exact 32-byte value. */
+export declare function pinWord(calldataOffset: bigint, referenceValue: Hex): UniversalActionPolicyParamRule;
+/** Pin a calldata word to an exact address. */
+export declare function pin(calldataOffset: bigint, referenceValue: Address): UniversalActionPolicyParamRule;
+/**
+ * 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 declare function cumulativeCap(calldataOffset: bigint, cap: bigint): UniversalActionPolicyParamRule;
+export declare function swapAction(target: Address, selector: `0x${string}`, rules: UniversalActionPolicyParamRule[], 
+/**
+ * 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?: UniversalActionPolicyParamRule[][]): ScopedAction;
+/** What a venue module returns for one configured venue. */
+export interface VenueScoping {
+    /**
+     * ERC-20 spenders the session may approve the sell token to. Plural because a
+     * venue reachable by more than one call shape has a different allowance
+     * target per shape — 0x direct pulls via its AllowanceHolder, the same swap
+     * wrapped pulls via the Swapper's proxy.
+     */
+    readonly approveSpenders: readonly Address[];
+    /**
+     * One or more scoped actions. Plural because a venue may expose several
+     * entrypoints that are all legitimate for the same scope — the Rhinestone
+     * Swapper has separate exact-in and exact-out selectors, and which one the
+     * orchestrator picks is its choice, not the caller's.
+     */
+    readonly actions: readonly ScopedAction[];
+}
+/** Everything a venue needs to know about the swap being scoped. */
+export interface VenueContext {
+    readonly chainId: number;
+    /** Selects the Swapper/proxy deployment pair. */
+    readonly environment: 'production' | 'development';
+    readonly sellToken: Address;
+    readonly buyToken: Address;
+    readonly recipient: Address;
+    /** Cumulative sell-token cap, or undefined for no cap. */
+    readonly cap: bigint | undefined;
+}
+//# sourceMappingURL=rules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../../../modules/validators/smart-sessions/swap/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,EAEV,YAAY,EAEZ,8BAA8B,EAC/B,MAAM,UAAU,CAAA;AAEjB;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,8BAA8B,CAEhC;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CACrB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,GAClB,8BAA8B,CAEhC;AAED,+CAA+C;AAC/C,wBAAgB,GAAG,CACjB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,OAAO,GACtB,8BAA8B,CAEhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,GACV,8BAA8B,CAOhC;AAgCD,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,MAAM,EAAE,EACvB,KAAK,EAAE,8BAA8B,EAAE;AACvC;;;;;;GAMG;AACH,YAAY,GAAE,8BAA8B,EAAE,EAAO,GACpD,YAAY,CA0Bd;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,OAAO,EAAE,CAAA;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,YAAY,GAAG,aAAa,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC"}

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"}