@aastar/dapp 0.16.7

package/dist/paymaster/src/V4/PaymasterClient.d.ts

@@ -0,0 +1,79 @@
+import { type Address, type Hex } from 'viem';
+/**
+ * PaymasterClient
+ * Focus: Integration, Funding, Interaction.
+ */
+export declare class PaymasterClient {
+    /**
+     * Get user's deposited balance on the Paymaster.
+     */
+    static getDepositedBalance(publicClient: any, address: Address, user: Address, token: Address): Promise<bigint>;
+    /**
+     * Deposit tokens to Paymaster for a user (enables gasless transactions).
+     */
+    static depositFor(wallet: any, address: Address, user: Address, token: Address, amount: bigint): Promise<any>;
+    /**
+     * Approve the Paymaster (or any spender) to spend gas tokens.
+     */
+    static approveGasToken(wallet: any, token: Address, spender: Address, amount: bigint): Promise<any>;
+    /**
+     * Estimate Gas for a UserOperation.
+     */
+    static estimateUserOperationGas(client: any, wallet: any, aaAddress: Address, entryPoint: Address, paymasterAddress: Address, token: Address, bundlerUrl: string, callData: `0x${string}`, options?: {
+        validityWindow?: number;
+        operator?: Address;
+        factory?: Address;
+        factoryData?: Hex;
+    }): Promise<{
+        preVerificationGas: bigint;
+        verificationGasLimit: bigint;
+        callGasLimit: bigint;
+        paymasterVerificationGasLimit: bigint | undefined;
+        paymasterPostOpGasLimit: bigint;
+    }>;
+    /**
+     * High-level API to submit a gasless UserOperation.
+     * Automatically handles nonce fetching, gas estimation (if not provided), signing, and submission.
+     */
+    static submitGaslessUserOperation(client: any, wallet: any, aaAddress: Address, entryPoint: Address, paymasterAddress: Address, token: Address, bundlerUrl: string, callData: `0x${string}`, options?: {
+        validityWindow?: number;
+        verificationGasLimit?: bigint;
+        callGasLimit?: bigint;
+        preVerificationGas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+        autoEstimate?: boolean;
+        operator?: Address;
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+        factory?: Address;
+        factoryData?: Hex;
+    }): Promise<`0x${string}`>;
+    /**
+     * Helper to extract the actual Gas Token fee from a UserOperation receipt.
+     * Looks for the 'PostOpProcessed' event emitted by the Paymaster.
+     */
+    static getFeeFromReceipt(receipt: any, paymasterAddress: Address): {
+        tokenCost: bigint;
+        actualGasCostWei: bigint;
+    } | null;
+    /**
+     * Get the fee for a specific transaction hash.
+     * Fetches the receipt (no scanning required) and decodes the log.
+     */
+    static getTransactionFee(publicClient: any, txHash: `0x${string}`, paymasterAddress: Address): Promise<{
+        tokenCost: bigint;
+        actualGasCostWei: bigint;
+    } | null>;
+    /**
+     * Helper: Encode a standardized ERC-20 Transfer.
+     * Returns the raw function data: `transfer(to, amount)`
+     */
+    static encodeTokenTransfer(recipient: Address, amount: bigint): `0x${string}`;
+    /**
+     * Helper: Encode a SimpleAccount execution.
+     * Wraps the inner call into: `execute(target, value, data)`
+     * This is the payload signed by the user.
+     */
+    static encodeExecution(target: Address, value: bigint, data: `0x${string}`): `0x${string}`;
+}

package/dist/paymaster/src/V4/PaymasterClient.js

