@introspectivelabs/x402-evm 0.0.1

package/dist/esm/userOperation-B2UUp3K6.d.mts

@@ -0,0 +1,409 @@
+import { PublicClient, Transport, Chain, Hex } from 'viem';
+import { SmartAccount } from 'viem/account-abstraction';
+import { U as UserOperation07Json } from './types-Dk5U6Xnw.mjs';
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayload } from '@x402/core/types';
+
+/**
+ * Configuration for bundler client operations
+ */
+interface BundlerClientConfig {
+    /**
+     * Timeout for operations in milliseconds
+     *
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Number of retries for failed operations
+     *
+     * @default 0
+     */
+    retries?: number;
+}
+/**
+ * Gas estimation result from bundler
+ */
+interface GasEstimate {
+    [key: string]: unknown;
+    callGasLimit?: string;
+    verificationGasLimit?: string;
+    preVerificationGas?: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    paymasterVerificationGasLimit?: string;
+    paymasterPostOpGasLimit?: string;
+}
+/**
+ * Prepared user operation (unsigned)
+ * This matches the format returned by viem's prepareUserOperation,
+ * which uses bigint for numeric values.
+ */
+interface PreparedUserOperation {
+    [key: string]: unknown;
+    sender: `0x${string}`;
+    nonce: bigint;
+    callData: `0x${string}`;
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    paymaster?: `0x${string}`;
+    paymasterData?: `0x${string}`;
+    paymasterVerificationGasLimit?: bigint;
+    paymasterPostOpGasLimit?: bigint;
+    signature?: `0x${string}`;
+}
+/**
+ * Call configuration for preparing user operations
+ */
+interface UserOperationCall {
+    /**
+     * Target contract address
+     */
+    to: `0x${string}`;
+    /**
+     * Value to send (in wei, for native ETH transfers)
+     */
+    value: bigint;
+    /**
+     * Call data (encoded function call)
+     */
+    data: `0x${string}`;
+}
+/**
+ * Abstract interface for bundler client operations.
+ * This allows different implementations (viem, custom, etc.)
+ */
+interface BundlerClient {
+    /**
+     * Prepares an unsigned user operation for the given calls.
+     * This method should estimate gas and populate all required fields.
+     *
+     * @param calls - Array of calls to execute in the user operation
+     * @param entryPoint - The entry point address
+     * @returns Promise resolving to a prepared (unsigned) user operation
+     */
+    prepareUserOperation(calls: UserOperationCall[], entryPoint: `0x${string}`): Promise<PreparedUserOperation>;
+    /**
+     * Estimates gas for a user operation.
+     *
+     * @param userOp - The user operation to estimate gas for
+     * @param entryPoint - The entry point address
+     * @returns Promise resolving to gas estimates
+     */
+    estimateGas(userOp: UserOperation07Json, entryPoint: `0x${string}`): Promise<GasEstimate>;
+    /**
+     * Sends a user operation to the bundler.
+     *
+     * @param userOp - The signed user operation to send
+     * @param entryPoint - The entry point address
+     * @returns Promise resolving to the user operation hash
+     */
+    sendUserOperation(userOp: UserOperation07Json, entryPoint: `0x${string}`): Promise<string>;
+}
+
+/**
+ * Configuration for creating a viem-based bundler client
+ */
+interface ViemBundlerClientConfig extends BundlerClientConfig {
+    /**
+     * Viem public client for blockchain interactions
+     */
+    publicClient: PublicClient<Transport, Chain>;
+    /**
+     * Smart account for user operation preparation (must be a SmartAccount, not a regular Account)
+     */
+    account: SmartAccount;
+    /**
+     * Chain configuration
+     */
+    chain: Chain;
+    /**
+     * Bundler RPC URL
+     */
+    bundlerUrl: string;
+}
+/**
+ * Viem-based implementation of BundlerClient.
+ * Uses viem's account-abstraction utilities for user operation handling.
+ */
+declare class ViemBundlerClient implements BundlerClient {
+    private readonly bundlerClient;
+    private readonly account;
+    private readonly entryPoint;
+    /**
+     * Creates a new ViemBundlerClient instance.
+     *
+     * @param config - Configuration for the bundler client
+     */
+    constructor(config: ViemBundlerClientConfig);
+    /**
+     * Prepares an unsigned user operation for the given calls.
+     *
+     * @param calls - Array of calls to execute in the user operation
+     * @param _entryPoint - The entry point address (unused, viem uses the configured entry point)
+     * @returns Promise resolving to a prepared (unsigned) user operation
+     */
+    prepareUserOperation(calls: UserOperationCall[], _entryPoint: `0x${string}`): Promise<PreparedUserOperation>;
+    /**
+     * Estimates gas for a user operation.
+     * Note: This is typically done as part of prepareUserOperation,
+     * but is available as a separate method for flexibility.
+     *
+     * @param _userOp - The user operation to estimate gas for
+     * @param _entryPoint - The entry point address
+     * @returns Promise resolving to gas estimates
+     */
+    estimateGas(_userOp: UserOperation07Json, _entryPoint: `0x${string}`): Promise<GasEstimate>;
+    /**
+     * Sends a user operation to the bundler.
+     *
+     * @param userOp - The signed user operation to send
+     * @param _entryPoint - The entry point address (unused, viem uses the configured entry point)
+     * @returns Promise resolving to the user operation hash
+     */
+    sendUserOperation(userOp: UserOperation07Json, _entryPoint: `0x${string}`): Promise<string>;
+}
+
+/**
+ * Abstract interface for signing user operations.
+ * This allows different signer implementations (Safe, EOA, etc.)
+ */
+interface UserOperationSigner {
+    /**
+     * The address of the signer
+     */
+    readonly address: `0x${string}`;
+    /**
+     * Signs a prepared (unsigned) user operation.
+     *
+     * @param userOp - The prepared user operation to sign
+     * @returns Promise resolving to the signature
+     */
+    signUserOperation(userOp: PreparedUserOperation): Promise<`0x${string}`>;
+}
+
+/**
+ * Base configuration properties shared by all configuration variants
+ */
+interface ExactEvmSchemeERC4337ConfigBase {
+    /**
+     * Entry point address (EntryPoint v0.7)
+     * Optional - can be provided in payment requirements if not set here
+     */
+    entrypoint?: Hex;
+    /**
+     * Bundler URL (optional, can be provided in payment requirements)
+     */
+    bundlerUrl?: string;
+}
+/**
+ * Configuration variant when bundlerClient is explicitly provided.
+ * Account and publicClient are NOT needed when bundlerClient is used.
+ * Signer is required when using bundlerClient.
+ */
+type ExactEvmSchemeERC4337ConfigWithBundler = ExactEvmSchemeERC4337ConfigBase & {
+    /**
+     * Bundler client for preparing and sending user operations.
+     */
+    bundlerClient: BundlerClient;
+    /**
+     * Signer for signing user operations (required when bundlerClient is provided).
+     */
+    signer: UserOperationSigner;
+} & {
+    /**
+     * Account must not be provided when bundlerClient is used.
+     * Using `never` type prevents this property from being set.
+     */
+    account?: never;
+    /**
+     * Public client must not be provided when bundlerClient is used.
+     * The bundlerClient already has its own publicClient configured.
+     */
+    publicClient?: never;
+};
+/**
+ * Configuration variant when bundlerClient is not provided.
+ * Account is required for dynamic bundlerClient creation.
+ * Signer is optional - will be auto-created from account if not provided.
+ * PublicClient is optional - will create a default from network if not provided.
+ */
+type ExactEvmSchemeERC4337ConfigWithAccount = ExactEvmSchemeERC4337ConfigBase & {
+    /**
+     * Bundler client is not provided - will be created dynamically from PaymentRequirements.
+     * Using `never` type prevents this property from being set.
+     */
+    bundlerClient?: never;
+} & {
+    /**
+     * Smart account for user operation preparation.
+     * Required when bundlerClient is not provided.
+     */
+    account: SmartAccount;
+    /**
+     * Signer for signing user operations.
+     * Optional - will be auto-created from account using SafeAccountSigner if not provided.
+     * The account must support signUserOperation method for auto-creation to work.
+     */
+    signer?: UserOperationSigner;
+    /**
+     * Public client for blockchain interactions.
+     * Optional - will create a default from network if not provided.
+     */
+    publicClient?: PublicClient<Transport, Chain>;
+};
+/**
+ * Configuration for the ERC-4337 client scheme.
+ *
+ * This is a discriminated union that enforces type-safe combinations:
+ * - Either `bundlerClient` is provided (account and publicClient must NOT be provided)
+ * - Or `account` is provided when bundlerClient is not (for dynamic creation, publicClient optional)
+ *
+ * @example
+ * ```typescript
+ * // Minimal config (just account - signer auto-created)
+ * const scheme1 = new ExactEvmSchemeERC4337({
+ *   account: myAccount,
+ *   // signer will be auto-created from account
+ *   // bundlerClient will be created dynamically from PaymentRequirements
+ * });
+ *
+ * // With account and custom signer
+ * const scheme2 = new ExactEvmSchemeERC4337({
+ *   account: myAccount,
+ *   signer: myCustomSigner,
+ *   publicClient: myPublicClient, // Optional
+ * });
+ *
+ * // With explicit bundlerClient (backward compatible)
+ * const scheme3 = new ExactEvmSchemeERC4337({
+ *   bundlerClient: myBundlerClient,
+ *   signer: mySigner, // Required when bundlerClient is provided
+ *   // account and publicClient must NOT be provided (bundlerClient has its own)
+ * });
+ * ```
+ */
+type ExactEvmSchemeERC4337Config = ExactEvmSchemeERC4337ConfigWithBundler | ExactEvmSchemeERC4337ConfigWithAccount;
+/**
+ * EVM client implementation for the Exact payment scheme using ERC-4337 UserOperations.
+ *
+ * This implementation creates payment payloads by building and signing UserOperations
+ * that execute ERC20 transfers. The UserOperations are prepared using a bundler client
+ * and signed using a user operation signer (e.g., Safe account, EOA).
+ *
+ * Supports minimal configuration: when bundlerClient is not provided and
+ * PaymentRequirements.extra.userOperation.supported is true, a ViemBundlerClient
+ * will be created dynamically from the payment requirements.
+ *
+ * @example
+ * ```typescript
+ * // Minimal config (just account - signer and bundlerClient auto-created)
+ * import { ExactEvmSchemeERC4337 } from '@introspectivelabs/x402-evm/exact/client';
+ * import { x402Client } from '@x402/core/client';
+ *
+ * const scheme = new ExactEvmSchemeERC4337({
+ *   account: safeAccount,  // SmartAccount - signer will be auto-created
+ * });
+ *
+ * // With custom signer
+ * const scheme2 = new ExactEvmSchemeERC4337({
+ *   account: safeAccount,
+ *   signer: customSigner,  // Optional - overrides auto-creation
+ * });
+ *
+ * // Explicit config (backward compatible)
+ * import { ViemBundlerClient } from '@introspectivelabs/x402-evm/exact/client/bundler';
+ *
+ * const bundlerClient = new ViemBundlerClient({
+ *   publicClient,
+ *   account,
+ *   chain,
+ *   bundlerUrl: 'https://bundler.example.com',
+ * });
+ *
+ * const scheme3 = new ExactEvmSchemeERC4337({
+ *   bundlerClient,
+ *   signer: account,  // Required when bundlerClient is provided
+ * });
+ *
+ * const client = new x402Client();
+ * client.register('eip155:84532', scheme);
+ * ```
+ */
+declare class ExactEvmSchemeERC4337 implements SchemeNetworkClient {
+    readonly scheme = "exact";
+    private readonly bundlerClient?;
+    private readonly account?;
+    private readonly publicClient?;
+    private readonly signer;
+    private readonly entrypoint?;
+    private readonly bundlerUrl?;
+    /**
+     * Creates a new ExactEvmSchemeERC4337 instance.
+     *
+     * @param config - Configuration for the scheme (type-safe: either bundlerClient or account must be provided)
+     * @throws Error if bundlerClient is not provided and account is also not provided (runtime safety check)
+     * @throws Error if signer is not provided and account doesn't support signUserOperation
+     */
+    constructor(config: ExactEvmSchemeERC4337Config);
+    /**
+     * Creates a payment payload for the Exact scheme using ERC-4337 UserOperations.
+     *
+     * This method:
+     * 1. Extracts user operation capability from payment requirements
+     * 2. Creates bundlerClient dynamically if not provided (when userOperation.supported is true)
+     * 3. Builds ERC20 transfer call data
+     * 4. Prepares the user operation using the bundler client
+     * 5. Signs the user operation
+     * 6. Converts to JSON-RPC format
+     * 7. Returns the x402 payment payload
+     *
+     * @param x402Version - The x402 protocol version
+     * @param paymentRequirements - The payment requirements
+     * @returns Promise resolving to a payment payload
+     * @throws Error if user operation capability is not found or required fields are missing
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, "x402Version" | "payload">>;
+}
+
+/**
+ * Standard ERC20 transfer function ABI
+ */
+declare const ERC20_TRANSFER_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+}];
+/**
+ * Builds ERC20 transfer call data.
+ *
+ * @param token - The ERC20 token contract address
+ * @param to - The recipient address
+ * @param amount - The amount to transfer (in token's smallest unit)
+ * @returns The encoded call data for the transfer function
+ */
+declare function buildERC20TransferCallData(token: `0x${string}`, to: `0x${string}`, amount: bigint): `0x${string}`;
+
+/**
+ * Converts a user operation with bigint values to JSON-RPC compatible format.
+ * This recursively converts all bigint values to hex strings.
+ *
+ * @param userOp - The user operation object (may contain bigints)
+ * @returns The user operation in JSON-RPC format (all bigints converted to hex)
+ */
+declare function userOpToJson(userOp: Record<string, unknown>): UserOperation07Json;
+
+export { type BundlerClient as B, ExactEvmSchemeERC4337 as E, type GasEstimate as G, type PreparedUserOperation as P, type UserOperationSigner as U, ViemBundlerClient as V, type ExactEvmSchemeERC4337Config as a, type BundlerClientConfig as b, type UserOperationCall as c, type ViemBundlerClientConfig as d, buildERC20TransferCallData as e, ERC20_TRANSFER_ABI as f, userOpToJson as u };

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@introspectivelabs/x402-evm",
+  "version": "0.0.1",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "keywords": [
+    "x402",
+    "payment",
+    "protocol",
+    "evm",
+    "ethereum"
+  ],
+  "license": "Apache-2.0",
+  "author": "Introspective Labs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Introspective-Labs/x402-modules.git",
+    "directory": "packages/evm"
+  },
+  "description": "x402 Payment Protocol for Smart Wallets EVM Implementation",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "3.5.2",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.2.6",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.5"
+  },
+  "peerDependencies": {
+    "@x402/core": "2.*",
+    "@x402/evm": "2.*",
+    "viem": "2.*",
+    "zod": "3.*"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.mts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./exact/client": {
+      "import": {
+        "types": "./dist/esm/exact/client/index.d.mts",
+        "default": "./dist/esm/exact/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/client/index.d.ts",
+        "default": "./dist/cjs/exact/client/index.js"
+      }
+    },
+    "./exact/server": {
+      "import": {
+        "types": "./dist/esm/exact/server/index.d.mts",
+        "default": "./dist/esm/exact/server/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/server/index.d.ts",
+        "default": "./dist/cjs/exact/server/index.js"
+      }
+    },
+    "./exact/facilitator": {
+      "import": {
+        "types": "./dist/esm/exact/facilitator/index.d.mts",
+        "default": "./dist/esm/exact/facilitator/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/facilitator/index.d.ts",
+        "default": "./dist/cjs/exact/facilitator/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "tsx --env-file=.env index.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "watch": "tsc --watch",
+    "format": "prettier -c .prettierrc --write \"**/*.{ts,js,cjs,json,md}\"",
+    "format:check": "prettier -c .prettierrc --check \"**/*.{ts,js,cjs,json,md}\"",
+    "lint": "eslint . --ext .ts --fix",
+    "lint:check": "eslint . --ext .ts",
+    "publish:dev": "pnpm dlx yalc publish --push"
+  }
+}