@aastar/sdk 0.14.3 → 0.16.8

package/dist/sdk/src/clients/endUser.js

@@ -0,0 +1,388 @@
+import { createClient, publicActions, walletActions, parseEther, encodeFunctionData, pad, concat } from 'viem';
+import { registryActions, sbtActions, superPaymasterActions, paymasterV4Actions, CORE_ADDRESSES, TOKEN_ADDRESSES, TEST_ACCOUNT_ADDRESSES, RegistryABI, EntryPointABI, SimpleAccountFactoryABI, xPNTsFactoryABI, validateAddress, validateHex, } from '@aastar/core';
+import { AAStarError, AAStarErrorCode as AAStarErrorType, createError } from '../errors/AAStarError.js';
+import { decodeContractError } from '../errors/decoder.js';
+import { decodeContractEvents, logDecodedEvents } from '../utils/eventDecoder.js';
+export function createEndUserClient({ chain, transport, account, addresses }) {
+    const client = createClient({
+        chain,
+        transport,
+        account
+    })
+        .extend(publicActions)
+        .extend(walletActions);
+    const usedAddresses = { ...CORE_ADDRESSES, ...TOKEN_ADDRESSES, ...TEST_ACCOUNT_ADDRESSES, ...addresses };
+    const actions = {
+        ...registryActions(usedAddresses.registry)(client),
+        ...sbtActions(usedAddresses.mySBT)(client),
+        ...superPaymasterActions(usedAddresses.superPaymaster)(client),
+        ...paymasterV4Actions(usedAddresses.paymasterV4)(client)
+    };
+    return Object.assign(client, actions, {
+        async onboard({ community, roleId, roleData }) {
+            community = validateAddress(community, 'Community');
+            roleId = validateHex(roleId, 'RoleId');
+            console.log('👤 Onboarding user to community...');
+            const result = await this.joinAndActivate({ community, roleId, roleData });
+            console.log(`✅ User onboarded! SBT ID: ${result.sbtId}`);
+            return { hash: result.hash, events: result.events, sbtId: result.sbtId };
+        },
+        async joinAndActivate({ community, roleId, roleData }) {
+            const accountToUse = account;
+            if (!accountToUse)
+                throw createError.validation("Account", "Account required for joinAndActivate");
+            // Validation
+            community = validateAddress(community, 'Community');
+            roleId = validateHex(roleId, 'RoleId');
+            console.log(`   SDK: Joining community ${community}...`);
+            // Registry.registerRoleSelf is now idempotent (modified contract)
+            // If roleData not provided, encode EndUserRoleData structure
+            let finalData;
+            if (roleData) {
+                finalData = roleData;
+            }
+            else {
+                // Encode EndUserRoleData: (address account, address community, string avatarURI, string ensName, uint256 stakeAmount)
+                const { encodeAbiParameters } = await import('viem');
+                finalData = encodeAbiParameters([
+                    { name: 'account', type: 'address' },
+                    { name: 'community', type: 'address' },
+                    { name: 'avatarURI', type: 'string' },
+                    { name: 'ensName', type: 'string' },
+                    { name: 'stakeAmount', type: 'uint256' }
+                ], [accountToUse.address, community, '', '', 0n] // Use minimum stake (Registry will use roleConfig.minStake)
+                );
+            }
+            try {
+                const regTx = await client.writeContract({
+                    address: usedAddresses.registry,
+                    abi: RegistryABI,
+                    functionName: 'registerRoleSelf',
+                    args: [roleId, finalData],
+                    account: accountToUse,
+                    chain
+                });
+                const receipt = await client.waitForTransactionReceipt({ hash: regTx });
+                const events = decodeContractEvents(receipt.logs);
+                logDecodedEvents(events);
+                // 2. Fetch SBT ID
+                const sbtId = await actions.sbtGetUserSBT({ user: accountToUse.address, roleId });
+                console.log(`   SDK: User joined. SBT ID: ${sbtId}`);
+                // 3. Fetch Initial Credit for verification
+                let credit = 0n;
+                try {
+                    // Use Imported ABI
+                    const tokenAddress = await client.readContract({
+                        address: usedAddresses.xPNTsFactory,
+                        abi: xPNTsFactoryABI,
+                        functionName: 'communityToToken',
+                        args: [community]
+                    });
+                    // If token exists (not zero address), check credit
+                    if (tokenAddress && tokenAddress !== '0x0000000000000000000000000000000000000000') {
+                        credit = await actions.superPaymasterGetAvailableCredit({
+                            user: client.aaAddress || accountToUse.address,
+                            operator: tokenAddress
+                        });
+                        console.log(`   SDK: Activation complete. Current Credit: ${credit} points.`);
+                    }
+                }
+                catch (error) {
+                    // Graceful degradation if credit system not ready
+                    console.log(`   SDK: Credit system check skipped (${error.message?.split('\n')[0]}).`);
+                }
+                return {
+                    hash: regTx,
+                    events,
+                    sbtId,
+                    initialCredit: credit
+                };
+            }
+            catch (error) {
+                const decodedMsg = decodeContractError(error);
+                console.error(`   ❌ joinAndActivate failed:`, decodedMsg || error.message);
+                if (decodedMsg) {
+                    throw new AAStarError(`Joining Community Failed: ${decodedMsg}`, AAStarErrorType.CONTRACT_ERROR);
+                }
+                throw error;
+            }
+        },
+        async executeGasless({ target, data, value = 0n, operator }) {
+            const accountToUse = account;
+            if (!accountToUse)
+                throw createError.validation("Wallet", "Wallet account required for gasless execution");
+            // Validation
+            target = validateAddress(target, 'Target Address');
+            operator = validateAddress(operator, 'Operator Address');
+            if (value < 0n)
+                throw new AAStarError('Value must be positive', AAStarErrorType.VALIDATION_ERROR);
+            // 1. Get AA Address (Predict if necessary)
+            const { accountAddress } = await this.createSmartAccount({ owner: accountToUse.address });
+            console.log(`   SDK: Executing gasless via AA ${accountAddress} Sponsored by ${operator}`);
+            // 2. Fetch Nonce from EntryPoint (v0.7 standard)
+            let nonce = 0n;
+            try {
+                nonce = await client.readContract({
+                    address: usedAddresses.entryPoint,
+                    abi: EntryPointABI,
+                    functionName: 'getNonce',
+                    args: [accountAddress, 0n] // 0 = default nonce key
+                });
+            }
+            catch (e) {
+                console.warn(`   ⚠️  Failed to fetch nonce from EntryPoint, using default 0:`, e.message);
+                nonce = 0n;
+            }
+            // 3. Build UserOp via PaymasterClient Helpers available or explicit logic
+            // Since PaymasterClient.submitGaslessUserOperation is an all-in-one, we can't easily use it here 
+            // if we want to return the exact structure { hash, events } AND control the signing manually if needed (EndUserClient acts as the wallet interface).
+            // However, EndUserClient has access to 'account' (privateKey account usually).
+            // So we can use PaymasterClient helpers.
+            // Construct CallData
+            // PaymasterClient.encodeExecution is STATIC.
+            const callData = encodeFunctionData({
+                abi: [{ type: 'function', name: 'execute', inputs: [{ type: 'address' }, { type: 'uint256' }, { type: 'bytes' }] }],
+                functionName: 'execute',
+                args: [target, value, data]
+            });
+            // Construct UserOp
+            const paymasterVerificationGas = 250000n; // Estimation safe buffer
+            const paymasterPostOpGas = 50000n;
+            const paymasterAndData = concat([
+                usedAddresses.superPaymaster,
+                pad(`0x${paymasterVerificationGas.toString(16)}`, { dir: 'left', size: 16 }),
+                pad(`0x${paymasterPostOpGas.toString(16)}`, { dir: 'left', size: 16 }),
+                operator
+            ]);
+            const accountGasLimits = concat([
+                pad(`0x${(100000).toString(16)}`, { dir: 'left', size: 16 }), // verification
+                pad(`0x${(100000).toString(16)}`, { dir: 'left', size: 16 }) // call
+            ]);
+            const gasFees = concat([
+                pad(`0x${(2000000000).toString(16)}`, { dir: 'left', size: 16 }), // 2 gwei defaults
+                pad(`0x${(2000000000).toString(16)}`, { dir: 'left', size: 16 })
+            ]);
+            const userOp = {
+                sender: accountAddress,
+                nonce,
+                initCode: '0x', // Optimization: Assume deployed or separate deploy
+                callData,
+                accountGasLimits,
+                preVerificationGas: 50000n,
+                gasFees,
+                paymasterAndData,
+                signature: '0x'
+            };
+            // If account is not deployed, initCode needs to be set.
+            const byteCode = await client.getBytecode({ address: accountAddress });
+            if (!byteCode || byteCode === '0x') {
+                const { initCode } = await this.createSmartAccount({ owner: accountToUse.address });
+                userOp.initCode = initCode;
+            }
+            // Get Hash
+            const entryPointAddress = usedAddresses.entryPoint || '0x0000000071727De22E5E9d8BAf0edAc6f37da032';
+            const userOpHash = await client.readContract({
+                address: entryPointAddress,
+                abi: EntryPointABI,
+                functionName: 'getUserOpHash',
+                args: [userOp]
+            });
+            // Sign
+            const signature = await accountToUse.signMessage({
+                message: { raw: userOpHash }
+            });
+            userOp.signature = signature;
+            try {
+                // Submit
+                console.log(`   SDK: Submitting UserOp ${userOpHash}...`);
+                const tx = await client.writeContract({
+                    address: entryPointAddress,
+                    abi: EntryPointABI,
+                    functionName: 'handleOps',
+                    args: [[userOp], accountToUse.address],
+                    account,
+                    chain
+                });
+                const receipt = await client.waitForTransactionReceipt({ hash: tx });
+                const events = decodeContractEvents(receipt.logs);
+                logDecodedEvents(events);
+                return { hash: tx, events };
+            }
+            catch (error) {
+                const decodedMsg = decodeContractError(error);
+                if (decodedMsg) {
+                    throw new AAStarError(`Gasless Execution Failed: ${decodedMsg}`, AAStarErrorType.CONTRACT_ERROR);
+                }
+                throw error;
+            }
+        },
+        async executeGaslessBatch({ targets, datas, values, operator }) {
+            const accountToUse = account;
+            if (!accountToUse)
+                throw createError.validation("Wallet", "Wallet account required for gasless execution");
+            // Validation
+            targets.forEach(t => validateAddress(t, 'Target'));
+            operator = validateAddress(operator, 'Operator');
+            const finalValues = values || targets.map(() => 0n);
+            // 1. Get AA Address (Predict if necessary)
+            const { accountAddress } = await this.createSmartAccount({ owner: accountToUse.address });
+            console.log(`   SDK: Executing gasless batch via AA ${accountAddress} Sponsored by ${operator}`);
+            // 2. Fetch Nonce
+            let nonce = 0n;
+            try {
+                nonce = await client.readContract({
+                    address: usedAddresses.entryPoint,
+                    abi: EntryPointABI,
+                    functionName: 'getNonce',
+                    args: [accountAddress, 0n]
+                });
+            }
+            catch (e) {
+                nonce = 0n;
+            }
+            // 3. Build CallData (executeBatch)
+            const executeData = encodeFunctionData({
+                abi: [{ type: 'function', name: 'executeBatch', inputs: [{ type: 'address[]' }, { type: 'uint256[]' }, { type: 'bytes[]' }] }],
+                functionName: 'executeBatch',
+                args: [targets, finalValues, datas]
+            });
+            // 4. Build Gas Limits & Fees
+            const accountGasLimits = concat([
+                pad(`0x${(150000).toString(16)}`, { dir: 'left', size: 16 }),
+                pad(`0x${(300000).toString(16)}`, { dir: 'left', size: 16 })
+            ]);
+            const gasFees = concat([
+                pad(`0x${(2000000000).toString(16)}`, { dir: 'left', size: 16 }),
+                pad(`0x${(2000000000).toString(16)}`, { dir: 'left', size: 16 })
+            ]);
+            // 5. Paymaster
+            const paymasterAndData = concat([
+                usedAddresses.superPaymaster,
+                pad(`0x${(300000).toString(16)}`, { dir: 'left', size: 16 }),
+                pad(`0x${(50000).toString(16)}`, { dir: 'left', size: 16 }),
+                operator
+            ]);
+            const userOp = {
+                sender: accountAddress,
+                nonce,
+                initCode: '0x',
+                callData: executeData,
+                accountGasLimits,
+                preVerificationGas: 100000n,
+                gasFees,
+                paymasterAndData,
+                signature: '0x'
+            };
+            const byteCode = await client.getBytecode({ address: accountAddress });
+            if (!byteCode || byteCode === '0x') {
+                const { initCode } = await this.createSmartAccount({ owner: accountToUse.address });
+                userOp.initCode = initCode;
+            }
+            const entryPointAddress = usedAddresses.entryPoint || '0x0000000071727De22E5E9d8BAf0edAc6f37da032';
+            const userOpHash = await client.readContract({
+                address: entryPointAddress,
+                abi: EntryPointABI,
+                functionName: 'getUserOpHash',
+                args: [userOp]
+            });
+            const signature = await accountToUse.signMessage({
+                message: { raw: userOpHash }
+            });
+            userOp.signature = signature;
+            try {
+                console.log(`   SDK: Submitting Batch UserOp ${userOpHash}...`);
+                const tx = await client.writeContract({
+                    address: entryPointAddress,
+                    abi: EntryPointABI,
+                    functionName: 'handleOps',
+                    args: [[userOp], accountToUse.address],
+                    account,
+                    chain
+                });
+                const receipt = await client.waitForTransactionReceipt({ hash: tx });
+                const events = decodeContractEvents(receipt.logs);
+                logDecodedEvents(events);
+                return { hash: tx, events };
+            }
+            catch (error) {
+                const decodedMsg = decodeContractError(error);
+                if (decodedMsg) {
+                    throw new AAStarError(`Gasless Batch Execution Failed: ${decodedMsg}`, AAStarErrorType.CONTRACT_ERROR);
+                }
+                throw error;
+            }
+        },
+        async checkJoinRequirements(address) {
+            const accountToUse = address || account?.address;
+            if (!accountToUse)
+                throw createError.validation("Account", "Account address required for requirement check");
+            validateAddress(accountToUse, 'Check Address');
+            const { RequirementChecker } = await import('@aastar/core');
+            const checker = new RequirementChecker(client, usedAddresses);
+            return await checker.checkRequirements({
+                address: accountToUse,
+                requiredGToken: 440000000000000000n, // 0.44 GT
+                requireSBT: false
+            });
+        },
+        async createSmartAccount({ owner, salt = 0n }) {
+            // Using Imported ABI
+            owner = validateAddress(owner, 'Owner');
+            let factoryAddress = usedAddresses.simpleAccountFactory;
+            if (!factoryAddress || factoryAddress === '0x0000000000000000000000000000000000000000') {
+                throw new AAStarError("SimpleAccountFactory not found", AAStarErrorType.CONFIGURATION_ERROR);
+            }
+            const accountAddress = await client.readContract({
+                address: factoryAddress,
+                abi: SimpleAccountFactoryABI,
+                functionName: 'getAddress',
+                args: [owner, salt]
+            });
+            const createAccountData = encodeFunctionData({
+                abi: SimpleAccountFactoryABI,
+                functionName: 'createAccount',
+                args: [owner, salt]
+            });
+            const initCode = concat([factoryAddress, createAccountData]);
+            const byteCode = await client.getBytecode({ address: accountAddress });
+            const isDeployed = byteCode !== undefined && byteCode !== '0x';
+            return { accountAddress, initCode, isDeployed };
+        },
+        async deploySmartAccount({ owner, salt = 0n, fundWithETH = 0n }) {
+            const { accountAddress, isDeployed } = await this.createSmartAccount({ owner, salt });
+            const { formatEther } = await import('viem');
+            let deployHash = '0x0';
+            if (isDeployed) {
+                console.log(`   ℹ️ Account ${accountAddress} already deployed.`);
+            }
+            else {
+                let factoryAddress = usedAddresses.simpleAccountFactory;
+                console.log(`   🏭 Deploying Smart Account for ${owner}...`);
+                deployHash = await client.writeContract({
+                    address: factoryAddress,
+                    abi: SimpleAccountFactoryABI,
+                    functionName: 'createAccount',
+                    args: [owner, salt],
+                    account,
+                    chain
+                });
+                await client.waitForTransactionReceipt({ hash: deployHash });
+                console.log(`   ✅ Deployed at ${accountAddress}`);
+            }
+            if (fundWithETH > 0n) {
+                const balance = await client.getBalance({ address: accountAddress });
+                if (balance < parseEther('0.01')) {
+                    console.log(`   ⛽ Funding account with ${formatEther(fundWithETH)} ETH...`);
+                    const tx = await client.sendTransaction({
+                        to: accountAddress,
+                        value: fundWithETH,
+                        account,
+                        chain
+                    });
+                    await client.waitForTransactionReceipt({ hash: tx });
+                }
+            }
+            return { accountAddress, deployTxHash: deployHash, isDeployed: true };
+        }
+    });
+}

