@dynamic-labs/ethereum-gasless-core 0.0.0 → 4.84.0

package/src/lib/resolveChainId/resolveChainId.js

@@ -0,0 +1,8 @@
+'use client'
+/**
+ * Resolves a chain ID from either an explicit override or the chain ID
+ * configured in the gasless chain deps.
+ */
+const resolveChainId = ({ chainId }, { chainId: depsChainId }) => chainId ?? depsChainId;
+
+export { resolveChainId };

package/src/lib/sendSponsoredTransaction/sendSponsoredTransaction.cjs

@@ -0,0 +1,21 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var relaySponsoredTransaction = require('../relaySponsoredTransaction/relaySponsoredTransaction.cjs');
+var waitForSponsoredTransaction = require('../waitForSponsoredTransaction/waitForSponsoredTransaction.cjs');
+
+/**
+ * Sends a sponsored EVM transaction and waits for on-chain inclusion.
+ *
+ * Composes `relaySponsoredTransaction` (signs + submits to the relay) and
+ * `waitForSponsoredTransaction` (polls relay status). Returns the on-chain
+ * transaction hash once the relay reports inclusion.
+ */
+const sendSponsoredTransaction = async (params, deps) => {
+    const { requestId } = await relaySponsoredTransaction.relaySponsoredTransaction(params, deps);
+    return waitForSponsoredTransaction.waitForSponsoredTransaction({ requestId }, deps);
+};
+
+exports.sendSponsoredTransaction = sendSponsoredTransaction;

package/src/lib/sendSponsoredTransaction/sendSponsoredTransaction.d.ts

@@ -0,0 +1,29 @@
+import type { Hex } from 'viem';
+import type { SignAuthorizationReturnType } from 'viem/accounts';
+import type { EvmGaslessChainDeps, SignedSponsoredTransaction, SponsoredTransactionCall } from '../types';
+type SendWithCallsParams = {
+    /** Pre-signed EIP-7702 authorization. Takes priority over autoDelegate. */
+    authorization?: SignAuthorizationReturnType;
+    /** Whether to automatically sign 7702 authorization if not delegated. Defaults to true. */
+    autoDelegate?: boolean;
+    /** The batch of calls to execute. */
+    calls: SponsoredTransactionCall[];
+    /** How long the signed intent remains valid, in seconds. Defaults to 600. */
+    validForSeconds?: number;
+};
+type SendWithSignedTxParams = {
+    /** A pre-signed sponsored transaction payload from `signSponsoredTransaction`. */
+    signedTransaction: SignedSponsoredTransaction;
+};
+type SendSponsoredTransactionParams = SendWithCallsParams | SendWithSignedTxParams;
+/**
+ * Sends a sponsored EVM transaction and waits for on-chain inclusion.
+ *
+ * Composes `relaySponsoredTransaction` (signs + submits to the relay) and
+ * `waitForSponsoredTransaction` (polls relay status). Returns the on-chain
+ * transaction hash once the relay reports inclusion.
+ */
+export declare const sendSponsoredTransaction: (params: SendSponsoredTransactionParams, deps: EvmGaslessChainDeps) => Promise<{
+    transactionHash: Hex;
+}>;
+export {};

package/src/lib/sendSponsoredTransaction/sendSponsoredTransaction.js

@@ -0,0 +1,17 @@
+'use client'
+import { relaySponsoredTransaction } from '../relaySponsoredTransaction/relaySponsoredTransaction.js';
+import { waitForSponsoredTransaction } from '../waitForSponsoredTransaction/waitForSponsoredTransaction.js';
+
+/**
+ * Sends a sponsored EVM transaction and waits for on-chain inclusion.
+ *
+ * Composes `relaySponsoredTransaction` (signs + submits to the relay) and
+ * `waitForSponsoredTransaction` (polls relay status). Returns the on-chain
+ * transaction hash once the relay reports inclusion.
+ */
+const sendSponsoredTransaction = async (params, deps) => {
+    const { requestId } = await relaySponsoredTransaction(params, deps);
+    return waitForSponsoredTransaction({ requestId }, deps);
+};
+
+export { sendSponsoredTransaction };

