@aastar/sdk 0.16.8 → 0.16.12

package/README.md

@@ -138,6 +138,27 @@ AAstar SDK 基于 **viem** 构建，确保轻量级和类型安全的交互。
 
 ---
 
+## 📊 Gas Analytics & Reporting | Gas 分析与报表
+The SDK includes a powerful **Gas Analytics Module** for analyzing Paymaster efficiency, tracking costs, and generating industry comparison reports.
+SDK 包含一个强大的 **Gas 分析模块**，用于分析 Paymaster 效率、追踪成本并生成行业对比报告。
+
+### Quick Start | 快速开始
+Generate a real-time analysis of recent Sepolia transactions:
+生成最近 Sepolia 交易的实时分析：
+```bash
+npx tsx packages/analytics/src/gas-analyzer-v4.ts
+```
+
+### Key Features | 核心功能
+- **Double-Layer Analysis (双层分析)**: Intrinsic EVM Efficiency vs. Economic USD Costs
+- **Industry Benchmarking (行业对标)**: Compare AAStar vs. Optimism, Alchemy, Pimlico
+- **Profit Tracking (利润追踪)**: Transparent breakdown of Protocol Revenue & Profit
+- **L2 Simulation (L2 模拟)**: Estimate savings for migrating UserOps to Optimism
+
+👉 **[View Full Analytics Documentation | 查看完整分析文档](./packages/analytics/README.md)**
+
+---
+
 ## 🤝 Contributing | 贡献
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.  

package/dist/clients/admin.d.ts

@@ -0,0 +1,11 @@
+import { type Client, type Transport, type Chain, type Account, type PublicActions, type WalletActions, type Address } from 'viem';
+import { type RegistryActions, type SuperPaymasterActions, type PaymasterActions, type StakingActions, type SBTActions, type DVTActions, type XPNTsFactoryActions, type AggregatorActions } from '@aastar/core';
+export type AdminClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SuperPaymasterActions & PaymasterActions & StakingActions & SBTActions & DVTActions & XPNTsFactoryActions & AggregatorActions;
+export declare function createAdminClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): AdminClient;

package/dist/clients/admin.js

@@ -0,0 +1,20 @@
+import { createClient, publicActions, walletActions } from 'viem';
+import { registryActions, superPaymasterActions, paymasterActions, stakingActions, sbtActions, dvtActions, xPNTsFactoryActions, aggregatorActions, CORE_ADDRESSES, TOKEN_ADDRESSES } from '@aastar/core';
+const ADDRESS_PLACEHOLDER = '0x0000000000000000000000000000000000000000';
+export function createAdminClient({ chain, transport, account, addresses }) {
+    const baseClient = createClient({ chain, transport, account })
+        .extend(publicActions)
+        .extend(walletActions);
+    const usedAddresses = { ...CORE_ADDRESSES, ...TOKEN_ADDRESSES, ...addresses };
+    const actions = {
+        ...registryActions(usedAddresses.registry)(baseClient),
+        ...superPaymasterActions(usedAddresses.superPaymaster)(baseClient),
+        ...paymasterActions(usedAddresses.paymasterV4)(baseClient),
+        ...stakingActions(usedAddresses.gTokenStaking)(baseClient),
+        ...sbtActions(usedAddresses.mySBT)(baseClient),
+        ...dvtActions(ADDRESS_PLACEHOLDER)(baseClient),
+        ...xPNTsFactoryActions(usedAddresses.xPNTsFactory || '0x')(baseClient),
+        ...aggregatorActions(ADDRESS_PLACEHOLDER)(baseClient),
+    };
+    return Object.assign(baseClient, actions);
+}

package/dist/{sdk/src/clients → clients}/community.d.ts