package/dist/sdk/src/clients/endUser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/clients/endUser.test.js

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createEndUserClient } from './endUser.js';
+import { mainnet } from 'viem/chains';
+import { http, parseEther } from 'viem';
+vi.mock('@aastar/core', async () => {
+    const actual = await vi.importActual('@aastar/core');
+    return {
+        ...actual,
+        registryActions: vi.fn(() => vi.fn(() => ({
+            registryRegisterRoleSelf: vi.fn().mockResolvedValue('0xhash')
+        }))),
+        sbtActions: vi.fn(() => vi.fn(() => ({
+            sbtGetUserSBT: vi.fn().mockResolvedValue(123n)
+        }))),
+        superPaymasterActions: vi.fn(() => vi.fn(() => ({
+            superPaymasterGetAvailableCredit: vi.fn().mockResolvedValue(100n)
+        }))),
+        paymasterV4Actions: vi.fn(() => vi.fn(() => ({
+        // pmv4
+        }))),
+    };
+});
+describe('EndUserClient', () => {
+    const MOCK_ADDR = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+    const MOCK_COMMUNITY = '0x1111111111111111111111111111111111111111';
+    it('should create end user client', () => {
+        const client = createEndUserClient({ chain: mainnet, transport: http() });
+        expect(client.joinAndActivate).toBeDefined();
+    });
+    describe('joinAndActivate', () => {
+        it('should join community and fetch SBT', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR }
+            });
+            client.readContract = vi.fn().mockResolvedValue('0x0000000000000000000000000000000000000000');
+            client.writeContract = vi.fn().mockResolvedValue('0xhash');
+            client.waitForTransactionReceipt = vi.fn().mockResolvedValue({ logs: [] });
+            const result = await client.joinAndActivate({ community: MOCK_COMMUNITY, roleId: '0x1' });
+            expect(result.sbtId).toBe(123n);
+        });
+    });
+    describe('executeGasless', () => {
+        it('should execute gasless transaction', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR, signMessage: vi.fn().mockResolvedValue('0xsignature') }
+            });
+            client.createSmartAccount = vi.fn().mockResolvedValue({ accountAddress: '0xaa', isDeployed: true });
+            client.readContract = vi.fn().mockResolvedValue(0n); // nonce or userOpHash
+            client.getBytecode = vi.fn().mockResolvedValue('0x123');
+            client.writeContract = vi.fn().mockResolvedValue('0xhash');
+            client.waitForTransactionReceipt = vi.fn().mockResolvedValue({ logs: [] });
+            const result = await client.executeGasless({
+                target: MOCK_COMMUNITY,
+                data: '0x',
+                operator: MOCK_COMMUNITY
+            });
+            expect(result.hash).toBe('0xhash');
+        });
+    });
+    describe('executeGaslessBatch', () => {
+        it('should execute gasless batch', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR, signMessage: vi.fn().mockResolvedValue('0xsignature') }
+            });
+            client.createSmartAccount = vi.fn().mockResolvedValue({ accountAddress: '0xaa', isDeployed: true });
+            client.readContract = vi.fn().mockResolvedValue(0n);
+            client.getBytecode = vi.fn().mockResolvedValue('0x123');
+            client.writeContract = vi.fn().mockResolvedValue('0xhash');
+            client.waitForTransactionReceipt = vi.fn().mockResolvedValue({ logs: [] });
+            const result = await client.executeGaslessBatch({
+                targets: [MOCK_COMMUNITY],
+                datas: ['0x'],
+                operator: MOCK_COMMUNITY
+            });
+            expect(result.hash).toBe('0xhash');
+        });
+    });
+    describe('Requirements and Credits', () => {
+        it('should call onboard (alias for joinAndActivate)', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR }
+            });
+            client.joinAndActivate = vi.fn().mockResolvedValue({ hash: '0xhash', events: [], sbtId: 1n });
+            const result = await client.onboard({ community: MOCK_COMMUNITY, roleId: '0x1', roleData: '0x' });
+            expect(result.sbtId).toBe(1n);
+        });
+        it('should check join requirements', async () => {
+            const client = createEndUserClient({ chain: mainnet, transport: http() });
+            // Mock balance return for GToken balance check >= 0.44 GT
+            client.readContract = vi.fn().mockResolvedValue(1000000000000000000n);
+            const result = await client.checkJoinRequirements(MOCK_ADDR);
+            expect(result.hasEnoughGToken).toBe(true);
+        });
+        it('should get available credit', async () => {
+            const client = createEndUserClient({ chain: mainnet, transport: http() });
+            // getAvailableCredit is part of SuperPaymasterActions which is extended in client
+            const credit = await client.superPaymasterGetAvailableCredit({ operator: MOCK_COMMUNITY, user: MOCK_ADDR });
+            expect(credit).toBe(100n);
+        });
+    });
+    describe('Smart Account Management', () => {
+        it('should create smart account with prediction', async () => {
+            const client = createEndUserClient({ chain: mainnet, transport: http() });
+            client.readContract = vi.fn().mockResolvedValue('0xAccountAddress');
+            client.getBytecode = vi.fn().mockResolvedValue(undefined);
+            const result = await client.createSmartAccount({ owner: MOCK_ADDR, salt: 123n });
+            expect(result.accountAddress).toBe('0xAccountAddress');
+            expect(result.isDeployed).toBe(false);
+            expect(result.initCode).toBeDefined();
+        });
+        it('should detect already deployed smart account', async () => {
+            const client = createEndUserClient({ chain: mainnet, transport: http() });
+            client.readContract = vi.fn().mockResolvedValue('0xDeployedAccount');
+            client.getBytecode = vi.fn().mockResolvedValue('0x123456');
+            const result = await client.createSmartAccount({ owner: MOCK_ADDR });
+            expect(result.isDeployed).toBe(true);
+        });
+        it('should throw error if factory not configured', async () => {
+            const client = createEndUserClient({ chain: mainnet, transport: http(), addresses: { simpleAccountFactory: '0x0000000000000000000000000000000000000000' } });
+            await expect(client.createSmartAccount({ owner: MOCK_ADDR }))
+                .rejects.toThrow('SimpleAccountFactory not found');
+        });
+        it('should deploy new smart account', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR }
+            });
+            client.createSmartAccount = vi.fn().mockResolvedValue({ accountAddress: '0xNewAccount', isDeployed: false });
+            client.writeContract = vi.fn().mockResolvedValue('0xdeployhash');
+            client.waitForTransactionReceipt = vi.fn().mockResolvedValue({ logs: [] });
+            client.getBalance = vi.fn().mockResolvedValue(0n);
+            client.sendTransaction = vi.fn().mockResolvedValue('0xfundhash');
+            const result = await client.deploySmartAccount({ owner: MOCK_ADDR, fundWithETH: parseEther('0.1') });
+            expect(result.accountAddress).toBe('0xNewAccount');
+            expect(result.deployTxHash).toBe('0xdeployhash');
+        });
+        it('should skip deploy if already deployed', async () => {
+            const client = createEndUserClient({
+                chain: mainnet,
+                transport: http(),
+                account: { address: MOCK_ADDR }
+            });
+            client.createSmartAccount = vi.fn().mockResolvedValue({ accountAddress: '0xExisting', isDeployed: true });
+            client.getBalance = vi.fn().mockResolvedValue(parseEther('1'));
+            const result = await client.deploySmartAccount({ owner: MOCK_ADDR });
+            expect(result.accountAddress).toBe('0xExisting');
+            expect(result.deployTxHash).toBe('0x0');
+        });
+        it('should handle logic when smart account not deployed during batch', async () => {
+            const mockAccount = { address: MOCK_ADDR, signMessage: vi.fn().mockResolvedValue('0xsig') };
+            const client = createEndUserClient({ chain: mainnet, transport: http(), account: mockAccount });
+            // Mock getBytecode to return undefined/0x
+            client.getBytecode = vi.fn().mockResolvedValue('0x'); // Not deployed
+            client.createSmartAccount = vi.fn().mockResolvedValue({ initCode: '0x123' });
+            client.readContract = vi.fn().mockResolvedValue('0xhash');
+            client.writeContract = vi.fn().mockResolvedValue('0xhash');
+            client.waitForTransactionReceipt = vi.fn().mockResolvedValue({ logs: [] });
+            const results = await client.executeGaslessBatch({
+                targets: [MOCK_ADDR],
+                datas: ['0x'],
+                operator: MOCK_ADDR
+            });
+            expect(client.createSmartAccount).toHaveBeenCalled();
+            expect(results.hash).toBe('0xhash');
+        });
+        it('should handle execution errors in gasless batch', async () => {
+            const mockAccount = { address: MOCK_ADDR, signMessage: vi.fn().mockResolvedValue('0xsig') };
+            const client = createEndUserClient({ chain: mainnet, transport: http(), account: mockAccount });
+            client.getBytecode = vi.fn().mockResolvedValue('0xcode'); // deployed
+            client.readContract = vi.fn().mockResolvedValue('0xhash');
+            client.writeContract = vi.fn().mockRejectedValue(new Error('Contract Reverted'));
+            await expect(client.executeGaslessBatch({
+                targets: [MOCK_ADDR],
+                datas: ['0x'],
+                operator: MOCK_ADDR
+            })).rejects.toThrow('Contract Reverted');
+        });
+    });
+});