package/src/lib/sign7702Authorization/sign7702Authorization.cjs

@@ -0,0 +1,22 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var constants = require('../constants.cjs');
+
+/**
+ * Signs an EIP-7702 authorization to delegate the user's wallet to the
+ * Dynamic gasless delegation contract.
+ *
+ * The resulting authorization can be passed to `sendSponsoredTransaction`
+ * (or any first-time sponsored call) to activate delegation as part of the
+ * sponsored intent.
+ */
+const sign7702Authorization = async ({ chainId }, { chainId: depsChainId, walletClient }) => walletClient.signAuthorization({
+    account: walletClient.account,
+    chainId: chainId ?? depsChainId,
+    contractAddress: constants.DELEGATION_CONTRACT_ADDRESS,
+});
+
+exports.sign7702Authorization = sign7702Authorization;

package/src/lib/sign7702Authorization/sign7702Authorization.d.ts

@@ -0,0 +1,21 @@
+import type { Account, Chain, Transport, WalletClient } from 'viem';
+import type { SignAuthorizationReturnType } from 'viem/accounts';
+type Sign7702AuthorizationParams = {
+    /** Override the chain ID embedded in the signed authorization. */
+    chainId?: number;
+};
+type Sign7702AuthorizationDeps = {
+    /** Default chain ID used when none is supplied via `params`. */
+    chainId: number;
+    walletClient: WalletClient<Transport, Chain, Account>;
+};
+/**
+ * Signs an EIP-7702 authorization to delegate the user's wallet to the
+ * Dynamic gasless delegation contract.
+ *
+ * The resulting authorization can be passed to `sendSponsoredTransaction`
+ * (or any first-time sponsored call) to activate delegation as part of the
+ * sponsored intent.
+ */
+export declare const sign7702Authorization: ({ chainId }: Sign7702AuthorizationParams, { chainId: depsChainId, walletClient }: Sign7702AuthorizationDeps) => Promise<SignAuthorizationReturnType>;
+export {};

package/src/lib/sign7702Authorization/sign7702Authorization.js

@@ -0,0 +1,18 @@
+'use client'
+import { DELEGATION_CONTRACT_ADDRESS } from '../constants.js';
+
+/**
+ * Signs an EIP-7702 authorization to delegate the user's wallet to the
+ * Dynamic gasless delegation contract.
+ *
+ * The resulting authorization can be passed to `sendSponsoredTransaction`
+ * (or any first-time sponsored call) to activate delegation as part of the
+ * sponsored intent.
+ */
+const sign7702Authorization = async ({ chainId }, { chainId: depsChainId, walletClient }) => walletClient.signAuthorization({
+    account: walletClient.account,
+    chainId: chainId ?? depsChainId,
+    contractAddress: DELEGATION_CONTRACT_ADDRESS,
+});
+
+export { sign7702Authorization };

package/src/lib/signSponsoredTransaction/signSponsoredTransaction.cjs

