@aastar/sdk 0.18.0 → 0.20.2

package/dist/index.d.ts

@@ -1,23 +1,611 @@
+import { RegistryActions, SBTActions, SuperPaymasterActions, PaymasterActions, StakingActions, DVTActions, XPNTsFactoryActions, AggregatorActions } from '@aastar/core';
 export * from '@aastar/core';
 export * from '@aastar/account';
 export * from '@aastar/paymaster';
 export * from '@aastar/identity';
 export * from '@aastar/tokens';
-export * from '@aastar/dapp';
 export * from '@aastar/x402';
 export * from '@aastar/channel';
-export * from './clients/endUser.js';
-export * from './clients/operator.js';
-export { createCommunityClient, type CommunityClient as LegacyCommunityClient } from './clients/community.js';
-export * from './clients/admin.js';
-export * from './clients/ExperimentClient.js';
+import { Client, Transport, Chain, Account, PublicActions, WalletActions, Address, Hex, Hash, PublicClient } from 'viem';
 export * from '@aastar/enduser';
 export * from '@aastar/operator';
 export * from '@aastar/admin';
-export * as AirAccount from '@aastar/airaccount';
-export * from './utils/roleData.js';
-export * from './utils/keys.js';
-export * from './utils/funding.js';
-export * from './utils/userOp.js';
-export * from './utils/testScenarios.js';
-export * from './errors/decoder.js';
+import * as airaccount from '@aastar/airaccount';
+export { airaccount as AirAccount };
+
+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
+     */
+    onboard: (args: {
+        community: Address;
+        roleId: Hex;
+        roleData: Hex;
+    }) => Promise<{
+        tx: Hash;
+        sbtId: bigint;
+    }>;
+    /**
+     * Orchestrates the user joining a community and activating gas credit flow:
+     * 1. Mint SBT for the community (Register ENDUSER role)
+     * 2. Verify Credit is active (Reputation check)
+     */
+    joinAndActivate: (args: {
+        community: Address;
+        roleId: Hex;
+        roleData?: Hex;
+    }) => Promise<{
+        tx: Hash;
+        sbtId: bigint;
+        initialCredit: bigint;
+    }>;
+    /**
+     * Executes a gasless transaction via SuperPaymaster.
+     */
+    executeGasless: (args: {
+        target: Address;
+        data: Hex;
+        value?: bigint;
+        operator: Address;
+    }) => Promise<Hash>;
+    /**
+     * Check if the user meets the requirements to join a community (stake, sbt, etc.)
+     */
+    checkJoinRequirements: (address?: Address) => Promise<{
+        hasEnoughGToken: boolean;
+        hasSBT: boolean;
+        missingRequirements: string[];
+    }>;
+    /**
+     * Predict or deploy a SimpleAccount (ERC-4337)
+     */
+    deploySmartAccount: (params: {
+        owner: Address;
+        salt?: bigint;
+        fundWithETH?: bigint;
+    }) => Promise<{
+        accountAddress: Address;
+        deployTxHash: Hash;
+        isDeployed: boolean;
+    }>;
+    /**
+     * Predict the address of a SimpleAccount without deploying
+     */
+    createSmartAccount: (params: {
+        owner: Address;
+        salt?: bigint;
+    }) => Promise<{
+        accountAddress: Address;
+        initCode: Hex;
+        isDeployed: boolean;
+    }>;
+};
+declare function createEndUserClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): EndUserClient;
+
+type OperatorClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SuperPaymasterActions & PaymasterActions & StakingActions & {
+    /**
+     * High-level API: Setup operator with automatic funding and onboarding
+     */
+    setup: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+        roleData?: Hex;
+    }) => Promise<{
+        txs: Hash[];
+    }>;
+    deployPaymasterV4: (args?: {
+        version?: string;
+        initData?: Hex;
+    }) => Promise<Hash>;
+    /**
+     * Orchestrates the full onboarding flow:
+     * 1. Approve GToken (Stake)
+     * 2. Register Role (Stake Lock)
+     * 3. Approve aPNTs (Deposit)
+     * 4. Deposit aPNTs (SuperPaymaster)
+     */
+    onboardOperator: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+        roleData?: Hex;
+    }) => Promise<Hash[]>;
+    /** @deprecated Use onboardOperator */
+    onboardToSuperPaymaster: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+    }) => Promise<Hash[]>;
+    configureOperator: (args: {
+        xPNTsToken: Address;
+        treasury: Address;
+        account?: Account | Address;
+    }) => Promise<Hash>;
+    getOperatorStatus: (accountAddress: Address) => Promise<{
+        type: 'super' | 'v4' | null;
+        superPaymaster: {
+            hasRole: boolean;
+            isConfigured: boolean;
+            balance: bigint;
+            /** Exchange rate read from xPNTsToken.exchangeRate() — not from operators() */
+            exchangeRate: bigint;
+            treasury: Address;
+        } | null;
+        paymasterV4: {
+            address: Address;
+            balance: bigint;
+        } | null;
+    }>;
+};
+declare function createOperatorClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): OperatorClient;
+
+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
+     */
+    getCommunityInfo: (accountAddress: Address) => Promise<{
+        hasRole: boolean;
+        tokenAddress: Address | null;
+        communityData: {
+            name: string;
+            ensName: string;
+            website: string;
+            description: string;
+        } | null;
+    }>;
+    /**
+     * High-level API to launch a community with automatic roleData generation
+     */
+    launch: (args: {
+        name: string;
+        tokenName: string;
+        tokenSymbol: string;
+        description?: string;
+        logoURI?: string;
+        website?: string;
+    }) => Promise<{
+        tokenAddress: Address;
+        txs: Hex[];
+    }>;
+};
+declare function createCommunityClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): CommunityClient;
+
+type AdminClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SuperPaymasterActions & PaymasterActions & StakingActions & SBTActions & DVTActions & XPNTsFactoryActions & AggregatorActions;
+declare function createAdminClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): AdminClient;
+
+interface ExperimentRecord {
+    id: string;
+    scenario: string;
+    group: 'EOA' | 'AA' | 'SuperPaymaster';
+    txHash: string;
+    gasUsed: bigint;
+    gasPrice: bigint;
+    costETH: string;
+    status: 'Success' | 'Failed';
+    timestamp: number;
+    meta?: any;
+}
+/**
+ * ExperimentClient: Business-layer tool for measuring and recording execution metrics
+ */
+declare class ExperimentClient {
+    private records;
+    private scenarioId;
+    private group;
+    constructor(scenarioId: string, group: 'EOA' | 'AA' | 'SuperPaymaster');
+    /**
+     * Record a transaction result
+     */
+    recordTx(txHash: Hash, receipt: {
+        gasUsed: any;
+        effectiveGasPrice: any;
+    }, status: 'Success' | 'Failed', meta?: any): ExperimentRecord;
+    /**
+     * Measure an async task (transaction) automatically
+     */
+    measureTx(taskName: string, txPromise: Promise<Hash>, publicClient: any): Promise<Hash>;
+    getRecords(): ExperimentRecord[];
+}
+
+declare const RoleIds: {
+    readonly PAYMASTER_SUPER: `0x${string}`;
+    readonly DVT: `0x${string}`;
+    readonly PAYMASTER_AOA: `0x${string}`;
+    readonly KMS: `0x${string}`;
+    readonly COMMUNITY: `0x${string}`;
+    readonly ENDUSER: `0x${string}`;
+    readonly ANODE: `0x${string}`;
+};
+type RoleId = typeof RoleIds[keyof typeof RoleIds];
+declare const RoleDataFactory: {
+    /**
+     * Data for SuperPaymaster Operator (Empty)
+     */
+    paymasterSuper: () => Hex;
+    /**
+     * Data for Generic DVT Role (Empty)
+     */
+    dvt: () => Hex;
+    /**
+     * Data for Community Registration (matches Registry.sol CommunityRoleData)
+     * NOTE: Solidity's abi.encode(struct) adds a 32-byte offset prefix (0x20)
+     * which is required for abi.decode(struct) to work correctly.
+     *
+     * @param params.name Community Name (defaults to 'TestCommunity')
+     * @param params.ensName ENS name (optional)
+     * @param params.website Website URL (optional)
+     * @param params.description Community description (optional)
+     * @param params.logoURI Logo URI string (optional)
+     * @param params.stakeAmount Stake amount (defaults to 0)
+     */
+    community: (params?: {
+        name?: string;
+        ensName?: string;
+        website?: string;
+        description?: string;
+        logoURI?: string;
+        stakeAmount?: bigint;
+    }) => Hex;
+    /**
+     * Data for EndUser (matches Registry.sol EndUserRoleData)
+     */
+    endUser: (params?: {
+        account?: Address;
+        community?: Address;
+        avatarURI?: string;
+        ensName?: string;
+        stakeAmount?: bigint;
+    }) => Hex;
+    decodeCommunity: (data: Hex) => {
+        name: any;
+        ensName: any;
+        website: any;
+        description: any;
+        logoURI: any;
+        stakeAmount: any;
+    };
+    decodeEndUser: (data: Hex) => {
+        account: any;
+        community: any;
+        avatarURI: any;
+        ensName: any;
+        stakeAmount: any;
+    };
+};
+
+/**
+ * 密钥对接口
+ */
+interface KeyPair {
+    name: string;
+    privateKey: Hex;
+    address: Address;
+}
+/**
+ * 密钥管理器
+ * 提供密钥生成、存储、加载等工具函数
+ */
+declare class KeyManager {
+    /**
+     * 生成单个密钥对
+     * @param name - 密钥名称（如 'Jason', 'Anni'）
+     */
+    static generateKeyPair(name: string): KeyPair;
+    /**
+     * 批量生成密钥对
+     * @param names - 密钥名称数组
+     */
+    static generateKeyPairs(names: string[]): KeyPair[];
+    /**
+     * 生成指定数量的密钥对（自动命名为 Operator_1, Operator_2, ...）
+     * @param count - 数量
+     * @param prefix - 名称前缀（默认 'Operator'）
+     */
+    static generateMultiple(count: number, prefix?: string): KeyPair[];
+    /**
+     * 保存密钥到 .env 文件
+     * @param filePath - 文件路径（绝对路径）
+     * @param keys - 密钥对数组
+     * @param overwrite - 是否覆盖已存在的文件（默认 false）
+     */
+    static saveToEnvFile(filePath: string, keys: KeyPair[], overwrite?: boolean): void;
+    /**
+     * 从 .env 文件加载密钥
+     * @param filePath - 文件路径（绝对路径）
+     * @returns 密钥对数组
+     */
+    static loadFromEnvFile(filePath: string): KeyPair[];
+    /**
+     * 保存密钥到 JSON 文件（包含地址信息）
+     * @param filePath - 文件路径（绝对路径）
+     * @param keys - 密钥对数组
+     * @param overwrite - 是否覆盖已存在的文件（默认 false）
+     */
+    static saveToJsonFile(filePath: string, keys: KeyPair[], overwrite?: boolean): void;
+    /**
+     * 从 JSON 文件加载密钥
+     * @param filePath - 文件路径（绝对路径）
+     */
+    static loadFromJsonFile(filePath: string): KeyPair[];
+    /**
+     * 打印密钥信息（隐藏私钥）
+     * @param keys - 密钥对数组
+     */
+    static printKeys(keys: KeyPair[], showPrivateKey?: boolean): void;
+}
+
+/**
+ * 资金管理参数
+ */
+interface FundingParams {
+    /** RPC URL */
+    rpcUrl: string;
+    /** 链配置 */
+    chain: Chain;
+    /** 资金提供者私钥 */
+    supplierKey: Hex;
+    /** 目标地址 */
+    targetAddress: Address;
+}
+/**
+ * ETH 充值参数
+ */
+interface FundETHParams extends FundingParams {
+    /** 充值金额（ETH，如 '0.1'） */
+    amount: string;
+}
+/**
+ * ERC20 充值参数
+ */
+interface FundTokenParams extends FundingParams {
+    /** Token 合约地址 */
+    tokenAddress: Address;
+    /** 充值金额（Token，如 '100'） */
+    amount: string;
+}
+/**
+ * 智能充值参数
+ */
+interface EnsureFundingParams extends FundingParams {
+    /** 最小 ETH 余额阈值 */
+    minETH?: string;
+    /** 目标 ETH 充值金额 */
+    targetETH?: string;
+    /** Token 配置（可选） */
+    token?: {
+        address: Address;
+        minBalance?: string;
+        targetAmount?: string;
+    };
+}
+/**
+ * 充值结果
+ */
+interface FundingResult {
+    success: boolean;
+    txHash?: Hex;
+    error?: string;
+}
+/**
+ * 资金管理器
+ * 提供 ETH 和 ERC20 Token 的充值、验证等工具函数
+ */
+declare class FundingManager {
+    /**
+     * 创建 PublicClient 和 WalletClient
+     */
+    private static createClients;
+    /**
+     * 充值 ETH 到目标地址
+     * @param params - 充值参数
+     * @returns 充值结果
+     */
+    static fundWithETH(params: FundETHParams): Promise<FundingResult>;
+    /**
+     * 充值 ERC20 Token 到目标地址
+     * @param params - 充值参数
+     * @returns 充值结果
+     */
+    static fundWithToken(params: FundTokenParams): Promise<FundingResult>;
+    /**
+     * 检查 ETH 余额
+     * @param params - 基础参数
+     * @returns ETH 余额（wei）
+     */
+    static getETHBalance(params: FundingParams): Promise<bigint>;
+    /**
+     * 检查 ERC20 Token 余额
+     * @param params - 基础参数
+     * @param tokenAddress - Token 合约地址
+     * @returns Token 余额
+     */
+    static getTokenBalance(params: FundingParams, tokenAddress: Address): Promise<bigint>;
+    /**
+     * 智能充值：检查余额，不足时自动充值
+     * @param params - 充值参数
+     * @returns 充值结果数组
+     */
+    static ensureFunding(params: EnsureFundingParams): Promise<FundingResult[]>;
+    /**
+     * 批量充值 ETH
+     * @param params - 基础参数
+     * @param targets - 目标地址和金额数组
+     * @returns 充值结果数组
+     */
+    static batchFundETH(params: Omit<FundingParams, 'targetAddress'>, targets: Array<{
+        address: Address;
+        amount: string;
+    }>): Promise<FundingResult[]>;
+    /**
+     * 批量充值 Token
+     * @param params - 基础参数
+     * @param tokenAddress - Token 合约地址
+     * @param targets - 目标地址和金额数组
+     * @returns 充值结果数组
+     */
+    static batchFundToken(params: Omit<FundingParams, 'targetAddress'>, tokenAddress: Address, targets: Array<{
+        address: Address;
+        amount: string;
+    }>): Promise<FundingResult[]>;
+}
+
+/**
+ * ERC-4337 v0.7 Packed UserOperation structure.
+ */
+interface PackedUserOperation {
+    sender: Address;
+    nonce: Hex;
+    initCode: Hex;
+    callData: Hex;
+    accountGasLimits: Hex;
+    preVerificationGas: Hex;
+    gasFees: Hex;
+    paymasterAndData: Hex;
+    signature: Hex;
+}
+interface UserOpGasParams {
+    verificationGasLimit: bigint;
+    callGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    maxFeePerGas: bigint;
+}
+interface PaymasterGasParams {
+    paymasterGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+}
+declare class UserOperationBuilder {
+    /**
+     * Packs verificationGasLimit and callGasLimit into a bytes32 Hex string.
+     */
+    static packAccountGasLimits(verificationGasLimit: bigint, callGasLimit: bigint): Hex;
+    /**
+     * Packs maxPriorityFeePerGas and maxFeePerGas into a bytes32 Hex string.
+     */
+    static packGasFees(maxPriorityFeePerGas: bigint, maxFeePerGas: bigint): Hex;
+    static estimatePreVerificationGasV07(userOp: {
+        sender: Address;
+        nonce: bigint | Hex | number | string;
+        initCode: Hex;
+        callData: Hex;
+        accountGasLimits: Hex;
+        preVerificationGas: bigint | Hex | number | string;
+        gasFees: Hex;
+        paymasterAndData: Hex;
+        signature: Hex;
+    }): bigint;
+    /**
+     * Packs Paymaster parameters into the v0.7 paymasterAndData format.
+     */
+    static packPaymasterAndData(paymaster: Address, paymasterGasLimit: bigint, paymasterPostOpGasLimit: bigint, paymasterData?: Hex): Hex;
+    /**
+     * Pack PaymasterV4 Deposit-Only paymasterAndData
+     *
+     * v0.7 EntryPoint packs: [paymaster(20)][verificationGas(16)][postOpGas(16)][paymasterData]
+     * Contract extracts token at offset 52 = paymasterData[0:20]
+     *
+     * So paymasterData format must be: [token(20)][validUntil(6)][validAfter(6)]
+     *
+     * @param paymaster - Paymaster address (20 bytes)
+     * @param paymentToken - ERC20 token address (20 bytes, FIRST in paymasterData!)
+     * @param validUntil - Validity end timestamp (6 bytes)
+     * @param validAfter - Validity start timestamp (6 bytes)
+     */
+    static packPaymasterV4DepositData(paymaster: Address, paymasterVerificationGasLimit: bigint, paymasterPostOpGasLimit: bigint, paymentToken: Address, validUntil: bigint, validAfter: bigint): Hex;
+    /**
+     * Computes the UserOperation hash for signing.
+     */
+    static getUserOpHash({ userOp, entryPoint, chainId, publicClient }: {
+        userOp: PackedUserOperation;
+        entryPoint: Address;
+        chainId: number;
+        publicClient: PublicClient;
+    }): Promise<Hex>;
+    /**
+     * Formats a PackedUserOperation into a JSON-RPC compatible object with hex-encoded strings.
+     */
+    static jsonifyUserOp(userOp: any): any;
+    /**
+     * Converts a PackedUserOperation to the Alchemy-specific v0.7 JSON format.
+     * @param userOp - The packed UserOperation
+     * @param options - Optional configuration
+     * @param options.paymasterVerificationGasLimit - Gas limit for paymaster verification (default: 200000)
+     * @param options.paymasterPostOpGasLimit - Gas limit for paymaster postOp (default: 200000)
+     */
+    static toAlchemyUserOperation(userOp: any, options?: {
+        paymasterVerificationGasLimit?: bigint;
+        paymasterPostOpGasLimit?: bigint;
+    }): any;
+}
+
+declare enum UserOpScenarioType {
+    NATIVE = "NATIVE",// Plain ERC-4337, user pays ETH
+    GASLESS_V4 = "GASLESS_V4",// Standard PaymasterV4
+    SUPER_BPNT = "SUPER_BPNT",// SuperPaymaster with bPNT internal payment
+    SUPER_CPNT = "SUPER_CPNT",// SuperPaymaster with cPNT internal payment
+    SUPER_CUSTOM = "SUPER_CUSTOM"
+}
+interface ScenarioParams {
+    sender: Address;
+    ownerAccount: any;
+    recipient: Address;
+    tokenAddress: Address;
+    amount: bigint;
+    entryPoint: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    paymaster?: Address;
+    operator?: Address;
+    paymasterGasLimit?: bigint;
+    paymasterPostOpGasLimit?: bigint;
+    nonceKey?: bigint;
+    gasToken?: Address;
+}
+declare class UserOpScenarioBuilder {
+    /**
+     * Builds a signed PackedUserOperation for a token transfer based on the specified scenario.
+     */
+    static buildTransferScenario(type: UserOpScenarioType, params: ScenarioParams): Promise<{
+        userOp: any;
+        opHash: Hash;
+    }>;
+}
+
+declare const CustomErrors: {
+    readonly RoleNotConfigured: "RoleNotConfigured(bytes32,bool)";
+    readonly RoleAlreadyGranted: "RoleAlreadyGranted(bytes32,address)";
+    readonly InsufficientStake: "InsufficientStake(uint256,uint256)";
+};
+declare function decodeContractError(error: any): string | null;
+
+export { type AdminClient, CustomErrors, type EndUserClient, type EnsureFundingParams, ExperimentClient, type ExperimentRecord, type FundETHParams, type FundTokenParams, FundingManager, type FundingParams, type FundingResult, KeyManager, type KeyPair, type CommunityClient as LegacyCommunityClient, type OperatorClient, type PackedUserOperation, type PaymasterGasParams, RoleDataFactory, type RoleId, RoleIds, type ScenarioParams, type UserOpGasParams, UserOpScenarioBuilder, UserOpScenarioType, UserOperationBuilder, createAdminClient, createCommunityClient, createEndUserClient, createOperatorClient, decodeContractError };