@aastar/sdk 0.14.0 → 0.16.6

package/package.json

@@ -1,30 +1,66 @@
 {
   "name": "@aastar/sdk",
-  "version": "0.14.0",
-  "description": "AAStar SDK - The all-in-one package for Mycelium Network",
+  "version": "0.16.6",
+  "private": false,
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
+  "workspaces": [
+    "packages/*"
   ],
-  "dependencies": {
-    "viem": "2.43.3",
-    "@aastar/account": "0.12.0",
-    "@aastar/core": "0.12.0",
-    "@aastar/dapp": "0.12.0",
-    "@aastar/identity": "0.12.0",
-    "@aastar/paymaster": "0.12.0",
-    "@aastar/tokens": "0.12.0"
+  "scripts": {
+    "build": "pnpm -r build",
+    "test": "pnpm -r test",
+    "test:coverage": "vitest run packages --coverage",
+    "test:fast": "ts-node scripts/99_bug_hunting_fast.ts",
+    "test:init": "bash run_full_regression.sh init",
+    "test:admin": "ts-node scripts/10_test_protocol_admin_full.ts",
+    "test:credit": "ts-node scripts/14_test_credit_redesign.ts",
+    "test:reentrancy": "ts-node scripts/98_edge_reentrancy.ts",
+    "test:full_anvil": "bash run_full_regression.sh",
+    "test:full_sdk": "bash run_full_regression.sh sdk",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint packages/*/src --ext .ts",
+    "lint:fix": "ESLINT_USE_FLAT_CONFIG=false eslint packages/*/src --ext .ts --fix",
+    "audit": "pnpm audit --audit-level=moderate",
+    "audit:fix": "pnpm audit --fix",
+    "security:check": "bash scripts/security_audit.sh",
+    "security:full": "pnpm audit && bash scripts/security_audit.sh",
+    "audit:abi": "pnpm --filter @aastar/core run audit:abi",
+    "precommit": "pnpm security:check",
+    "prepare": "pnpm install --frozen-lockfile",
+    "example:local": "pnpm --filter @aastar/sdk run example:local",
+    "sync-config": "cp ../SuperPaymaster/script/v3/config.json ./packages/sdk/examples/config.json",
+    "test:env": "tsx scripts/validate_env.ts",
+    "test:regression": "pnpm run test:regression:00 && pnpm run test:regression:01 && pnpm run test:regression:02 && pnpm run test:regression:03 && pnpm run test:regression:04 && pnpm run test:regression:05 && pnpm run test:regression:bls",
+    "test:regression:00": "tsx scripts/v2_regression/00_validate_env.ts",
+    "test:regression:01": "tsx scripts/v2_regression/01_setup_and_fund.ts",
+    "test:regression:02": "tsx scripts/v2_regression/02_operator_onboarding.ts",
+    "test:regression:03": "tsx scripts/v2_regression/03_community_registry.ts",
+    "test:regression:04": "tsx scripts/v2_regression/04_enduser_flow.ts",
+    "test:regression:05": "tsx scripts/v2_regression/05_admin_audit.ts",
+    "test:regression:bls": "ts-node scripts/15_test_bls_full.ts",
+    "docs:generate": "typedoc --options typedoc.json",
+    "docs:sync": "bash scripts/extract-docs.sh"
   },
   "devDependencies": {
-    "typescript": "5.9.3"
+    "@types/node": "20.11.5",
+    "@typescript-eslint/eslint-plugin": "8.50.1",
+    "@typescript-eslint/parser": "8.50.1",
+    "@vitest/coverage-v8": "4.0.17",
+    "cross-env": "10.1.0",
+    "dotenv": "17.2.3",
+    "eslint": "9.39.2",
+    "ts-node": "10.9.2",
+    "tsx": "4.21.0",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "5.7.2",
+    "vitest": "4.0.17",
+    "axios": "1.13.2",
+    "cheerio": "1.1.2",
+    "csv-writer": "1.6.0"
   },
-  "scripts": {
-    "build": "tsc",
-    "example:local": "tsx examples/regression_test.ts"
+  "dependencies": {
+    "@noble/bls12-381": "1.4.0",
+    "@noble/curves": "^1.9.7",
+    "viem": "2.43.3"
   }
-}
+}

package/packages/account/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@aastar/account",
+  "version": "0.16.6",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aastar/core": "workspace:*",
+    "viem": "2.43.3"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/account/src/accounts/simple.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from 'vitest';
+import { toSimpleSmartAccount } from './simple.js';
+import { type Address } from 'viem';
+
+describe('SimpleSmartAccount', () => {
+    const MOCK_OWNER = {
+        address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266' as Address,
+        signMessage: vi.fn().mockResolvedValue('0xsignature'),
+        signTypedData: vi.fn(),
+    };
+    const MOCK_FACTORY = '0x1111111111111111111111111111111111111111' as Address;
+    const MOCK_SMART_ACCOUNT = '0x2222222222222222222222222222222222222222' as Address;
+    const MOCK_EP = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789' as Address;
+
+    it('should create simple smart account wrapper', async () => {
+        const mockClient = {
+            readContract: vi.fn().mockResolvedValue(MOCK_SMART_ACCOUNT),
+            chain: { id: 31337 }
+        };
+
+        const account = await toSimpleSmartAccount({
+            client: mockClient,
+            owner: MOCK_OWNER as any,
+            factoryAddress: MOCK_FACTORY,
+            entryPoint: { address: MOCK_EP, version: '0.6' }
+        });
+
+        expect(account.address).toBe(MOCK_SMART_ACCOUNT);
+        expect(account.entryPoint).toBe(MOCK_EP);
+        
+        const initCode = await account.getInitCode();
+        expect(initCode.startsWith(MOCK_FACTORY)).toBe(true);
+        
+        const dummy = await account.getDummySignature();
+        expect(dummy).toBeDefined();
+    });
+
+    it('should sign user operation', async () => {
+        const mockClient = {
+            readContract: vi.fn().mockResolvedValue(MOCK_SMART_ACCOUNT),
+            chain: { id: 31337 }
+        };
+        const account = await toSimpleSmartAccount({
+            client: mockClient,
+            owner: MOCK_OWNER as any,
+            factoryAddress: MOCK_FACTORY,
+            entryPoint: { address: MOCK_EP, version: '0.6' }
+        });
+
+        const userOp = {
+            sender: MOCK_SMART_ACCOUNT,
+            nonce: 0n,
+            initCode: '0x',
+            callData: '0x',
+            accountGasLimits: '0x0000000000000000000000000000000000000000000000000000000000000000',
+            preVerificationGas: 0n,
+            gasFees: '0x0000000000000000000000000000000000000000000000000000000000000000',
+            paymasterAndData: '0x'
+        };
+
+        const sig = await account.signUserOperation(userOp);
+        expect(sig).toBe('0xsignature');
+        expect(MOCK_OWNER.signMessage).toHaveBeenCalled();
+    });
+
+    it('should sign message and typed data', async () => {
+        const mockClient = { readContract: vi.fn().mockResolvedValue(MOCK_SMART_ACCOUNT) };
+        const account = await toSimpleSmartAccount({
+            client: mockClient,
+            owner: MOCK_OWNER as any,
+            factoryAddress: MOCK_FACTORY,
+            entryPoint: { address: MOCK_EP, version: '0.6' }
+        });
+
+        await account.signMessage({ message: 'hello' });
+        expect(MOCK_OWNER.signMessage).toHaveBeenCalled();
+
+        await account.signTypedData({} as any);
+        expect(MOCK_OWNER.signTypedData).toHaveBeenCalled();
+    });
+
+    it('should throw on signTransaction', async () => {
+        const mockClient = { readContract: vi.fn().mockResolvedValue(MOCK_SMART_ACCOUNT) };
+        const account = await toSimpleSmartAccount({
+            client: mockClient,
+            owner: MOCK_OWNER as any,
+            factoryAddress: MOCK_FACTORY,
+            entryPoint: { address: MOCK_EP, version: '0.6' }
+        });
+
+        await expect(account.signTransaction({})).rejects.toThrow('UserOperations');
+    });
+});

package/packages/account/src/accounts/simple.ts

@@ -0,0 +1,84 @@
+import { 
+    type Address, 
+    type Hex, 
+    type LocalAccount, 
+    type SignableMessage, 
+    type TypedDataDefinition,
+    type Hash,
+    concatHex, 
+    encodeFunctionData, 
+    keccak256,
+} from 'viem';
+import { SimpleAccountFactoryABI } from '@aastar/core';
+import { getUserOpHash } from '../index.js';
+
+export type SimpleSmartAccount = LocalAccount & {
+    signUserOperation: (userOp: any) => Promise<Hex>;
+    getInitCode: () => Promise<Hex>;
+    getDummySignature: () => Promise<Hex>;
+    entryPoint: Address;
+};
+
+export async function toSimpleSmartAccount(parameters: {
+    client: any;
+    owner: LocalAccount;
+    factoryAddress: Address;
+    entryPoint: { address: Address; version: '0.6' | '0.7' };
+    salt?: bigint;
+    index?: bigint;
+}): Promise<SimpleSmartAccount> {
+    const { client, owner, factoryAddress, entryPoint, index = 0n, salt = 0n } = parameters;
+    
+    // Calculate initCode
+    const factoryData = encodeFunctionData({
+        abi: SimpleAccountFactoryABI,
+        functionName: 'createAccount',
+        args: [owner.address, salt]
+    });
+    const initCode = concatHex([factoryAddress, factoryData]);
+
+    // Calculate counterfactual address
+    const address = await client.readContract({
+         address: factoryAddress,
+         abi: SimpleAccountFactoryABI,
+         functionName: 'getAddress',
+         args: [owner.address, salt]
+    });
+
+    return {
+        address,
+        publicKey: owner.address,
+        source: 'custom', 
+        type: 'local',
+        entryPoint: entryPoint.address,
+        
+        async signMessage({ message }: { message: SignableMessage }): Promise<Hex> {
+            // validating signature for smart account usually involves EIP-1271, 
+            // but here we just sign with owner for SimpleAccount which validates owner sig
+            return owner.signMessage({ message });
+        },
+
+        async signTypedData(typedData: TypedDataDefinition): Promise<Hex> {
+            return owner.signTypedData(typedData);
+        },
+
+        async signTransaction(transaction: any): Promise<Hex> {
+            throw new Error('Smart Accounts cannot sign transactions directly. Use UserOperations.');
+        },
+        
+        async signUserOperation(userOp: any): Promise<Hex> {
+            const chainId = client.chain?.id || 31337; // Default to local anvil if not found
+            const hash = getUserOpHash(userOp, entryPoint.address, chainId);
+            return owner.signMessage({ message: { raw: hash } });
+        },
+        
+        async getInitCode() {
+            return initCode;
+        },
+
+        async getDummySignature() {
+            return '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
+        }
+
+    } as any as SimpleSmartAccount;
+}

package/packages/account/src/eoa.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createEOAWalletClient } from './eoa.js';
+import * as viem from 'viem';
+import { mainnet } from 'viem/chains';
+
+vi.mock('viem', async () => {
+    const actual = await vi.importActual('viem');
+    return {
+        ...actual,
+        createWalletClient: vi.fn(),
+    };
+});
+
+describe('EOAWalletClient', () => {
+    const MOCK_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+    const MOCK_ADDR = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+
+    it('should create and use EOA wallet client', async () => {
+        const sendTransactionSpy = vi.fn().mockResolvedValue('0xhash');
+        const mockViemClient = {
+            sendTransaction: sendTransactionSpy,
+            account: { address: MOCK_ADDR }
+        };
+        (viem.createWalletClient as any).mockReturnValue(mockViemClient);
+
+        const client = createEOAWalletClient(MOCK_KEY, mainnet);
+        
+        expect(client.getAddress()).toBe(MOCK_ADDR);
+        
+        const hash = await client.sendTransaction({ to: MOCK_ADDR, value: 100n });
+        expect(hash).toBe('0xhash');
+        expect(sendTransactionSpy).toHaveBeenCalledWith(expect.objectContaining({
+            to: MOCK_ADDR,
+            value: 100n
+        }));
+    });
+});

