@aastar/dapp 0.16.7

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/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/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,31 @@
+{
+  "name": "@aastar/dapp",
+  "version": "0.16.7",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "viem": "2.43.3",
+    "@aastar/core": "0.16.7",
+    "@aastar/paymaster": "0.16.7"
+  },
+  "devDependencies": {
+    "@types/react": "18.2.0",
+    "@types/react-dom": "18.2.0",
+    "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"
+  }
+}