package/dist/sdk/src/clients/operator.d.ts

@@ -0,0 +1,96 @@
+import { type Client, type Transport, type Chain, type Account, type Hash, type Hex, type PublicActions, type WalletActions, type Address } from 'viem';
+import { type StakingActions, type RegistryActions, type SuperPaymasterActions, type PaymasterV4Actions, type TokenActions } from '@aastar/core';
+import { type DecodedEvent } from '../utils/eventDecoder.js';
+export type OperatorClient = Client<Transport, Chain, Account | undefined> & PublicActions<Transport, Chain, Account | undefined> & WalletActions<Chain, Account | undefined> & RegistryActions & SuperPaymasterActions & PaymasterV4Actions & StakingActions & TokenActions & {
+    /**
+     * High-level API: Setup operator with automatic funding and onboarding
+     */
+    setup: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+        roleData?: Hex;
+    }) => Promise<{
+        txs: {
+            hash: Hash;
+            events: DecodedEvent[];
+        }[];
+    }>;
+    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)
+     */
+    onboardFully: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+        roleData?: Hex;
+        gasTokens?: Address[];
+    }) => Promise<{
+        hash: Hash;
+        events: DecodedEvent[];
+    }[]>;
+    /** @deprecated Use onboardFully */
+    onboardOperator: (args: {
+        stakeAmount: bigint;
+        depositAmount: bigint;
+        roleId: Hex;
+        roleData?: Hex;
+    }) => Promise<{
+        hash: Hash;
+        events: DecodedEvent[];
+    }[]>;
+    configureOperator: (args: {
+        xPNTsToken: Address;
+        treasury: Address;
+        exchangeRate: bigint;
+        account?: Account | Address;
+    }) => Promise<Hash>;
+    /**
+     * 🧙 Wisdom: Check if operator is ready and compliant.
+     */
+    checkReadiness: () => Promise<{
+        isRegistered: boolean;
+        isConfigured: boolean;
+        collateralBalance: bigint;
+        isPaused: boolean;
+        roleStatus: boolean;
+    }>;
+    getOperatorStatus: (accountAddress: Address) => Promise<{
+        type: 'super' | 'v4' | null;
+        superPaymaster: {
+            hasRole: boolean;
+            isConfigured: boolean;
+            balance: bigint;
+            exchangeRate: bigint;
+            treasury: Address;
+        } | null;
+        paymasterV4: {
+            address: Address;
+            balance: bigint;
+        } | null;
+    }>;
+    isOperator: (operator: Address) => Promise<boolean>;
+    getDepositDetails: () => Promise<{
+        deposit: bigint;
+    }>;
+    deposit: (args: {
+        amount: bigint;
+        account?: Account | Address;
+    }) => Promise<Hash>;
+};
+export declare function createOperatorClient({ chain, transport, account, addresses }: {
+    chain: Chain;
+    transport: Transport;
+    account?: Account;
+    addresses?: {
+        [key: string]: Address;
+    };
+}): OperatorClient;