package/packages/account/src/eoa.ts

@@ -0,0 +1,33 @@
+import { type WalletClient, type PublicClient, type Address, type Chain, type Transport, type Hash, type Hex, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+export type EOAWalletClient = WalletClient & {
+    sendTransaction: (args: { to: Address, value?: bigint, data?: Hex }) => Promise<Hash>;
+    getAddress: () => Address;
+};
+
+export const createEOAWalletClient = (
+    privateKey: Hex, 
+    chain: Chain, 
+    transport: Transport = http()
+): EOAWalletClient => {
+    const account = privateKeyToAccount(privateKey);
+    const client = createWalletClient({
+        account,
+        chain,
+        transport
+    });
+
+    const baseSendTransaction = client.sendTransaction.bind(client);
+
+    return Object.assign(client, {
+        async sendTransaction(args: { to: Address, value?: bigint, data?: Hex }) {
+            return baseSendTransaction({
+                ...args,
+                account,
+                chain
+            } as any);
+        },
+        getAddress: () => account.address
+    }) as EOAWalletClient;
+};

package/packages/account/src/index.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi } from 'vitest';
+import { packUserOpLimits, UserOpClient } from './index.js';
+
+describe('Account Utils', () => {
+    it('should pack user op limits', () => {
+        const packed = packUserOpLimits(100n, 200n);
+        expect(packed).toBeDefined();
+        expect(packed.length).toBe(66); // 0x + 64 chars
+    });
+
+    describe('UserOpClient', () => {
+        const mockBundler = {
+            request: vi.fn()
+        };
+
+        it('should estimate gas', async () => {
+            mockBundler.request.mockResolvedValue({ preVerificationGas: 1000n });
+            const res = await UserOpClient.estimateGas(mockBundler, {}, '0x1' as any);
+            expect(res.preVerificationGas).toBe(1000n);
+        });
+
+        it('should send user operation', async () => {
+            mockBundler.request.mockResolvedValue('0xhash');
+            const res = await UserOpClient.sendUserOp(mockBundler, {}, '0x1' as any);
+            expect(res).toBe('0xhash');
+        });
+
+        it('should get receipt', async () => {
+            mockBundler.request.mockResolvedValue({ success: true });
+            const res = await UserOpClient.getReceipt(mockBundler, '0xhash');
+            expect(res.success).toBe(true);
+        });
+    });
+});

