@aastar/sdk 0.14.3 → 0.16.6

package/packages/core/src/actions/faucet.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { type Address, type PublicClient, type WalletClient, type Account, parseEther } from 'viem';
+import { SepoliaFaucetAPI } from './faucet.js';
+
+describe('SepoliaFaucetAPI', () => {
+    let mockAdminWallet: Partial<WalletClient>;
+    let mockPublicClient: Partial<PublicClient>;
+    let mockAccount: Account;
+
+    const MOCK_ADMIN: Address = '0x1111111111111111111111111111111111111111';
+    const MOCK_TARGET: Address = '0x2222222222222222222222222222222222222222';
+    const MOCK_TOKEN: Address = '0x3333333333333333333333333333333333333333';
+    const MOCK_REGISTRY: Address = '0x4444444444444444444444444444444444444444';
+    const MOCK_PM_V4: Address = '0x5555555555555555555555555555555555555555';
+
+    beforeEach(() => {
+        mockAccount = {
+            address: MOCK_ADMIN,
+            type: 'json-rpc'
+        } as Account;
+
+        mockAdminWallet = {
+            account: mockAccount,
+            sendTransaction: vi.fn(),
+            writeContract: vi.fn(),
+        };
+
+        mockPublicClient = {
+            getBalance: vi.fn(),
+            readContract: vi.fn(),
+            waitForTransactionReceipt: vi.fn(),
+        };
+    });
+
+    describe('fundETH', () => {
+        it('should fund ETH if balance is low', async () => {
+            (mockPublicClient.getBalance as any).mockResolvedValue(parseEther('0.01'));
+            (mockAdminWallet.sendTransaction as any).mockResolvedValue('0xhash');
+            (mockPublicClient.waitForTransactionReceipt as any).mockResolvedValue({});
+
+            const funded = await SepoliaFaucetAPI.fundETH(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_TARGET,
+                parseEther('0.1')
+            );
+
+            expect(funded).toBe(true);
+            expect(mockAdminWallet.sendTransaction).toHaveBeenCalled();
+        });
+
+        it('should not fund ETH if balance is sufficient', async () => {
+            (mockPublicClient.getBalance as any).mockResolvedValue(parseEther('0.1'));
+
+            const funded = await SepoliaFaucetAPI.fundETH(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_TARGET,
+                parseEther('0.1')
+            );
+
+            expect(funded).toBe(false);
+            expect(mockAdminWallet.sendTransaction).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('registerEndUser', () => {
+        it('should register end user if role not held', async () => {
+            (mockPublicClient.readContract as any)
+                .mockResolvedValueOnce(false) // hasRole
+                .mockResolvedValueOnce('0xstaking') // GTOKEN_STAKING
+                .mockResolvedValueOnce(parseEther('1000')); // allowance
+
+            (mockAdminWallet.writeContract as any).mockResolvedValue('0xhash');
+            (mockPublicClient.waitForTransactionReceipt as any).mockResolvedValue({});
+
+            const registered = await SepoliaFaucetAPI.registerEndUser(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_REGISTRY,
+                MOCK_TARGET,
+                MOCK_TOKEN
+            );
+
+            expect(registered).toBe(true);
+            expect(mockAdminWallet.writeContract).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    functionName: 'safeMintForRole',
+                })
+            );
+        });
+
+        it('should skip registration if role already held', async () => {
+            (mockPublicClient.readContract as any).mockResolvedValue(true);
+
+            const registered = await SepoliaFaucetAPI.registerEndUser(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_REGISTRY,
+                MOCK_TARGET,
+                MOCK_TOKEN
+            );
+
+            expect(registered).toBe(false);
+        });
+    });
+
+    describe('mintTestTokens', () => {
+        it('should mint tokens if balance is low', async () => {
+            (mockPublicClient.readContract as any).mockResolvedValue(0n);
+            (mockAdminWallet.writeContract as any).mockResolvedValue('0xhash');
+            (mockPublicClient.waitForTransactionReceipt as any).mockResolvedValue({});
+
+            const minted = await SepoliaFaucetAPI.mintTestTokens(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_TOKEN,
+                MOCK_TARGET,
+                parseEther('1000')
+            );
+
+            expect(minted).toBe(true);
+            expect(mockAdminWallet.writeContract).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    functionName: 'mint',
+                    args: [MOCK_TARGET, parseEther('1000')],
+                })
+            );
+        });
+
+        it('should skip minting if balance is sufficient', async () => {
+            (mockPublicClient.readContract as any).mockResolvedValue(parseEther('1000'));
+
+            const minted = await SepoliaFaucetAPI.mintTestTokens(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_TOKEN,
+                MOCK_TARGET,
+                parseEther('1000')
+            );
+
+            expect(minted).toBe(false);
+        });
+    });
+
+    describe('adminDepositForUser', () => {
+        it('should perform admin deposit flow', async () => {
+            (mockPublicClient.readContract as any)
+                .mockResolvedValueOnce(parseEther('100')) // admin balance
+                .mockResolvedValueOnce(parseEther('10000')); // allowance
+
+            (mockAdminWallet.writeContract as any).mockResolvedValue('0xhash');
+            (mockPublicClient.waitForTransactionReceipt as any).mockResolvedValue({});
+
+            const deposited = await SepoliaFaucetAPI.adminDepositForUser(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                MOCK_PM_V4,
+                MOCK_TARGET,
+                MOCK_TOKEN,
+                parseEther('10')
+            );
+
+            expect(deposited).toBe(true);
+            expect(mockAdminWallet.writeContract).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    functionName: 'depositFor',
+                    args: [MOCK_TARGET, parseEther('10')],
+                })
+            );
+        });
+    });
+
+    describe('prepareTestAccount', () => {
+        it('should orchestrate complete setup', async () => {
+            // Mock fundETH
+            vi.spyOn(SepoliaFaucetAPI, 'fundETH').mockResolvedValue(true);
+            // Mock registerEndUser
+            vi.spyOn(SepoliaFaucetAPI, 'registerEndUser').mockResolvedValue(true);
+            // Mock mintTestTokens
+            vi.spyOn(SepoliaFaucetAPI, 'mintTestTokens').mockResolvedValue(true);
+            // Mock adminDepositForUser
+            vi.spyOn(SepoliaFaucetAPI, 'adminDepositForUser').mockResolvedValue(true);
+
+            const result = await SepoliaFaucetAPI.prepareTestAccount(
+                mockAdminWallet as WalletClient,
+                mockPublicClient as PublicClient,
+                {
+                    targetAA: MOCK_TARGET,
+                    token: MOCK_TOKEN,
+                    registry: MOCK_REGISTRY,
+                    paymasterV4: MOCK_PM_V4
+                }
+            );
+
+            expect(result.ethFunded).toBe(true);
+            expect(result.roleRegistered).toBe(true);
+            expect(result.tokenMinted).toBe(true);
+            expect(result.paymasterDeposited).toBe(true);
+        });
+    });
+});