@@ -1,7 +1,6 @@
-import { type Client, type Transport, type Chain, type Account, type Hash, type PublicActions, type WalletActions, type Address } from 'viem';
-import { type RegistryActions, type SBTActions, type ReputationActions } from '@aastar/core';
-import { type DecodedEvent } from '../utils/eventDecoder.js';
-export type CommunityClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SBTActions & ReputationActions & {
+import { type Client, type Transport, type Chain, type Account, type Hex, type PublicActions, type WalletActions, type Address } from 'viem';
+import { type RegistryActions, type SBTActions } from '@aastar/core';
+export type CommunityClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SBTActions & {
     /**
      * Query community registration status and token information
      * Returns null if not registered, otherwise returns community details
@@ -26,16 +25,9 @@ export type CommunityClient = Client<Transport, Chain, Account | undefined> & Pu
         description?: string;
         logoURI?: string;
         website?: string;
-        governance?: {
-            minStake?: bigint;
-            initialReputationRule?: boolean;
-        };
     }) => Promise<{
         tokenAddress: Address;
-        results: {
-            hash: Hash;
-            events: DecodedEvent[];
-        }[];
+        txs: Hex[];
     }>;
 };
 export declare function createCommunityClient({ chain, transport, account, addresses }: {

package/dist/clients/community.js

@@ -0,0 +1,300 @@
+import { createClient, publicActions, walletActions, erc20Abi } from 'viem';
+import { registryActions, RegistryABI, sbtActions, CORE_ADDRESSES, TEST_TOKEN_ADDRESSES } from '@aastar/core';
+import { RoleDataFactory, RoleIds } from '../utils/roleData.js';
+export function createCommunityClient({ chain, transport, account, addresses }) {
+    const client = createClient({
+        chain,
+        transport,
+        account
+    })
+        .extend(publicActions)
+        .extend(walletActions);
+    const usedAddresses = { ...CORE_ADDRESSES, ...TEST_TOKEN_ADDRESSES, ...addresses };
+    const registryActionsObj = registryActions(usedAddresses.registry)(client);
+    const sbtActionsObj = sbtActions(usedAddresses.mySBT)(client);
+    const launch = async (args) => {
+        try {
+            console.log(`🚀 Launching community: ${args.name}`);
+            if (!account) {
+                throw new Error('Account is required for launch()');
+            }
+            // Generate unique community name with timestamp
+            const uniqueName = `${args.name}_${Date.now()}`;
+            console.log(`   📝 Unique name: ${uniqueName}`);
+            // Generate roleData using RoleDataFactory
+            const roleData = RoleDataFactory.community({
+                name: uniqueName,
+                ensName: '',
+                website: args.website || '',
+                description: args.description || '',
+                logoURI: args.logoURI || '',
+                stakeAmount: 0n
+            });
+            console.log(`   ✅ RoleData generated:`, roleData);
+            console.log(`   📊 RoleData type:`, typeof roleData);
+            console.log(`   📏 RoleData length:`, roleData?.length);
+            // 1. Check if already has role
+            const hasRole = await client.readContract({
+                address: usedAddresses.registry,
+                abi: RegistryABI,
+                functionName: 'hasRole',
+                args: [RoleIds.COMMUNITY, account.address]
+            });
+            let registerTx;
+            if (hasRole) {
+                console.log(`   ℹ️  Account already has COMMUNITY role. Skipping registration.`);
+            }
+            else {
+                // 2. Check GToken Allowance and Balance
+                if (usedAddresses.gToken && usedAddresses.gTokenStaking) {
+                    console.log(`   💰 Checking GToken allowance...`);
+                    const balance = await client.readContract({
+                        address: usedAddresses.gToken,
+                        abi: erc20Abi,
+                        functionName: 'balanceOf',
+                        args: [account.address]
+                    });
+                    if (balance < 50000000000000000000n) { // 50 GT assumption, should ideally check minStake
+                        console.warn(`   ⚠️ Warning: Low GToken balance (${balance}). Registration may fail if minStake > balance.`);
+                    }
+                    const allowance = await client.readContract({
+                        address: usedAddresses.gToken,
+                        abi: erc20Abi,
+                        functionName: 'allowance',
+                        args: [account.address, usedAddresses.gTokenStaking]
+                    });
+                    if (allowance < 50000000000000000000n) {
+                        console.log(`   🔓 Approving GToken for Staking...`);
+                        const approveTx = await client.writeContract({
+                            address: usedAddresses.gToken,
+                            abi: erc20Abi,
+                            functionName: 'approve',
+                            args: [usedAddresses.gTokenStaking, 115792089237316195423570985008687907853269984665640564039457584007913129639935n], // MaxUint256
+                            account: account
+                        });
+                        console.log(`   ✅ Approved: ${approveTx}`);
+                        await client.waitForTransactionReceipt({ hash: approveTx });
+                    }
+                }
+                // Register community role
+                console.log(`   📤 Registering community role...`);
+                try {
+                    registerTx = await registryActionsObj.registerRole({
+                        roleId: RoleIds.COMMUNITY,
+                        user: account.address,
+                        data: roleData,
+                        account: account
+                    });
+                    console.log(`   ✅ Community registered: ${registerTx}`);
+                }
+                catch (e) {
+                    // Check for RoleAlreadyGranted (just in case hasRole returned false but race condition or cache)
+                    const isRoleError = e.message?.includes('RoleAlreadyGranted') ||
+                        e.cause?.data?.errorName === 'RoleAlreadyGranted' ||
+                        e.name === 'RoleAlreadyGranted' ||
+                        e.name === 'RoleAlreadyGranted';
+                    if (isRoleError) {
+                        console.log(`   ℹ️  Role already granted (caught in tx). Skipping.`);
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            // Deploy xPNTs token if factory is available
+            let tokenAddress = '0x0000000000000000000000000000000000000000';
+            const txs = [];
+            if (registerTx)
+                txs.push(registerTx);
+            if (usedAddresses.xPNTsFactory) {
+                if (!client.account) {
+                    throw new Error("Client account is required for token deployment");
+                }
+                // ABI from xPNTsFactory.sol
+                const factoryAbi = [
+                    {
+                        type: 'function',
+                        name: 'deployxPNTsToken',
+                        inputs: [
+                            { name: 'name', type: 'string' },
+                            { name: 'symbol', type: 'string' },
+                            { name: 'communityName', type: 'string' },
+                            { name: 'communityENS', type: 'string' },
+                            { name: 'exchangeRate', type: 'uint256' },
+                            { name: 'paymasterAOA', type: 'address' }
+                        ],
+                        outputs: [{ name: 'token', type: 'address' }],
+                        stateMutability: 'nonpayable'
+                    },
+                    {
+                        type: 'function',
+                        name: 'getTokenAddress',
+                        inputs: [{ name: 'community', type: 'address' }],
+                        outputs: [{ name: 'token', type: 'address' }],
+                        stateMutability: 'view'
+                    }
+                ];
+                // 1. Check if token already exists
+                try {
+                    const existingToken = await client.readContract({
+                        address: usedAddresses.xPNTsFactory,
+                        abi: factoryAbi,
+                        functionName: 'getTokenAddress',
+                        args: [account.address]
+                    });
+                    if (existingToken && existingToken !== '0x0000000000000000000000000000000000000000') {
+                        console.log(`   ℹ️  Found existing token at ${existingToken}`);
+                        tokenAddress = existingToken;
+                        // Return early or continue? Logic expects result.
+                        // If we found it, we don't need to deploy.
+                        return { tokenAddress, txs };
+                    }
+                }
+                catch (e) {
+                    console.warn(`   ⚠️ Failed to check for existing token:`, e);
+                }
+                console.log(`   🏭 Deploying Token via Factory: ${usedAddresses.xPNTsFactory}`);
+                try {
+                    // deployxPNTsToken(name, symbol, communityName, communityENS, exchangeRate, paymasterAOA)
+                    const { request } = await client.simulateContract({
+                        address: usedAddresses.xPNTsFactory,
+                        abi: factoryAbi,
+                        functionName: 'deployxPNTsToken',
+                        args: [
+                            args.tokenName,
+                            args.tokenSymbol,
+                            args.name, // communityName
+                            args.website || '', // communityENS (mapping website to ENS param for now)
+                            1000000000000000000n, // exchangeRate 1e18 (1:1)
+                            '0x0000000000000000000000000000000000000000' // paymasterAOA (optional)
+                        ],
+                        account: client.account
+                    });
+                    const deployTx = await client.writeContract(request);
+                    console.log(`   📤 Deploy Token Tx: ${deployTx}`);
+                    txs.push(deployTx);
+                    const receipt = await client.waitForTransactionReceipt({ hash: deployTx });
+                    // After deployment, fetch the address again
+                    const newTokenAddress = await client.readContract({
+                        address: usedAddresses.xPNTsFactory,
+                        abi: factoryAbi,
+                        functionName: 'getTokenAddress',
+                        args: [account.address]
+                    });
+                    if (newTokenAddress) {
+                        tokenAddress = newTokenAddress;
+                        console.log(`   🪙 Token Deployed: ${tokenAddress}`);
+                    }
+                }
+                catch (deployError) {
+                    console.warn('   ⚠️ Failed to deploy token, but community registered:', deployError);
+                }
+            }
+            return { tokenAddress, txs };
+        }
+        catch (error) {
+            console.error('❌ Error in launch():', error);
+            // 检查是否是 RoleAlreadyGranted 错误
+            const errorMessage = error.message || '';
+            const errorData = error.data?.errorName || '';
+            const errorString = JSON.stringify(error);
+            if (errorMessage.includes('RoleAlreadyGranted') ||
+                errorData === 'RoleAlreadyGranted' ||
+                errorString.includes('RoleAlreadyGranted')) {
+                throw new Error(`Account ${account?.address || 'unknown'} already has COMMUNITY role. Please use a different account or exit the role first.`);
+            }
+            // 检查其他常见错误
+            if (errorMessage.includes('InsufficientStake')) {
+                throw new Error('Insufficient stake. Please ensure you have enough GToken staked.');
+            }
+            if (errorMessage.includes('RoleNotConfigured')) {
+                throw new Error('COMMUNITY role is not configured in the Registry contract.');
+            }
+            // 重新抛出原始错误
+            throw error;
+        }
+    };
+    // State query method - check before operations
+    const getCommunityInfo = async (accountAddress) => {
+        try {
+            // 1. Check if account has COMMUNITY role
+            const hasRole = await client.readContract({
+                address: usedAddresses.registry,
+                abi: RegistryABI,
+                functionName: 'hasRole',
+                args: [RoleIds.COMMUNITY, accountAddress]
+            });
+            if (!hasRole) {
+                return {
+                    hasRole: false,
+                    tokenAddress: null,
+                    communityData: null
+                };
+            }
+            // 2. Get token address from factory
+            const factoryAbi = [
+                {
+                    inputs: [{ name: 'community', type: 'address' }],
+                    name: 'getTokenAddress',
+                    outputs: [{ name: '', type: 'address' }],
+                    stateMutability: 'view',
+                    type: 'function'
+                }
+            ];
+            const tokenAddress = await client.readContract({
+                address: usedAddresses.xPNTsFactory,
+                abi: factoryAbi,
+                functionName: 'getTokenAddress',
+                args: [accountAddress]
+            });
+            // 3. Get community metadata from Registry
+            const metadata = await client.readContract({
+                address: usedAddresses.registry,
+                abi: RegistryABI,
+                functionName: 'roleMetadata',
+                args: [RoleIds.COMMUNITY, accountAddress]
+            });
+            let communityData = {
+                name: 'Community',
+                ensName: '',
+                website: '',
+                description: '',
+                logoURI: ''
+            };
+            if (metadata && metadata !== '0x') {
+                try {
+                    // RoleMetadata is encoded as CommunityRoleData struct:
+                    // (string name, string ensName, string website, string description, string logoURI, uint256 stakeAmount)
+                    const decoded = RoleDataFactory.decodeCommunity(metadata);
+                    communityData = {
+                        name: decoded.name || 'Community',
+                        ensName: decoded.ensName || '',
+                        website: decoded.website || '',
+                        description: decoded.description || '',
+                        logoURI: decoded.logoURI || ''
+                    };
+                }
+                catch (e) {
+                    console.warn('   ⚠️ Failed to decode community metadata:', e);
+                }
+            }
+            return {
+                hasRole: true,
+                tokenAddress: (tokenAddress && tokenAddress !== '0x0000000000000000000000000000000000000000') ? tokenAddress : null,
+                communityData: (metadata && metadata !== '0x') ? communityData : null
+            };
+        }
+        catch (error) {
+            console.error('Error fetching community info:', error);
+            return {
+                hasRole: false,
+                tokenAddress: null,
+                communityData: null
+            };
+        }
+    };
+    return Object.assign(client, registryActionsObj, sbtActionsObj, {
+        launch,
+        getCommunityInfo
+    });
+}

package/dist/{sdk/src/clients → clients}/endUser.d.ts

@@ -1,7 +1,6 @@
 import { type Client, type Transport, type Chain, type Account, type PublicActions, type WalletActions, type Address, type Hex, type Hash } from 'viem';
-import { type RegistryActions, type SBTActions, type SuperPaymasterActions, type PaymasterV4Actions } from '@aastar/core';
-import { type DecodedEvent } from '../utils/eventDecoder.js';
-export type EndUserClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SBTActions & SuperPaymasterActions & PaymasterV4Actions & {
+import { type RegistryActions, type SBTActions, type SuperPaymasterActions, type PaymasterActions } from '@aastar/core';
+export type EndUserClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SBTActions & SuperPaymasterActions & PaymasterActions & {
     /**
      * High-level API: Onboard user to community with automatic funding
      */
@@ -10,8 +9,7 @@ export type EndUserClient = Client<Transport, Chain, Account | undefined> & Publ
         roleId: Hex;
         roleData: Hex;
     }) => Promise<{
-        hash: Hash;
-        events: DecodedEvent[];
+        tx: Hash;
         sbtId: bigint;
     }>;
     /**
@@ -24,8 +22,7 @@ export type EndUserClient = Client<Transport, Chain, Account | undefined> & Publ
         roleId: Hex;
         roleData?: Hex;
     }) => Promise<{
-        hash: Hash;
-        events: DecodedEvent[];
+        tx: Hash;
         sbtId: bigint;
         initialCredit: bigint;
     }>;
@@ -37,22 +34,7 @@ export type EndUserClient = Client<Transport, Chain, Account | undefined> & Publ
         data: Hex;
         value?: bigint;
         operator: Address;
-    }) => Promise<{
-        hash: Hash;
-        events: DecodedEvent[];
-    }>;
-    /**
-     * Executes a batch of gasless transactions via SuperPaymaster.
-     */
-    executeGaslessBatch: (args: {
-        targets: Address[];
-        datas: Hex[];
-        values?: bigint[];
-        operator: Address;
-    }) => Promise<{
-        hash: Hash;
-        events: DecodedEvent[];
-    }>;
+    }) => Promise<Hash>;
     /**
      * Check if the user meets the requirements to join a community (stake, sbt, etc.)
      */