@aastar/enduser 0.16.14 → 0.16.18

package/dist/enduser/src/testAccountManager.d.ts

@@ -0,0 +1,149 @@
+import { Address, Hash } from 'viem';
+import { type PublicClient, type WalletClient } from '@aastar/core';
+/**
+ * PhD Paper Experiment Test Toolkit
+ *
+ * **Purpose**: Comprehensive API suite for preparing and managing test accounts
+ * for ERC-4337 performance comparison experiments (EOA vs AA vs SuperPaymaster).
+ *
+ * **Core Features**:
+ * 1. **Account Generation**: Create random EOA keys and deploy SimpleAccounts
+ * 2. **Token Funding**: Transfer test tokens (GToken, aPNTs, bPNTs, ETH)
+ * 3. **AA Deployment**: Deploy SimpleAccount contracts using official factory
+ * 4. **UserOp Execution**: Send ERC-4337 UserOperations with various paymasters
+ * 5. **Data Collection**: Generate experiment data for PhD paper analysis
+ *
+ * @example
+ * ```typescript
+ * const toolkit = new TestAccountManager(publicClient, supplierWallet);
+ *
+ * // Prepare complete test environment
+ * const env = await toolkit.prepareTestEnvironment({
+ *   accountCount: 3,
+ *   fundEachEOAWithETH: parseEther("0.01"),
+ *   fundEachAAWithETH: parseEther("0.02"),
+ *   tokens: {
+ *     gToken: { address: '0x...', amount: parseEther("100") },
+ *     aPNTs: { address: '0x...', amount: parseEther("50") }
+ *   }
+ * });
+ * ```
+ */
+export declare class TestAccountManager {
+    /** @internal */
+    private publicClient;
+    /** @internal */
+    private walletClient;
+    constructor(
+    /** @internal */
+    publicClient: PublicClient, 
+    /** @internal */
+    walletClient: WalletClient);
+    /**
+     * Prepare complete test environment for PhD experiments
+     *
+     * **Workflow**:
+     * 1. Generate N random EOA private keys
+     * 2. Deploy SimpleAccount for each EOA
+     * 3. Fund EOAs with ETH
+     * 4. Fund AAs with ETH
+     * 5. Transfer test tokens (GToken, aPNTs, bPNTs) to both EOAs and AAs
+     *
+     * @param config - Test environment configuration
+     * @returns Complete test environment with all accounts and tokens ready
+     */
+    prepareTestEnvironment(config: TestEnvironmentConfig): Promise<TestEnvironment>;
+    /**
+     * Generate multiple test accounts for experiments
+     * (Simplified version without token funding)
+     */
+    generateTestAccounts(count?: number, options?: {
+        fundEachAAWith?: bigint;
+        fundEachEOAWith?: bigint;
+        startingSalt?: number;
+    }): Promise<TestAccount[]>;
+    /**
+     * Export test accounts to .env format
+     */
+    exportToEnv(accounts: TestAccount[]): string;
+    /**
+     * Load test accounts from environment variables
+     */
+    static loadFromEnv(labels?: string[]): (TestAccount | null)[];
+    /**
+     * Get a single test account by label
+     */
+    static getTestAccount(label: string): TestAccount | null;
+    private records;
+    /**
+     * Add a standardized experiment record
+     */
+    addExperimentRecord(record: {
+        scenario: string;
+        group: 'EOA' | 'AA' | 'SuperPaymaster';
+        txHash: string;
+        gasUsed: bigint;
+        gasPrice: bigint;
+        status: string;
+        meta?: any;
+    }): {
+        id: string;
+        timestamp: number;
+        costETH: string;
+        scenario: string;
+        group: "EOA" | "AA" | "SuperPaymaster";
+        txHash: string;
+        gasUsed: bigint;
+        gasPrice: bigint;
+        status: string;
+        meta?: any;
+    };
+    /**
+     * Export collected data to CSV for PhD paper analysis
+     */
+    exportExperimentResults(filename?: string): void;
+}
+/**
+ * Test environment configuration
+ */
+export interface TestEnvironmentConfig {
+    accountCount?: number;
+    fundEachEOAWithETH?: bigint;
+    fundEachAAWithETH?: bigint;
+    startingSalt?: number;
+    tokens?: {
+        [tokenName: string]: {
+            address: Address;
+            amount: bigint;
+            fundEOA?: boolean;
+            fundAA?: boolean;
+        };
+    };
+}
+/**
+ * Complete test environment
+ */
+export interface TestEnvironment {
+    accounts: TestAccount[];
+    tokenFunding: TokenFundingRecord[];
+}
+/**
+ * Token funding record
+ */
+export interface TokenFundingRecord {
+    account: string;
+    token: string;
+    eoaAmount: bigint;
+    aaAmount: bigint;
+}
+/**
+ * Test account data structure
+ */
+export interface TestAccount {
+    label: string;
+    ownerKey: `0x${string}`;
+    ownerAddress: Address;
+    aaAddress: Address;
+    deployTxHash: Hash;
+    salt: number;
+}