package/packages/account/src/index.ts

@@ -0,0 +1,61 @@
+import { type Hex, type Address, encodeAbiParameters, keccak256 } from 'viem';
+
+export * from './eoa.js';
+export * from './accounts/simple.js';
+
+/**
+ * Common Pack Logic for v0.7 UserOperations
+ */
+export function packUserOpLimits(high: bigint, low: bigint): Hex {
+    return `0x${((high << 128n) | low).toString(16).padStart(64, '0')}` as Hex;
+}
+
+/**
+ * Local implementation of EntryPoint v0.7 getUserOpHash
+ */
+export function getUserOpHash(op: any, ep: Address, chainId: number): Hex {
+    const packed = encodeAbiParameters(
+        [
+            { type: 'address' }, { type: 'uint256' }, { type: 'bytes32' }, { type: 'bytes32' },
+            { type: 'bytes32' }, { type: 'uint256' }, { type: 'bytes32' }, { type: 'bytes32' }
+        ],
+        [
+            op.sender, BigInt(op.nonce), 
+            keccak256(op.initCode && op.initCode !== "0x" ? op.initCode : '0x'), 
+            keccak256(op.callData),
+            op.accountGasLimits, BigInt(op.preVerificationGas), op.gasFees,
+            keccak256(op.paymasterAndData)
+        ]
+    );
+    const enc = encodeAbiParameters(
+        [{ type: 'bytes32' }, { type: 'address' }, { type: 'uint256' }],
+        [keccak256(packed), ep, BigInt(chainId)]
+    );
+    return keccak256(enc);
+}
+
+/**
+ * UserOperation Client for handling high-level flows
+ */
+export class UserOpClient {
+    static async estimateGas(bundler: any, op: any, entryPoint: Address) {
+        return bundler.request({
+            method: 'eth_estimateUserOperationGas',
+            params: [op, entryPoint]
+        });
+    }
+
+    static async sendUserOp(bundler: any, op: any, entryPoint: Address) {
+        return bundler.request({
+            method: 'eth_sendUserOperation',
+            params: [op, entryPoint]
+        });
+    }
+
+    static async getReceipt(bundler: any, hash: Hex) {
+        return bundler.request({
+            method: 'eth_getUserOperationReceipt',
+            params: [hash]
+        });
+    }
+}

