@aastar/enduser 0.16.11

package/dist/UserClient.js

@@ -0,0 +1,395 @@
+import { BaseClient } from '@aastar/core';
+import { accountActions, sbtActions, tokenActions, entryPointActions, stakingActions, registryActions } from '@aastar/core';
+import { bundlerActions, getUserOperationHash } from 'viem/account-abstraction';
+import { encodeFunctionData } from 'viem';
+export class UserClient extends BaseClient {
+    accountAddress;
+    sbtAddress;
+    entryPointAddress;
+    gTokenStakingAddress;
+    registryAddress;
+    gTokenAddress;
+    constructor(config) {
+        super(config);
+        this.accountAddress = config.accountAddress;
+        this.sbtAddress = config.sbtAddress;
+        this.entryPointAddress = config.entryPointAddress;
+        this.gTokenStakingAddress = config.gTokenStakingAddress;
+        this.registryAddress = config.registryAddress;
+        this.gTokenAddress = config.gTokenAddress;
+    }
+    // ========================================
+    // 1. 账户基本操作 (基于 L1 simpleAccountActions)
+    // ========================================
+    /**
+     * Get the nonce of the account from EntryPoint (more reliable for 4337)
+     */
+    async getNonce(key = 0n) {
+        try {
+            if (!this.entryPointAddress) {
+                throw new Error('EntryPoint address required for this client');
+            }
+            const entryPoint = entryPointActions(this.entryPointAddress);
+            return await entryPoint(this.getStartPublicClient()).getNonce({
+                sender: this.accountAddress,
+                key
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Get the owner of the AA account
+     */
+    async getOwner() {
+        try {
+            const account = accountActions(this.accountAddress);
+            return await account(this.getStartPublicClient()).owner();
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Execute a transaction from the AA account
+     */
+    async execute(target, value, data, options) {
+        try {
+            const account = accountActions(this.accountAddress);
+            // Use standard AA execute
+            return await account(this.client).execute({
+                dest: target,
+                value,
+                func: data,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Execute a batch of transactions
+     */
+    async executeBatch(targets, values, datas, options) {
+        try {
+            const account = accountActions(this.accountAddress);
+            return await account(this.client).executeBatch({
+                dest: targets,
+                value: values,
+                func: datas,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // identity 与 SBT (基于 L1 sbtActions)
+    // ========================================
+    /**
+     * Get user's SBT balance
+     */
+    async getSBTBalance() {
+        try {
+            if (!this.sbtAddress)
+                throw new Error('SBT address required for this client');
+            const sbt = sbtActions(this.sbtAddress);
+            return await sbt(this.getStartPublicClient()).balanceOf({
+                owner: this.accountAddress
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Self-mint SBT for a role (user self-service)
+     */
+    async mintSBT(roleId, options) {
+        try {
+            if (!this.sbtAddress)
+                throw new Error('SBT address required for this client');
+            const sbt = sbtActions(this.sbtAddress);
+            return await sbt(this.client).mintForRole({
+                user: this.accountAddress,
+                roleId,
+                roleData: '0x',
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 3. 资产管理 (基于 L1 tokenActions)
+    // ========================================
+    /**
+     * Transfer GToken or any ERC20
+     */
+    async transferToken(token, to, amount, options) {
+        try {
+            const tokens = tokenActions()(this.client);
+            return await tokens.transfer({
+                token,
+                to,
+                amount,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Get Token Balance
+     */
+    async getTokenBalance(token) {
+        try {
+            const tokens = tokenActions()(this.getStartPublicClient());
+            return await tokens.balanceOf({
+                token,
+                account: this.accountAddress
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 4. 委托与质押 (Delegation & Staking)
+    // ========================================
+    /**
+     * Delegate stake to a role (Delegate to an operator/community)
+     */
+    async stakeForRole(roleId, amount, options) {
+        try {
+            if (!this.gTokenStakingAddress)
+                throw new Error('GTokenStaking address required for this client');
+            const staking = stakingActions(this.gTokenStakingAddress);
+            return await staking(this.client).lockStake({
+                user: this.accountAddress,
+                roleId,
+                stakeAmount: amount,
+                entryBurn: 0n,
+                payer: this.accountAddress,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Unstake from a role
+     */
+    async unstakeFromRole(roleId, options) {
+        try {
+            if (!this.gTokenStakingAddress)
+                throw new Error('GTokenStaking address required for this client');
+            const staking = stakingActions(this.gTokenStakingAddress);
+            return await staking(this.client).unlockAndTransfer({
+                user: this.accountAddress,
+                roleId,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Get staked balance for a specific role
+     */
+    async getStakedBalance(roleId) {
+        try {
+            if (!this.gTokenStakingAddress)
+                throw new Error('GTokenStaking address required for this client');
+            const staking = stakingActions(this.gTokenStakingAddress);
+            return await staking(this.getStartPublicClient()).getLockedStake({
+                user: this.accountAddress,
+                roleId
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 5. 生命周期管理 (Lifecycle)
+    // ========================================
+    /**
+     * Exit a specific role (Cleanup registry status)
+     */
+    async exitRole(roleId, options) {
+        try {
+            if (!this.registryAddress)
+                throw new Error('Registry address required for this client');
+            const registry = registryActions(this.registryAddress);
+            return await registry(this.client).exitRole({
+                roleId,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Leave a community (Burn SBT and clean up)
+     */
+    async leaveCommunity(community, options) {
+        try {
+            if (!this.sbtAddress)
+                throw new Error('SBT address required for this client');
+            const sbt = sbtActions(this.sbtAddress);
+            return await sbt(this.client).leaveCommunity({
+                community,
+                account: options?.account
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Register as EndUser (One-click: Approve + Register)
+     * Handles GToken approval to Staking contract and Role registration.
+     */
+    async registerAsEndUser(communityAddress, stakeAmount, options) {
+        try {
+            if (!this.registryAddress)
+                throw new Error('Registry address required for this client');
+            if (!this.gTokenStakingAddress)
+                throw new Error('GTokenStaking address required for this client');
+            if (!this.gTokenAddress)
+                throw new Error('GToken address required for this client');
+            const { encodeAbiParameters, keccak256, toBytes, parseEther } = await import('viem');
+            const ROLE_ENDUSER = keccak256(toBytes("ENDUSER"));
+            // Correct mapping for Registry Actions
+            const registry = registryActions(this.registryAddress);
+            const tokens = tokenActions()(this.getStartPublicClient());
+            // 1. Check Allowance
+            const allowance = await tokens.allowance({
+                token: this.gTokenAddress,
+                owner: this.accountAddress,
+                spender: this.gTokenStakingAddress
+            });
+            const txs = [];
+            if (allowance < stakeAmount) {
+                const approveData = encodeFunctionData({
+                    abi: [{ name: 'approve', type: 'function', inputs: [{ type: 'address' }, { type: 'uint256' }], outputs: [{ type: 'bool' }], stateMutability: 'nonpayable' }],
+                    functionName: 'approve',
+                    args: [this.gTokenStakingAddress, parseEther('1000')]
+                });
+                txs.push({ target: this.gTokenAddress, value: 0n, data: approveData });
+            }
+            // 2. Construct Register Call
+            // struct EndUserRoleData { address account; address community; string avatarURI; string ensName; uint256 stakeAmount; }
+            const roleData = encodeAbiParameters([
+                { type: 'address', name: 'account' },
+                { type: 'address', name: 'community' },
+                { type: 'string', name: 'avatarURI' },
+                { type: 'string', name: 'ensName' },
+                { type: 'uint256', name: 'stakeAmount' }
+            ], [
+                this.accountAddress,
+                communityAddress,
+                '',
+                '',
+                stakeAmount
+            ]);
+            const registerData = encodeFunctionData({
+                abi: [{ name: 'registerRoleSelf', type: 'function', inputs: [{ type: 'bytes32' }, { type: 'bytes' }], outputs: [{ type: 'uint256' }], stateMutability: 'nonpayable' }],
+                functionName: 'registerRoleSelf',
+                args: [ROLE_ENDUSER, roleData]
+            });
+            txs.push({ target: this.registryAddress, value: 0n, data: registerData });
+            // 3. Execute
+            if (txs.length === 1) {
+                return await this.execute(txs[0].target, txs[0].value, txs[0].data, options);
+            }
+            else {
+                return await this.executeBatch(txs.map(t => t.target), txs.map(t => t.value), txs.map(t => t.data), options);
+            }
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // ========================================
+    // 6. Gasless Execution (Advanced)
+    // ========================================
+    /**
+     * Execute a transaction with Gasless Sponsorship
+     */
+    async executeGasless(params, options) {
+        try {
+            const client = this.client.extend(bundlerActions);
+            const ep = this.requireEntryPoint();
+            const publicClient = this.getStartPublicClient();
+            // 1. Prepare Call Data
+            const callData = encodeFunctionData({
+                abi: [{ name: 'execute', type: 'function', inputs: [{ name: 'dest', type: 'address' }, { name: 'value', type: 'uint256' }, { name: 'func', type: 'bytes' }], outputs: [] }],
+                functionName: 'execute',
+                args: [params.target, params.value, params.data]
+            });
+            // 2. Prepare Paymaster Data
+            let paymasterAndData = params.paymaster;
+            // Note: In real scenarios, PM V4 or Super might need additional encoded data.
+            // For now, we use the address as the base.
+            // 3. Estimate Gas
+            const sender = this.accountAddress;
+            const nonce = await this.getNonce();
+            const userOpPartial = {
+                sender,
+                nonce,
+                initCode: '0x',
+                callData,
+                paymasterAndData,
+                signature: '0x'
+            };
+            const gasEstimate = await client.estimateUserOperationGas({
+                userOperation: userOpPartial,
+                entryPoint: ep
+            });
+            // 4. Construct Final UserOp 
+            const fees = await publicClient.estimateFeesPerGas();
+            const userOp = {
+                ...userOpPartial,
+                callGasLimit: gasEstimate.callGasLimit,
+                verificationGasLimit: gasEstimate.verificationGasLimit + 50000n,
+                preVerificationGas: gasEstimate.preVerificationGas,
+                maxFeePerGas: fees.maxFeePerGas || fees.gasPrice || 1000000000n,
+                maxPriorityFeePerGas: fees.maxPriorityFeePerGas || 1000000000n
+            };
+            // 5. Sign
+            const chainId = this.client.chain?.id || 31337;
+            const hash = getUserOperationHash({
+                userOperation: userOp,
+                entryPointAddress: ep,
+                entryPointVersion: '0.7',
+                chainId
+            });
+            const signature = await this.client.signMessage({
+                message: { raw: hash },
+                account: this.client.account
+            });
+            const signedUserOp = {
+                ...userOp,
+                signature
+            };
+            // 6. Send
+            return await client.sendUserOperation({
+                userOperation: signedUserOp,
+                entryPoint: ep
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/testAccountManager.d.ts

@@ -0,0 +1,142 @@
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
+/**
+ * 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 {
+    private publicClient;
+    private walletClient;
+    constructor(publicClient: PublicClient, 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;
+}