@aastar/sdk 0.14.3 → 0.16.6

package/packages/sdk/src/errors/AAStarError.ts

@@ -0,0 +1,70 @@
+
+export enum AAStarErrorCode {
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
+    CONTRACT_ERROR = 'CONTRACT_ERROR',
+    NETWORK_ERROR = 'NETWORK_ERROR',
+    CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
+    INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
+    PERMISSION_DENIED = 'PERMISSION_DENIED',
+    OPERATION_FAILED = 'OPERATION_FAILED',
+    UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+export class AAStarError extends Error {
+    public readonly code: AAStarErrorCode;
+    public readonly details?: any;
+
+    constructor(message: string, code: AAStarErrorCode = AAStarErrorCode.UNKNOWN_ERROR, details?: any) {
+        super(message);
+        this.name = 'AAStarError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+/**
+ * Error factory functions for consistent error creation
+ */
+export const createError = {
+    validation: (field: string, reason: string): AAStarError =>
+        new AAStarError(
+            `Validation failed for ${field}: ${reason}`,
+            AAStarErrorCode.VALIDATION_ERROR,
+            { field, reason }
+        ),
+
+    contract: (contract: string, reason: string): AAStarError =>
+        new AAStarError(
+            `Contract ${contract} error: ${reason}`,
+            AAStarErrorCode.CONTRACT_ERROR,
+            { contract, reason }
+        ),
+
+    network: (operation: string, reason: string): AAStarError =>
+        new AAStarError(
+            `Network error during ${operation}: ${reason}`,
+            AAStarErrorCode.NETWORK_ERROR,
+            { operation, reason }
+        ),
+
+    insufficientFunds: (required: string, available: string): AAStarError =>
+        new AAStarError(
+            `Insufficient funds: required ${required}, available ${available}`,
+            AAStarErrorCode.INSUFFICIENT_FUNDS,
+            { required, available }
+        ),
+
+    permissionDenied: (operation: string, reason: string): AAStarError =>
+        new AAStarError(
+            `Permission denied for ${operation}: ${reason}`,
+            AAStarErrorCode.PERMISSION_DENIED,
+            { operation, reason }
+        ),
+
+    operationFailed: (operation: string, reason: string): AAStarError =>
+        new AAStarError(
+            `Operation ${operation} failed: ${reason}`,
+            AAStarErrorCode.OPERATION_FAILED,
+            { operation, reason }
+        ),
+};

package/packages/sdk/src/errors/decoder.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { decodeContractError } from './decoder.js';
+import * as viem from 'viem';
+
+vi.mock('viem', async () => {
+    const actual = await vi.importActual('viem');
+    return {
+        ...actual,
+        decodeErrorResult: vi.fn()
+    };
+});
+
+describe('ErrorDecoder', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+
+    it('should extract data from viem error walk', () => {
+        const mockError = {
+            walk: (fn: any) => {
+                const e = { data: '0x123' };
+                return fn(e) ? e : null;
+            }
+        } as any;
+        (viem.decodeErrorResult as any).mockReturnValue({
+            errorName: 'Unauthorized',
+            args: []
+        });
+        
+        const result = decodeContractError(mockError);
+        expect(result).toContain('Unauthorized');
+    });
+
+    it('should extract data from cause', () => {
+        const mockError = {
+            cause: { data: '0x123' }
+        };
+        (viem.decodeErrorResult as any).mockReturnValue({
+            errorName: 'InsufficientBalance',
+            args: [100n, 500n]
+        });
+        
+        const result = decodeContractError(mockError);
+        expect(result).toContain('InsufficientBalance');
+        expect(result).toContain('Available 100, Required 500');
+    });
+
+    it('should handle specialized formatting for RoleNotConfigured', () => {
+        (viem.decodeErrorResult as any).mockReturnValue({
+            errorName: 'RoleNotConfigured',
+            args: ['0x1', false]
+        });
+        
+        const result = decodeContractError({ data: '0x123' });
+        expect(result).toContain('Role 0x1 is INACTIVE');
+    });
+
+    it('should fallback to unknown error message if decoding fails', () => {
+        (viem.decodeErrorResult as any).mockImplementation(() => { throw new Error('mismatch'); });
+        
+        const result = decodeContractError({ data: '0x1234567890' });
+        expect(result).toContain('Unknown Error (data: 0x12345678...)');
+    });
+
+    it('should handle raw revert messages', () => {
+        const result = decodeContractError({ message: 'execution reverted: CustomError' });
+        expect(result).toBe('execution reverted: CustomError');
+    });
+
+    it('should return null for non-error input', () => {
+        expect(decodeContractError(null)).toBeNull();
+    });
+
+    it('should extract data from nested object structure', () => {
+        // Case A: { data: { data: "0x..." } }
+        const errorA = { data: { data: '0xA1' } };
+        (viem.decodeErrorResult as any).mockReturnValue({ errorName: 'TestA', args: [] });
+        expect(decodeContractError(errorA)).toContain('TestA');
+
+        // Case B: { data: { object: "0x..." } }
+        const errorB = { data: { object: '0xB1' } };
+        (viem.decodeErrorResult as any).mockReturnValue({ errorName: 'TestB', args: [] });
+        expect(decodeContractError(errorB)).toContain('TestB');
+    });
+
+    it('should format all known error types', () => {
+        const testCases = [
+            { name: 'RoleAlreadyGranted', args: ['0xRole', '0xUser'], expected: 'User 0xUser already has role 0xRole' },
+            { name: 'InsufficientStake', args: [100n, 200n], expected: 'Provided 100, Required 200' },
+            { name: 'InvalidParameter', args: ['BadInput'], expected: 'InvalidParameter: BadInput' },
+            { name: 'RoleNotGranted', args: ['0xRole', '0xUser'], expected: 'User 0xUser does not have role 0xRole' },
+            { name: 'UnknownCustom', args: [123n], expected: 'UnknownCustom: ["123"]' }
+        ];
+
+        for (const { name, args, expected } of testCases) {
+            (viem.decodeErrorResult as any).mockReturnValue({ errorName: name, args });
+            const result = decodeContractError({ data: '0x1' });
+            expect(result).toContain(expected);
+        }
+    });
+
+    it('should handle non-string unknown data', () => {
+        (viem.decodeErrorResult as any).mockImplementation(() => { throw new Error('fail'); });
+        const result = decodeContractError({ data: { complex: true } });
+        expect(result).toContain('non-string data');
+    });
+});

package/packages/sdk/src/errors/decoder.ts

@@ -1,48 +1,91 @@
-import { decodeErrorResult, type Hex, type ContractFunctionExecutionError } from 'viem';
-import { RegistryABI } from '../index.js'; // Assuming RegistryABI is exported
+import { decodeErrorResult, type Hex } from 'viem';
+import { RegistryABI, SuperPaymasterABI, GTokenStakingABI, MySBTABI, xPNTsTokenABI } from '../index.js';
 
-export const CustomErrors = {
-    RoleNotConfigured: 'RoleNotConfigured(bytes32,bool)',
-    RoleAlreadyGranted: 'RoleAlreadyGranted(bytes32,address)',
-    InsufficientStake: 'InsufficientStake(uint256,uint256)',
-} as const;
+const ABIS_TO_TRY = [
+    { name: 'Registry', abi: RegistryABI },
+    { name: 'SuperPaymaster', abi: SuperPaymasterABI },
+    { name: 'GTokenStaking', abi: GTokenStakingABI },
+    { name: 'MySBT', abi: MySBTABI },
+    { name: 'xPNTsToken', abi: xPNTsTokenABI }
+];
 
 export function decodeContractError(error: any): string | null {
-    if (!error || typeof error !== 'object') return null;
-
-    // Check if it's a viem ContractFunctionExecutionError
-    if (error.name === 'ContractFunctionExecutionError' || error.walk) {
-        // Try to extract internal error data
-        const internalError = error.walk ? error.walk((e: any) => e.data) : error;
-        const data = internalError?.data;
-
-        if (data) {
-             try {
-                const decoded = decodeErrorResult({
-                    abi: RegistryABI,
-                    data: data as Hex
-                });
-                
-                if (decoded.errorName === 'RoleNotConfigured') {
-                    const [roleId, isActive] = decoded.args as [Hex, boolean];
-                    return `RoleNotConfigured: Role ${roleId} is ${isActive ? 'ACTIVE' : 'INACTIVE'} in Registry.`;
-                }
-                if (decoded.errorName === 'RoleAlreadyGranted') {
-                    const [roleId, user] = decoded.args as [Hex, string];
-                    return `RoleAlreadyGranted: User ${user} already has role ${roleId}.`;
-                }
-                if (decoded.errorName === 'InsufficientStake') {
-                     const [stake, minStake] = decoded.args as [bigint, bigint];
-                     // Viem returns bigints, format them?
-                     return `InsufficientStake: Provided ${stake}, Required ${minStake}.`;
-                }
-                
-                return `${decoded.errorName}: ${decoded.args}`;
-            } catch (e) {
-                // ABI mismatch or unknown error
-                return null;
+    if (!error) return null;
+
+    // 1. Try to extract data from various error structures (viem, common RPC)
+    let data: Hex | undefined;
+    
+    if (typeof error === 'object') {
+        // Walk for internal data (viem pattern)
+        if (error.walk) {
+            const internalError = error.walk((e: any) => e.data);
+            data = internalError?.data;
+        }
+        
+        // Fallback to direct properties
+        if (!data) {
+            data = error.data || (error.error && error.error.data) || (error.cause && error.cause.data);
+        }
+
+        // Handle nested data objects (common in some RPCs or viem errors)
+        if (data && typeof data === 'object') {
+            if ('data' in data && typeof (data as any).data === 'string') {
+                data = (data as any).data;
+            } else if ('object' in data && typeof (data as any).object === 'string') {
+                 // specific edge case
+                 data = (data as any).object as Hex;
+            }
+        }
+    }
+
+    if (!data) {
+        // Handle "contract reverted" or similar string errors
+        const msg = error.message || String(error);
+        if (msg.includes('reverted')) return msg;
+        return null;
+    }
+
+    // 2. Iterate through known ABIs to decode
+    for (const { name, abi } of ABIS_TO_TRY) {
+        try {
+            const decoded = decodeErrorResult({
+                abi: abi as any,
+                data: data as Hex
+            });
+
+            if (decoded) {
+                return formatDecodedError(name, decoded);
             }
+        } catch (e) {
+            // Mismatch, continue to next ABI
         }
     }
-    return null;
+
+    return typeof data === 'string' 
+        ? `Unknown Error (data: ${data.slice(0, 10)}...)`
+        : `Unknown Error (non-string data: ${JSON.stringify(data, (_, v) => typeof v === 'bigint' ? v.toString() : v)})`;
+}
+
+function formatDecodedError(contractName: string, decoded: any): string {
+    const { errorName, args } = decoded;
+
+    // Specialized formatting for common errors
+    switch (errorName) {
+        case 'RoleNotConfigured':
+            return `[${contractName}] RoleNotConfigured: Role ${args[0]} is ${args[1] ? 'ACTIVE' : 'INACTIVE'}.`;
+        case 'RoleAlreadyGranted':
+            return `[${contractName}] RoleAlreadyGranted: User ${args[1]} already has role ${args[0]}.`;
+        case 'InsufficientStake':
+            return `[${contractName}] InsufficientStake: Provided ${args[0].toString()}, Required ${args[1].toString()}.`;
+        case 'InsufficientBalance':
+            return `[${contractName}] InsufficientBalance: Available ${args[0].toString()}, Required ${args[1].toString()}.`;
+        case 'InvalidParameter':
+            return `[${contractName}] InvalidParameter: ${args[0]}`;
+        case 'Unauthorized':
+            return `[${contractName}] Unauthorized: Caller does not have permission.`;
+        case 'RoleNotGranted':
+            return `[${contractName}] RoleNotGranted: User ${args[1]} does not have role ${args[0]}.`;
+        default:
+            return `[${contractName}] ${errorName}${args && args.length > 0 ? ': ' + JSON.stringify(args, (_, v) => typeof v === 'bigint' ? v.toString() : v) : ''}`;
+    }
 }

package/packages/sdk/src/index.ts

@@ -6,15 +6,18 @@ export * from '@aastar/tokens';
 export * from '@aastar/dapp';
 
 // Export Role-Based Clients
-export * from './clients/endUser.js';
-export * from './clients/operator.js';
-export * from './clients/community.js';
-export * from './clients/admin.js';
+// Export Role-Based Clients
+export { createEndUserClient } from './clients/endUser.js';
+export { createOperatorClient } from './clients/operator.js';
+export { createCommunityClient } from './clients/community.js';
+export { createAdminClient } from './clients/admin.js';
+export * from './clients/ExperimentClient.js';
 
 // Export Utils & Errors
+export { AAStarError, AAStarErrorCode, createError } from './errors/AAStarError.js';
 export * from './utils/roleData.js';
-export * from './utils/keys.js';
-export * from './utils/funding.js';
-export * from './utils/validation.js';
-export * from './errors/decoder.js';
+export * from './utils/userOp.js';
+export * from './utils/eventDecoder.js';
 
+// Export Types
+export * from './types/result.js';

package/packages/sdk/src/node/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Node.js specific utilities
+ * ⚠️ NOT COMPATIBLE WITH BROWSER ENVIRONMENTS
+ */
+
+export { KeyManager, type KeyPair } from '../utils/keys.js';
+export { FundingManager, type FundingParams } from '../utils/funding.js';
+export * from '../utils/testScenarios.js';

package/packages/sdk/src/types/result.ts

@@ -0,0 +1,29 @@
+import { AAStarError } from '../errors/AAStarError.js';
+
+export type SDKResult<T> = 
+    | { success: true; data: T }
+    | { success: false; error: AAStarError };
+
+export function success<T>(data: T): SDKResult<T> {
+    return { success: true, data };
+}
+
+export function failure<T>(error: AAStarError): SDKResult<T> {
+    return { success: false, error };
+}
+
+/**
+ * Utility to wrap a Promise in an SDKResult.
+ * Handles AAStarError explicitly, and wraps unknown errors.
+ */
+export async function safeSDKCall<T>(promise: Promise<T>): Promise<SDKResult<T>> {
+    try {
+        const data = await promise;
+        return success(data);
+    } catch (e: any) {
+        if (e instanceof AAStarError) {
+            return failure(e);
+        }
+        return failure(new AAStarError(e.message || 'Unknown error occurred', undefined, e));
+    }
+}

package/packages/sdk/src/utils/errorHandler.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { handleContractError } from './errorHandler.js';
+
+describe('ErrorHandler', () => {
+    const MOCK_CTX = {
+        operation: 'test operation',
+        roleId: '0xRole' as const,
+        account: '0xUser'
+    };
+
+    it('should enhance known contract errors', () => {
+        const error = new Error('Execution reverted: Error: RoleNotGranted(0xabc, 0xdef)');
+        const enhanced = handleContractError(error, MOCK_CTX);
+        expect(enhanced.message).toContain('does not have role');
+        expect(enhanced.message).toContain('Please register for this role first');
+    });
+
+    it('should use context if args missing', () => {
+        const error = new Error('Execution reverted: Error: RoleNotGranted()');
+        const enhanced = handleContractError(error, MOCK_CTX);
+        expect(enhanced.message).toContain('0xUser does not have role 0xRole');
+    });
+
+    it('should extract error from message if data.errorName is missing', () => {
+        // Simulate an error where data.errorName is missing but message contains relevant info
+        const error = {
+            message: 'Error: Registry: Role "0xRole" is not configured in the Registry'
+        };
+        const enhanced = handleContractError(error, MOCK_CTX);
+        expect(enhanced.message).toContain('is not configured in the Registry');
+    });
+
+    it('should handle all known contract errors', () => {
+        const errors = [
+            { name: 'RoleNotGranted', args: ['0xRole', '0xUser'], match: 'does not have role' },
+            { name: 'InsufficientBalance', args: [], match: 'Insufficient balance' },
+            { name: 'InvalidParameter', args: ['BadParam'], match: 'Invalid parameter' },
+            { name: 'Unauthorized', args: [], match: 'Unauthorized operation' },
+            { name: 'OwnableUnauthorizedAccount', args: ['0xUser'], match: 'not authorized' },
+            { name: 'RoleNotConfigured', args: ['0xRole'], match: 'not configured' }
+        ];
+
+        for (const { name, args, match } of errors) {
+            const error = {
+                data: { errorName: name, args },
+                message: `Error: ${name}(...`
+            };
+            const enhanced = handleContractError(error, MOCK_CTX);
+            expect(enhanced.message).toContain(match);
+        }
+    });
+
+    it('should fallback to stringify matching', () => {
+        // The implementation checks if JSON.stringify(error) includes known keys
+        const weirdError = {
+            inner: 'RoleNotConfigured'
+        };
+        const enhanced = handleContractError(weirdError, MOCK_CTX);
+        expect(enhanced.message).toContain('not configured');
+    });
+
+    it('should fallback for unknown error', () => {
+        const error = new Error('Random connection failed');
+        const enhanced = handleContractError(error, MOCK_CTX);
+        expect(enhanced.message).toContain('Random connection failed');
+    });
+
+    it('should handle empty error object', () => {
+        const enhanced = handleContractError({}, MOCK_CTX);
+        expect(enhanced.message).toBe('Failed to test operation: Unknown error');
+    });
+
+    it('should prioritize args over context for RoleAlreadyGranted', () => {
+        const enhanced = handleContractError({
+            data: { errorName: 'RoleAlreadyGranted', args: ['0xArgRole', '0xArgUser'] }
+        }, MOCK_CTX);
+        expect(enhanced.message).toContain('Account 0xArgUser already has this role (0xArgRole)');
+    });
+
+    it('should use context if args missing for RoleAlreadyGranted', () => {
+        const enhanced = handleContractError({
+            data: { errorName: 'RoleAlreadyGranted', args: [] }
+        }, MOCK_CTX);
+        expect(enhanced.message).toContain(`Account ${MOCK_CTX.account} already has this role (${MOCK_CTX.roleId})`);
+    });
+
+    it('should prioritize args for InsufficientStake', () => {
+        const enhanced = handleContractError({
+            data: { errorName: 'InsufficientStake', args: [100n, 200n] }
+        }, MOCK_CTX);
+        expect(enhanced.message).toContain('Required: 100');
+        expect(enhanced.message).toContain('Actual: 200');
+    });
+
+    it('should handle missing args for InsufficientStake', () => {
+        const enhanced = handleContractError({
+            data: { errorName: 'InsufficientStake', args: [] } // Missing args
+        }, MOCK_CTX);
+        expect(enhanced.message).toContain('Insufficient stake for this operation.');
+        expect(enhanced.message).not.toContain('Required:');
+    });
+});

package/packages/sdk/src/utils/eventDecoder.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi } from 'vitest';
+import { decodeContractEvents, logDecodedEvents } from './eventDecoder.js';
+import { keccak256, encodeAbiParameters, stringToBytes, type Hex, type Address } from 'viem';
+
+describe('eventDecoder', () => {
+    it('should decode known events', () => {
+        // Manual topic construction for RoleGranted(bytes32,address,address)
+        const ROLE_GRANTED_SIG = keccak256(stringToBytes('RoleGranted(bytes32,address,address)'));
+        const roleId = keccak256(stringToBytes('COMMUNITY'));
+        const account = '0x0000000000000000000000000000000000000001';
+        const sender = '0x0000000000000000000000000000000000000002';
+
+        const topics = [
+            ROLE_GRANTED_SIG,
+            roleId,
+            encodeAbiParameters([{ type: 'address' }], [account as Address]),
+            encodeAbiParameters([{ type: 'address' }], [sender as Address])
+        ];
+
+        const logs = [{
+            data: '0x' as Hex,
+            topics: topics as any
+        }];
+
+        const decoded = decodeContractEvents(logs);
+        expect(decoded).toHaveLength(1);
+        expect(decoded[0].contractName).toBe('Registry');
+        expect(decoded[0].eventName).toBe('RoleGranted');
+    });
+
+    it('should skip invalid logs', () => {
+        const logs = [{ data: 'invalid', topics: [] }];
+        const decoded = decodeContractEvents(logs);
+        expect(decoded).toHaveLength(0);
+    });
+
+    it('should handle decoding errors gracefully', () => {
+        const logs = [{ data: '0x123', topics: ['0x0000000000000000000000000000000000000000000000000000000000000000'] }];
+        const decoded = decodeContractEvents(logs);
+        expect(decoded).toHaveLength(0);
+    });
+
+    it('should log decoded events', () => {
+        const consoleSpy = vi.spyOn(console, 'log');
+        const events = [{
+            contractName: 'Test',
+            eventName: 'Event',
+            args: { amount: 100n, user: '0x0000000000000000000000000000000000000001' }
+        }];
+
+        logDecodedEvents(events);
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[Test] Event: Event'));
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('amount: 100'));
+        consoleSpy.mockRestore();
+    });
+});

package/packages/sdk/src/utils/eventDecoder.ts

@@ -0,0 +1,66 @@
+import { decodeEventLog, type Hex, type Abi } from 'viem';
+import { RegistryABI, SuperPaymasterABI, GTokenStakingABI, MySBTABI, xPNTsTokenABI, PaymasterFactoryABI } from '../index.js';
+
+const ABIS_TO_TRY = [
+    { name: 'Registry', abi: RegistryABI },
+    { name: 'SuperPaymaster', abi: SuperPaymasterABI },
+    { name: 'GTokenStaking', abi: GTokenStakingABI },
+    { name: 'MySBT', abi: MySBTABI },
+    { name: 'xPNTsToken', abi: xPNTsTokenABI },
+    { name: 'PaymasterFactory', abi: PaymasterFactoryABI }
+];
+
+export interface DecodedEvent {
+    contractName: string;
+    eventName: string;
+    args: any;
+}
+
+export function decodeContractEvents(logs: any[]): DecodedEvent[] {
+    const decodedEvents: DecodedEvent[] = [];
+
+    for (const log of logs) {
+        if (typeof log.data !== 'string' || !log.data.startsWith('0x')) {
+            console.warn('   ⚠️ Skipping log with invalid data:', log);
+            continue; 
+        }
+
+        for (const { name, abi } of ABIS_TO_TRY) {
+            try {
+                const decoded = decodeEventLog({
+                    abi: abi as Abi,
+                    data: log.data as Hex,
+                    topics: log.topics as any
+                });
+
+                if (decoded && decoded.eventName) {
+                    decodedEvents.push({
+                        contractName: name,
+                        eventName: decoded.eventName,
+                        args: decoded.args
+                    });
+                    break; // Found the right ABI for this log
+                }
+            } catch (e: any) {
+               // Ignore mismatch errors, but log weird ones
+               if (e.message && Object.values(e.message).some((m: any) => m?.includes?.('slice'))) {
+                   console.warn(`   ⚠️ decodeEventLog failed (slice error) for ${name}:`, e.message);
+               }
+            }
+        }
+    }
+
+    return decodedEvents;
+}
+
+export function logDecodedEvents(events: DecodedEvent[]) {
+    for (const event of events) {
+        console.log(`📡 [${event.contractName}] Event: ${event.eventName}`);
+        if (event.args) {
+            Object.entries(event.args).forEach(([key, value]) => {
+                const displayValue = typeof value === 'bigint' ? value.toString() : value;
+                console.log(`   └─ ${key}: ${displayValue}`);
+            });
+        }
+    }
+}