@@ -0,0 +1,61 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var constants = require('../constants.cjs');
+var generateIntentNonce = require('../generateIntentNonce/generateIntentNonce.cjs');
+var getAvailableEvmGaslessRelayer = require('../getAvailableEvmGaslessRelayer/getAvailableEvmGaslessRelayer.cjs');
+var resolveAuthorization = require('../resolveAuthorization/resolveAuthorization.cjs');
+var toSerializedAuthorization = require('../toSerializedAuthorization/toSerializedAuthorization.cjs');
+
+/**
+ * Signs a sponsored transaction as an EIP-712 `AuthorizedExecutions` intent.
+ *
+ * Orchestrates the full signing flow: resolves the (optional) EIP-7702
+ * authorization, generates a bitmap nonce, fetches the relay address for
+ * the target chain, and signs the typed-data payload with the wallet client
+ * provided in `deps`.
+ */
+const signSponsoredTransaction = async ({ authorization, autoDelegate = true, calls, validForSeconds = constants.DEFAULT_VALID_FOR_SECONDS, }, deps) => {
+    const { chainId, walletClient } = deps;
+    const walletAddress = walletClient.account.address;
+    const resolvedAuthorization = await resolveAuthorization.resolveAuthorization({ authorization, autoDelegate, walletAddress }, deps);
+    const nonce = await generateIntentNonce.generateIntentNonce({ walletAddress }, deps);
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + validForSeconds);
+    const { relayerAddress } = await getAvailableEvmGaslessRelayer.getAvailableEvmGaslessRelayer({ chainId }, deps);
+    const signature = await walletClient.signTypedData({
+        account: walletClient.account,
+        domain: {
+            chainId,
+            verifyingContract: constants.DELEGATION_CONTRACT_ADDRESS,
+        },
+        message: {
+            calls: calls.map((c) => ({
+                data: c.data,
+                target: c.target,
+                value: c.value,
+            })),
+            deadline,
+            mode: constants.BATCH_CALL_OPDATA_AUTH_MODE,
+            nonce,
+            relayer: relayerAddress,
+        },
+        primaryType: 'AuthorizedExecutions',
+        types: constants.AUTHORIZED_EXECUTIONS_TYPES,
+    });
+    return {
+        authorization: resolvedAuthorization
+            ? toSerializedAuthorization.toSerializedAuthorization(resolvedAuthorization)
+            : undefined,
+        calls,
+        chainId,
+        deadline: deadline.toString(),
+        nonce: nonce.toString(),
+        relayer: relayerAddress,
+        signature: signature,
+        walletAddress,
+    };
+};
+
+exports.signSponsoredTransaction = signSponsoredTransaction;

package/src/lib/signSponsoredTransaction/signSponsoredTransaction.d.ts

@@ -0,0 +1,22 @@
+import type { SignAuthorizationReturnType } from 'viem/accounts';
+import type { EvmGaslessChainDeps, SignedSponsoredTransaction, SponsoredTransactionCall } from '../types';
+type SignSponsoredTransactionParams = {
+    /** Pre-signed EIP-7702 authorization. Takes priority over autoDelegate. */
+    authorization?: SignAuthorizationReturnType;
+    /** Whether to automatically sign 7702 authorization if not delegated. Defaults to true. */
+    autoDelegate?: boolean;
+    /** The batch of calls to execute. */
+    calls: SponsoredTransactionCall[];
+    /** How long the signed intent remains valid, in seconds. Defaults to 600 (10 minutes). */
+    validForSeconds?: number;
+};
+/**
+ * Signs a sponsored transaction as an EIP-712 `AuthorizedExecutions` intent.
+ *
+ * Orchestrates the full signing flow: resolves the (optional) EIP-7702
+ * authorization, generates a bitmap nonce, fetches the relay address for
+ * the target chain, and signs the typed-data payload with the wallet client
+ * provided in `deps`.
+ */
+export declare const signSponsoredTransaction: ({ authorization, autoDelegate, calls, validForSeconds, }: SignSponsoredTransactionParams, deps: EvmGaslessChainDeps) => Promise<SignedSponsoredTransaction>;
+export {};

package/src/lib/signSponsoredTransaction/signSponsoredTransaction.js