package/dist/enduser/src/testAccountManager.js

@@ -0,0 +1,271 @@
+import { parseEther } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { accountFactoryActions, TEST_ACCOUNT_ADDRESSES } from '@aastar/core';
+/**
+ * PhD Paper Experiment Test Toolkit
+ *
+ * **Purpose**: Comprehensive API suite for preparing and managing test accounts
+ * for ERC-4337 performance comparison experiments (EOA vs AA vs SuperPaymaster).
+ *
+ * **Core Features**:
+ * 1. **Account Generation**: Create random EOA keys and deploy SimpleAccounts
+ * 2. **Token Funding**: Transfer test tokens (GToken, aPNTs, bPNTs, ETH)
+ * 3. **AA Deployment**: Deploy SimpleAccount contracts using official factory
+ * 4. **UserOp Execution**: Send ERC-4337 UserOperations with various paymasters
+ * 5. **Data Collection**: Generate experiment data for PhD paper analysis
+ *
+ * @example
+ * ```typescript
+ * const toolkit = new TestAccountManager(publicClient, supplierWallet);
+ *
+ * // Prepare complete test environment
+ * const env = await toolkit.prepareTestEnvironment({
+ *   accountCount: 3,
+ *   fundEachEOAWithETH: parseEther("0.01"),
+ *   fundEachAAWithETH: parseEther("0.02"),
+ *   tokens: {
+ *     gToken: { address: '0x...', amount: parseEther("100") },
+ *     aPNTs: { address: '0x...', amount: parseEther("50") }
+ *   }
+ * });
+ * ```
+ */
+export class TestAccountManager {
+    publicClient;
+    walletClient;
+    constructor(
+    /** @internal */
+    publicClient, 
+    /** @internal */
+    walletClient) {
+        this.publicClient = publicClient;
+        this.walletClient = walletClient;
+        if (!walletClient.account) {
+            // Placeholder account if not provided to avoid strict null checks in experiments
+            // In production, the consumer must ensure the wallet is connected.
+        }
+    }
+    /**
+     * Prepare complete test environment for PhD experiments
+     *
+     * **Workflow**:
+     * 1. Generate N random EOA private keys
+     * 2. Deploy SimpleAccount for each EOA
+     * 3. Fund EOAs with ETH
+     * 4. Fund AAs with ETH
+     * 5. Transfer test tokens (GToken, aPNTs, bPNTs) to both EOAs and AAs
+     *
+     * @param config - Test environment configuration
+     * @returns Complete test environment with all accounts and tokens ready
+     */
+    async prepareTestEnvironment(config) {
+        const { accountCount = 3, fundEachEOAWithETH = parseEther("0.01"), fundEachAAWithETH = parseEther("0.02"), tokens = {}, startingSalt = 0 } = config;
+        console.log(`🧪 Preparing PhD Experiment Test Environment (${accountCount} accounts)...\n`);
+        const accounts = [];
+        const labels = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'];
+        const factoryAddress = TEST_ACCOUNT_ADDRESSES.simpleAccountFactory;
+        const factoryRead = accountFactoryActions(factoryAddress)(this.publicClient);
+        const factoryWrite = accountFactoryActions(factoryAddress)(this.walletClient);
+        // Step 1: Generate accounts and deploy AAs
+        for (let i = 0; i < accountCount; i++) {
+            const label = labels[i] || `${i + 1}`;
+            console.log(`\n📝 [${i + 1}/${accountCount}] Setting up Account ${label}...`);
+            // Generate EOA
+            const ownerKey = generatePrivateKey();
+            const ownerAccount = privateKeyToAccount(ownerKey);
+            console.log(`   🔑 EOA: ${ownerAccount.address}`);
+            // Deploy AA
+            const salt = BigInt(startingSalt + i);
+            console.log(`   🏭 Deploying SimpleAccount (salt: ${salt})...`);
+            // Predict address
+            const accountAddress = await factoryRead.getAddress({ owner: ownerAccount.address, salt });
+            // Deploy if needed (createAccount sends tx regardless, or we can check code?)
+            // For simplicitly we just call createAccount. If already deployed it might revert?
+            // SimpleAccountFactory doesn't seem to check existence in createAccount, but CREATE2 validates.
+            // But we are using a fresh key/salt, so collision is unlikely unless we rerun.
+            // We'll try-catch or just execute.
+            let deployTxHash = '0x0';
+            try {
+                deployTxHash = await factoryWrite.createAccount({
+                    owner: ownerAccount.address,
+                    salt,
+                    account: this.walletClient.account
+                });
+                await this.publicClient.waitForTransactionReceipt({ hash: deployTxHash });
+            }
+            catch (e) {
+                console.log(`      ⚠️ Deployment might have failed (or already deployed): ${e.message?.split('\n')[0]}`);
+            }
+            console.log(`   ✅ AA: ${accountAddress}`);
+            // Fund AA with ETH
+            if (fundEachAAWithETH > 0n) {
+                console.log(`   ⛽ Funding AA with ${fundEachAAWithETH} wei ETH...`);
+                const fundTx = await this.walletClient.sendTransaction({
+                    to: accountAddress,
+                    value: fundEachAAWithETH,
+                    account: this.walletClient.account,
+                    chain: this.walletClient.chain
+                });
+                await this.publicClient.waitForTransactionReceipt({ hash: fundTx });
+            }
+            // Fund EOA with ETH
+            if (fundEachEOAWithETH > 0n) {
+                console.log(`   ⛽ Funding EOA with ${fundEachEOAWithETH} wei ETH...`);
+                const fundTx = await this.walletClient.sendTransaction({
+                    to: ownerAccount.address,
+                    value: fundEachEOAWithETH,
+                    account: this.walletClient.account,
+                    chain: this.walletClient.chain
+                });
+                await this.publicClient.waitForTransactionReceipt({ hash: fundTx });
+            }
+            accounts.push({
+                label,
+                ownerKey,
+                ownerAddress: ownerAccount.address,
+                aaAddress: accountAddress,
+                deployTxHash,
+                salt: startingSalt + i
+            });
+        }
+        // Step 2: Fund with test tokens
+        console.log(`\n💰 Funding accounts with test tokens...`);
+        const tokenFunding = [];
+        for (const [tokenName, tokenConfig] of Object.entries(tokens)) {
+            if (!tokenConfig)
+                continue;
+            console.log(`\n   📊 Distributing ${tokenName}...`);
+            const erc20Abi = [
+                { name: 'transfer', type: 'function', stateMutability: 'nonpayable', inputs: [{ name: 'to', type: 'address' }, { name: 'amount', type: 'uint256' }], outputs: [{ name: '', type: 'bool' }] }
+            ];
+            for (const account of accounts) {
+                // Fund EOA
+                if (tokenConfig.fundEOA !== false) {
+                    const tx = await this.walletClient.writeContract({
+                        address: tokenConfig.address,
+                        abi: erc20Abi,
+                        functionName: 'transfer',
+                        args: [account.ownerAddress, tokenConfig.amount],
+                        account: this.walletClient.account,
+                        chain: this.walletClient.chain
+                    });
+                    await this.publicClient.waitForTransactionReceipt({ hash: tx });
+                    console.log(`      ✅ ${account.label} EOA: ${tokenConfig.amount}`);
+                }
+                // Fund AA
+                if (tokenConfig.fundAA !== false) {
+                    const tx = await this.walletClient.writeContract({
+                        address: tokenConfig.address,
+                        abi: erc20Abi,
+                        functionName: 'transfer',
+                        args: [account.aaAddress, tokenConfig.amount],
+                        account: this.walletClient.account,
+                        chain: this.walletClient.chain
+                    });
+                    await this.publicClient.waitForTransactionReceipt({ hash: tx });
+                    console.log(`      ✅ ${account.label} AA: ${tokenConfig.amount}`);
+                }
+                tokenFunding.push({
+                    account: account.label,
+                    token: tokenName,
+                    eoaAmount: tokenConfig.fundEOA !== false ? tokenConfig.amount : 0n,
+                    aaAmount: tokenConfig.fundAA !== false ? tokenConfig.amount : 0n
+                });
+            }
+        }
+        console.log(`\n✅ Test environment ready!`);
+        return { accounts, tokenFunding };
+    }
+    /**
+     * Generate multiple test accounts for experiments
+     * (Simplified version without token funding)
+     */
+    async generateTestAccounts(count = 3, options = {}) {
+        const { fundEachAAWith = parseEther("0.02"), fundEachEOAWith = parseEther("0.01"), startingSalt = 0 } = options;
+        const env = await this.prepareTestEnvironment({
+            accountCount: count,
+            fundEachEOAWithETH: fundEachEOAWith,
+            fundEachAAWithETH: fundEachAAWith,
+            startingSalt
+        });
+        return env.accounts;
+    }
+    /**
+     * Export test accounts to .env format
+     */
+    exportToEnv(accounts) {
+        const lines = [
+            '# Test Accounts for PhD Paper Experiments',
+            '# Generated by TestAccountManager API',
+            ''
+        ];
+        accounts.forEach(acc => lines.push(`TEST_OWNER_KEY_${acc.label}=${acc.ownerKey}`));
+        lines.push('');
+        accounts.forEach(acc => lines.push(`TEST_OWNER_EOA_${acc.label}=${acc.ownerAddress}`));
+        lines.push('');
+        accounts.forEach(acc => lines.push(`TEST_SIMPLE_ACCOUNT_${acc.label}=${acc.aaAddress}`));
+        return lines.join('\n');
+    }
+    /**
+     * Load test accounts from environment variables
+     */
+    static loadFromEnv(labels = ['A', 'B', 'C']) {
+        return labels.map(label => {
+            const ownerKey = process.env[`TEST_OWNER_KEY_${label}`];
+            const ownerAddress = process.env[`TEST_OWNER_EOA_${label}`];
+            const aaAddress = process.env[`TEST_SIMPLE_ACCOUNT_${label}`];
+            if (!ownerKey || !ownerAddress || !aaAddress)
+                return null;
+            return {
+                label,
+                ownerKey: ownerKey,
+                ownerAddress: ownerAddress,
+                aaAddress: aaAddress,
+                deployTxHash: '0x0',
+                salt: 0
+            };
+        });
+    }
+    /**
+     * Get a single test account by label
+     */
+    static getTestAccount(label) {
+        const accounts = TestAccountManager.loadFromEnv([label]);
+        return accounts[0] || null;
+    }
+    // --- Data Collection Extensions ---
+    records = [];
+    /**
+     * Add a standardized experiment record
+     */
+    addExperimentRecord(record) {
+        const fullRecord = {
+            ...record,
+            id: `${Date.now()}-${Math.floor(Math.random() * 1000)}`,
+            timestamp: Date.now(),
+            costETH: formatEther(record.gasUsed * record.gasPrice)
+        };
+        this.records.push(fullRecord);
+        return fullRecord;
+    }
+    /**
+     * Export collected data to CSV for PhD paper analysis
+     */
+    exportExperimentResults(filename = 'sdk_experiment_data.csv') {
+        const fs = require('fs');
+        const path = require('path');
+        const headers = ['ID', 'Scenario', 'Group', 'TxHash', 'GasUsed', 'GasPrice', 'CostETH', 'Status', 'Timestamp', 'Latency'];
+        const rows = this.records.map(r => [
+            r.id, r.scenario, r.group, r.txHash,
+            r.gasUsed.toString(), r.gasPrice.toString(), r.costETH,
+            r.status, new Date(r.timestamp).toISOString(),
+            r.meta?.latency || ''
+        ].join(','));
+        const csv = [headers.join(','), ...rows].join('\n');
+        fs.writeFileSync(path.join(process.cwd(), filename), csv);
+        console.log(`📊 Exported ${this.records.length} records to ${filename}`);
+    }
+}
+function formatEther(wei) {
+    return (Number(wei) / 1e18).toString();
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from './CommunityClient.js';
 export * from './UserClient.js';
+export * from './CommunityClient.js';
+export * from './UserLifecycle.js';

package/dist/index.js

@@ -1,2 +1,3 @@
-export * from './CommunityClient.js';
 export * from './UserClient.js';
+export * from './CommunityClient.js';
+export * from './UserLifecycle.js';

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

@@ -0,0 +1,28 @@
+import { type Address } from 'viem';
+/**
+ * Bundler types we support
+ */
+export declare enum BundlerType {
+    ALCHEMY = "alchemy",
+    PIMLICO = "pimlico",
+    STACKUP = "stackup",
+    CANDIDE = "candide",
+    UNKNOWN = "unknown"
+}
+/**
+ * Detect bundler type from URL
+ */
+export declare function detectBundlerType(bundlerUrl: string): BundlerType;
+/**
+ * Minimal interface to satisfy basic Pimlico/Bundler needs
+ * without bringing in heavy permissionless types that might conflict
+ */
+export interface BundlerConfig {
+    type: BundlerType;
+    url: string;
+    entryPoint: Address;
+}
+/**
+ * Create a bundler client config
+ */
+export declare function createBundlerClient(bundlerUrl: string, entryPoint: Address): BundlerConfig;

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

@@ -0,0 +1,37 @@
+/**
+ * Bundler types we support
+ */
+export var BundlerType;
+(function (BundlerType) {
+    BundlerType["ALCHEMY"] = "alchemy";
+    BundlerType["PIMLICO"] = "pimlico";
+    BundlerType["STACKUP"] = "stackup";
+    BundlerType["CANDIDE"] = "candide";
+    BundlerType["UNKNOWN"] = "unknown";
+})(BundlerType || (BundlerType = {}));
+/**
+ * Detect bundler type from URL
+ */
+export function detectBundlerType(bundlerUrl) {
+    const url = bundlerUrl.toLowerCase();
+    if (url.includes('alchemy.com'))
+        return BundlerType.ALCHEMY;
+    if (url.includes('pimlico.io'))
+        return BundlerType.PIMLICO;
+    if (url.includes('stackup'))
+        return BundlerType.STACKUP;
+    if (url.includes('candide.dev'))
+        return BundlerType.CANDIDE;
+    return BundlerType.UNKNOWN;
+}
+/**
+ * Create a bundler client config
+ */
+export function createBundlerClient(bundlerUrl, entryPoint) {
+    const bundlerType = detectBundlerType(bundlerUrl);
+    return {
+        type: bundlerType,
+        url: bundlerUrl,
+        entryPoint
+    };
+}

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

@@ -0,0 +1,89 @@
+import { type Address, type Hex } from 'viem';
+/**
+ * PaymasterClient
+ * Focus: Integration, Funding, Interaction.
+ */
+export declare class PaymasterClient {
+    /**
+     * @private
+     * Static utility class, should not be instantiated.
+     */
+    private constructor();
+    /**
+     * 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}`;
+    /**
+     * More robust version of waitForUserOperationReceipt.
+     * Catches timeouts and returns a cleaner result.
+     */
+    static waitForUserOperation(bundlerClient: any, hash: `0x${string}`, timeout?: number): Promise<any>;
+}