package/packages/account/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "noEmit": false,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src", "src/abis/*.json"]
+}

package/packages/analytics/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@aastar/analytics",
+  "version": "0.16.6",
+  "description": "Analytics client for AAstar SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests"
+  },
+  "keywords": [
+    "aastar",
+    "analytics",
+    "web3"
+  ],
+  "author": "AAstar Team",
+  "license": "MIT",
+  "dependencies": {
+    "@aastar/core": "workspace:*",
+    "viem": "2.43.3"
+  },
+  "devDependencies": {
+    "typescript": "5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/analytics/src/index.ts

@@ -0,0 +1,145 @@
+import { Address, Hash, PublicClient, zeroAddress, parseAbiItem, Log, parseAbi } from 'viem';
+
+/**
+ * Analytics client for monitoring and statistics
+ * 
+ * @roleRequired None (public query APIs)
+ * @description Dashboard and monitoring tools
+ * 
+ * ## No Permission Required - All Public Queries
+ * 
+ * ## Typical Users:
+ * - Dashboard Developers
+ * - Community Analytics
+ * - Investors & Researchers
+ */
+export class AnalyticsClient {
+    private publicClient: PublicClient;
+    private gtokenAddress?: Address;
+    private registryAddress?: Address;
+
+    constructor(
+        publicClient: PublicClient,
+        addresses?: {
+            gtoken?: Address;
+            registry?: Address;
+        }
+    ) {
+        this.publicClient = publicClient;
+        this.gtokenAddress = addresses?.gtoken;
+        this.registryAddress = addresses?.registry;
+    }
+
+    /**
+     * Get complete supply metrics
+     * @roleRequired None (public view)
+     */
+    async getSupplyMetrics(): Promise<{
+        cap: bigint;
+        totalSupply: bigint;
+        totalLifetimeBurned: bigint;
+        remainingMintable: bigint;
+        deflationRate: number;
+    }> {
+        const { CORE_ADDRESSES } = await import('@aastar/core');
+        const gtokenAddress = this.gtokenAddress || CORE_ADDRESSES.gToken;
+
+        const [cap, totalSupply, remainingMintable] = await Promise.all([
+            this.publicClient.readContract({
+                address: gtokenAddress,
+                abi: parseAbi(['function cap() view returns (uint256)']),
+                functionName: 'cap'
+            }) as Promise<bigint>,
+            this.publicClient.readContract({
+                address: gtokenAddress,
+                abi: parseAbi(['function totalSupply() view returns (uint256)']),
+                functionName: 'totalSupply'
+            }) as Promise<bigint>,
+            this.publicClient.readContract({
+                address: gtokenAddress,
+                abi: parseAbi(['function remainingMintableSupply() view returns (uint256)']),
+                functionName: 'remainingMintableSupply'
+            }) as Promise<bigint>
+        ]);
+
+        let totalLifetimeBurned = 0n;
+        try {
+            totalLifetimeBurned = await this.publicClient.readContract({
+                address: gtokenAddress,
+                abi: parseAbi(['function totalLifetimeBurned() view returns (uint256)']),
+                functionName: 'totalLifetimeBurned'
+            }) as bigint;
+        } catch {
+            totalLifetimeBurned = cap - totalSupply - remainingMintable;
+        }
+
+        const deflationRate = Number(totalLifetimeBurned * 10000n / cap) / 100;
+
+        return { cap, totalSupply, totalLifetimeBurned, remainingMintable, deflationRate };
+    }
+
+    /**
+     * Subscribe to real-time burn events
+     * @roleRequired None (public events)
+     */
+    subscribeToBurnEvents(callback: (event: {
+        from: Address;
+        amount: bigint;
+        blockNumber: number;
+        timestamp: number;
+    }) => void): () => void {
+        const { CORE_ADDRESSES } = require('@aastar/core');
+        const gtokenAddress = this.gtokenAddress || CORE_ADDRESSES.gToken;
+
+        const unwatch = this.publicClient.watchEvent({
+            address: gtokenAddress,
+            event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
+            onLogs: async (logs) => {
+                for (const log of logs) {
+                    if (log.args && (log.args as any).to === zeroAddress) {
+                        const block = await this.publicClient.getBlock({ blockNumber: log.blockNumber! });
+                        callback({
+                            from: (log.args as any).from,
+                            amount: (log.args as any).value,
+                            blockNumber: Number(log.blockNumber),
+                            timestamp: Number(block.timestamp)
+                        });
+                    }
+                }
+            }
+        });
+
+        return unwatch;
+    }
+
+    /**
+     * Get role entrance cost breakdown
+     * @roleRequired None (public view)
+     */
+    async getRoleEntranceCost(roleId: Hash): Promise<{
+        minStake: bigint;
+        entryBurn: bigint;
+        totalRequired: bigint;
+        exitFee: { percent: number; minFee: bigint };
+    }> {
+        const { CORE_ADDRESSES } = await import('@aastar/core');
+        const registryAddress = this.registryAddress || CORE_ADDRESSES.registry;
+
+        const config = await this.publicClient.readContract({
+            address: registryAddress,
+            abi: parseAbi(['function getRoleConfig(bytes32) view returns ((uint256 minStake, uint256 entryBurn, uint8 slashThreshold, uint8 slashBase, uint8 slashIncrement, uint8 slashMax, uint256 exitFeePercent, uint256 minExitFee, bool isActive, string description))']),
+            functionName: 'getRoleConfig',
+            args: [roleId]
+        }) as any;
+
+        return {
+            minStake: config.minStake,
+            entryBurn: config.entryBurn,
+            totalRequired: config.minStake + config.entryBurn,
+            exitFee: {
+                percent: Number(config.exitFeePercent) / 100,
+                minFee: config.minExitFee
+            }
+        };
+    }
+}

package/packages/analytics/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+}