@@ -0,0 +1,57 @@
+'use client'
+import { DELEGATION_CONTRACT_ADDRESS, BATCH_CALL_OPDATA_AUTH_MODE, AUTHORIZED_EXECUTIONS_TYPES, DEFAULT_VALID_FOR_SECONDS } from '../constants.js';
+import { generateIntentNonce } from '../generateIntentNonce/generateIntentNonce.js';
+import { getAvailableEvmGaslessRelayer } from '../getAvailableEvmGaslessRelayer/getAvailableEvmGaslessRelayer.js';
+import { resolveAuthorization } from '../resolveAuthorization/resolveAuthorization.js';
+import { toSerializedAuthorization } from '../toSerializedAuthorization/toSerializedAuthorization.js';
+
+/**
+ * Signs a sponsored transaction as an EIP-712 `AuthorizedExecutions` intent.
+ *
+ * Orchestrates the full signing flow: resolves the (optional) EIP-7702
+ * authorization, generates a bitmap nonce, fetches the relay address for
+ * the target chain, and signs the typed-data payload with the wallet client
+ * provided in `deps`.
+ */
+const signSponsoredTransaction = async ({ authorization, autoDelegate = true, calls, validForSeconds = DEFAULT_VALID_FOR_SECONDS, }, deps) => {
+    const { chainId, walletClient } = deps;
+    const walletAddress = walletClient.account.address;
+    const resolvedAuthorization = await resolveAuthorization({ authorization, autoDelegate, walletAddress }, deps);
+    const nonce = await generateIntentNonce({ walletAddress }, deps);
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + validForSeconds);
+    const { relayerAddress } = await getAvailableEvmGaslessRelayer({ chainId }, deps);
+    const signature = await walletClient.signTypedData({
+        account: walletClient.account,
+        domain: {
+            chainId,
+            verifyingContract: DELEGATION_CONTRACT_ADDRESS,
+        },
+        message: {
+            calls: calls.map((c) => ({
+                data: c.data,
+                target: c.target,
+                value: c.value,
+            })),
+            deadline,
+            mode: BATCH_CALL_OPDATA_AUTH_MODE,
+            nonce,
+            relayer: relayerAddress,
+        },
+        primaryType: 'AuthorizedExecutions',
+        types: AUTHORIZED_EXECUTIONS_TYPES,
+    });
+    return {
+        authorization: resolvedAuthorization
+            ? toSerializedAuthorization(resolvedAuthorization)
+            : undefined,
+        calls,
+        chainId,
+        deadline: deadline.toString(),
+        nonce: nonce.toString(),
+        relayer: relayerAddress,
+        signature: signature,
+        walletAddress,
+    };
+};
+
+export { signSponsoredTransaction };

package/src/lib/toSerializedAuthorization/toSerializedAuthorization.cjs

@@ -0,0 +1,28 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Converts a viem `SignAuthorizationReturnType` into a plain serializable
+ * object suitable for JSON transport to the sponsorship API.
+ *
+ * viem's `Signature` type allows legacy v-only signatures without `yParity`,
+ * but our signing flow always produces one — explicitly check for `undefined`
+ * (not falsiness) so the valid `yParity: 0` recovery bit isn't rejected.
+ */
+const toSerializedAuthorization = (auth) => {
+    if (auth.yParity === undefined) {
+        throw new Error('Signed authorization is missing yParity');
+    }
+    return {
+        address: auth.address,
+        chainId: auth.chainId,
+        nonce: auth.nonce,
+        r: auth.r,
+        s: auth.s,
+        yParity: auth.yParity,
+    };
+};
+
+exports.toSerializedAuthorization = toSerializedAuthorization;

package/src/lib/toSerializedAuthorization/toSerializedAuthorization.d.ts

@@ -0,0 +1,11 @@
+import type { SignAuthorizationReturnType } from 'viem/accounts';
+import type { SerializedAuthorization } from '../types';
+/**
+ * Converts a viem `SignAuthorizationReturnType` into a plain serializable
+ * object suitable for JSON transport to the sponsorship API.
+ *
+ * viem's `Signature` type allows legacy v-only signatures without `yParity`,
+ * but our signing flow always produces one — explicitly check for `undefined`
+ * (not falsiness) so the valid `yParity: 0` recovery bit isn't rejected.
+ */
+export declare const toSerializedAuthorization: (auth: SignAuthorizationReturnType) => SerializedAuthorization;

package/src/lib/toSerializedAuthorization/toSerializedAuthorization.js

