@zbase-protocol/core 0.1.0

package/dist/stealth.js

@@ -0,0 +1,387 @@
+/**
+ * @zbase-protocol/core — ERC-5564 stealth addresses (scheme id 1, secp256k1)
+ *
+ * Implements the canonical ERC-5564 scheme 1 ("secp256k1-1") as deployed by
+ * ScopeLift / Umbra / Fluidkey, the same scheme audited by Trail of Bits.
+ * Spec: https://eips.ethereum.org/EIPS/eip-5564
+ *
+ * The scheme:
+ *   - Provider holds two secp256k1 keypairs: spending (k_s, K_s) and viewing (k_v, K_v).
+ *   - Meta-address encodes the two compressed public keys as
+ *       st:<chain>:0x<spendingPubKey:33B><viewingPubKey:33B>      // 132 hex chars
+ *   - For each payment the facilitator (sender) generates a fresh ephemeral
+ *     keypair (r, R = r·G), computes the ECDH shared point S = r · K_v,
+ *     hashes it: s_h = keccak256(S_compressed). The view tag is s_h[0].
+ *   - The stealth public key is P = K_s + s_h · G. The stealth Ethereum
+ *     address is the standard keccak256(uncompressed-pub-key-without-prefix)[12:].
+ *   - The provider scans Announcement events, recomputes S = k_v · R for
+ *     each ephemeral pubkey, checks the view tag, and (on match) derives the
+ *     stealth private key as k = (k_s + s_h) mod n.
+ *
+ * Why this matters: today every payment to OpenAI's x402 endpoint pays the
+ * same address; an outside observer maps "wallet X pays Nansen every 60s".
+ * After this ship, every payment to the same provider lands on a different
+ * stealth address derived from their registered meta-address — the buyer
+ * sees a single endpoint, the chain sees N unrelated recipients.
+ *
+ * Security boundary: the viewing private key never leaves the provider.
+ * An attacker who controls the facilitator AND knows the viewing key can
+ * correlate ephemeralPubkey → stealth recipient. Without the viewing key,
+ * the link is computationally hidden by the discrete-log assumption on
+ * secp256k1 (same assumption Ethereum signatures rely on).
+ */
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { keccak_256 } from "@noble/hashes/sha3";
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+/** ERC-5564 scheme identifier. Only scheme 1 (secp256k1 + keccak256) is supported. */
+export const STEALTH_SCHEME_ID = 1;
+/** Default chain tag used in meta-address URIs ("st:<chain>:0x..."). */
+export const DEFAULT_CHAIN_TAG = "base";
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider-side: meta-address generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Produce a fresh ERC-5564 meta-address from an optional seed.
+ *
+ * The seed is intentionally optional: passing a deterministic seed enables
+ * reproducible tests; omitting it pulls 64 bytes of OS randomness. Either
+ * way, both keys live for the life of the provider — they are NOT rotated
+ * per call.
+ *
+ * @param seed Optional 64-byte Uint8Array. First 32 bytes seed the spending
+ *   key, last 32 bytes seed the viewing key. If omitted, secure random.
+ */
+export function generateMetaAddress(seed, chainTag = DEFAULT_CHAIN_TAG) {
+    let spendingPrivateKey;
+    let viewingPrivateKey;
+    if (seed) {
+        if (seed.length !== 64) {
+            throw new Error(`stealth: seed must be exactly 64 bytes, got ${seed.length}`);
+        }
+        spendingPrivateKey = clampToCurve(seed.slice(0, 32));
+        viewingPrivateKey = clampToCurve(seed.slice(32, 64));
+    }
+    else {
+        spendingPrivateKey = secp256k1.utils.randomPrivateKey();
+        viewingPrivateKey = secp256k1.utils.randomPrivateKey();
+    }
+    const spendingPublicKey = secp256k1.getPublicKey(spendingPrivateKey, true);
+    const viewingPublicKey = secp256k1.getPublicKey(viewingPrivateKey, true);
+    const metaAddress = `st:${chainTag}:0x${bytesToHex(spendingPublicKey)}${bytesToHex(viewingPublicKey)}`;
+    return {
+        metaAddress,
+        spendingPublicKey: "0x" + bytesToHex(spendingPublicKey),
+        viewingPublicKey: "0x" + bytesToHex(viewingPublicKey),
+        spendingPrivateKey: "0x" + bytesToHex(spendingPrivateKey),
+        viewingPrivateKey: "0x" + bytesToHex(viewingPrivateKey),
+    };
+}
+/**
+ * Parse a "st:<chain>:0x<spending:33B><viewing:33B>" meta-address URI.
+ * Accepts either the full URI or a bare 0x-prefixed 132-hex-char string.
+ */
+export function parseMetaAddress(metaAddress) {
+    let chainTag = DEFAULT_CHAIN_TAG;
+    let raw;
+    if (metaAddress.startsWith("st:")) {
+        const parts = metaAddress.split(":");
+        if (parts.length !== 3) {
+            throw new Error(`stealth: malformed meta-address URI: ${metaAddress}`);
+        }
+        chainTag = parts[1];
+        raw = parts[2];
+    }
+    else {
+        raw = metaAddress;
+    }
+    if (raw.startsWith("0x"))
+        raw = raw.slice(2);
+    if (raw.length !== 132) {
+        throw new Error(`stealth: meta-address payload must be 132 hex chars (got ${raw.length})`);
+    }
+    if (!/^[0-9a-fA-F]+$/.test(raw)) {
+        throw new Error("stealth: meta-address payload must be hex");
+    }
+    const spendingPublicKey = hexToBytes(raw.slice(0, 66));
+    const viewingPublicKey = hexToBytes(raw.slice(66));
+    if (!isValidCompressedPubKey(spendingPublicKey)) {
+        throw new Error("stealth: spendingPublicKey is not a valid compressed secp256k1 point");
+    }
+    if (!isValidCompressedPubKey(viewingPublicKey)) {
+        throw new Error("stealth: viewingPublicKey is not a valid compressed secp256k1 point");
+    }
+    return { chainTag, spendingPublicKey, viewingPublicKey };
+}
+/**
+ * Quick sniff test: is this string an ERC-5564 meta-address (vs a plain
+ * 0x-address)? Used by the facilitator to decide which path to take.
+ */
+export function isStealthMetaAddress(s) {
+    if (typeof s !== "string")
+        return false;
+    if (s.startsWith("st:"))
+        return true;
+    // bare 0x form is allowed: 132 hex chars + 0x prefix
+    if (s.startsWith("0x") && s.length === 134 && /^0x[0-9a-fA-F]+$/.test(s))
+        return true;
+    return false;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Facilitator-side: per-payment stealth derivation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Derive a fresh stealth address for a provider, given their meta-address
+ * and a 32-byte ephemeral nonce (= ephemeral private key r).
+ *
+ * The facilitator publishes `ephemeralPublicKey` on-chain alongside the
+ * payment; the provider scans for it and recovers the funds. The nonce
+ * MUST be unpredictable to anyone but the facilitator and MUST NOT repeat
+ * (a repeat collapses two payments to the same stealth address, leaking
+ * the link). Pass `undefined` to generate a fresh CSPRNG nonce.
+ *
+ * @param metaAddress provider's "st:base:0x..." meta-address
+ * @param ephemeralNonce 32-byte scalar, or undefined for fresh randomness
+ */
+export function deriveStealthAddress(metaAddress, ephemeralNonce) {
+    const { spendingPublicKey, viewingPublicKey } = parseMetaAddress(metaAddress);
+    // F8: the stealth private key the recipient later derives is
+    //   k = (k_s + keccak256(r·K_v)) mod n
+    // and is UNSPENDABLE if it lands on 0. Pre-fix, the sender announced the
+    // ephemeral key R first and only the recipient discovered the doomed key —
+    // funds permanently stuck. Here, on the sender side, we detect the degenerate
+    // case (the derived stealth POINT being the curve identity, which is exactly
+    // when k ≡ 0) BEFORE returning anything to announce. With a random nonce we
+    // simply redraw; with a caller-supplied nonce we throw so the caller picks
+    // another. The event is ~1-in-2^256, so this never loops in practice.
+    const PP = secp256k1
+        .ProjectivePoint;
+    const n = secp256k1.CURVE.n;
+    for (let attempt = 0;; attempt++) {
+        const r = attempt === 0 && ephemeralNonce
+            ? clampToCurve(ephemeralNonce)
+            : secp256k1.utils.randomPrivateKey();
+        if (r.length !== 32) {
+            throw new Error(`stealth: ephemeralNonce must be 32 bytes, got ${r.length}`);
+        }
+        const ephemeralPublicKey = secp256k1.getPublicKey(r, true);
+        // S = r · K_v, compressed (33B). Hash with keccak256 per scheme 1.
+        const sharedPointCompressed = secp256k1.getSharedSecret(r, viewingPublicKey);
+        const sharedSecretHash = keccak_256(sharedPointCompressed);
+        // Necessary condition: the additive scalar must be non-zero mod n.
+        const sScalar = bytesToBigInt(sharedSecretHash) % n;
+        let degenerate = sScalar === 0n;
+        let stealthAddress = "";
+        if (!degenerate) {
+            try {
+                // Throws if the resulting point is the identity (k ≡ 0) — the exact
+                // unspendable case we must avoid announcing.
+                const hashedPoint = PP.BASE.multiply(sScalar);
+                const stealthPoint = PP.fromHex(spendingPublicKey).add(hashedPoint);
+                const uncompressed = stealthPoint.toRawBytes(false);
+                const addressBytes = keccak_256(uncompressed.slice(1)).slice(12);
+                stealthAddress = "0x" + bytesToHex(addressBytes);
+            }
+            catch {
+                degenerate = true;
+            }
+        }
+        if (degenerate) {
+            if (ephemeralNonce && attempt === 0) {
+                throw new Error("stealth: supplied ephemeralNonce yields an unspendable (zero) stealth key — pick another");
+            }
+            continue; // random path: redraw (astronomically rare)
+        }
+        const viewTag = bytesToHex(sharedSecretHash.slice(0, 1));
+        return {
+            stealthAddress,
+            ephemeralPublicKey: "0x" + bytesToHex(ephemeralPublicKey),
+            viewTag: "0x" + viewTag,
+        };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider-side: scanning + private-key recovery
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Given the provider's viewing private key and a batch of recent ephemeral
+ * pubkeys (from on-chain Announcement events or facilitator settle logs),
+ * return the stealth addresses that belong to this provider.
+ *
+ * View-tag optimization: if `expectedViewTags` is supplied, each candidate
+ * is filtered on its 1-byte view tag before the (more expensive) point add.
+ * This reduces scan cost by ~256× when most announcements aren't ours.
+ *
+ * @param viewingPrivateKey provider's viewing private key (32 bytes or hex)
+ * @param recentEphemeralPubkeys array of compressed ephemeral pubkeys
+ * @param spendingPublicKey provider's spending public key (needed to derive
+ *        the stealth address from the shared secret)
+ * @param expectedViewTags optional array (same length as recentEphemeralPubkeys);
+ *        if a tag is provided and doesn't match, the entry is skipped without
+ *        doing the point arithmetic
+ */
+export function scanForPayments(viewingPrivateKey, recentEphemeralPubkeys, spendingPublicKey, expectedViewTags) {
+    const kv = toBytes32(viewingPrivateKey);
+    const Ks = toCompressedPubKey(spendingPublicKey);
+    const matches = [];
+    for (let i = 0; i < recentEphemeralPubkeys.length; i++) {
+        const R = toCompressedPubKey(recentEphemeralPubkeys[i]);
+        // S = k_v · R, hashed.
+        const sharedPointCompressed = secp256k1.getSharedSecret(kv, R);
+        const sharedSecretHash = keccak_256(sharedPointCompressed);
+        const observedTag = sharedSecretHash[0];
+        // View-tag pre-filter: skip the point add if the tag is provided and mismatches.
+        if (expectedViewTags && expectedViewTags[i] !== undefined) {
+            const expected = parseViewTagByte(expectedViewTags[i]);
+            if (expected !== observedTag)
+                continue;
+        }
+        const stealthAddress = stealthAddressFromHashed(Ks, sharedSecretHash);
+        matches.push({
+            index: i,
+            ephemeralPublicKey: "0x" + bytesToHex(R),
+            stealthAddress,
+            viewTag: "0x" + bytesToHex(Uint8Array.of(observedTag)),
+        });
+    }
+    return matches;
+}
+/**
+ * Given the provider's spending+viewing private keys and an ephemeral pubkey
+ * that's known to belong to this provider, derive the stealth address's
+ * private key. With this key the provider can sweep funds to a treasury.
+ *
+ *   k_stealth = (k_s + keccak256(k_v · R)) mod n
+ *
+ * @returns 32-byte stealth private key (raw bytes; 0x-encode if you need hex)
+ */
+export function computeStealthPrivateKey(spendingPrivateKey, viewingPrivateKey, ephemeralPublicKey) {
+    const ks = toBytes32(spendingPrivateKey);
+    const kv = toBytes32(viewingPrivateKey);
+    const R = toCompressedPubKey(ephemeralPublicKey);
+    const sharedPointCompressed = secp256k1.getSharedSecret(kv, R);
+    const sharedSecretHash = keccak_256(sharedPointCompressed);
+    // Field is the curve's scalar order n.
+    const n = secp256k1.CURVE.n;
+    const sum = (bytesToBigInt(ks) + bytesToBigInt(sharedSecretHash)) % n;
+    if (sum === 0n) {
+        // 1-in-2^256 event; refuse rather than emit the zero key.
+        throw new Error("stealth: derived stealth private key is zero (refusing)");
+    }
+    return bigIntToBytes32(sum);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/** P = K_s + s_h · G   →   address = keccak256(uncompressed(P)[1:])[-20:] */
+function stealthAddressFromHashed(spendingPubKeyCompressed, sharedSecretHash) {
+    // ProjectivePoint is exposed on @noble/curves secp256k1 for back-compat.
+    const PP = secp256k1
+        .ProjectivePoint;
+    const hashedPoint = PP.BASE.multiply(bytesToBigInt(sharedSecretHash));
+    const spendingPoint = PP.fromHex(spendingPubKeyCompressed);
+    const stealthPoint = spendingPoint.add(hashedPoint);
+    const uncompressed = stealthPoint.toRawBytes(false); // 65 bytes, 0x04 || X || Y
+    const addressBytes = keccak_256(uncompressed.slice(1)).slice(12);
+    return "0x" + bytesToHex(addressBytes);
+}
+function clampToCurve(scalar) {
+    if (scalar.length !== 32) {
+        throw new Error(`stealth: scalar must be 32 bytes (got ${scalar.length})`);
+    }
+    const n = secp256k1.CURVE.n;
+    let v = bytesToBigInt(scalar) % n;
+    if (v === 0n)
+        v = 1n; // never emit the zero scalar
+    return bigIntToBytes32(v);
+}
+function isValidCompressedPubKey(bytes) {
+    if (bytes.length !== 33)
+        return false;
+    if (bytes[0] !== 0x02 && bytes[0] !== 0x03)
+        return false;
+    try {
+        const PP = secp256k1
+            .ProjectivePoint;
+        PP.fromHex(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toBytes32(input) {
+    if (input instanceof Uint8Array) {
+        if (input.length !== 32)
+            throw new Error(`stealth: expected 32 bytes, got ${input.length}`);
+        return input;
+    }
+    let s = input.startsWith("0x") ? input.slice(2) : input;
+    if (s.length !== 64)
+        throw new Error(`stealth: expected 32-byte hex, got ${s.length / 2} bytes`);
+    return hexToBytes(s);
+}
+function toCompressedPubKey(input) {
+    if (input instanceof Uint8Array) {
+        if (input.length === 33)
+            return input;
+        if (input.length === 65) {
+            // Re-compress: just take parity bit + X.
+            const PP = secp256k1
+                .ProjectivePoint;
+            return PP.fromHex(input).toRawBytes(true);
+        }
+        throw new Error(`stealth: pubkey must be 33B (compressed) or 65B (uncompressed), got ${input.length}`);
+    }
+    let s = input.startsWith("0x") ? input.slice(2) : input;
+    if (s.length !== 66 && s.length !== 130) {
+        throw new Error(`stealth: pubkey hex must be 66 or 130 chars, got ${s.length}`);
+    }
+    return toCompressedPubKey(hexToBytes(s));
+}
+function parseViewTagByte(input) {
+    if (input instanceof Uint8Array) {
+        if (input.length === 0)
+            throw new Error("stealth: empty view tag");
+        return input[0];
+    }
+    let s = input.startsWith("0x") ? input.slice(2) : input;
+    if (s.length < 2)
+        throw new Error(`stealth: view tag too short: ${input}`);
+    return parseInt(s.slice(0, 2), 16);
+}
+function bytesToHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+function hexToBytes(hex) {
+    const s = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (s.length % 2 !== 0)
+        throw new Error("stealth: odd-length hex");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+function bytesToBigInt(bytes) {
+    let v = 0n;
+    for (const b of bytes)
+        v = (v << 8n) | BigInt(b);
+    return v;
+}
+function bigIntToBytes32(v) {
+    if (v < 0n)
+        throw new Error("stealth: negative scalar");
+    const out = new Uint8Array(32);
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    if (v !== 0n)
+        throw new Error("stealth: scalar > 2^256");
+    return out;
+}

package/dist/swapPlan.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Build a `CallPlan` for private swap-as-settlement: an agent pays the pool asset
+ * (USDC) and the seller receives a DIFFERENT token, unlinkably, in one settlement.
+ *
+ * This is NOT a private trading venue — it is private SETTLEMENT that happens to
+ * cross assets. The ExecutorProcessooor hides WHO funded the swap; the swap itself
+ * is public on-chain. See the zBase threat model + docs/strategy/xochi-competitive-
+ * analysis-2026-07-08.md §7.
+ *
+ * The executor whitelists a swap router `(target, selector)` at construction. This
+ * helper produces the exact `exactInputSingle` calldata for that router.
+ *
+ * ── The load-bearing constraint (audit F1) ───────────────────────────────────────
+ * The executor measures the produced output on ITS OWN balance and then sweeps to
+ * the final recipient. So the router's `recipient` field MUST be the executor, NOT
+ * the seller. If you point the router at the seller directly, the executor sees
+ * outDelta == 0 and reverts `NoOutputProduced`. This helper hardcodes
+ * `recipient = executor` so a caller cannot get it wrong — the seller is carried in
+ * the CallPlan's own `recipient` field, which the executor sweeps to afterward.
+ */
+import type { CallPlan } from "./facilitatorClient.js";
+/** Uniswap V3 SwapRouter02 `exactInputSingle` selector — the whitelisted selector. */
+export declare const EXACT_INPUT_SINGLE_SELECTOR: "0x04e45aaf";
+export interface BuildSwapCallPlanOpts {
+    /** The whitelisted Uniswap V3 SwapRouter02 address (executor's frozen whitelist). */
+    router: string;
+    /** The deployed ExecutorProcessooor — the swap recipient MUST be this (audit F1). */
+    executor: string;
+    /** Pool asset spent into the swap (USDC). Must equal the pool's ASSET. */
+    inputToken: string;
+    /** Token the seller wants to receive (e.g. EURC). Must differ from inputToken (F5). */
+    outputToken: string;
+    /** The Uniswap V3 pool fee tier (e.g. 500, 3000, 10000). */
+    poolFee: number;
+    /** Atomic amount of inputToken to swap (post-fee spend). */
+    amountIn: bigint;
+    /** Slippage floor on outputToken (atomic). MUST be > 0 (audit F2). */
+    minOut: bigint;
+    /** The final seller/recipient of outputToken — the executor sweeps here after the swap. */
+    recipient: string;
+}
+/**
+ * Build a well-formed `CallPlan` for a Uniswap-V3-style single-hop swap.
+ *
+ * Enforces the executor's invariants up front so a malformed plan is caught here,
+ * not at a wasted on-chain revert:
+ *  - `recipient` in the router calldata = the executor (F1)
+ *  - `inputToken != outputToken` (F5)
+ *  - `minOut > 0` (F2)
+ *  - `amountOutMinimum` in calldata == the CallPlan `minOut` (consistency)
+ */
+export declare function buildSwapCallPlan(opts: BuildSwapCallPlanOpts): CallPlan;

package/dist/swapPlan.js

@@ -0,0 +1,104 @@
+/**
+ * Build a `CallPlan` for private swap-as-settlement: an agent pays the pool asset
+ * (USDC) and the seller receives a DIFFERENT token, unlinkably, in one settlement.
+ *
+ * This is NOT a private trading venue — it is private SETTLEMENT that happens to
+ * cross assets. The ExecutorProcessooor hides WHO funded the swap; the swap itself
+ * is public on-chain. See the zBase threat model + docs/strategy/xochi-competitive-
+ * analysis-2026-07-08.md §7.
+ *
+ * The executor whitelists a swap router `(target, selector)` at construction. This
+ * helper produces the exact `exactInputSingle` calldata for that router.
+ *
+ * ── The load-bearing constraint (audit F1) ───────────────────────────────────────
+ * The executor measures the produced output on ITS OWN balance and then sweeps to
+ * the final recipient. So the router's `recipient` field MUST be the executor, NOT
+ * the seller. If you point the router at the seller directly, the executor sees
+ * outDelta == 0 and reverts `NoOutputProduced`. This helper hardcodes
+ * `recipient = executor` so a caller cannot get it wrong — the seller is carried in
+ * the CallPlan's own `recipient` field, which the executor sweeps to afterward.
+ */
+import { encodeFunctionData, getAddress } from "viem";
+/** Uniswap V3 SwapRouter02 `exactInputSingle` selector — the whitelisted selector. */
+export const EXACT_INPUT_SINGLE_SELECTOR = "0x04e45aaf";
+/**
+ * Minimal ABI for Uniswap V3 SwapRouter02 `exactInputSingle`. SwapRouter02 drops the
+ * `deadline` field that the original SwapRouter carried, so the params tuple is 7
+ * fields. `amountOutMinimum` is the on-chain slippage floor; we set it equal to the
+ * CallPlan `minOut` the executor independently enforces (belt and suspenders).
+ */
+const EXACT_INPUT_SINGLE_ABI = [
+    {
+        name: "exactInputSingle",
+        type: "function",
+        stateMutability: "payable",
+        inputs: [
+            {
+                name: "params",
+                type: "tuple",
+                components: [
+                    { name: "tokenIn", type: "address" },
+                    { name: "tokenOut", type: "address" },
+                    { name: "fee", type: "uint24" },
+                    { name: "recipient", type: "address" },
+                    { name: "amountIn", type: "uint256" },
+                    { name: "amountOutMinimum", type: "uint256" },
+                    { name: "sqrtPriceLimitX96", type: "uint160" },
+                ],
+            },
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+    },
+];
+/**
+ * Build a well-formed `CallPlan` for a Uniswap-V3-style single-hop swap.
+ *
+ * Enforces the executor's invariants up front so a malformed plan is caught here,
+ * not at a wasted on-chain revert:
+ *  - `recipient` in the router calldata = the executor (F1)
+ *  - `inputToken != outputToken` (F5)
+ *  - `minOut > 0` (F2)
+ *  - `amountOutMinimum` in calldata == the CallPlan `minOut` (consistency)
+ */
+export function buildSwapCallPlan(opts) {
+    const inputToken = getAddress(opts.inputToken);
+    const outputToken = getAddress(opts.outputToken);
+    const executor = getAddress(opts.executor);
+    const router = getAddress(opts.router);
+    const recipient = getAddress(opts.recipient);
+    if (inputToken === outputToken) {
+        throw new Error("buildSwapCallPlan: inputToken must differ from outputToken (executor audit F5)");
+    }
+    if (opts.minOut <= 0n) {
+        throw new Error("buildSwapCallPlan: minOut must be > 0 (executor audit F2)");
+    }
+    if (opts.amountIn <= 0n) {
+        throw new Error("buildSwapCallPlan: amountIn must be > 0");
+    }
+    const callData = encodeFunctionData({
+        abi: EXACT_INPUT_SINGLE_ABI,
+        functionName: "exactInputSingle",
+        args: [
+            {
+                tokenIn: inputToken,
+                tokenOut: outputToken,
+                fee: opts.poolFee,
+                // ★ audit F1: the swap output goes to the EXECUTOR, which then sweeps to
+                //   the CallPlan `recipient` (the seller). Pointing this at the seller
+                //   directly makes outDelta == 0 → NoOutputProduced revert.
+                recipient: executor,
+                amountIn: opts.amountIn,
+                amountOutMinimum: opts.minOut,
+                sqrtPriceLimitX96: 0n,
+            },
+        ],
+    });
+    return {
+        target: router,
+        inputToken,
+        outputToken,
+        minOut: opts.minOut.toString(),
+        recipient, // the seller — the executor sweeps outputToken here after the swap
+        callData,
+    };
+}