package/packages/core/src/actions/faucet.ts

@@ -0,0 +1,421 @@
+import { 
+    type Address, 
+    type WalletClient, 
+    type PublicClient, 
+    parseEther, 
+    parseAbi, 
+    createPublicClient,
+    http,
+    formatEther,
+    zeroAddress,
+    encodeAbiParameters
+} from 'viem';
+import { sepolia } from 'viem/chains';
+import { registryActions } from './registry';
+import { paymasterV4Actions } from './paymasterV4';
+
+// Standard ERC20 ABI for minting/approving
+const ERC20_ABI = parseAbi([
+    'function mint(address to, uint256 amount) external',
+    'function approve(address spender, uint256 amount) external returns (bool)',
+    'function balanceOf(address account) external view returns (uint256)',
+    'function allowance(address owner, address spender) external view returns (uint256)',
+    'function transfer(address to, uint256 amount) external returns (bool)'
+]);
+
+const PAYMASTER_ABI = parseAbi([
+    'function depositFor(address target, uint256 amount) external',
+    'function deposit() external payable'
+]); 
+
+export class SepoliaFaucetAPI {
+    
+    /**
+     * Orchestrates the complete setup for a test account.
+     * 1. Funds ETH
+     * 2. Registers ENDUSER role
+     * 3. Mints potential Paymaster Tokens (cPNTs/dPNTs)
+     * 4. Deposits to Paymaster V4 (if address provided) using Admin's tokens
+     */
+    static async prepareTestAccount(
+        adminWallet: WalletClient, 
+        publicClient: PublicClient,
+        config: {
+            targetAA: Address;
+            token: Address;
+            registry: Address;
+            paymasterV4?: Address;
+            superPaymaster?: Address; // Just for context, no specific action needed if user holds token
+            ethAmount?: bigint; // Default 0.1 ETH
+            tokenAmount?: bigint; // Default 1000 Tokens
+            community?: Address;
+        }
+    ) {
+        console.log(`\n🚰 SepoliaFaucetAPI: Preparing ${config.targetAA}...`);
+        const results = {
+            ethFunded: false,
+            roleRegistered: false,
+            tokenMinted: false,
+            paymasterDeposited: false
+        };
+
+        // 1. Fund ETH
+        const ethAmount = config.ethAmount ?? parseEther('0.1');
+        results.ethFunded = await this.fundETH(adminWallet, publicClient, config.targetAA, ethAmount);
+
+        // 2. Register EndUser
+        results.roleRegistered = await this.registerEndUser(adminWallet, publicClient, config.registry, config.targetAA, config.token, config.community);
+
+        // 3. Mint Tokens (User Holding Logic - for SuperPaymaster)
+        // If SuperPaymaster is involved, User needs to HOLD the token.
+        // If Paymaster V4 is involved, User might need to HOLD (Pull mode) or Admin Deposits (Push mode).
+        // Strategy: Always mint some to User for flexibility.
+        const tokenAmount = config.tokenAmount ?? parseEther('1000');
+        results.tokenMinted = await this.mintTestTokens(adminWallet, publicClient, config.token, config.targetAA, tokenAmount);
+
+        // 4. Admin Deposit for User (Paymaster V4 Logic)
+        if (config.paymasterV4) {
+            results.paymasterDeposited = await this.adminDepositForUser(
+                adminWallet, 
+                publicClient, 
+                config.paymasterV4, 
+                config.targetAA, 
+                config.token, 
+                parseEther('10') // Deposit 10 Tokens for testing
+            );
+        }
+
+        console.log(`✅ Preparation Complete!`, results);
+        return results;
+    }
+
+    /**
+     * Funds the target with ETH if balance is below threshold.
+     */
+    static async fundETH(adminWallet: WalletClient, publicClient: PublicClient, target: Address, amount: bigint): Promise<boolean> {
+        const balance = await publicClient.getBalance({ address: target });
+        // Threshold: 50% of target amount
+        if (balance < (amount / 2n)) {
+            console.log(`   💰 Funding ETH... (Before: ${formatEther(balance)})`);
+            const hash = await adminWallet.sendTransaction({
+                to: target,
+                value: amount,
+                chain: sepolia,
+                account: adminWallet.account! 
+            });
+            await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+            console.log(`      -> Sent ${formatEther(amount)} ETH. Tx: ${hash}`);
+            return true;
+        }
+        console.log(`   ✅ ETH Balance adequate (${formatEther(balance)} ETH).`);
+        return false;
+    }
+
+    /**
+     * Registers the ENDUSER role via Registry.
+     */
+    /**
+     * Registers the ENDUSER role using Sponsor Mode (Admin pays stake).
+     */
+    static async registerEndUser(
+        adminWallet: WalletClient, 
+        publicClient: PublicClient, 
+        registryAddr: Address, 
+        target: Address,
+        gasToken: Address, // Re-using the 'token' passed in config which is GToken
+        community?: Address
+    ): Promise<boolean> {
+        // ENDUSER Hash: keccak256("ENDUSER")
+        const ENDUSER_ROLE = '0x0c34ecc75d3bf122e0609d2576e167f53fb42429262ce8c9b33cab91ff670e3a';
+        
+        // 1. Check if already registered
+        const hasRole = await publicClient.readContract({
+            address: registryAddr,
+            abi: parseAbi(['function hasRole(bytes32 role, address account) view returns (bool)']),
+            functionName: 'hasRole',
+            args: [ENDUSER_ROLE as `0x${string}`, target]
+        });
+
+        if (hasRole) {
+            console.log(`   ✅ ENDUSER Role already held.`);
+            return false;
+        }
+
+        console.log(`   👤 Registering ENDUSER role (Sponsor Mode)...`);
+
+        try {
+            // 2. Get Staking Contract Address
+            const stakingAddr = await publicClient.readContract({
+                address: registryAddr,
+                abi: parseAbi(['function GTOKEN_STAKING() view returns (address)']),
+                functionName: 'GTOKEN_STAKING'
+            }) as Address;
+
+            // Fetch the actual GToken required by Staking
+            const stakingToken = await publicClient.readContract({
+                address: stakingAddr,
+                abi: parseAbi(['function GTOKEN() view returns (address)']),
+                functionName: 'GTOKEN'
+            }) as Address;
+
+            // 3. Admin Approves Staking Contract (if needed)
+            const adminAddr = adminWallet.account!.address;
+            console.log(`      🔎 Debug Staking: Registry=${registryAddr}, Staking=${stakingAddr}`);
+            console.log(`      🔎 Debug Token: Contract=${stakingToken}`);
+            
+            // Check allowance for the STAKING TOKEN
+            const allowance = await publicClient.readContract({
+                address: stakingToken,
+                abi: ERC20_ABI,
+                functionName: 'allowance',
+                args: [adminAddr, stakingAddr]
+            });
+            console.log(`      🔎 Debug Allowance: ${formatEther(allowance)} (Needed: >0.5)`);
+
+            // Approve if needed (standard stake ~0.3 ETH, verify enough)
+            const approveAmount = parseEther('1000'); // A sufficiently large amount
+            if (allowance < parseEther('500')) {
+                console.log('      🔓 Approving Staking Contract (Core Token)...');
+                const hashApprove = await adminWallet.writeContract({
+                    address: stakingToken,
+                    abi: ERC20_ABI,
+                    functionName: 'approve',
+                    args: [stakingAddr, approveAmount],
+                    chain: sepolia,
+                    account: adminWallet.account!
+                });
+                await publicClient.waitForTransactionReceipt({ hash: hashApprove, timeout: 300000 });
+                console.log(`      🔓 Approving Staking Contract... ${hashApprove}`);
+
+                // Ensure Admin has GTokens (Staking Token) balance
+                const adminGBal = await publicClient.readContract({
+                    address: stakingToken,
+                    abi: ERC20_ABI,
+                    functionName: 'balanceOf',
+                    args: [adminAddr]
+                }) as bigint;
+
+                if (adminGBal < parseEther('100')) {
+                    console.log(`      🪙 Minting GTokens (Staking Token) to Admin...`);
+                    try {
+                        const hashGMint = await adminWallet.writeContract({
+                            address: stakingToken,
+                            abi: ERC20_ABI,
+                            functionName: 'mint',
+                            args: [adminAddr, parseEther('1000')],
+                            chain: sepolia,
+                            account: adminWallet.account!
+                        });
+                        await publicClient.waitForTransactionReceipt({ hash: hashGMint, timeout: 300000 });
+                        console.log(`      ✅ GTokens Minted. Tx: ${hashGMint}`);
+                    } catch (e) {
+                        console.warn(`      ⚠️ Failed to mint GTokens (Admin might not be minter):`, e);
+                    }
+                }
+            }
+
+            // ALSO Approve Registry (just in case it pulls first)
+            const allowReg = await publicClient.readContract({
+                address: stakingToken,
+                abi: ERC20_ABI,
+                functionName: 'allowance',
+                args: [adminAddr, registryAddr]
+            });
+            if (allowReg < parseEther('500')) {
+                console.log('      🔓 Approving Registry Contract...');
+                const hash = await adminWallet.writeContract({
+                    address: stakingToken,
+                    abi: ERC20_ABI,
+                    functionName: 'approve',
+                    args: [registryAddr, parseEther('1000')],
+                    chain: sepolia,
+                    account: adminWallet.account!
+                });
+                await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+                console.log(`      ✅ Approved Registry. Tx: ${hash}`);
+            } else {
+                 console.log('      ✅ Allowance sufficient.');
+            }
+
+            // 5. Register Role (registerRole)
+            // EndUser Role Data: (address account, address community, string avatarURI, string ensName, uint256 stakeAmount)
+            const userData = encodeAbiParameters(
+                [
+                    { name: 'account', type: 'address' },
+                    { name: 'community', type: 'address' },
+                    { name: 'avatarURI', type: 'string' },
+                    { name: 'ensName', type: 'string' },
+                    { name: 'stakeAmount', type: 'uint256' }
+                ],
+                // Stake Amount 0, relying on Registry to enforce minStake and charge msg.sender
+                [target, community || zeroAddress, '', '', 0n] 
+            ); 
+            
+            const hashMint = await adminWallet.writeContract({
+                address: registryAddr,
+                abi: parseAbi([
+                    'function safeMintForRole(bytes32 roleId, address user, bytes calldata data) external returns (uint256)',
+                    'error InvalidParameter(string message)'
+                ]),
+                functionName: 'safeMintForRole',
+                args: [ENDUSER_ROLE as `0x${string}`, target, userData],
+                chain: sepolia,
+                account: adminWallet.account!
+            });
+            
+            await publicClient.waitForTransactionReceipt({ hash: hashMint, timeout: 300000 });
+            console.log(`      -> Role Sponsored & Granted. Tx: ${hashMint}`);
+            return true;
+
+        } catch (error) {
+            console.warn(`      ⚠️ Failed to sponsor ENDUSER role. Error:`, error);
+            return false;
+        }
+    }
+
+    /**
+     * Mints tokens directly to the target.
+     */
+    static async mintTestTokens(
+        adminWallet: WalletClient, 
+        publicClient: PublicClient, 
+        token: Address, 
+        target: Address, 
+        amount: bigint
+    ): Promise<boolean> {
+        const balance = await publicClient.readContract({
+            address: token,
+            abi: ERC20_ABI,
+            functionName: 'balanceOf',
+            args: [target]
+        });
+
+        if (balance < amount) {
+            console.log(`   🪙 Funding Tokens... (Current: ${formatEther(balance)})`);
+            const adminAddr = adminWallet.account!.address;
+            
+            // 1. Try Transfer from Admin (if Admin has balance)
+            const adminBal = await publicClient.readContract({
+                address: token,
+                abi: ERC20_ABI,
+                functionName: 'balanceOf',
+                args: [adminAddr]
+            });
+
+            if (adminBal >= amount) {
+                 console.log(`      💸 Transferring from Admin...`);
+                 const hash = await adminWallet.writeContract({
+                     address: token,
+                     abi: ERC20_ABI,
+                     functionName: 'transfer',
+                     args: [target, amount],
+                     chain: sepolia,
+                     account: adminWallet.account!
+                 });
+                 await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+                 console.log(`      ✅ Transferred ${formatEther(amount)}. Tx: ${hash}`);
+                 return true;
+            }
+
+            // 2. Try Mint (Assuming Admin has Minter Role or is Owner)
+            console.log(`      🪙 Admin balance low. Attempting Mint...`);
+            try {
+                const hash = await adminWallet.writeContract({
+                    address: token,
+                    abi: ERC20_ABI,
+                    functionName: 'mint',
+                    args: [target, amount],
+                    chain: sepolia,
+                    account: adminWallet.account!
+                });
+                await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+                console.log(`      ✅ Minted ${formatEther(amount)}. Tx: ${hash}`);
+                return true;
+            } catch (e) {
+                console.warn(`      ⚠️ Failed to mint/transfer tokens. Check Admin permissions/balance.`, e);
+                return false;
+            }
+        }
+        console.log(`   ✅ Token Balance adequate.`);
+        return false;
+    }
+
+    /**
+     * Complex Flow:
+     * 1. Admin mints tokens to SELF.
+     * 2. Admin approves Paymaster.
+     * 3. Admin calls depositFor(target) on Paymaster.
+     */
+    static async adminDepositForUser(
+        adminWallet: WalletClient, 
+        publicClient: PublicClient, 
+        paymaster: Address, 
+        target: Address, 
+        token: Address, 
+        amount: bigint
+    ): Promise<boolean> {
+        // 1. Mint to Admin First
+        const adminAddr = adminWallet.account!.address;
+        const adminBal = await publicClient.readContract({
+            address: token,
+            abi: ERC20_ABI,
+            functionName: 'balanceOf',
+            args: [adminAddr]
+        });
+
+        if (adminBal < amount) {
+            console.log(`   🏧 Admin Minting to Self (for deposit)...`);
+            const hash = await adminWallet.writeContract({
+                address: token,
+                abi: ERC20_ABI,
+                functionName: 'mint',
+                args: [adminAddr, amount * 10n], // bulk mint
+                chain: sepolia,
+                account: adminWallet.account!
+            });
+            await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+            console.log(`      -> Admin Minted. Tx: ${hash}`);
+        }
+
+        // 2. Approve Paymaster
+        const allowance = await publicClient.readContract({
+            address: token,
+            abi: ERC20_ABI,
+            functionName: 'allowance',
+            args: [adminAddr, paymaster]
+        });
+        
+        if (allowance < amount) {
+            console.log(`   🔓 Admin Approving Paymaster...`);
+            const hash = await adminWallet.writeContract({
+                address: token,
+                abi: ERC20_ABI,
+                functionName: 'approve',
+                args: [paymaster, 115792089237316195423570985008687907853269984665640564039457584007913129639935n], // Max Uint
+                chain: sepolia,
+                account: adminWallet.account!
+            });
+            await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+            console.log(`      -> Approved Paymaster. Tx: ${hash}`);
+        }
+
+        // 3. Deposit For
+        console.log(`   🏦 Depositing FOR User...`);
+        try {
+            const hash = await adminWallet.writeContract({
+                address: paymaster,
+                abi: PAYMASTER_ABI,
+                functionName: 'depositFor',
+                args: [target, amount],
+                chain: sepolia,
+                account: adminWallet.account!
+            });
+            await publicClient.waitForTransactionReceipt({ hash, timeout: 300000 });
+            console.log(`      -> Deposited ${formatEther(amount)} to PM. Tx: ${hash}`);
+            return true;
+        } catch (e) {
+            console.warn(`      ⚠️ Deposit Failed (Maybe not supported on this PM?):`, e);
+            return false;
+        }
+    }
+}