@@ -0,0 +1,24 @@
+'use client'
+/**
+ * Converts a viem `SignAuthorizationReturnType` into a plain serializable
+ * object suitable for JSON transport to the sponsorship API.
+ *
+ * viem's `Signature` type allows legacy v-only signatures without `yParity`,
+ * but our signing flow always produces one — explicitly check for `undefined`
+ * (not falsiness) so the valid `yParity: 0` recovery bit isn't rejected.
+ */
+const toSerializedAuthorization = (auth) => {
+    if (auth.yParity === undefined) {
+        throw new Error('Signed authorization is missing yParity');
+    }
+    return {
+        address: auth.address,
+        chainId: auth.chainId,
+        nonce: auth.nonce,
+        r: auth.r,
+        s: auth.s,
+        yParity: auth.yParity,
+    };
+};
+
+export { toSerializedAuthorization };

package/src/lib/types.d.ts

@@ -0,0 +1,83 @@
+import type { Account, Chain, Hex, PublicClient, Transport, WalletClient } from 'viem';
+import type { SDKApi } from '@dynamic-labs/sdk-api-core';
+/**
+ * An EIP-712 sponsored-transaction call: a single (target, value, data) tuple
+ * batched together with other calls inside one sponsored intent.
+ */
+export type SponsoredTransactionCall = {
+    data: Hex;
+    target: Hex;
+    value: bigint;
+};
+/**
+ * Plain-object form of a viem signed EIP-7702 authorization, suitable for
+ * JSON transport to the sponsorship API.
+ */
+export type SerializedAuthorization = {
+    address: Hex;
+    chainId: number;
+    nonce: number;
+    r: Hex;
+    s: Hex;
+    yParity: number;
+};
+/**
+ * Lifecycle states reported by the relay for a sponsored transaction.
+ */
+export type SponsoredTransactionStatus = 'failure' | 'pending' | 'submitted' | 'success';
+/**
+ * Full status payload returned by `getEVMSponsoredTransactionStatus`.
+ */
+export type SponsoredTransactionStatusResult = {
+    errorMessage?: string;
+    status: SponsoredTransactionStatus;
+    transactionHash?: Hex;
+};
+/**
+ * A signed sponsored-transaction payload ready to be relayed.
+ */
+export type SignedSponsoredTransaction = {
+    authorization?: SerializedAuthorization;
+    calls: SponsoredTransactionCall[];
+    chainId: number;
+    deadline: string;
+    nonce: string;
+    relayer: Hex;
+    signature: Hex;
+    walletAddress: Hex;
+};
+/**
+ * In-memory cache of "this wallet on this chain has active 7702 delegation",
+ * scoped to the host (controller / extension) instance. Only positive
+ * delegations are cached — a missing entry means the status is unknown and
+ * should be resolved via RPC.
+ */
+export type Delegation7702Registry = {
+    isDelegated: (params: {
+        chainId: number;
+        walletAddress: string;
+    }) => boolean;
+    markDelegated: (params: {
+        chainId: number;
+        walletAddress: string;
+    }) => void;
+};
+/**
+ * Dependencies needed by gasless API-only functions (relay, status, relayer
+ * lookup, sponsorship-enabled).
+ */
+export type EvmGaslessApiDeps = {
+    environmentId: string;
+    sdkApi: SDKApi;
+};
+/**
+ * Dependencies needed by gasless signing flows. Includes the API deps plus a
+ * viem `WalletClient` for signing, a viem `PublicClient` for read RPC, the
+ * chain ID being signed against, and the host-wide delegation registry.
+ */
+export type EvmGaslessChainDeps = EvmGaslessApiDeps & {
+    chainId: number;
+    delegationRegistry: Delegation7702Registry;
+    publicClient: PublicClient<Transport, Chain>;
+    walletClient: WalletClient<Transport, Chain, Account>;
+};

package/src/lib/waitForSponsoredTransaction/waitForSponsoredTransaction.cjs