@@ -0,0 +1,315 @@
+import { concat, pad, toHex, parseAbi, encodeFunctionData } from 'viem';
+import { buildPaymasterData, buildSuperPaymasterData, formatUserOpV07, getUserOpHashV07 } from './PaymasterUtils';
+/**
+ * PaymasterClient
+ * Focus: Integration, Funding, Interaction.
+ */
+export class PaymasterClient {
+    /**
+     * Get user's deposited balance on the Paymaster.
+     */
+    static async getDepositedBalance(publicClient, address, user, token) {
+        return publicClient.readContract({
+            address,
+            abi: [{
+                    name: 'balances',
+                    type: 'function',
+                    inputs: [
+                        { name: 'user', type: 'address' },
+                        { name: 'token', type: 'address' }
+                    ],
+                    outputs: [{ name: '', type: 'uint256' }],
+                    stateMutability: 'view'
+                }],
+            functionName: 'balances',
+            args: [user, token]
+        });
+    }
+    /**
+     * Deposit tokens to Paymaster for a user (enables gasless transactions).
+     */
+    static async depositFor(wallet, address, user, token, amount) {
+        return wallet.writeContract({
+            address,
+            abi: parseAbi(['function depositFor(address user, address token, uint256 amount) external']),
+            functionName: 'depositFor',
+            args: [user, token, amount],
+            chain: wallet.chain
+        });
+    }
+    /**
+     * Approve the Paymaster (or any spender) to spend gas tokens.
+     */
+    static async approveGasToken(wallet, token, spender, amount) {
+        return wallet.writeContract({
+            address: token,
+            abi: parseAbi(['function approve(address spender, uint256 amount) external returns (bool)']),
+            functionName: 'approve',
+            args: [spender, amount],
+            chain: wallet.chain
+        });
+    }
+    /**
+     * Estimate Gas for a UserOperation.
+     */
+    static async estimateUserOperationGas(client, wallet, aaAddress, entryPoint, paymasterAddress, token, bundlerUrl, callData, options) {
+        // 1. Construct a dummy UserOp for estimation
+        let paymasterAndData;
+        if (options?.operator) {
+            paymasterAndData = buildSuperPaymasterData(paymasterAddress, options.operator, {
+                verificationGasLimit: 300000n,
+                postOpGasLimit: 300000n
+            });
+        }
+        else {
+            paymasterAndData = buildPaymasterData(paymasterAddress, token, {
+                validityWindow: options?.validityWindow,
+                verificationGasLimit: 60000n, // Placeholder
+                postOpGasLimit: 60000n // Placeholder
+            });
+        }
+        // 1.5. Get dynamic gas prices from network
+        let maxFeePerGas = 30000000000n; // 30 Gwei default
+        let maxPriorityFeePerGas = 1000000000n; // 1 Gwei default
+        try {
+            const feeData = await client.estimateFeesPerGas();
+            maxFeePerGas = (feeData.maxFeePerGas ?? 30000000000n) * 150n / 100n; // 1.5x buffer
+            maxPriorityFeePerGas = (feeData.maxPriorityFeePerGas ?? 1000000000n) * 150n / 100n;
+            if (maxPriorityFeePerGas < 500000000n)
+                maxPriorityFeePerGas = 500000000n; // Min 0.5 Gwei
+        }
+        catch (e) {
+            // Use defaults if estimation fails
+        }
+        const partialUserOp = {
+            sender: aaAddress,
+            nonce: 0n,
+            initCode: (options?.factory && options?.factoryData)
+                ? concat([options.factory, options.factoryData])
+                : '0x',
+            callData,
+            accountGasLimits: concat([pad(toHex(60000n), { size: 16 }), pad(toHex(100000n), { size: 16 })]), // 60k verification, 100k call
+            preVerificationGas: 50000n, // 50k PVG
+            gasFees: concat([pad(toHex(maxPriorityFeePerGas), { size: 16 }), pad(toHex(maxFeePerGas), { size: 16 })]),
+            paymasterAndData,
+            signature: '0x'
+        };
+        // Get actual nonce
+        try {
+            const nonce = await client.readContract({
+                address: aaAddress,
+                abi: parseAbi(['function getNonce() view returns (uint256)']),
+                functionName: 'getNonce'
+            });
+            partialUserOp.nonce = BigInt(nonce);
+        }
+        catch (e) { }
+        const userOpHash = getUserOpHashV07(partialUserOp, entryPoint, BigInt(client.chain.id));
+        partialUserOp.signature = (await wallet.account.signMessage({ message: { raw: userOpHash } }));
+        const payload = {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'eth_estimateUserOperationGas',
+            params: [formatUserOpV07(partialUserOp), entryPoint]
+        };
+        const response = await fetch(bundlerUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload, (_, v) => typeof v === 'bigint' ? '0x' + v.toString(16) : v)
+        });
+        const result = await response.json();
+        if (result.error)
+            throw new Error(`Estimation Error: ${JSON.stringify(result.error)}`);
+        const data = result.result;
+        // Dynamic tuning based on "Efficiency Guard" formulas
+        return {
+            preVerificationGas: BigInt(data.preVerificationGas),
+            verificationGasLimit: BigInt(data.verificationGasLimit),
+            callGasLimit: (BigInt(data.callGasLimit) * 110n) / 100n, // 1.1x safety buffer
+            paymasterVerificationGasLimit: data.paymasterVerificationGasLimit ? BigInt(data.paymasterVerificationGasLimit) : undefined,
+            paymasterPostOpGasLimit: data.paymasterPostOpGasLimit ? BigInt(data.paymasterPostOpGasLimit) : 100000n
+        };
+    }
+    /**
+     * High-level API to submit a gasless UserOperation.
+     * Automatically handles nonce fetching, gas estimation (if not provided), signing, and submission.
+     */
+    static async submitGaslessUserOperation(client, wallet, aaAddress, entryPoint, paymasterAddress, token, bundlerUrl, callData, options) {
+        // 0. Auto-Estimate if requested or if limits missing
+        let gasLimits = {
+            preVerificationGas: options?.preVerificationGas,
+            verificationGasLimit: options?.verificationGasLimit,
+            callGasLimit: options?.callGasLimit,
+            paymasterVerificationGasLimit: options?.paymasterVerificationGasLimit,
+            paymasterPostOpGasLimit: options?.paymasterPostOpGasLimit ?? 100000n
+        };
+        if (options?.autoEstimate !== false && (!gasLimits.verificationGasLimit || !gasLimits.callGasLimit)) {
+            const est = await this.estimateUserOperationGas(client, wallet, aaAddress, entryPoint, paymasterAddress, token, bundlerUrl, callData, {
+                validityWindow: options?.validityWindow,
+                operator: options?.operator,
+                factory: options?.factory,
+                factoryData: options?.factoryData
+            });
+            gasLimits.preVerificationGas = options?.preVerificationGas ?? est.preVerificationGas;
+            gasLimits.verificationGasLimit = options?.verificationGasLimit ?? est.verificationGasLimit;
+            gasLimits.callGasLimit = options?.callGasLimit ?? est.callGasLimit;
+            gasLimits.paymasterVerificationGasLimit = options?.paymasterVerificationGasLimit ?? est.paymasterVerificationGasLimit;
+            gasLimits.paymasterPostOpGasLimit = options?.paymasterPostOpGasLimit ?? est.paymasterPostOpGasLimit;
+        }
+        // 1. Get Nonce
+        const nonce = await client.readContract({
+            address: aaAddress,
+            abi: parseAbi(['function getNonce() view returns (uint256)']),
+            functionName: 'getNonce'
+        });
+        // 1.5 Get Gas Prices from Network if not provided
+        let maxFeePerGas = options?.maxFeePerGas;
+        let maxPriorityFeePerGas = options?.maxPriorityFeePerGas;
+        if (!maxFeePerGas || !maxPriorityFeePerGas) {
+            try {
+                const feeData = await client.estimateFeesPerGas();
+                // Apply 1.5x buffer for network volatility
+                maxFeePerGas = maxFeePerGas ?? ((feeData.maxFeePerGas ?? 30000000000n) * 150n) / 100n;
+                maxPriorityFeePerGas = maxPriorityFeePerGas ?? ((feeData.maxPriorityFeePerGas ?? 1000000000n) * 150n) / 100n;
+                if (maxPriorityFeePerGas < 500000000n) {
+                    console.log(`[PaymasterClient] Priority Fee ${maxPriorityFeePerGas} too low, clamping to 0.5 Gwei`);
+                    maxPriorityFeePerGas = 500000000n; // Min 0.5 Gwei
+                }
+                // Ensure MaxFee >= Priority
+                if (maxFeePerGas < maxPriorityFeePerGas) {
+                    maxFeePerGas = maxPriorityFeePerGas + 1000000n; // Add small buffer
+                    console.log(`[PaymasterClient] MaxFee bumped to accommodate Priority Fee`);
+                }
+                console.log(`[PaymasterClient] Fees Set: MaxFee=${maxFeePerGas}, Priority=${maxPriorityFeePerGas}`);
+            }
+            catch (e) {
+                console.log('[PaymasterClient] Fee Estimation Failed:', e);
+                // Fallback to safer defaults if estimation fails
+                maxFeePerGas = maxFeePerGas ?? 50000000000n; // 50 Gwei
+                maxPriorityFeePerGas = maxPriorityFeePerGas ?? 2000000000n; // 2 Gwei
+            }
+        }
+        // 2. Build paymasterAndData
+        let paymasterAndData;
+        if (options?.operator) {
+            paymasterAndData = buildSuperPaymasterData(paymasterAddress, options.operator, {
+                verificationGasLimit: gasLimits.paymasterVerificationGasLimit ?? gasLimits.verificationGasLimit ?? 150000n,
+                postOpGasLimit: gasLimits.paymasterPostOpGasLimit ?? 100000n
+            });
+        }
+        else {
+            paymasterAndData = buildPaymasterData(paymasterAddress, token, {
+                validityWindow: options?.validityWindow,
+                verificationGasLimit: gasLimits.paymasterVerificationGasLimit ?? gasLimits.verificationGasLimit ?? 150000n, // Use tuned value
+                postOpGasLimit: gasLimits.paymasterPostOpGasLimit ?? 100000n
+            });
+        }
+        // 3. Construct UserOp
+        const userOp = {
+            sender: aaAddress,
+            nonce: BigInt(nonce),
+            initCode: (options?.factory && options?.factoryData)
+                ? concat([options.factory, options.factoryData])
+                : '0x',
+            callData,
+            accountGasLimits: concat([
+                pad(toHex(gasLimits.verificationGasLimit ?? 150000n), { size: 16 }), // Verification (Tuned or Default)
+                pad(toHex(gasLimits.callGasLimit ?? 500000n), { size: 16 }) // Call (Tuned or Default)
+            ]),
+            preVerificationGas: gasLimits.preVerificationGas ?? 50000n,
+            gasFees: concat([
+                pad(toHex(maxPriorityFeePerGas), { size: 16 }),
+                pad(toHex(maxFeePerGas), { size: 16 })
+            ]),
+            paymasterAndData,
+            signature: '0x'
+        };
+        // Debug logs (Commented out for production)
+        /*
+        console.log("DEBUG: UserOp Gas Limits:", {
+            accountGasLimits: userOp.accountGasLimits,
+            preVerificationGas: userOp.preVerificationGas,
+            gasFees: userOp.gasFees,
+            paymasterAndData: userOp.paymasterAndData
+        });
+        */
+        // 4. Final Hashing and Signing
+        const userOpHash = getUserOpHashV07(userOp, entryPoint, BigInt(client.chain.id));
+        const signature = (await wallet.account.signMessage({ message: { raw: userOpHash } }));
+        userOp.signature = signature;
+        // 6. Submit to Bundler
+        const response = await fetch(bundlerUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'eth_sendUserOperation',
+                params: [formatUserOpV07(userOp), entryPoint]
+            }, (_, v) => typeof v === 'bigint' ? '0x' + v.toString(16) : v)
+        });
+        const result = await response.json();
+        if (result.error)
+            throw new Error(`Bundler Error: ${JSON.stringify(result.error)}`);
+        return result.result;
+    }
+    /**
+     * Helper to extract the actual Gas Token fee from a UserOperation receipt.
+     * Looks for the 'PostOpProcessed' event emitted by the Paymaster.
+     */
+    static getFeeFromReceipt(receipt, paymasterAddress) {
+        // Event Signature: PostOpProcessed(address indexed user, address indexed token, uint256 actualGasCostWei, uint256 tokenCost, uint256 protocolRevenue)
+        // Topic0: 0x62544d7f48b11c32334310ebd306b47224fca220163218d4a7264322c52ae073
+        const TOPIC_POST_OP = '0x62544d7f48b11c32334310ebd306b47224fca220163218d4a7264322c52ae073';
+        for (const log of receipt.logs) {
+            if (log.address.toLowerCase() === paymasterAddress.toLowerCase() && log.topics[0] === TOPIC_POST_OP) {
+                // Decode Data: actualGasCostWei, tokenCost, protocolRevenue (3x uint256)
+                // We manually decode or use viem's decodeEventLog if available.
+                // Here we use a lightweight manual decode for the data part (non-indexed).
+                // Data is 3 * 32 bytes.
+                const data = log.data.replace('0x', '');
+                if (data.length >= 192) { // 3 * 64 hex chars = 192
+                    const actualGasCostWei = BigInt('0x' + data.slice(0, 64));
+                    const tokenCost = BigInt('0x' + data.slice(64, 128));
+                    // const protocolRevenue = BigInt('0x' + data.slice(128, 192));
+                    return { tokenCost, actualGasCostWei };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the fee for a specific transaction hash.
+     * Fetches the receipt (no scanning required) and decodes the log.
+     */
+    static async getTransactionFee(publicClient, txHash, paymasterAddress) {
+        const receipt = await publicClient.getTransactionReceipt({ hash: txHash });
+        return this.getFeeFromReceipt(receipt, paymasterAddress);
+    }
+    // ===========================================
+    // 🛠️ Semantic CallData Builders (For DX)
+    // ===========================================
+    /**
+     * Helper: Encode a standardized ERC-20 Transfer.
+     * Returns the raw function data: `transfer(to, amount)`
+     */
+    static encodeTokenTransfer(recipient, amount) {
+        return encodeFunctionData({
+            abi: parseAbi(['function transfer(address to, uint256 amount) external returns (bool)']),
+            functionName: 'transfer',
+            args: [recipient, amount]
+        });
+    }
+    /**
+     * Helper: Encode a SimpleAccount execution.
+     * Wraps the inner call into: `execute(target, value, data)`
+     * This is the payload signed by the user.
+     */
+    static encodeExecution(target, value, data) {
+        return encodeFunctionData({
+            abi: parseAbi(['function execute(address dest, uint256 value, bytes func) external']),
+            functionName: 'execute',
+            args: [target, value, data]
+        });
+    }
+}

package/dist/paymaster/src/V4/PaymasterOperator.d.ts

@@ -0,0 +1,41 @@
+import { type Address } from 'viem';
+import { type GaslessReadinessReport } from './PaymasterUtils';
+/**
+ * PaymasterOperator
+ * Focus: Deployment, Configuration, Maintenance, Keeper Bots.
+ */
+export declare class PaymasterOperator {
+    /**
+     * Update the cached ETH/USD price from Chainlink Oracle.
+     * Must be called if cachedPrice is 0 (uninitialized).
+     */
+    static updatePrice(wallet: any, address: Address): Promise<any>;
+    /**
+     * Set the token price (in 8 decimals, e.g., 1e8 = $1 USD).
+     */
+    static setTokenPrice(wallet: any, address: Address, token: Address, priceUSD: bigint): Promise<any>;
+    static getCachedPrice(publicClient: any, address: Address): Promise<{
+        price: bigint;
+        updatedAt: bigint;
+    }>;
+    static getTokenPrice(publicClient: any, address: Address, token: Address): Promise<bigint>;
+    static getDepositedBalance(publicClient: any, address: Address, user: Address, token: Address): Promise<bigint>;
+    static ensurePriceInitialized(wallet: any, publicClient: any, address: Address): Promise<boolean>;
+    static addStake(wallet: any, address: Address, amount: bigint, unstakeDelaySec: number): Promise<any>;
+    static addDeposit(wallet: any, address: Address, amount: bigint): Promise<any>;
+    static addGasToken(wallet: any, address: Address, token: Address): Promise<any>;
+    static removeGasToken(wallet: any, address: Address, token: Address): Promise<any>;
+    static setServiceFeeRate(wallet: any, address: Address, rate: bigint): Promise<any>;
+    static setMaxGasCostCap(wallet: any, address: Address, cap: bigint): Promise<any>;
+    static withdrawPNT(wallet: any, address: Address, to: Address, token: Address, amount: bigint): Promise<any>;
+    static checkGaslessReadiness(publicClient: any, entryPoint: Address, paymasterAddress: Address, user: Address, token: Address): Promise<GaslessReadinessReport>;
+    static prepareGaslessEnvironment(operatorWallet: any, publicClient: any, entryPoint: Address, paymasterAddress: Address, token: Address, options?: {
+        minStake?: bigint;
+        minDeposit?: bigint;
+        tokenPriceUSD?: bigint;
+    }): Promise<{
+        step: string;
+        hash?: string;
+        status: string;
+    }[]>;
+}

package/dist/paymaster/src/V4/PaymasterOperator.js

@@ -0,0 +1,241 @@
+import { parseAbi } from 'viem';
+/**
+ * PaymasterOperator
+ * Focus: Deployment, Configuration, Maintenance, Keeper Bots.
+ */
+export class PaymasterOperator {
+    /**
+     * Update the cached ETH/USD price from Chainlink Oracle.
+     * Must be called if cachedPrice is 0 (uninitialized).
+     */
+    static async updatePrice(wallet, address) {
+        return wallet.writeContract({
+            address,
+            abi: parseAbi(['function updatePrice() external']),
+            functionName: 'updatePrice',
+            chain: wallet.chain
+        });
+    }
+    /**
+     * Set the token price (in 8 decimals, e.g., 1e8 = $1 USD).
+     */
+    static async setTokenPrice(wallet, address, token, priceUSD) {
+        return wallet.writeContract({
+            address,
+            abi: parseAbi(['function setTokenPrice(address token, uint256 price) external']),
+            functionName: 'setTokenPrice',
+            args: [token, priceUSD],
+            chain: wallet.chain
+        });
+    }
+    static async getCachedPrice(publicClient, address) {
+        const result = await publicClient.readContract({
+            address,
+            abi: [{
+                    name: 'cachedPrice',
+                    type: 'function',
+                    inputs: [],
+                    outputs: [
+                        { name: 'price', type: 'uint208' },
+                        { name: 'updatedAt', type: 'uint48' }
+                    ],
+                    stateMutability: 'view'
+                }],
+            functionName: 'cachedPrice'
+        });
+        return { price: result[0], updatedAt: result[1] };
+    }
+    static async getTokenPrice(publicClient, address, token) {
+        return publicClient.readContract({
+            address,
+            abi: [{
+                    name: 'tokenPrices',
+                    type: 'function',
+                    inputs: [{ name: 'token', type: 'address' }],
+                    outputs: [{ name: '', type: 'uint256' }],
+                    stateMutability: 'view'
+                }],
+            functionName: 'tokenPrices',
+            args: [token]
+        });
+    }
+    static async getDepositedBalance(publicClient, address, user, token) {
+        return publicClient.readContract({
+            address,
+            abi: [{
+                    name: 'balances',
+                    type: 'function',
+                    inputs: [
+                        { name: 'user', type: 'address' },
+                        { name: 'token', type: 'address' }
+                    ],
+                    outputs: [{ name: '', type: 'uint256' }],
+                    stateMutability: 'view'
+                }],
+            functionName: 'balances',
+            args: [user, token]
+        });
+    }
+    static async ensurePriceInitialized(wallet, publicClient, address) {
+        const { price } = await this.getCachedPrice(publicClient, address);
+        if (price === 0n) {
+            await this.updatePrice(wallet, address);
+            return true;
+        }
+        return false;
+    }
+    static async addStake(wallet, address, amount, unstakeDelaySec) {
+        return wallet.writeContract({
+            address,
+            abi: parseAbi(['function addStake(uint32 unstakeDelaySec) external payable']),
+            functionName: 'addStake',
+            args: [unstakeDelaySec],
+            value: amount,
+            chain: wallet.chain
+        });
+    }
+    static async addDeposit(wallet, address, amount) {
+        return wallet.writeContract({
+            address,
+            abi: parseAbi(['function addDeposit() external payable']),
+            functionName: 'addDeposit',
+            value: amount,
+            chain: wallet.chain
+        });
+    }
+    static async addGasToken(wallet, address, token) {
+        return wallet.writeContract({
+            address,
+            abi: ['function addGasToken(address token)'],
+            functionName: 'addGasToken',
+            args: [token],
+            chain: wallet.chain
+        });
+    }
+    static async removeGasToken(wallet, address, token) {
+        return wallet.writeContract({
+            address,
+            abi: ['function removeGasToken(address token)'],
+            functionName: 'removeGasToken',
+            args: [token],
+            chain: wallet.chain
+        });
+    }
+    static async setServiceFeeRate(wallet, address, rate) {
+        return wallet.writeContract({
+            address,
+            abi: ['function setServiceFeeRate(uint256 rate)'],
+            functionName: 'setServiceFeeRate',
+            args: [rate],
+            chain: wallet.chain
+        });
+    }
+    static async setMaxGasCostCap(wallet, address, cap) {
+        return wallet.writeContract({
+            address,
+            abi: ['function setMaxGasCostCap(uint256 cap)'],
+            functionName: 'setMaxGasCostCap',
+            args: [cap],
+            chain: wallet.chain
+        });
+    }
+    static async withdrawPNT(wallet, address, to, token, amount) {
+        return wallet.writeContract({
+            address,
+            abi: ['function withdrawPNT(address to, address token, uint256 amount)'],
+            functionName: 'withdrawPNT',
+            args: [to, token, amount],
+            chain: wallet.chain
+        });
+    }
+    // --- Diagnostics & Automation ---
+    static async checkGaslessReadiness(publicClient, entryPoint, paymasterAddress, user, token) {
+        const issues = [];
+        // 1. EntryPoint Stake/Deposit
+        const depositInfo = await publicClient.readContract({
+            address: entryPoint,
+            abi: parseAbi(['function getDepositInfo(address account) external view returns (uint256 deposit, bool staked, uint256 stake, uint32 unstakeDelaySec, uint48 withdrawTime)']),
+            functionName: 'getDepositInfo',
+            args: [paymasterAddress]
+        });
+        if (depositInfo[2] < 50000000000000000n)
+            issues.push('Paymaster stake in EntryPoint is less than 0.05 ETH');
+        if (depositInfo[3] < 86400)
+            issues.push('Paymaster unstake delay is less than 1 day');
+        if (depositInfo[0] < 100000000000000000n)
+            issues.push('Paymaster deposit in EntryPoint is less than 0.1 ETH');
+        // 2. Oracle Price
+        const ethPrice = await publicClient.readContract({
+            address: paymasterAddress,
+            abi: parseAbi(['function cachedPrice() external view returns (uint208 price, uint48 updatedAt)']),
+            functionName: 'cachedPrice'
+        }).catch(() => [0n, 0n]);
+        if (ethPrice[0] === 0n)
+            issues.push('Paymaster ETH/USD price not initialized');
+        // 3. Token Support & Price
+        const [tokenPrice, userTokenBal, userPMDeposit] = await Promise.all([
+            this.getTokenPrice(publicClient, paymasterAddress, token),
+            publicClient.readContract({
+                address: token,
+                abi: parseAbi(['function balanceOf(address account) external view returns (uint256)']),
+                functionName: 'balanceOf',
+                args: [user]
+            }),
+            this.getDepositedBalance(publicClient, paymasterAddress, user, token)
+        ]);
+        if (tokenPrice === 0n)
+            issues.push('Token price not set in Paymaster');
+        if (userPMDeposit === 0n)
+            issues.push('User has no deposit in Paymaster');
+        return {
+            isReady: issues.length === 0,
+            issues,
+            details: {
+                paymasterStake: depositInfo[2],
+                paymasterDeposit: depositInfo[0],
+                ethUsdPrice: ethPrice.price,
+                tokenSupported: true,
+                tokenPrice: tokenPrice,
+                userTokenBalance: userTokenBal,
+                userPaymasterDeposit: userPMDeposit
+            }
+        };
+    }
+    static async prepareGaslessEnvironment(operatorWallet, publicClient, entryPoint, paymasterAddress, token, options = {}) {
+        const report = await this.checkGaslessReadiness(publicClient, entryPoint, paymasterAddress, operatorWallet.account.address, token);
+        const results = [];
+        // 1. Stake
+        if (report.details.paymasterStake < (options.minStake || 50000000000000000n)) {
+            const hash = await this.addStake(operatorWallet, paymasterAddress, options.minStake || 50000000000000000n, 86400);
+            await publicClient.waitForTransactionReceipt({ hash });
+            results.push({ step: 'Stake', hash, status: 'Confirmed' });
+        }
+        // 2. Deposit (EntryPoint)
+        if (report.details.paymasterDeposit < (options.minDeposit || 100000000000000000n)) {
+            const hash = await this.addDeposit(operatorWallet, paymasterAddress, options.minDeposit || 300000000000000000n);
+            await publicClient.waitForTransactionReceipt({ hash });
+            results.push({ step: 'Deposit', hash, status: 'Confirmed' });
+        }
+        // 3. Oracle Price
+        if (report.details.ethUsdPrice === 0n) {
+            const hash = await this.updatePrice(operatorWallet, paymasterAddress);
+            await publicClient.waitForTransactionReceipt({ hash });
+            results.push({ step: 'OraclePrice', hash, status: 'Confirmed' });
+        }
+        // 4. Token Support & Price
+        if (report.details.tokenPrice === 0n) {
+            try {
+                const hash = await this.addGasToken(operatorWallet, paymasterAddress, token);
+                await publicClient.waitForTransactionReceipt({ hash });
+                results.push({ step: 'AddGasToken', hash, status: 'Confirmed' });
+            }
+            catch (e) { }
+            if (options.tokenPriceUSD) {
+                const hash = await this.setTokenPrice(operatorWallet, paymasterAddress, token, options.tokenPriceUSD);
+                await publicClient.waitForTransactionReceipt({ hash });
+                results.push({ step: 'TokenPrice', hash, status: 'Confirmed' });
+            }
+        }
+        return results;
+    }
+}