@t402/wdk-gasless 1.0.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,409 @@
+import { PublicClient, Address, Hex } from 'viem';
+import { SmartAccountSigner, BundlerConfig, PaymasterConfig } from '@t402/evm';
+export { BundlerConfig, PaymasterConfig, SmartAccountSigner, UserOperationReceipt } from '@t402/evm';
+
+/**
+ * WDK Gasless Types
+ *
+ * Type definitions for gasless payments using Tether WDK and ERC-4337.
+ */
+
+/**
+ * WDK account interface (compatible with @tetherto/wdk)
+ */
+interface WdkAccount {
+    /** Get the account's address */
+    getAddress(): Promise<string>;
+    /** Get the account's native balance */
+    getBalance(): Promise<bigint>;
+    /** Get the account's token balance */
+    getTokenBalance(tokenAddress: string): Promise<bigint>;
+    /** Sign a message */
+    signMessage(message: string): Promise<string>;
+    /** Sign typed data (EIP-712) */
+    signTypedData(params: {
+        domain: {
+            name?: string;
+            version?: string;
+            chainId?: number;
+            verifyingContract?: string;
+        };
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<string>;
+    /** Send a transaction */
+    sendTransaction(params: {
+        to: string;
+        value?: bigint;
+        data?: string;
+    }): Promise<string>;
+}
+/**
+ * WDK instance interface
+ */
+interface WdkInstance {
+    /** Get accounts */
+    getAccounts(): WdkAccount[];
+    /** Get account by index */
+    getAccount(index: number): WdkAccount;
+}
+/**
+ * Configuration for WDK smart account
+ */
+interface WdkSmartAccountConfig {
+    /** WDK account to use as the signer */
+    wdkAccount: WdkAccount;
+    /** Public client for chain interactions */
+    publicClient: PublicClient;
+    /** Chain ID */
+    chainId: number;
+    /** Additional owners for multi-sig (optional) */
+    additionalOwners?: Address[];
+    /** Threshold for multi-sig (defaults to 1) */
+    threshold?: number;
+    /** Salt nonce for address generation (defaults to 0) */
+    saltNonce?: bigint;
+}
+/**
+ * Configuration for WDK gasless client
+ */
+interface WdkGaslessClientConfig {
+    /** WDK smart account signer */
+    signer: SmartAccountSigner;
+    /** Bundler configuration */
+    bundler: BundlerConfig;
+    /** Paymaster configuration for gas sponsorship */
+    paymaster?: PaymasterConfig;
+    /** Chain ID */
+    chainId: number;
+    /** Public client */
+    publicClient: PublicClient;
+}
+/**
+ * Parameters for a gasless payment
+ */
+interface GaslessPaymentParams {
+    /** Recipient address */
+    to: Address;
+    /** Amount to send (in token decimals, e.g., 1000000 for 1 USDT) */
+    amount: bigint;
+    /** Token to send (defaults to USDT0) */
+    token?: "USDT0" | "USDC" | Address;
+}
+/**
+ * Parameters for a batch payment
+ */
+interface BatchPaymentParams {
+    /** List of payments to execute */
+    payments: Array<{
+        /** Recipient address */
+        to: Address;
+        /** Amount to send */
+        amount: bigint;
+        /** Token to send (defaults to USDT0) */
+        token?: "USDT0" | "USDC" | Address;
+    }>;
+}
+/**
+ * Result of a gasless payment
+ */
+interface GaslessPaymentResult {
+    /** UserOperation hash */
+    userOpHash: Hex;
+    /** Smart account address */
+    sender: Address;
+    /** Whether the payment was sponsored (free gas) */
+    sponsored: boolean;
+    /** Wait for the operation to be included */
+    wait(): Promise<GaslessPaymentReceipt>;
+}
+/**
+ * Receipt of a gasless payment
+ */
+interface GaslessPaymentReceipt {
+    /** UserOperation hash */
+    userOpHash: Hex;
+    /** Transaction hash (on-chain) */
+    txHash: Hex;
+    /** Block number */
+    blockNumber: bigint;
+    /** Whether the payment succeeded */
+    success: boolean;
+    /** Gas used (in native token) */
+    gasUsed: bigint;
+    /** Gas cost (in native token wei) */
+    gasCost: bigint;
+    /** Revert reason if failed */
+    reason?: string;
+}
+/**
+ * Sponsorship check result
+ */
+interface SponsorshipInfo {
+    /** Whether the payment can be sponsored */
+    canSponsor: boolean;
+    /** Reason if cannot sponsor */
+    reason?: string;
+    /** Maximum amount that can be sponsored (if applicable) */
+    maxAmount?: bigint;
+    /** Estimated gas cost if not sponsored */
+    estimatedGasCost?: bigint;
+}
+
+/**
+ * WDK Gasless Client
+ *
+ * High-level client for executing gasless USDT0 payments using
+ * Tether WDK accounts and ERC-4337 Account Abstraction.
+ */
+
+/**
+ * WDK Gasless Client
+ *
+ * Provides a simple API for executing gasless USDT0 payments using
+ * WDK accounts and ERC-4337 smart accounts.
+ */
+declare class WdkGaslessClient {
+    private readonly signer;
+    private readonly builder;
+    private readonly bundler;
+    private readonly paymaster?;
+    private readonly chainId;
+    private readonly publicClient;
+    private readonly chainName;
+    constructor(config: WdkGaslessClientConfig);
+    /**
+     * Execute a gasless payment
+     *
+     * Sends USDT0 (or other tokens) without the user paying gas fees.
+     * Gas is sponsored by a paymaster if configured.
+     */
+    pay(params: GaslessPaymentParams): Promise<GaslessPaymentResult>;
+    /**
+     * Execute multiple payments in a single transaction
+     *
+     * More gas efficient than individual payments.
+     * All payments are executed atomically.
+     */
+    payBatch(params: BatchPaymentParams): Promise<GaslessPaymentResult>;
+    /**
+     * Check if a payment can be sponsored (free gas)
+     */
+    canSponsor(params: GaslessPaymentParams): Promise<SponsorshipInfo>;
+    /**
+     * Get the smart account address
+     */
+    getAccountAddress(): Promise<Address>;
+    /**
+     * Check if the smart account is deployed
+     */
+    isAccountDeployed(): Promise<boolean>;
+    /**
+     * Get the token balance of the smart account
+     */
+    getBalance(token?: "USDT0" | "USDC" | Address): Promise<bigint>;
+    /**
+     * Get the formatted token balance
+     */
+    getFormattedBalance(token?: "USDT0" | "USDC" | Address, decimals?: number): Promise<string>;
+    /**
+     * Estimate gas for a single transaction
+     */
+    private estimateGas;
+    /**
+     * Estimate gas for a batch transaction
+     */
+    private estimateBatchGas;
+    /**
+     * Get paymaster data if configured
+     */
+    private getPaymasterData;
+}
+/**
+ * Configuration for creating a WDK gasless client
+ */
+interface CreateWdkGaslessClientConfig {
+    /** WDK account to use as the signer */
+    wdkAccount: WdkAccount;
+    /** Public client for chain interactions */
+    publicClient: PublicClient;
+    /** Chain ID */
+    chainId: number;
+    /** Bundler configuration */
+    bundler: BundlerConfig;
+    /** Optional paymaster for gas sponsorship */
+    paymaster?: PaymasterConfig;
+    /** Salt nonce for address generation (defaults to 0) */
+    saltNonce?: bigint;
+}
+/**
+ * Create a WDK gasless client
+ *
+ * This is the main entry point for using WDK with gasless payments.
+ *
+ * @example
+ * ```typescript
+ * import { createWdkGaslessClient } from '@t402/wdk-gasless';
+ *
+ * const client = await createWdkGaslessClient({
+ *   wdkAccount: myWdkAccount,
+ *   publicClient,
+ *   chainId: 42161, // Arbitrum
+ *   bundler: {
+ *     bundlerUrl: 'https://api.pimlico.io/v2/arbitrum/rpc?apikey=...',
+ *     chainId: 42161,
+ *   },
+ *   paymaster: {
+ *     address: '0x...',
+ *     url: 'https://api.pimlico.io/v2/arbitrum/rpc?apikey=...',
+ *     type: 'sponsoring',
+ *   },
+ * });
+ *
+ * // Execute gasless payment
+ * const result = await client.pay({
+ *   to: '0x...',
+ *   amount: 1000000n, // 1 USDT0
+ * });
+ *
+ * const receipt = await result.wait();
+ * console.log('Payment confirmed:', receipt.txHash);
+ * ```
+ */
+declare function createWdkGaslessClient(config: CreateWdkGaslessClientConfig): Promise<WdkGaslessClient>;
+
+/**
+ * WDK Smart Account
+ *
+ * Wraps a Tether WDK account to work with ERC-4337 smart accounts.
+ * Creates a Safe smart account with the WDK account as the owner/signer.
+ */
+
+/**
+ * Safe 4337 module addresses (v0.3.0)
+ * Deployed on all major EVM chains at the same addresses
+ */
+declare const SAFE_4337_ADDRESSES: {
+    /** Safe 4337 Module */
+    readonly module: Address;
+    /** Safe Module Setup */
+    readonly moduleSetup: Address;
+    /** Safe Singleton */
+    readonly singleton: Address;
+    /** Safe Proxy Factory */
+    readonly proxyFactory: Address;
+    /** Safe Fallback Handler */
+    readonly fallbackHandler: Address;
+    /** Add Modules Lib */
+    readonly addModulesLib: Address;
+};
+/**
+ * WDK Smart Account
+ *
+ * Creates a Safe smart account using a WDK account as the owner/signer.
+ * Implements SmartAccountSigner for ERC-4337 compatibility.
+ */
+declare class WdkSmartAccount implements SmartAccountSigner {
+    private readonly wdkAccount;
+    private readonly publicClient;
+    private readonly chainId;
+    private readonly owners;
+    private readonly threshold;
+    private readonly saltNonce;
+    private cachedAddress?;
+    private cachedInitCode?;
+    private cachedOwnerAddress?;
+    private deploymentChecked;
+    private isAccountDeployed;
+    constructor(config: WdkSmartAccountConfig);
+    /**
+     * Initialize the account (fetch WDK address)
+     * Call this before using the account
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the WDK account's EOA address
+     */
+    getOwnerAddress(): Promise<Address>;
+    /**
+     * Get the smart account address (counterfactual)
+     */
+    getAddress(): Promise<Address>;
+    /**
+     * Sign a UserOperation hash using the WDK account
+     */
+    signUserOpHash(userOpHash: Hex): Promise<Hex>;
+    /**
+     * Get the account's init code for deployment
+     */
+    getInitCode(): Promise<Hex>;
+    /**
+     * Check if the account is deployed
+     */
+    isDeployed(): Promise<boolean>;
+    /**
+     * Encode a call to the account's execute function
+     */
+    encodeExecute(target: Address, value: bigint, data: Hex): Hex;
+    /**
+     * Encode a batch call to the account's executeBatch function
+     */
+    encodeExecuteBatch(targets: Address[], values: bigint[], datas: Hex[]): Hex;
+    /**
+     * Build the Safe setup initializer data
+     */
+    private buildInitializer;
+    /**
+     * Get the Safe's owners
+     */
+    getOwners(): Address[];
+    /**
+     * Get the Safe's threshold
+     */
+    getThreshold(): number;
+    /**
+     * Clear cached values (useful after deployment)
+     */
+    clearCache(): void;
+}
+/**
+ * Create a WDK smart account
+ */
+declare function createWdkSmartAccount(config: WdkSmartAccountConfig): Promise<WdkSmartAccount>;
+
+/**
+ * WDK Gasless Constants
+ *
+ * Addresses and configuration for gasless USDT0 payments.
+ */
+
+/**
+ * USDT0 OFT addresses by chain
+ */
+declare const USDT0_ADDRESSES: Record<string, Address>;
+/**
+ * USDC addresses by chain
+ */
+declare const USDC_ADDRESSES: Record<string, Address>;
+/**
+ * Chain IDs for supported networks
+ */
+declare const CHAIN_IDS: Record<string, number>;
+/**
+ * Default bundler URLs by chain (using public endpoints)
+ */
+declare const DEFAULT_BUNDLER_URLS: Record<number, string>;
+/**
+ * Get token address for a chain
+ */
+declare function getTokenAddress(token: "USDT0" | "USDC" | Address, chainName: string): Address;
+/**
+ * Get chain name from chain ID
+ */
+declare function getChainName(chainId: number): string;
+
+export { type BatchPaymentParams, CHAIN_IDS, type CreateWdkGaslessClientConfig, DEFAULT_BUNDLER_URLS, type GaslessPaymentParams, type GaslessPaymentReceipt, type GaslessPaymentResult, SAFE_4337_ADDRESSES, type SponsorshipInfo, USDC_ADDRESSES, USDT0_ADDRESSES, type WdkAccount, WdkGaslessClient, type WdkGaslessClientConfig, type WdkInstance, WdkSmartAccount, type WdkSmartAccountConfig, createWdkGaslessClient, createWdkSmartAccount, getChainName, getTokenAddress };