@shroud-fi/relayer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShroudFi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @shroud-fi/relayer
+
+> Gasless sweep client for ShroudFi. ERC-20 via Gelato + EIP-2612 permit; ETH via EIP-7702.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/relayer.svg)](https://www.npmjs.com/package/@shroud-fi/relayer)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/relayer viem
+```
+
+## What it does
+
+`@shroud-fi/relayer` is the client side of a gasless sweep. A stealth address that holds USDC or ETH but **no ETH for gas** can still extract its funds — the relayer pays gas, the recipient pays a 1% fee.
+
+- **ERC-20 path:** signs an EIP-2612 `permit` + ERC-2771 metaTx, submits via Gelato 1Balance. The Gelato sponsor EOA broadcasts; the stealth EOA never needs ETH.
+- **ETH path:** signs an EIP-7702 authorization that delegates the stealth EOA's code to `ShroudFiEthRelayer`, then calls `sweepETH(destination, fee)` in a single tx.
+
+The recipient pays a 1% fee at sweep time — taken inside the contract execution, not at send time, so the sender's graph stays clean.
+
+## Quick start
+
+```ts
+import { relayedSweepERC20 } from '@shroud-fi/relayer';
+
+const receipt = await relayedSweepERC20({
+  transport,
+  stealthPrivateKey,
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC Base
+  destination: '0xYourDestination',
+  relayerContract: '0x44f35ED32516AE8247aF5ec4ED5d5BEb501631d1', // ShroudFi mainnet
+});
+
+// receipt: { txHash, gasUsed, taskStatus }  — no plaintext amount field
+```
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `relayedSweepERC20(args)` | Gasless ERC-20 sweep via Gelato 1Balance. |
+| `relayedSweepETH(args)` | Gasless ETH sweep via EIP-7702 delegated relayer. |
+| `RelayerSweepReceipt` | Result type — no plaintext amount field by design. |
+| `StealthAddressEmptyError` | Distinguishes "already swept" from wallet insufficiency. |
+| `RelayerInsufficientBalanceError` | Despite the name, this means the **stealth address is empty**, not the relayer. |
+
+Full API reference: [shroudfi.live/sdk#relayer](https://shroudfi.live/sdk#relayer)
+
+## Direct sweep escape hatch
+
+`@shroud-fi/payments` provides `sweepETH` / `sweepERC20` for the fee-free direct path. The relayer is opt-in — agents that already hold ETH can sweep without paying the 1%.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/constants.d.ts

@@ -0,0 +1,41 @@
+import type { Address } from 'viem';
+/**
+ * Default EIP-2612 permit deadline lifetime (in seconds).
+ *
+ * 30 minutes balances:
+ *   - long enough for Gelato task scheduling + L2 inclusion under congestion
+ *   - short enough to keep the signed permit window tight (smaller front-run /
+ *     replay attack window if a permit signature leaks)
+ */
+export declare const DEFAULT_PERMIT_DEADLINE_SECS: bigint;
+/** Poll Gelato task status every 2s by default. */
+export declare const DEFAULT_POLL_INTERVAL_MS: number;
+/** Abort polling after 90s by default — well past Base L2 inclusion p99. */
+export declare const DEFAULT_POLL_TIMEOUT_MS: number;
+/**
+ * Gelato Trusted Forwarder addresses ("Group A") for ShroudFi-supported chains.
+ *
+ * Both Base Sepolia (84532) and Base Mainnet (8453) share the same
+ * forwarder address per Gelato's Group A deployment.
+ *
+ * Defense-in-depth: at runtime the SDK reads `ShroudFiRelayer.trustedForwarder()`
+ * and asserts equality against this table before submitting any metaTx.
+ */
+export declare const GELATO_FORWARDER_BY_CHAIN: Readonly<Record<number, Address>>;
+/**
+ * Gelato public task-status endpoint. No auth required.
+ * Used as a fallback if the SDK's `getTaskStatus` is unavailable.
+ */
+export declare const GELATO_TASK_STATUS_URL: string;
+/**
+ * Default EIP-712 EthSweep deadline lifetime (seconds). Matches the ERC-20
+ * permit deadline — 30 minutes balances inclusion headroom against a tight
+ * replay window if the signature leaks.
+ */
+export declare const DEFAULT_ETH_SWEEP_DEADLINE_SECS: bigint;
+/**
+ * Chains where the ShroudFiEthRelayer is deployed AND EIP-7702 is active.
+ * Base Sepolia (84532) + Base mainnet (8453). Pectra activated on both.
+ */
+export declare const ETH_RELAYER_SUPPORTED_CHAINS: ReadonlySet<number>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAc,CAAC;AAE1D,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,EAAE,MAAa,CAAC;AAErD,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,EAAE,MAAe,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIpE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MACO,CAAC;AAI7C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAc,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAE3D,CAAC"}

package/dist/cjs/constants.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ETH_RELAYER_SUPPORTED_CHAINS = exports.DEFAULT_ETH_SWEEP_DEADLINE_SECS = exports.GELATO_TASK_STATUS_URL = exports.GELATO_FORWARDER_BY_CHAIN = exports.DEFAULT_POLL_TIMEOUT_MS = exports.DEFAULT_POLL_INTERVAL_MS = exports.DEFAULT_PERMIT_DEADLINE_SECS = void 0;
+/**
+ * Default EIP-2612 permit deadline lifetime (in seconds).
+ *
+ * 30 minutes balances:
+ *   - long enough for Gelato task scheduling + L2 inclusion under congestion
+ *   - short enough to keep the signed permit window tight (smaller front-run /
+ *     replay attack window if a permit signature leaks)
+ */
+exports.DEFAULT_PERMIT_DEADLINE_SECS = 1800n;
+/** Poll Gelato task status every 2s by default. */
+exports.DEFAULT_POLL_INTERVAL_MS = 2000;
+/** Abort polling after 90s by default — well past Base L2 inclusion p99. */
+exports.DEFAULT_POLL_TIMEOUT_MS = 90_000;
+/**
+ * Gelato Trusted Forwarder addresses ("Group A") for ShroudFi-supported chains.
+ *
+ * Both Base Sepolia (84532) and Base Mainnet (8453) share the same
+ * forwarder address per Gelato's Group A deployment.
+ *
+ * Defense-in-depth: at runtime the SDK reads `ShroudFiRelayer.trustedForwarder()`
+ * and asserts equality against this table before submitting any metaTx.
+ */
+exports.GELATO_FORWARDER_BY_CHAIN = Object.freeze({
+    8453: '0xd8253782c45a12053594b9deB72d8e8aB2Fca54c',
+    84532: '0xd8253782c45a12053594b9deB72d8e8aB2Fca54c',
+});
+/**
+ * Gelato public task-status endpoint. No auth required.
+ * Used as a fallback if the SDK's `getTaskStatus` is unavailable.
+ */
+exports.GELATO_TASK_STATUS_URL = 'https://api.gelato.digital/tasks/status/';
+// ─── ETH sweep (P5.1) ─────────────────────────────────────────────────────
+/**
+ * Default EIP-712 EthSweep deadline lifetime (seconds). Matches the ERC-20
+ * permit deadline — 30 minutes balances inclusion headroom against a tight
+ * replay window if the signature leaks.
+ */
+exports.DEFAULT_ETH_SWEEP_DEADLINE_SECS = 1800n;
+/**
+ * Chains where the ShroudFiEthRelayer is deployed AND EIP-7702 is active.
+ * Base Sepolia (84532) + Base mainnet (8453). Pectra activated on both.
+ */
+exports.ETH_RELAYER_SUPPORTED_CHAINS = new Set([
+    8453, 84532,
+]);
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AACU,QAAA,4BAA4B,GAAW,KAAK,CAAC;AAE1D,mDAAmD;AACtC,QAAA,wBAAwB,GAAW,IAAI,CAAC;AAErD,4EAA4E;AAC/D,QAAA,uBAAuB,GAAW,MAAM,CAAC;AAEtD;;;;;;;;GAQG;AACU,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC;IACZ,IAAI,EAAE,4CAAuD;IAC7D,KAAK,EAAE,4CAAuD;CAC/D,CAAC,CAAC;AAEL;;;GAGG;AACU,QAAA,sBAAsB,GACjC,0CAA0C,CAAC;AAE7C,6EAA6E;AAE7E;;;;GAIG;AACU,QAAA,+BAA+B,GAAW,KAAK,CAAC;AAE7D;;;GAGG;AACU,QAAA,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IACvE,IAAI,EAAE,KAAK;CACZ,CAAC,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Base class for all relayer-layer failures. Carries no key or amount
+ * material. Mirrors the shape of `@shroud-fi/payments` errors.
+ */
+export declare class RelayerError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+/** EIP-2612 permit could not be signed (typed-data path failed). */
+export declare class RelayerSignatureError extends RelayerError {
+    readonly name: string;
+    constructor();
+}
+/** Gelato accepted/rejected the metaTx submission — no taskId obtained. */
+export declare class RelayerSubmissionError extends RelayerError {
+    readonly name: string;
+    constructor(tag?: string);
+}
+/**
+ * Gelato accepted the task but on-chain execution reverted (or was blacklisted).
+ * Carries the lifecycle state but no signature / amount / address bytes.
+ */
+export declare class RelayerExecutionFailedError extends RelayerError {
+    readonly name: string;
+    constructor(state: string);
+}
+/** Polling exceeded the configured timeout. */
+export declare class RelayerTimeoutError extends RelayerError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * On-chain `ShroudFiRelayer.trustedForwarder()` did not match the Gelato
+ * forwarder we expected for this chain. Defense-in-depth against deploying
+ * against the wrong forwarder.
+ */
+export declare class RelayerForwarderMismatchError extends RelayerError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * Stealth address held zero balance of the target token at the time the
+ * relayer was asked to sweep it. Distinct from a wallet "insufficient funds"
+ * condition — this means the inbound stealth has already been swept (or never
+ * funded), so there's nothing left to relay.
+ */
+export declare class StealthAddressEmptyError extends RelayerError {
+    readonly name: string;
+    constructor();
+}
+/** Transport chain is not in the supported Gelato forwarder table. */
+export declare class RelayerInvalidChainError extends RelayerError {
+    readonly name: string;
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,EAAE,MAAM,CAAkB;gBACpC,OAAO,EAAE,MAAM;CAG5B;AAED,oEAAoE;AACpE,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,SAAkB,IAAI,EAAE,MAAM,CAA2B;;CAI1D;AAED,2EAA2E;AAC3E,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,SAAkB,IAAI,EAAE,MAAM,CAA4B;gBAC9C,GAAG,CAAC,EAAE,MAAM;CAOzB;AAED;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,YAAY;IAC3D,SAAkB,IAAI,EAAE,MAAM,CAAiC;gBACnD,KAAK,EAAE,MAAM;CAG1B;AAED,+CAA+C;AAC/C,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,SAAkB,IAAI,EAAE,MAAM,CAAyB;;CAIxD;AAED;;;;GAIG;AACH,qBAAa,6BAA8B,SAAQ,YAAY;IAC7D,SAAkB,IAAI,EAAE,MAAM,CAAmC;;CAIlE;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,YAAY;IACxD,SAAkB,IAAI,EAAE,MAAM,CAA8B;;CAI7D;AAED,sEAAsE;AACtE,qBAAa,wBAAyB,SAAQ,YAAY;IACxD,SAAkB,IAAI,EAAE,MAAM,CAA8B;;CAI7D"}

package/dist/cjs/errors.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayerInvalidChainError = exports.StealthAddressEmptyError = exports.RelayerForwarderMismatchError = exports.RelayerTimeoutError = exports.RelayerExecutionFailedError = exports.RelayerSubmissionError = exports.RelayerSignatureError = exports.RelayerError = void 0;
+/**
+ * Base class for all relayer-layer failures. Carries no key or amount
+ * material. Mirrors the shape of `@shroud-fi/payments` errors.
+ */
+class RelayerError extends Error {
+    name = 'RelayerError';
+    constructor(message) {
+        super(message);
+    }
+}
+exports.RelayerError = RelayerError;
+/** EIP-2612 permit could not be signed (typed-data path failed). */
+class RelayerSignatureError extends RelayerError {
+    name = 'RelayerSignatureError';
+    constructor() {
+        super('Failed to sign EIP-2612 permit');
+    }
+}
+exports.RelayerSignatureError = RelayerSignatureError;
+/** Gelato accepted/rejected the metaTx submission — no taskId obtained. */
+class RelayerSubmissionError extends RelayerError {
+    name = 'RelayerSubmissionError';
+    constructor(tag) {
+        super(tag === undefined
+            ? 'Failed to submit sponsored call to relayer network'
+            : `Failed to submit sponsored call to relayer network (${tag})`);
+    }
+}
+exports.RelayerSubmissionError = RelayerSubmissionError;
+/**
+ * Gelato accepted the task but on-chain execution reverted (or was blacklisted).
+ * Carries the lifecycle state but no signature / amount / address bytes.
+ */
+class RelayerExecutionFailedError extends RelayerError {
+    name = 'RelayerExecutionFailedError';
+    constructor(state) {
+        super(`Relayed sweep execution did not succeed (state=${state})`);
+    }
+}
+exports.RelayerExecutionFailedError = RelayerExecutionFailedError;
+/** Polling exceeded the configured timeout. */
+class RelayerTimeoutError extends RelayerError {
+    name = 'RelayerTimeoutError';
+    constructor() {
+        super('Timed out waiting for relayer task to reach a terminal state');
+    }
+}
+exports.RelayerTimeoutError = RelayerTimeoutError;
+/**
+ * On-chain `ShroudFiRelayer.trustedForwarder()` did not match the Gelato
+ * forwarder we expected for this chain. Defense-in-depth against deploying
+ * against the wrong forwarder.
+ */
+class RelayerForwarderMismatchError extends RelayerError {
+    name = 'RelayerForwarderMismatchError';
+    constructor() {
+        super('Relayer contract trustedForwarder does not match expected Gelato forwarder');
+    }
+}
+exports.RelayerForwarderMismatchError = RelayerForwarderMismatchError;
+/**
+ * Stealth address held zero balance of the target token at the time the
+ * relayer was asked to sweep it. Distinct from a wallet "insufficient funds"
+ * condition — this means the inbound stealth has already been swept (or never
+ * funded), so there's nothing left to relay.
+ */
+class StealthAddressEmptyError extends RelayerError {
+    name = 'StealthAddressEmptyError';
+    constructor() {
+        super('Stealth address has zero balance of the target token');
+    }
+}
+exports.StealthAddressEmptyError = StealthAddressEmptyError;
+/** Transport chain is not in the supported Gelato forwarder table. */
+class RelayerInvalidChainError extends RelayerError {
+    name = 'RelayerInvalidChainError';
+    constructor() {
+        super('Transport chain is not supported by the Gelato relayer');
+    }
+}
+exports.RelayerInvalidChainError = RelayerInvalidChainError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,YAAa,SAAQ,KAAK;IACnB,IAAI,GAAW,cAAc,CAAC;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AALD,oCAKC;AAED,oEAAoE;AACpE,MAAa,qBAAsB,SAAQ,YAAY;IACnC,IAAI,GAAW,uBAAuB,CAAC;IACzD;QACE,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC1C,CAAC;CACF;AALD,sDAKC;AAED,2EAA2E;AAC3E,MAAa,sBAAuB,SAAQ,YAAY;IACpC,IAAI,GAAW,wBAAwB,CAAC;IAC1D,YAAY,GAAY;QACtB,KAAK,CACH,GAAG,KAAK,SAAS;YACf,CAAC,CAAC,oDAAoD;YACtD,CAAC,CAAC,uDAAuD,GAAG,GAAG,CAClE,CAAC;IACJ,CAAC;CACF;AATD,wDASC;AAED;;;GAGG;AACH,MAAa,2BAA4B,SAAQ,YAAY;IACzC,IAAI,GAAW,6BAA6B,CAAC;IAC/D,YAAY,KAAa;QACvB,KAAK,CAAC,kDAAkD,KAAK,GAAG,CAAC,CAAC;IACpE,CAAC;CACF;AALD,kEAKC;AAED,+CAA+C;AAC/C,MAAa,mBAAoB,SAAQ,YAAY;IACjC,IAAI,GAAW,qBAAqB,CAAC;IACvD;QACE,KAAK,CAAC,8DAA8D,CAAC,CAAC;IACxE,CAAC;CACF;AALD,kDAKC;AAED;;;;GAIG;AACH,MAAa,6BAA8B,SAAQ,YAAY;IAC3C,IAAI,GAAW,+BAA+B,CAAC;IACjE;QACE,KAAK,CAAC,4EAA4E,CAAC,CAAC;IACtF,CAAC;CACF;AALD,sEAKC;AAED;;;;;GAKG;AACH,MAAa,wBAAyB,SAAQ,YAAY;IACtC,IAAI,GAAW,0BAA0B,CAAC;IAC5D;QACE,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;CACF;AALD,4DAKC;AAED,sEAAsE;AACtE,MAAa,wBAAyB,SAAQ,YAAY;IACtC,IAAI,GAAW,0BAA0B,CAAC;IAC5D;QACE,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAClE,CAAC;CACF;AALD,4DAKC"}

package/dist/cjs/eth-sweep.d.ts

@@ -0,0 +1,36 @@
+/**
+ * relayedSweepETH — gasless ETH sweep via EIP-7702 + self-host relayer service.
+ *
+ * Flow:
+ *   1. Validate chain is in the supported ETH-relayer table.
+ *   2. Read stealth EOA balance; refuse if zero.
+ *   3. Read stealth EOA nonce (required for the EIP-7702 auth tuple).
+ *   4. Sign an EIP-7702 SET_CODE authorization delegating the stealth EOA to
+ *      `ethRelayerContract`.
+ *   5. Sign an EIP-712 `EthSweep(destination, deadline)` message — the
+ *      contract verifies this binds the specific destination + deadline so a
+ *      compromised relayer cannot redirect funds.
+ *   6. POST both signatures to the self-host relayer's /relay-eth endpoint.
+ *   7. Wait for the on-chain receipt and return.
+ *
+ * Privacy invariants:
+ *   - `stealthPrivateKey` never logged, never serialized to any persistent
+ *     surface. Held in a closure during this call only.
+ *   - No amount fields in the returned receipt. Callers wanting amount can
+ *     compare pre/post balances themselves.
+ *   - Error messages contain no addresses, signature bytes, or chain ids.
+ *   - The fetch request body is constructed once and discarded. No fetch
+ *     library that caches request bodies is used (native `fetch` only).
+ *
+ * Why self-host instead of Gelato:
+ *   Gelato's 7702 path is bundled into their Smart Wallets product (passkeys,
+ *   wallet abstraction). It doesn't expose a "submit my pre-signed 7702 auth"
+ *   endpoint that fits our threat model. Our self-host relayer at
+ *   api.shroudfi.live already controls its own EOA and can build arbitrary
+ *   tx types — fewer vendor dependencies, full control of the broadcast path.
+ */
+import { type Address, type Hex } from 'viem';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { RelayedEthSweepOptions, RelayedEthSweepReceipt } from './types.js';
+export declare function relayedSweepETH(transport: ShroudFiTransport, stealthPrivateKey: Hex, destination: Address, ethRelayerContract: Address, relayerServiceUrl: string, options?: RelayedEthSweepOptions): Promise<RelayedEthSweepReceipt>;
+//# sourceMappingURL=eth-sweep.d.ts.map

package/dist/cjs/eth-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eth-sweep.d.ts","sourceRoot":"","sources":["../../src/eth-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAE9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAoCpB,wBAAsB,eAAe,CACnC,SAAS,EAAE,iBAAiB,EAC5B,iBAAiB,EAAE,GAAG,EACtB,WAAW,EAAE,OAAO,EACpB,kBAAkB,EAAE,OAAO,EAC3B,iBAAiB,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAkJjC"}

package/dist/cjs/eth-sweep.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * relayedSweepETH — gasless ETH sweep via EIP-7702 + self-host relayer service.
+ *
+ * Flow:
+ *   1. Validate chain is in the supported ETH-relayer table.
+ *   2. Read stealth EOA balance; refuse if zero.
+ *   3. Read stealth EOA nonce (required for the EIP-7702 auth tuple).
+ *   4. Sign an EIP-7702 SET_CODE authorization delegating the stealth EOA to
+ *      `ethRelayerContract`.
+ *   5. Sign an EIP-712 `EthSweep(destination, deadline)` message — the
+ *      contract verifies this binds the specific destination + deadline so a
+ *      compromised relayer cannot redirect funds.
+ *   6. POST both signatures to the self-host relayer's /relay-eth endpoint.
+ *   7. Wait for the on-chain receipt and return.
+ *
+ * Privacy invariants:
+ *   - `stealthPrivateKey` never logged, never serialized to any persistent
+ *     surface. Held in a closure during this call only.
+ *   - No amount fields in the returned receipt. Callers wanting amount can
+ *     compare pre/post balances themselves.
+ *   - Error messages contain no addresses, signature bytes, or chain ids.
+ *   - The fetch request body is constructed once and discarded. No fetch
+ *     library that caches request bodies is used (native `fetch` only).
+ *
+ * Why self-host instead of Gelato:
+ *   Gelato's 7702 path is bundled into their Smart Wallets product (passkeys,
+ *   wallet abstraction). It doesn't expose a "submit my pre-signed 7702 auth"
+ *   endpoint that fits our threat model. Our self-host relayer at
+ *   api.shroudfi.live already controls its own EOA and can build arbitrary
+ *   tx types — fewer vendor dependencies, full control of the broadcast path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayedSweepETH = relayedSweepETH;
+const accounts_1 = require("viem/accounts");
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * EIP-712 typed-data spec for the EthSweep struct. Matches
+ * `bytes32 SWEEP_TYPEHASH = keccak256("EthSweep(address destination,uint256 deadline)")`
+ * in ShroudFiEthRelayer.sol.
+ */
+const ETH_SWEEP_TYPES = {
+    EthSweep: [
+        { name: 'destination', type: 'address' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+const ETH_SWEEP_DOMAIN_NAME = 'ShroudFiEthRelayer';
+const ETH_SWEEP_DOMAIN_VERSION = '1';
+function isHex(s) {
+    return typeof s === 'string' && /^0x[0-9a-fA-F]+$/.test(s);
+}
+async function relayedSweepETH(transport, stealthPrivateKey, destination, ethRelayerContract, relayerServiceUrl, options) {
+    const chainId = transport.chain.id;
+    // 1. Chain support gate.
+    if (!constants_js_1.ETH_RELAYER_SUPPORTED_CHAINS.has(chainId)) {
+        throw new errors_js_1.RelayerInvalidChainError();
+    }
+    const account = (0, accounts_1.privateKeyToAccount)(stealthPrivateKey);
+    const stealthAddress = account.address;
+    // 2. Balance pre-flight.
+    const balance = await transport.publicClient.getBalance({
+        address: stealthAddress,
+    });
+    if (balance === 0n) {
+        throw new errors_js_1.StealthAddressEmptyError();
+    }
+    // 3. Read stealth EOA's nonce. EIP-7702 auth tuples include the EOA's
+    // nonce; mismatches at submission time cause invalid_auth_signature reverts.
+    const nonce = await transport.publicClient.getTransactionCount({
+        address: stealthAddress,
+    });
+    // 4. Compute deadline against on-chain block timestamp.
+    const lifetime = options?.deadlineSecs ?? constants_js_1.DEFAULT_ETH_SWEEP_DEADLINE_SECS;
+    const block = await transport.publicClient.getBlock();
+    const deadline = block.timestamp + lifetime;
+    // 5a. Sign EIP-7702 SET_CODE authorization.
+    let authorization;
+    try {
+        authorization = await account.signAuthorization({
+            contractAddress: ethRelayerContract,
+            chainId,
+            nonce,
+        });
+    }
+    catch {
+        throw new errors_js_1.RelayerSignatureError();
+    }
+    // 5b. Sign EIP-712 EthSweep. verifyingContract = stealthAddress because the
+    // contract runs as delegated code at the stealth EOA's address. OZ EIP712
+    // rebuilds the domain at runtime when address(this) != _cachedThis.
+    let signature;
+    try {
+        signature = await account.signTypedData({
+            domain: {
+                name: ETH_SWEEP_DOMAIN_NAME,
+                version: ETH_SWEEP_DOMAIN_VERSION,
+                chainId,
+                verifyingContract: stealthAddress,
+            },
+            types: ETH_SWEEP_TYPES,
+            primaryType: 'EthSweep',
+            message: { destination, deadline },
+        });
+    }
+    catch {
+        throw new errors_js_1.RelayerSignatureError();
+    }
+    // 6. POST to self-host relayer. The relayer reconstructs the 7702
+    // SignedAuthorization, builds a type-0x04 transaction, and broadcasts.
+    const url = `${relayerServiceUrl.replace(/\/$/, '')}/relay-eth`;
+    const body = {
+        stealthAddress,
+        destination,
+        chainId,
+        deadline: deadline.toString(),
+        signature,
+        authorization: {
+            address: authorization.address,
+            chainId: authorization.chainId,
+            nonce: authorization.nonce,
+            r: authorization.r,
+            s: authorization.s,
+            yParity: authorization.yParity,
+        },
+    };
+    let response;
+    try {
+        const init = {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        };
+        if (options?.signal !== undefined) {
+            init.signal = options.signal;
+        }
+        response = await fetch(url, init);
+    }
+    catch {
+        throw new errors_js_1.RelayerSubmissionError();
+    }
+    if (!response.ok) {
+        let tag;
+        try {
+            const parsed = (await response.json());
+            if (typeof parsed.error === 'string')
+                tag = parsed.error;
+        }
+        catch {
+            // body wasn't JSON — fall through with no tag.
+        }
+        throw new errors_js_1.RelayerSubmissionError(tag);
+    }
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch {
+        throw new errors_js_1.RelayerSubmissionError();
+    }
+    if (parsed.ok !== true || !isHex(parsed.txHash)) {
+        const tag = typeof parsed.error === 'string' ? parsed.error : 'unknown';
+        throw new errors_js_1.RelayerExecutionFailedError(tag);
+    }
+    const txHash = parsed.txHash;
+    // 7. Wait for on-chain confirmation. Relayer responded with a tx hash; the
+    // tx is broadcasting but not necessarily mined. Use viem's standard
+    // wait-for-receipt with the configured timeout.
+    const timeoutMs = options?.pollTimeoutMs ?? constants_js_1.DEFAULT_POLL_TIMEOUT_MS;
+    let receipt;
+    try {
+        receipt = await transport.publicClient.waitForTransactionReceipt({
+            hash: txHash,
+            timeout: timeoutMs,
+        });
+    }
+    catch {
+        throw new errors_js_1.RelayerTimeoutError();
+    }
+    if (receipt.status !== 'success') {
+        throw new errors_js_1.RelayerExecutionFailedError('reverted');
+    }
+    return {
+        txHash,
+        status: 'success',
+        blockNumber: receipt.blockNumber,
+        ethRelayerContract,
+        destination,
+        stealthAddress,
+    };
+}
+//# sourceMappingURL=eth-sweep.js.map

package/dist/cjs/eth-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eth-sweep.js","sourceRoot":"","sources":["../../src/eth-sweep.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AAiDH,0CAyJC;AAvMD,4CAAoD;AAEpD,iDAIwB;AAKxB,2CAOqB;AAErB;;;;GAIG;AACH,MAAM,eAAe,GAAG;IACtB,QAAQ,EAAE;QACR,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE;QACxC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;KACtC;CACO,CAAC;AAEX,MAAM,qBAAqB,GAAG,oBAAoB,CAAC;AACnD,MAAM,wBAAwB,GAAG,GAAG,CAAC;AASrC,SAAS,KAAK,CAAC,CAAU;IACvB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAEM,KAAK,UAAU,eAAe,CACnC,SAA4B,EAC5B,iBAAsB,EACtB,WAAoB,EACpB,kBAA2B,EAC3B,iBAAyB,EACzB,OAAgC;IAEhC,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IAEnC,yBAAyB;IACzB,IAAI,CAAC,2CAA4B,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,oCAAwB,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,8BAAmB,EAAC,iBAAiB,CAAC,CAAC;IACvD,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAEvC,yBAAyB;IACzB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC;QACtD,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IACH,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,oCAAwB,EAAE,CAAC;IACvC,CAAC;IAED,sEAAsE;IACtE,6EAA6E;IAC7E,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,mBAAmB,CAAC;QAC7D,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,wDAAwD;IACxD,MAAM,QAAQ,GAAG,OAAO,EAAE,YAAY,IAAI,8CAA+B,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;IACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC;IAE5C,4CAA4C;IAC5C,IAAI,aAAa,CAAC;IAClB,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC;YAC9C,eAAe,EAAE,kBAAkB;YACnC,OAAO;YACP,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iCAAqB,EAAE,CAAC;IACpC,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,oEAAoE;IACpE,IAAI,SAAc,CAAC;IACnB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC;YACtC,MAAM,EAAE;gBACN,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,wBAAwB;gBACjC,OAAO;gBACP,iBAAiB,EAAE,cAAc;aAClC;YACD,KAAK,EAAE,eAAe;YACtB,WAAW,EAAE,UAAU;YACvB,OAAO,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;SACnC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iCAAqB,EAAE,CAAC;IACpC,CAAC;IAED,kEAAkE;IAClE,uEAAuE;IACvE,MAAM,GAAG,GAAG,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC;IAChE,MAAM,IAAI,GAAG;QACX,cAAc;QACd,WAAW;QACX,OAAO;QACP,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;QAC7B,SAAS;QACT,aAAa,EAAE;YACb,OAAO,EAAE,aAAa,CAAC,OAAO;YAC9B,OAAO,EAAE,aAAa,CAAC,OAAO;YAC9B,KAAK,EAAE,aAAa,CAAC,KAAK;YAC1B,CAAC,EAAE,aAAa,CAAC,CAAC;YAClB,CAAC,EAAE,aAAa,CAAC,CAAC;YAClB,OAAO,EAAE,aAAa,CAAC,OAAO;SAC/B;KACF,CAAC;IAEF,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,IAAI,GAAgB;YACxB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC;QACF,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/B,CAAC;QACD,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kCAAsB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,IAAI,GAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;YAC/D,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;gBAAE,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;QACjD,CAAC;QACD,MAAM,IAAI,kCAAsB,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,MAA4B,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kCAAsB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,MAAM,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,MAAM,IAAI,uCAA2B,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAE7B,2EAA2E;IAC3E,oEAAoE;IACpE,gDAAgD;IAChD,MAAM,SAAS,GAAG,OAAO,EAAE,aAAa,IAAI,sCAAuB,CAAC;IACpE,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,yBAAyB,CAAC;YAC/D,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,+BAAmB,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,uCAA2B,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,MAAM;QACN,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,kBAAkB;QAClB,WAAW;QACX,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/cjs/gelato-adapter.d.ts

@@ -0,0 +1,69 @@
+import type { Address, Hex, Chain } from 'viem';
+import type { GelatoTaskId, RelayerSweepStatus } from './types.js';
+/**
+ * Parameters for submitting a sponsored (1Balance) ERC-2771 metaTx.
+ *
+ * `data` must already be ABI-encoded for the target function on `target`.
+ * The Gelato relay layer appends the `user` address to the calldata so the
+ * `_msgSender()` inside the target contract returns the stealth address.
+ *
+ * Privacy: `userPrivateKey` is consumed once to construct an ephemeral
+ * `walletClient`, which is then handed to the Gelato SDK. It is never logged,
+ * stored on `this`, or attached to thrown errors.
+ */
+export interface SubmitMetaTxParams {
+    readonly chainId: number;
+    readonly target: Address;
+    readonly data: Hex;
+    readonly user: Address;
+    readonly userPrivateKey: Hex;
+    /**
+     * Optional Gelato 1Balance sponsor API key.
+     * The SDK requires a string; if absent we forward an empty string and let
+     * Gelato reject with a structured error.
+     */
+    readonly apiKey?: string;
+    readonly signal?: AbortSignal;
+    /**
+     * viem `Chain` to attach to the ephemeral walletClient. Required so viem
+     * has a chainId/rpc context for typed-data signing.
+     */
+    readonly chain: Chain;
+    /** RPC URL forwarded to the ephemeral walletClient. */
+    readonly rpcUrl?: string;
+}
+/**
+ * Normalized Gelato task status surfaced to the SDK caller. Strips PII /
+ * un-needed metadata (creation date, gas used, etc.) from the upstream type.
+ */
+export interface GelatoTaskStatus {
+    readonly taskId: GelatoTaskId;
+    readonly state: RelayerSweepStatus;
+    readonly txHash?: Hex;
+    readonly blockNumber?: bigint;
+    readonly lastErrorMsg?: string;
+}
+/**
+ * Submit a sponsored ERC-2771 metaTx via Gelato 1Balance.
+ *
+ * Returns the Gelato `taskId`. Caller is responsible for polling.
+ */
+export declare function submitSponsoredCallErc2771(p: SubmitMetaTxParams): Promise<GelatoTaskId>;
+/**
+ * Poll Gelato task status until terminal (success / failed / cancelled) or
+ * until the timeout expires / the abort signal fires.
+ *
+ * Strategy:
+ *   1. Try the SDK's `getTaskStatus` first (it shares websocket cache).
+ *   2. Fall back to direct HTTP if the SDK returns undefined.
+ *
+ * Errors:
+ *   - RelayerTimeoutError on timeout / abort
+ *   - RelayerExecutionFailedError on `failed`/`cancelled` terminal state
+ */
+export declare function pollGelatoTaskUntilTerminal(taskId: GelatoTaskId, opts: {
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<GelatoTaskStatus>;
+//# sourceMappingURL=gelato-adapter.d.ts.map

package/dist/cjs/gelato-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gelato-adapter.d.ts","sourceRoot":"","sources":["../../src/gelato-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAOhD,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAOnE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAYD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,YAAY,CAAC,CAgCvB;AA2FD;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE;IACJ,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GACA,OAAO,CAAC,gBAAgB,CAAC,CAsD3B"}