@@ -0,0 +1,38 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var SponsorTransactionError = require('../errors/SponsorTransactionError/SponsorTransactionError.cjs');
+var getEVMSponsoredTransactionStatus = require('../getEVMSponsoredTransactionStatus/getEVMSponsoredTransactionStatus.cjs');
+
+const POLL_INTERVAL_MS = 2000;
+const TIMEOUT_MS = 60000;
+const MAX_POLLING_ATTEMPTS = TIMEOUT_MS / POLL_INTERVAL_MS;
+const TERMINAL_FAILURE_STATUSES = new Set([
+    'failure',
+]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Polls `getEVMSponsoredTransactionStatus` until the relay reports the
+ * transaction has been included on-chain, then returns the transaction hash.
+ *
+ * Throws if the relay returns a terminal failure or if polling times out.
+ */
+const waitForSponsoredTransaction = async ({ requestId }, deps) => {
+    for (let attempt = 0; attempt < MAX_POLLING_ATTEMPTS; attempt++) {
+        const result = await getEVMSponsoredTransactionStatus.getEVMSponsoredTransactionStatus({ requestId }, deps);
+        if (TERMINAL_FAILURE_STATUSES.has(result.status)) {
+            throw new SponsorTransactionError.SponsorTransactionError(null, result.errorMessage);
+        }
+        if (result.transactionHash) {
+            return { transactionHash: result.transactionHash };
+        }
+        if (attempt < MAX_POLLING_ATTEMPTS - 1) {
+            await sleep(POLL_INTERVAL_MS);
+        }
+    }
+    throw new SponsorTransactionError.SponsorTransactionError(null, `Timed out waiting for sponsored transaction ${requestId}`);
+};
+
+exports.waitForSponsoredTransaction = waitForSponsoredTransaction;

package/src/lib/waitForSponsoredTransaction/waitForSponsoredTransaction.d.ts

@@ -0,0 +1,16 @@
+import type { Hex } from 'viem';
+import type { EvmGaslessApiDeps } from '../types';
+type WaitForSponsoredTransactionParams = {
+    /** The request ID returned by `relaySponsoredTransaction` / `sendSponsoredTransaction`. */
+    requestId: string;
+};
+/**
+ * Polls `getEVMSponsoredTransactionStatus` until the relay reports the
+ * transaction has been included on-chain, then returns the transaction hash.
+ *
+ * Throws if the relay returns a terminal failure or if polling times out.
+ */
+export declare const waitForSponsoredTransaction: ({ requestId }: WaitForSponsoredTransactionParams, deps: EvmGaslessApiDeps) => Promise<{
+    transactionHash: Hex;
+}>;
+export {};

package/src/lib/waitForSponsoredTransaction/waitForSponsoredTransaction.js

@@ -0,0 +1,34 @@
+'use client'
+import { SponsorTransactionError } from '../errors/SponsorTransactionError/SponsorTransactionError.js';
+import { getEVMSponsoredTransactionStatus } from '../getEVMSponsoredTransactionStatus/getEVMSponsoredTransactionStatus.js';
+
+const POLL_INTERVAL_MS = 2000;
+const TIMEOUT_MS = 60000;
+const MAX_POLLING_ATTEMPTS = TIMEOUT_MS / POLL_INTERVAL_MS;
+const TERMINAL_FAILURE_STATUSES = new Set([
+    'failure',
+]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Polls `getEVMSponsoredTransactionStatus` until the relay reports the
+ * transaction has been included on-chain, then returns the transaction hash.
+ *
+ * Throws if the relay returns a terminal failure or if polling times out.
+ */
+const waitForSponsoredTransaction = async ({ requestId }, deps) => {
+    for (let attempt = 0; attempt < MAX_POLLING_ATTEMPTS; attempt++) {
+        const result = await getEVMSponsoredTransactionStatus({ requestId }, deps);
+        if (TERMINAL_FAILURE_STATUSES.has(result.status)) {
+            throw new SponsorTransactionError(null, result.errorMessage);
+        }
+        if (result.transactionHash) {
+            return { transactionHash: result.transactionHash };
+        }
+        if (attempt < MAX_POLLING_ATTEMPTS - 1) {
+            await sleep(POLL_INTERVAL_MS);
+        }
+    }
+    throw new SponsorTransactionError(null, `Timed out waiting for sponsored transaction ${requestId}`);
+};
+
+export { waitForSponsoredTransaction };