@aastar/enduser 0.16.11

package/dist/testAccountManager.js

@@ -0,0 +1,267 @@
+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(publicClient, 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/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@aastar/enduser",
+  "version": "0.16.11",
+  "type": "module",
+  "description": "Enduser client for AAstar SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "aastar",
+    "enduser",
+    "web3"
+  ],
+  "author": "AAstar Team",
+  "license": "MIT",
+  "dependencies": {
+    "viem": "2.43.3",
+    "@aastar/core": "0.16.11"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}

package/src/CommunityClient.ts

@@ -0,0 +1,235 @@
+import { type Address, type Hash, parseEther, encodeAbiParameters, parseAbiParameters } from 'viem';
+import { BaseClient, type ClientConfig, type TransactionOptions } from '@aastar/core';
+import { registryActions, sbtActions, xPNTsFactoryActions, reputationActions, tokenActions } from '@aastar/core';
+
+export interface CommunityClientConfig extends ClientConfig {
+    sbtAddress?: Address;
+    factoryAddress?: Address;
+    reputationAddress?: Address;
+}
+
+export interface CreateCommunityParams {
+    name: string;
+    tokenSymbol: string;
+    ensName?: string;
+    description?: string;
+}
+
+export interface CommunityInfo {
+    address: Address; // Community ID (hash) usually, but here likely the SBT/profile? No, Community in Registry is bytes32 ID.
+    // Wait, Registry defines Community as a Role (ROLE_COMMUNITY).
+    // The "Community" entity usually implies a collection of contracts (Token, maybe Paymaster).
+}
+
+/**
+ * Client for Community Managers (`ROLE_COMMUNITY`)
+ */
+export class CommunityClient extends BaseClient {
+    public sbtAddress?: Address;
+    public factoryAddress?: Address;
+    public reputationAddress?: Address;
+
+    constructor(config: CommunityClientConfig) {
+        super(config);
+        this.sbtAddress = config.sbtAddress;
+        this.factoryAddress = config.factoryAddress;
+        this.reputationAddress = config.reputationAddress;
+    }
+
+    // ========================================
+    // 1. 社区创建与配置
+    // ========================================
+
+    /**
+     * Create a new Community Token (xPNTs) and register it.
+     * Note: In the current architecture, creating a community often involves:
+     * 1. Registering the ROLE_COMMUNITY on Registry (if not exists) -> usually manual or self-register
+     * 2. Deploying a Token (xPNTs) via Factory
+     * 3. Linking the Token to the Community in Registry
+     */
+    async createCommunityToken(params: CreateCommunityParams, options?: TransactionOptions): Promise<Hash> {
+        try {
+            if (!this.factoryAddress) {
+                throw new Error('Factory address required for this client');
+            }
+            const factory = xPNTsFactoryActions(this.factoryAddress);
+
+            // 1. Deploy Token
+            // Note: The address calculation should be handled via event parsing or predictive deployment
+            // For now, returning the transaction hash as per L1 pattern
+            return await factory(this.client).createToken({
+                name: params.name,
+                symbol: params.tokenSymbol,
+                community: '0x0000000000000000000000000000000000000000', // Default empty community mapping
+                account: options?.account
+            });
+        } catch (error) {
+            // Error is likely already an AAStarError from L1, but we wrap it for context
+            throw error; 
+        }
+    }
+
+    /**
+     * Register self as a Community Manager.
+     * This method handles all necessary steps:
+     * 1. Checks and approves GToken to GTokenStaking
+     * 2. Encodes CommunityRoleData with provided parameters
+     * 3. Calls registerRoleSelf on Registry
+     * 
+     * @param params Community registration parameters
+     * @param options Transaction options
+     * @returns Transaction hash
+     */
+    async registerAsCommunity(params: {
+        name: string;
+        ensName?: string;
+        website?: string;
+        description?: string;
+        logoURI?: string;
+        stakeAmount?: bigint;
+    }, options?: TransactionOptions): Promise<Hash> {
+        try {
+            const registryAddr = this.requireRegistry();
+            const registry = registryActions(registryAddr);
+            const gTokenStakingAddr = this.requireGTokenStaking();
+            const gTokenAddr = this.requireGToken();
+            
+            // 1. Get ROLE_COMMUNITY
+            const roleCommunity = await registry(this.getStartPublicClient()).ROLE_COMMUNITY();
+            
+            // 2. Prepare stake amount (default 30 GToken as per Registry config)
+            const stakeAmount = params.stakeAmount || parseEther('30');
+            
+            // 3. Check and approve GToken to GTokenStaking if needed
+            const gToken = tokenActions();
+            
+            const allowance = await gToken(this.getStartPublicClient()).allowance({
+                token: gTokenAddr,
+                owner: this.getAddress(),
+                spender: gTokenStakingAddr
+            });
+            
+            if (allowance < stakeAmount) {
+                const approveHash = await gToken(this.client).approve({
+                    token: gTokenAddr,
+                    spender: gTokenStakingAddr,
+                    amount: stakeAmount * BigInt(2), // Approve 2x for future use
+                    account: options?.account
+                });
+                await (this.getStartPublicClient() as any).waitForTransactionReceipt({ hash: approveHash });
+            }
+            
+            // 4. Encode CommunityRoleData
+            // struct CommunityRoleData { string name; string ensName; string website; string description; string logoURI; uint256 stakeAmount; }
+            const communityData = encodeAbiParameters(
+                parseAbiParameters('string, string, string, string, string, uint256'),
+                [
+                    params.name,
+                    params.ensName || '',
+                    params.website || '',
+                    params.description || `${params.name} Community`,
+                    params.logoURI || '',
+                    stakeAmount
+                ]
+            );
+            
+            // 5. Register role
+            return await registry(this.client).registerRoleSelf({
+                roleId: roleCommunity,
+                data: communityData,
+                account: options?.account
+            });
+        } catch (error) {
+            throw error;
+        }
+    }
+
+    // ========================================
+    // 2. 成员管理
+    // ========================================
+
+    /**
+     * Airdrop SBTs to users to make them members
+     */
+    async airdropSBT(users: Address[], roleId: bigint, options?: TransactionOptions): Promise<Hash> {
+        try {
+            if (!this.sbtAddress) throw new Error('SBT address required for this client');
+            const sbt = sbtActions(this.sbtAddress);
+
+            if (users.length === 1) {
+                // Convert roleId to Hex (bytes32)
+                const roleIdHex = `0x${roleId.toString(16).padStart(64, '0')}` as Hash;
+
+                return await sbt(this.client).mintForRole({
+                    user: users[0],
+                    roleId: roleIdHex,
+                    roleData: '0x',
+                    account: options?.account
+                });
+            }
+            
+            throw new Error('Batch airdrop not fully implemented in L1 yet, use single user');
+        } catch (error) {
+            throw error;
+        }
+    }
+
+    // ========================================
+    // 3. 信誉系统
+    // ========================================
+
+    async setReputationRule(ruleId: bigint, ruleConfig: any, options?: TransactionOptions): Promise<Hash> {
+        try {
+            if (!this.reputationAddress) throw new Error('Reputation address required for this client');
+            const reputation = reputationActions(this.reputationAddress);
+            
+            const ruleIdHex = `0x${ruleId.toString(16).padStart(64, '0')}` as Hash;
+
+            return await reputation(this.client).setReputationRule({
+                ruleId: ruleIdHex,
+                rule: ruleConfig,
+                account: options?.account
+            });
+        } catch (error) {
+            throw error;
+        }
+    }
+
+    // ========================================
+    // 4. 管理功能
+    // ========================================
+
+    /**
+     * Revoke membership (Burn SBT)
+     */
+    async revokeMembership(userAddr: Address, options?: TransactionOptions): Promise<Hash> {
+        try {
+            if (!this.sbtAddress) throw new Error('SBT address required for this client');
+            const sbt = sbtActions(this.sbtAddress);
+            
+            return await sbt(this.client).burnSBT({
+                user: userAddr,
+                account: options?.account
+            });
+        } catch (error) {
+            throw error;
+        }
+    }
+
+    /**
+     * Transfer ownership of the Community Token
+     */
+    async transferCommunityTokenOwnership(tokenAddress: Address, newOwner: Address, options?: TransactionOptions): Promise<Hash> {
+        try {
+            const token = tokenActions()(this.client);
+            
+            return await token.transferOwnership({
+                token: tokenAddress,
+                newOwner,
+                account: options?.account
+            });
+        } catch (error) {
+            throw error;
+        }
+    }
+}