@aastar/paymaster 0.16.7

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PaymasterOperator } from './PaymasterOperator.js';
+describe('PaymasterOperator', () => {
+    const MOCK_PM = '0x1111111111111111111111111111111111111111';
+    const MOCK_USER = '0x2222222222222222222222222222222222222222';
+    const MOCK_TOKEN = '0x3333333333333333333333333333333333333333';
+    const MOCK_EP = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';
+    let mockPublicClient;
+    let mockWallet;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockPublicClient = {
+            readContract: vi.fn(),
+            waitForTransactionReceipt: vi.fn().mockResolvedValue({ status: 'success' })
+        };
+        mockWallet = {
+            writeContract: vi.fn().mockResolvedValue('0xhash'),
+            account: { address: MOCK_USER },
+            chain: { id: 31337 }
+        };
+    });
+    it('should update price', async () => {
+        const hash = await PaymasterOperator.updatePrice(mockWallet, MOCK_PM);
+        expect(hash).toBe('0xhash');
+    });
+    it('should get cached price', async () => {
+        mockPublicClient.readContract.mockResolvedValue([1000n, 123n]);
+        const { price, updatedAt } = await PaymasterOperator.getCachedPrice(mockPublicClient, MOCK_PM);
+        expect(price).toBe(1000n);
+        expect(updatedAt).toBe(123n);
+    });
+    it('should check gasless readiness', async () => {
+        mockPublicClient.readContract
+            .mockResolvedValueOnce([10n ** 18n, true, 10n ** 18n, 100000, 0]) // EntryPoint depositInfo
+            .mockResolvedValueOnce([2000n, 123n]) // cachedPrice
+            .mockResolvedValueOnce(1n) // tokenPrice
+            .mockResolvedValueOnce(1000n) // balance
+            .mockResolvedValueOnce(500n); // deposit
+        const report = await PaymasterOperator.checkGaslessReadiness(mockPublicClient, MOCK_EP, MOCK_PM, MOCK_USER, MOCK_TOKEN);
+        expect(report.isReady).toBe(true);
+        expect(report.issues.length).toBe(0);
+    });
+    it('should identify readiness issues', async () => {
+        mockPublicClient.readContract
+            .mockResolvedValueOnce([0n, false, 0n, 0, 0]) // EntryPoint depositInfo
+            .mockResolvedValueOnce([0n, 0n]) // cachedPrice
+            .mockResolvedValueOnce(0n) // tokenPrice
+            .mockResolvedValueOnce(0n) // balance
+            .mockResolvedValueOnce(0n); // deposit
+        const report = await PaymasterOperator.checkGaslessReadiness(mockPublicClient, MOCK_EP, MOCK_PM, MOCK_USER, MOCK_TOKEN);
+        expect(report.isReady).toBe(false);
+        expect(report.issues.length).toBeGreaterThan(0);
+    });
+    it('should prepare gasless environment', async () => {
+        // Mock readiness check to have issues
+        mockPublicClient.readContract
+            .mockResolvedValueOnce([0n, false, 0n, 0, 0]) // first check inside prepareGaslessEnvironment
+            .mockResolvedValueOnce([0n, 0n])
+            .mockResolvedValueOnce(0n)
+            .mockResolvedValueOnce(0n)
+            .mockResolvedValueOnce(0n);
+        const results = await PaymasterOperator.prepareGaslessEnvironment(mockWallet, mockPublicClient, MOCK_EP, MOCK_PM, MOCK_TOKEN);
+        expect(results.length).toBeGreaterThan(0);
+        expect(mockWallet.writeContract).toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,55 @@
+import { type Address, type Hex } from 'viem';
+export type PaymasterV4MiddlewareConfig = {
+    paymasterAddress: Address;
+    gasToken: Address;
+    verificationGasLimit?: bigint;
+    postOpGasLimit?: bigint;
+};
+export type GaslessReadinessReport = {
+    isReady: boolean;
+    issues: string[];
+    details: {
+        paymasterStake: bigint;
+        paymasterDeposit: bigint;
+        ethUsdPrice: bigint;
+        tokenSupported: boolean;
+        tokenPrice: bigint;
+        userTokenBalance: bigint;
+        userPaymasterDeposit: bigint;
+    };
+};
+/**
+ * Constructs the middleware for Paymaster V4.
+ * Returns the `paymasterAndData` hex string.
+ */
+export declare function getPaymasterV4Middleware(config: PaymasterV4MiddlewareConfig): {
+    sponsorUserOperation: (args: {
+        userOperation: any;
+    }) => Promise<{
+        paymasterAndData: `0x${string}`;
+        verificationGasLimit: bigint;
+        preVerificationGas: any;
+    }>;
+};
+/**
+ * Build paymasterAndData for gasless UserOperation.
+ * Layout: [Paymaster(20)] [VerificationGasLimit(16)] [PostOpGasLimit(16)] [Token(20)] [ValidUntil(6)] [ValidAfter(6)]
+ */
+export declare function buildPaymasterData(paymasterAddress: Address, token: Address, options?: {
+    validityWindow?: number;
+    verificationGasLimit?: bigint;
+    postOpGasLimit?: bigint;
+}): `0x${string}`;
+/**
+ * Build paymasterAndData for SuperPaymaster V3.
+ * Layout: [Paymaster(20)] [verGas(16)] [postGas(16)] [operator(20)] [maxRate(32)]
+ */
+export declare function buildSuperPaymasterData(paymasterAddress: Address, operator: Address, options?: {
+    verificationGasLimit?: bigint;
+    postOpGasLimit?: bigint;
+}): `0x${string}`;
+/**
+ * Helper to format UserOp for Alchemy/Standard Bundlers (v0.7 Decomposed)
+ */
+export declare function formatUserOpV07(userOp: any): any;
+export declare function getUserOpHashV07(userOp: any, entryPoint: Address, chainId: bigint): Hex;

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

@@ -0,0 +1,124 @@
+import { concat, pad, toHex, keccak256, encodeAbiParameters, toBytes } from 'viem';
+import { validateAddress, validateUint128 } from '@aastar/core';
+const DEFAULT_VERIFICATION_GAS_V4 = 80000n;
+const DEFAULT_POSTOP_GAS_V4 = 100000n;
+/**
+ * Constructs the middleware for Paymaster V4.
+ * Returns the `paymasterAndData` hex string.
+ */
+export function getPaymasterV4Middleware(config) {
+    return {
+        sponsorUserOperation: async (args) => {
+            const verGas = config.verificationGasLimit ?? DEFAULT_VERIFICATION_GAS_V4;
+            const postGas = config.postOpGasLimit ?? DEFAULT_POSTOP_GAS_V4;
+            // Layout: [Paymaster(20)] [VerGas(16)] [PostOpGas(16)] [Token(20)]
+            const paymasterAndData = concat([
+                config.paymasterAddress,
+                pad(toHex(verGas), { size: 16 }),
+                pad(toHex(postGas), { size: 16 }),
+                config.gasToken
+            ]);
+            return {
+                paymasterAndData,
+                verificationGasLimit: verGas,
+                preVerificationGas: args.userOperation.preVerificationGas
+            };
+        }
+    };
+}
+/**
+ * Build paymasterAndData for gasless UserOperation.
+ * Layout: [Paymaster(20)] [VerificationGasLimit(16)] [PostOpGasLimit(16)] [Token(20)] [ValidUntil(6)] [ValidAfter(6)]
+ */
+export function buildPaymasterData(paymasterAddress, token, options) {
+    const validityWindow = options?.validityWindow ?? 3600;
+    const verGas = options?.verificationGasLimit ?? 80000n;
+    const postGas = options?.postOpGasLimit ?? 100000n;
+    // Hardening: uint128 bounds check
+    validateUint128(verGas, 'verificationGasLimit');
+    validateUint128(postGas, 'postOpGasLimit');
+    const now = Math.floor(Date.now() / 1000);
+    const validUntil = now + validityWindow;
+    const validAfter = now - 100; // 100 seconds grace period
+    return concat([
+        paymasterAddress,
+        pad(toHex(verGas), { size: 16 }),
+        pad(toHex(postGas), { size: 16 }),
+        token,
+        pad(toHex(validUntil), { size: 6 }),
+        pad(toHex(validAfter), { size: 6 })
+    ]);
+}
+/**
+ * Build paymasterAndData for SuperPaymaster V3.
+ * Layout: [Paymaster(20)] [verGas(16)] [postGas(16)] [operator(20)] [maxRate(32)]
+ */
+export function buildSuperPaymasterData(paymasterAddress, operator, options) {
+    const verGas = options?.verificationGasLimit ?? 80000n;
+    const postGas = options?.postOpGasLimit ?? 100000n;
+    // Hardening
+    validateAddress(paymasterAddress, 'Paymaster Address');
+    validateAddress(operator, 'Operator Address');
+    validateUint128(verGas, 'verificationGasLimit');
+    validateUint128(postGas, 'postOpGasLimit');
+    return concat([
+        paymasterAddress,
+        pad(toHex(verGas), { size: 16 }),
+        pad(toHex(postGas), { size: 16 }),
+        operator
+    ]);
+}
+/**
+ * Helper to format UserOp for Alchemy/Standard Bundlers (v0.7 Decomposed)
+ */
+export function formatUserOpV07(userOp) {
+    const result = {
+        sender: userOp.sender,
+        nonce: toHex(userOp.nonce),
+        callData: userOp.callData,
+        preVerificationGas: toHex(userOp.preVerificationGas),
+        signature: userOp.signature,
+        initCode: userOp.initCode
+    };
+    // Extract Factory/FactoryData if present
+    if (userOp.initCode && userOp.initCode !== '0x') {
+        result.factory = userOp.initCode.slice(0, 42);
+        result.factoryData = '0x' + userOp.initCode.slice(42);
+    }
+    // Unpack accountGasLimits: [verificationGasLimit(16)][callGasLimit(16)]
+    if (userOp.accountGasLimits && userOp.accountGasLimits !== '0x') {
+        const packed = userOp.accountGasLimits.replace('0x', '').padStart(64, '0');
+        result.verificationGasLimit = '0x' + BigInt('0x' + packed.slice(0, 32)).toString(16);
+        result.callGasLimit = '0x' + BigInt('0x' + packed.slice(32, 64)).toString(16);
+    }
+    // Unpack gasFees: [maxPriorityFee(16)][maxFee(16)]
+    if (userOp.gasFees && userOp.gasFees !== '0x') {
+        const packed = userOp.gasFees.replace('0x', '').padStart(64, '0');
+        result.maxPriorityFeePerGas = '0x' + BigInt('0x' + packed.slice(0, 32)).toString(16);
+        result.maxFeePerGas = '0x' + BigInt('0x' + packed.slice(32, 64)).toString(16);
+    }
+    // Unpack paymasterAndData: [paymaster(20)][verificationGas(16)][postOpGas(16)][paymasterData]
+    if (userOp.paymasterAndData && userOp.paymasterAndData !== '0x') {
+        const packed = userOp.paymasterAndData.replace('0x', '');
+        if (packed.length >= 104) {
+            result.paymaster = '0x' + packed.slice(0, 40);
+            result.paymasterVerificationGasLimit = '0x' + BigInt('0x' + packed.slice(40, 72)).toString(16);
+            result.paymasterPostOpGasLimit = '0x' + BigInt('0x' + packed.slice(72, 104)).toString(16);
+            result.paymasterData = '0x' + packed.slice(104);
+        }
+    }
+    return result;
+}
+export function getUserOpHashV07(userOp, entryPoint, chainId) {
+    const hashedUserOp = keccak256(encodeAbiParameters(['address', 'uint256', 'bytes32', 'bytes32', 'bytes32', 'uint256', 'bytes32', 'bytes32'].map(t => ({ type: t })), [
+        userOp.sender,
+        userOp.nonce,
+        keccak256(toBytes(userOp.initCode)),
+        keccak256(toBytes(userOp.callData)),
+        userOp.accountGasLimits,
+        toHex(userOp.preVerificationGas),
+        userOp.gasFees,
+        keccak256(toBytes(userOp.paymasterAndData))
+    ]));
+    return keccak256(encodeAbiParameters(['bytes32', 'address', 'uint256'].map(t => ({ type: t })), [hashedUserOp, entryPoint, chainId]));
+}

package/dist/paymaster/src/V4/PaymasterUtils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/paymaster/src/V4/PaymasterUtils.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { getPaymasterV4Middleware, buildPaymasterData, buildSuperPaymasterData, formatUserOpV07 } from './PaymasterUtils.js';
+describe('PaymasterUtils', () => {
+    const MOCK_PM = '0x1111111111111111111111111111111111111111';
+    const MOCK_TOKEN = '0x2222222222222222222222222222222222222222';
+    const MOCK_OPERATOR = '0x3333333333333333333333333333333333333333';
+    it('should get V4 middleware', async () => {
+        const middleware = getPaymasterV4Middleware({
+            paymasterAddress: MOCK_PM,
+            gasToken: MOCK_TOKEN
+        });
+        const result = await middleware.sponsorUserOperation({
+            userOperation: { preVerificationGas: 100n }
+        });
+        expect(result.paymasterAndData).toBeDefined();
+        expect(result.paymasterAndData.toLowerCase()).toContain(MOCK_PM.toLowerCase().replace('0x', ''));
+    });
+    it('should build paymaster data for V4', () => {
+        const data = buildPaymasterData(MOCK_PM, MOCK_TOKEN);
+        expect(data.length).toBe(2 + 40 + 32 + 32 + 40 + 12 + 12); // Layout check
+    });
+    it('should build super paymaster data', () => {
+        const data = buildSuperPaymasterData(MOCK_PM, MOCK_OPERATOR);
+        expect(data.toLowerCase()).toContain(MOCK_OPERATOR.toLowerCase().replace('0x', ''));
+    });
+    it('should format UserOp for v0.7', () => {
+        const userOp = {
+            sender: MOCK_PM,
+            nonce: 1n,
+            callData: '0x123',
+            preVerificationGas: 1000n,
+            accountGasLimits: '0x' + '1'.repeat(32) + '2'.repeat(32),
+            gasFees: '0x' + '3'.repeat(32) + '4'.repeat(32),
+            paymasterAndData: '0x' + MOCK_PM.slice(2) + '5'.repeat(32) + '6'.repeat(32) + '7788',
+            signature: '0x'
+        };
+        const formatted = formatUserOpV07(userOp);
+        expect(formatted.sender).toBe(MOCK_PM);
+        expect(formatted.verificationGasLimit).toBeDefined();
+        expect(formatted.maxFeePerGas).toBeDefined();
+        expect(formatted.paymaster).toBe(MOCK_PM);
+    });
+});

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

@@ -0,0 +1,21 @@
+import { type Address, type Hex } from 'viem';
+export type GaslessTransactionConfig = {
+    token: Address;
+    recipient: Address;
+    amount: bigint;
+    operator: Address;
+    paymasterAddress: Address;
+    factory?: Address;
+    factoryData?: Hex;
+};
+/**
+ * SuperPaymasterClient
+ * High-level API for SuperPaymaster operations, including dynamic gas estimation.
+ */
+export declare class SuperPaymasterClient {
+    /**
+     * Submit a gasless transaction using SuperPaymaster.
+     * Automatically handles gas estimation with a smart efficiency buffer.
+     */
+    static submitGaslessTransaction(client: any, wallet: any, aaAddress: Address, entryPoint: Address, bundlerUrl: string, config: GaslessTransactionConfig): Promise<Hex>;
+}

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

@@ -0,0 +1,73 @@
+import { encodeFunctionData, parseAbi } from 'viem';
+import { PaymasterClient } from './PaymasterClient';
+import { validateAddress, validateAmount } from '@aastar/core';
+/**
+ * SuperPaymasterClient
+ * High-level API for SuperPaymaster operations, including dynamic gas estimation.
+ */
+export class SuperPaymasterClient {
+    /**
+     * Submit a gasless transaction using SuperPaymaster.
+     * Automatically handles gas estimation with a smart efficiency buffer.
+     */
+    static async submitGaslessTransaction(client, wallet, aaAddress, entryPoint, bundlerUrl, config) {
+        // Validation (Phase 0 Hardening)
+        validateAddress(config.token, 'Token Address');
+        validateAddress(config.recipient, 'Recipient Address');
+        validateAddress(config.operator, 'Operator Address');
+        validateAddress(config.paymasterAddress, 'Paymaster Address');
+        validateAmount(config.amount, 'Amount', 1n); // Must be > 0
+        // 1. Prepare Calldata (Standard ERC20 Transfer)
+        const callData = encodeFunctionData({
+            abi: parseAbi(['function execute(address dest, uint256 value, bytes func) external']),
+            functionName: 'execute',
+            args: [
+                config.token,
+                0n,
+                encodeFunctionData({
+                    abi: parseAbi(['function transfer(address to, uint256 amount) external returns (bool)']),
+                    functionName: 'transfer',
+                    args: [config.recipient, config.amount]
+                })
+            ]
+        });
+        // 2. Initial Gas Estimation (Bundler Query)
+        console.log('[SuperPaymasterClient] ☁️  Estimating Gas usage...');
+        const est = await PaymasterClient.estimateUserOperationGas(client, wallet, aaAddress, entryPoint, config.paymasterAddress, config.token, bundlerUrl, callData, {
+            operator: config.operator,
+            factory: config.factory,
+            factoryData: config.factoryData
+        });
+        console.log('[SuperPaymasterClient] ☁️  Bundler Estimates:', est);
+        // 3. Apply Smart Buffer Strategy
+        // We need to ensure:
+        // A. verificationGasLimit >= est.verificationGasLimit (Bundler's minimum)
+        // B. verificationGasLimit >= SuperPaymaster's Actual Usage (~80k-100k)
+        // C. verificationGasLimit / PreVerificationGas > 0.4 (Efficiency Ratio) PRE-CHECK
+        //    Actually, the Bundler checks: (gas limits) / (actual gas used) > efficiency.
+        //    So we must NOT set limits WAY higher than actual usage. 
+        //    Best strategy: Use Bundler's Estimate + Small Buffer (e.g. 10-20k).
+        // SuperPaymaster Logic Cost: ~80,000 to 120,000 gas depending on cold storage
+        // Bundler Estimate usually returns the *actual execution path* gas.
+        let vgl = est.verificationGasLimit;
+        // Safety Floor: If estimate is suspiciously low (e.g. < 50k), bump it for PM logic
+        // But if we bump it too high, we hit "Efficiency too low".
+        // Let's trust the bundler's estimate but add a fixed safety pad for dynamic storage
+        const SAFETY_PAD = 20000n;
+        const tunedVGL = vgl + SAFETY_PAD;
+        // Same for PostOp
+        const tunedPostOp = est.paymasterPostOpGasLimit + 10000n;
+        console.log(`[SuperPaymasterClient] 🔧 Tuned Limits: VGL=${tunedVGL}, PostOp=${tunedPostOp}`);
+        // 4. Submit with Tuned Limits
+        return PaymasterClient.submitGaslessUserOperation(client, wallet, aaAddress, entryPoint, config.paymasterAddress, config.token, bundlerUrl, callData, {
+            operator: config.operator,
+            verificationGasLimit: tunedVGL,
+            callGasLimit: est.callGasLimit,
+            preVerificationGas: est.preVerificationGas,
+            paymasterPostOpGasLimit: tunedPostOp, // Pass specific PM limits if supported
+            autoEstimate: false, // We did it ourselves
+            factory: config.factory,
+            factoryData: config.factoryData
+        });
+    }
+}

package/dist/paymaster/src/V4/SuperPaymasterClient.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/paymaster/src/V4/SuperPaymasterClient.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SuperPaymasterClient } from './SuperPaymasterClient.js';
+import { PaymasterClient } from './PaymasterClient.js';
+// Mock PaymasterClient
+vi.mock('./PaymasterClient.js', () => ({
+    PaymasterClient: {
+        estimateUserOperationGas: vi.fn(),
+        submitGaslessUserOperation: vi.fn()
+    }
+}));
+describe('SuperPaymasterClient', () => {
+    const MOCK_PM = '0x1111111111111111111111111111111111111111';
+    const MOCK_USER = '0x2222222222222222222222222222222222222222';
+    const MOCK_TOKEN = '0x3333333333333333333333333333333333333333';
+    const MOCK_RECIPIENT = '0x4444444444444444444444444444444444444444';
+    const MOCK_OPERATOR = '0x5555555555555555555555555555555555555555';
+    const MOCK_EP = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('should submit gasless transaction with tuned limits', async () => {
+        PaymasterClient.estimateUserOperationGas.mockResolvedValue({
+            verificationGasLimit: 100000n,
+            callGasLimit: 200000n,
+            preVerificationGas: 50000n,
+            paymasterPostOpGasLimit: 100000n
+        });
+        PaymasterClient.submitGaslessUserOperation.mockResolvedValue('0xuserOpHash');
+        const hash = await SuperPaymasterClient.submitGaslessTransaction({}, // client
+        {}, // wallet
+        MOCK_USER, MOCK_EP, 'http://bundler', {
+            token: MOCK_TOKEN,
+            recipient: MOCK_RECIPIENT,
+            amount: 100n,
+            operator: MOCK_OPERATOR,
+            paymasterAddress: MOCK_PM
+        });
+        expect(hash).toBe('0xuserOpHash');
+        expect(PaymasterClient.submitGaslessUserOperation).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), expect.anything(), expect.anything(), expect.anything(), expect.anything(), expect.anything(), expect.objectContaining({
+            verificationGasLimit: 120000n, // 100k + 20k buffer
+            autoEstimate: false
+        }));
+    });
+    it('should throw on invalid configuration', async () => {
+        await expect(SuperPaymasterClient.submitGaslessTransaction({}, {}, MOCK_USER, MOCK_EP, 'http://bundler', {
+            token: 'invalid',
+            recipient: MOCK_RECIPIENT,
+            amount: 100n,
+            operator: MOCK_OPERATOR,
+            paymasterAddress: MOCK_PM
+        })).rejects.toThrow();
+    });
+});

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

@@ -0,0 +1,4 @@
+export * from './PaymasterUtils';
+export * from './PaymasterClient';
+export * from './PaymasterOperator';
+export * from './SuperPaymasterClient';

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

@@ -0,0 +1,4 @@
+export * from './PaymasterUtils';
+export * from './PaymasterClient';
+export * from './PaymasterOperator';
+export * from './SuperPaymasterClient';

package/dist/paymaster/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SuperPaymaster/index.js';
+export * from './V4/index.js';

package/dist/paymaster/src/index.js

@@ -0,0 +1,4 @@
+// SuperPaymaster middleware
+export * from './SuperPaymaster/index.js';
+// Paymaster V4 middleware
+export * from './V4/index.js';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@aastar/paymaster",
+  "version": "0.16.7",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "viem": "2.43.3",
+    "@aastar/core": "0.16.7"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "clean": "find src -name '*.js' -o -name '*.d.ts' -o -name '*.map' | xargs rm -f",
+    "prebuild": "pnpm clean",
+    "build": "tsc"
+  }
+}