@aastar/sdk 0.14.3 → 0.16.6

package/docs/API_REFERENCE.md

@@ -1,10 +1,10 @@
-# AAStar SDK API Documentation
+****# AAStar SDK API Documentation
 
 ## Overview
 
 AAStar SDK is a comprehensive TypeScript SDK for interacting with the AAStar Public Goods Infrastructure and create Your Own Protocol (YOP), providing Account Abstraction (ERC-4337) capabilities with advanced features like gasless SuperPaymaster(AOA+), EOA RainBow Bridge and community management, and reputation systems.
 
-**Version**: 0.14.0  
+**Version**: 0.16.4  
 **License**: MIT  
 **Repository**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
 
@@ -14,13 +14,14 @@ AAStar SDK is a comprehensive TypeScript SDK for interacting with the AAStar Pub
 
 1. [Installation](#installation)
 2. [Quick Start](#quick-start)
-3. [Core Module](#core-module)
-4. [Account Module](#account-module)
-5. [Paymaster Module](#paymaster-module)
-6. [Tokens Module](#tokens-module)
-7. [Identity Module](#identity-module)
-8. [DApp Module](#dapp-module)
-9. [Complete Examples](#complete-examples)
+3. [Error Handling - AAStarError](#error-handling---aastarerror)
+4. [Core Module](#core-module)
+5. [Account Module](#account-module)
+6. [Paymaster Module](#paymaster-module)
+7. [Tokens Module](#tokens-module)
+8. [Identity Module](#identity-module)
+9. [DApp Module](#dapp-module)
+10. [Complete Examples](#complete-examples)
 
 ---
 
@@ -32,6 +33,15 @@ pnpm add @aastar/sdk
 pnpm add @aastar/core @aastar/account @aastar/paymaster
 ```
 
+### Development & Maintenance
+```bash
+# Audit ABI alignment with contracts
+pnpm run audit:abi
+
+# Generate code coverage report
+pnpm run test:coverage
+```
+
 ---
 
 ## Quick Start
@@ -55,6 +65,156 @@ const stakeTx = await operatorClient.stake({
 
 ---
 
+## Error Handling - AAStarError
+
+### Overview
+
+All SDK clients throw `AAStarError` for better error handling and debugging. `AAStarError` provides structured error information with error codes, messages, and optional details.
+
+### AAStarErrorCode Enum
+
+```typescript
+export enum AAStarErrorCode {
+    VALIDATION_ERROR = 'VALIDATION_ERROR',     // Invalid input parameters
+    CONTRACT_ERROR = 'CONTRACT_ERROR',          // Smart contract execution failed
+    NETWORK_ERROR = 'NETWORK_ERROR',            // RPC or network issues
+    CONFIGURATION_ERROR = 'CONFIGURATION_ERROR', // Missing or invalid configuration
+    UNKNOWN_ERROR = 'UNKNOWN_ERROR',            // Unclassified errors
+}
+```
+
+### AAStarError Class
+
+```typescript
+class AAStarError extends Error {
+    code: AAStarErrorCode;
+    details?: any;
+    
+    constructor(message: string, code: AAStarErrorCode, details?: any);
+}
+```
+
+### Usage Example
+
+```typescript
+import { createEndUserClient, AAStarError, AAStarErrorCode } from '@aastar/sdk';
+
+try {
+    await client.executeGasless({
+        to: '0xinvalid',  // Invalid address
+        value: 1000n,
+    });
+} catch (error) {
+    if (error instanceof AAStarError) {
+        switch (error.code) {
+            case AAStarErrorCode.VALIDATION_ERROR:
+                console.error(`Validation failed: ${error.message}`);
+                console.error(`Details:`, error.details);
+                break;
+            case AAStarErrorCode.CONTRACT_ERROR:
+                console.error(`Contract execution failed: ${error.message}`);
+                break;
+            case AAStarErrorCode.NETWORK_ERROR:
+                console.error(`Network error: ${error.message}`);
+                // Retry logic here
+                break;
+            case AAStarErrorCode.CONFIGURATION_ERROR:
+                console.error(`Configuration error: ${error.message}`);
+                break;
+            default:
+                console.error(`Unknown error: ${error.message}`);
+        }
+    } else {
+        // Handle non-AAStarError exceptions
+        console.error('Unexpected error:', error);
+    }
+}
+```
+
+### Error Code Reference
+
+| Error Code | Description | Common Causes | Recommended Action |
+|------------|-------------|---------------|-------------------|
+| `VALIDATION_ERROR` | Invalid input parameters | Invalid address format, negative amounts, missing required fields | Validate inputs before calling SDK methods |
+| `CONTRACT_ERROR` | Smart contract execution failed | Insufficient gas, reverted transaction, access denied | Check contract state, user permissions, and gas limits |
+| `NETWORK_ERROR` | RPC or network communication failed | Timeout, connection refused, invalid RPC endpoint | Retry with exponential backoff, check network status |
+| `CONFIGURATION_ERROR` | SDK configuration is invalid | Missing contract addresses, invalid network configuration | Verify SDK initialization parameters |
+| `UNKNOWN_ERROR` | Unclassified error | Unexpected runtime errors | Report to SDK maintainers with error details |
+
+### Best Practices
+
+#### 1. Always Check Error Type
+
+```typescript
+try {
+    await sdkMethod();
+} catch (error) {
+    if (error instanceof AAStarError) {
+        // Handle AAStarError
+    } else {
+        // Handle other errors
+    }
+}
+```
+
+#### 2. Use Error Details for Debugging
+
+```typescript
+catch (error) {
+    if (error instanceof AAStarError) {
+        console.error({
+            code: error.code,
+            message: error.message,
+            details: error.details,  // Additional context
+        });
+    }
+}
+```
+
+####3. Implement Retry Logic for Network Errors
+
+```typescript
+async function withRetry(fn: () => Promise<any>, maxRetries = 3) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        } catch (error) {
+            if (error instanceof AAStarError && 
+                error.code === AAStarErrorCode.NETWORK_ERROR && 
+                i < maxRetries - 1) {
+                await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+
+// Usage
+await withRetry(() => client.executeGasless({...}));
+```
+
+#### 4. Provide User-Friendly Messages
+
+```typescript
+function getUserFriendlyMessage(error: AAStarError): string {
+    switch (error.code) {
+        case AAStarErrorCode.VALIDATION_ERROR:
+            return 'Please check your input and try again.';
+        case AAStarErrorCode.CONTRACT_ERROR:
+            return 'Transaction failed. Please try again later.';
+        case AAStarErrorCode.NETWORK_ERROR:
+            return 'Network connection issue. Please check your internet.';
+        case AAStarErrorCode.CONFIGURATION_ERROR:
+            return 'SDK configuration error. Please contact support.';
+        default:
+            return 'An unexpected error occurred. Please try again.';
+    }
+}
+```
+
+---
+
 ## Core Module
 
 ### `@aastar/core`

package/docs/Configuration_Sync.md

@@ -0,0 +1,47 @@
+# SDK & Contract Repository Configuration Sync
+
+This document outlines the synchronization mechanism between the `SuperPaymaster` (Contracts) repository and the `aastar-sdk`.
+
+## Overview
+
+The SDK relies on two artifacts from the contract repository:
+1.  **ABIs**: JSON files defining the contract interfaces.
+2.  **Configuration**: JSON files defining deployed contract addresses and source code verification hashes.
+
+## Sync Workflow
+
+The synchronization is automated via the `run_sdk_complete_regression.sh` script (and standalone `sync_to_sdk.sh` in SuperPaymaster).
+
+### 1. Artifact Generation (SuperPaymaster Side)
+*   **ABIs**: `forge build` generates artifacts. `extract_v3_abis.sh` extracts verified ABIs to `abis/*.json`.
+*   **Config**: Deployment scripts (e.g., `DeployAnvil.s.sol`) generate `deployments/config.{network}.json`. This file includes:
+    *   Contract Addresses (Registry, SuperPaymaster, etc.)
+    *   `srcHash`: SHA-256 hash of the `contracts/src` directory for integrity checks.
+
+### 2. Synchronization Bridge
+Artifacts are copied to the SDK:
+*   `abis/*.json` -> `packages/core/src/abis/`
+*   `deployments/config.{network}.json` -> `config.{network}.json` (SDK Root)
+
+### 3. SDK Abstraction Layer (`constants.ts`)
+The SDK avoids hardcoding addresses or reading JSON files directly in business logic.
+*   **File**: `packages/core/src/constants.ts`
+*   **Mechanism**:
+    *   Reads `process.env.NETWORK` (default: 'anvil').
+    *   Dynamically loads `config.{network}.json`.
+    *   Exports constants like `REGISTRY_ADDRESS`, `SUPER_PAYMASTER_ADDRESS`.
+*   **Legacy Support**: `contract-addresses.ts` has been refactored to consume `constants.ts`, ensuring backward compatibility.
+
+## Verification (`verify_onchain_milestone.ts`)
+
+A verification script (`scripts/verify_onchain_milestone.ts`) ensures the SDK is in sync with the chain:
+1.  Loads `config.{network}.json` via `constants.ts`.
+2.  Verifies `srcHash` existence.
+3.  Checks on-chain code presence for all critical contracts using `viem`.
+
+## Usage
+
+To run the full regression with sync and verification:
+```bash
+./run_sdk_complete_regression.sh --env anvil
+```

package/docs/DEMO_REFACTOR_PLAN.md

@@ -0,0 +1,289 @@
+# Demo 重构计划
+
+## 项目目标
+创建一个基于 SDK 高层 API (99%) 的交互式演示系统，提供清晰的左右分栏界面，展示 AAStar 生态系统的完整生命周期。
+
+## UI/UX 架构设计
+
+### 界面布局
+```
+┌─────────────────────────────────────────────────────────┐
+│                      AAStar Demo                         │
+├──────────────┬──────────────────────────────────────────┤
+│              │                                           │
+│  左侧导航栏  │            右侧内容区域                   │
+│              │                                           │
+│  ┌────────┐  │  ┌─────────────────────────────────────┐ │
+│  │ Step 1 │  │  │                                     │ │
+│  │Accounts│  │  │    当前步骤的详细信息和操作界面      │ │
+│  └────────┘  │  │                                     │ │
+│  ┌────────┐  │  │  - 显示历史记录                     │ │
+│  │ Step 2 │  │  │  - 显示当前状态                     │ │
+│  │Community│  │  │  - 提供操作按钮                     │ │
+│  └────────┘  │  │  - 实时反馈                         │ │
+│  ┌────────┐  │  │                                     │ │
+│  │ Step 3 │  │  └─────────────────────────────────────┘ │
+│  │Operator│  │                                           │
+│  └────────┘  │                                           │
+│  ┌────────┐  │                                           │
+│  │ Step 4 │  │                                           │
+│  │End User│  │                                           │
+│  └────────┘  │                                           │
+│              │                                           │
+└──────────────┴──────────────────────────────────────────┘
+```
+
+### 分步骤功能设计
+
+#### Step 1: Account Management (账户管理)
+**右侧显示内容**
+- 账户列表表格
+
+| 名称    | 地址              | ETH 余额 | GToken 余额 | 操作    |
+|---------|-------------------|----------|-------------|---------|
+| Alice   | 0xB6D3...         | 0.1000   | 200.00      | [选择]  |
+| Bob     | 0x2944...         | 0.1000   | 200.00      | [选择]  |
+| Charlie | 0xa74f...         | 0.1000   | 100.00      | [选择]  |
+
+**操作按钮**
+- `+ 新建账户` - 生成新的 EOA 账户
+- `刷新余额` - 更新所有账户余额
+- `充值选中账户` - 为选中账户充值 ETH 和 GToken
+
+**SDK API 需求**
+- ✅ `KeyManager.generateAccount()` - 生成账户
+- ✅ `FundingManager.fundWithETH()` - ETH 充值
+- ✅ `FundingManager.fundWithToken()` - Token 充值
+- 🆕 `StateValidator.getAccountBalances()` - 批量查询余额
+
+#### Step 2: Launch Community (启动社区)
+**右侧显示内容**
+- 当前账户状态卡片
+  ```
+  选中账户: Alice (0xB6D3...)
+  ┌─────────────────────────────────────┐
+  │ 社区状态                             │
+  ├─────────────────────────────────────┤
+  │ ✅ 已注册 COMMUNITY 角色             │
+  │ ✅ 已部署社区 Token                  │
+  │                                     │
+  │ Token 地址: 0xb65D...               │
+  │ Token 名称: DemoDAO_xxx             │
+  │ 注册时间: 2024-12-29 11:37          │
+  └─────────────────────────────────────┘
+  ```
+
+**操作流程**
+- 如果未注册：显示 `[启动新社区]` 表单
+  - 社区名称输入框
+  - ENS 名称（可选）
+  - 描述（可选）
+  - `[确认启动]` 按钮
+- 如果已注册：显示社区详情 + `[查看 Token 详情]`
+
+**SDK API 需求**
+- ✅ `CommunityClient.launch()` - 启动社区
+- 🆕 `CommunityClient.getCommunityInfo(account)` - 查询社区信息
+  ```typescript
+  {
+    hasRole: boolean;
+    tokenAddress: Address | null;
+    communityData: {
+      name: string;
+      ensName: string;
+      createdAt: number;
+    } | null;
+  }
+  ```
+
+#### Step 3: Setup Operator (运营商设置)
+**右侧显示内容**
+- 运营商类型选择
+  ```
+  选中账户: Bob (0x2944...)
+  请选择运营商类型：
+  ┌──────────────────────────────────────┐
+  │ ⭕ SuperPaymaster (推荐)              │
+  │    - 跨社区共享流动性                │
+  │    - 支持多 Token 支付               │
+  │    - 需要质押 50 GToken + 存入 aPNTs │
+  └──────────────────────────────────────┘
+  ┌──────────────────────────────────────┐
+  │ ⭕ Paymaster V4 (独立)                │
+  │    - 社区独立部署                    │
+  │    - 单一 Token 支付                 │
+  │    - 需要指定 Token 和 SBT           │
+  └──────────────────────────────────────┘
+  ```
+
+- 已注册状态显示
+  ```
+  ┌─────────────────────────────────────┐
+  │ SuperPaymaster 运营商                │
+  ├─────────────────────────────────────┤
+  │ ✅ 已质押: 50 GToken                 │
+  │ ✅ 已存入: 100 aPNTs                 │
+  │ 📊 可用余额: 75 aPNTs                │
+  │ 🏦 Treasury: 0x2944...              │
+  │ 📈 Exchange Rate: 1:1               │
+  └─────────────────────────────────────┘
+  ```
+
+**操作:**
+- `[追加存款]` `[提取余额]` `[修改配置]`
+
+**SDK API 需求**
+- ✅ `OperatorClient.onboardOperator()` - 注册运营商（SuperPaymaster）
+- ✅ `OperatorClient.deployPaymasterV4()` - 部署 Paymaster V4
+- 🆕 `OperatorClient.getOperatorInfo(account)` - 查询运营商状态
+  ```typescript
+  {
+    type: 'super' | 'v4' | null;
+    superPaymaster: {
+      isConfigured: boolean;
+      balance: bigint;
+      exchangeRate: bigint;
+      treasury: Address;
+    } | null;
+    paymasterV4: {
+      address: Address;
+      token: Address;
+      balance: bigint;
+    } | null;
+  }
+  ```
+- 🆕 `OperatorClient.depositFunds(amount)` - 追加存款
+- 🆕 `OperatorClient.withdrawFunds(amount)` - 提取余额
+
+#### Step 4: Onboard End User (用户入驻)
+**右侧显示内容**
+- 用户账户来源选择
+  ```
+  选择用户账户类型：
+  ┌──────────────────────────────────────┐
+  │ ⭕ 从现有 EOA 创建                    │
+  │    选择账户: [下拉列表]              │
+  │    [创建 AA 账户]                    │
+  └──────────────────────────────────────┘
+  ┌──────────────────────────────────────┐
+  │ ⭕ 生成新的 Simple Account           │
+  │    盐值: [自动生成]                  │
+  │    [部署新账户]                      │
+  └──────────────────────────────────────┘
+  ```
+
+- 用户状态显示
+  ```
+  ┌─────────────────────────────────────┐
+  │ AA Account: 0x1234...               │
+  ├─────────────────────────────────────┤
+  │ 📍 已部署                            │
+  │ 👤 Owner: Alice (0xB6D3...)         │
+  │ 💰 余额:                             │
+  │    - 0.05 ETH                       │
+  │    - 50 xPNTs (社区 Token)          │
+  │    - 100 aPNTs                      │
+  │                                     │
+  │ 🎫 SBT 持有:                         │
+  │    - MySBT #1234 (已mint)           │
+  └─────────────────────────────────────┘
+  ```
+
+**操作:**
+- `[充值 xPNTs]` `[Mint SBT]` `[发送 UserOp]`
+
+**SDK API 需求**
+- 🆕 `EndUserClient.deployAccount(owner, salt?)` - 部署 AA 账户
+- 🆕 `EndUserClient.getAccountInfo(address)` - 查询 AA 账户信息
+- 🆕 `EndUserClient.mintSBT(account)` - 为用户 Mint SBT
+- 🆕 `EndUserClient.fundWithXPNTs(account, amount)` - 充值社区 Token
+- ✅ `EndUserClient.sendUserOp()` - 发送 UserOperation
+
+## SDK API 增强计划
+
+### 优先级分类
+**P0 - 立即实现（状态查询类）**
+- `CommunityClient.getCommunityInfo(account: Address)`
+- `OperatorClient.getOperatorInfo(account: Address)`
+- `StateValidator.getAccountBalances(addresses: Address[])`
+
+**P1 - 高优先级（核心功能）**
+- `EndUserClient.deployAccount(owner: Address, salt?: bigint)`
+- `EndUserClient.mintSBT(account: Address)`
+- `OperatorClient.depositFunds(amount: bigint)`
+- `OperatorClient.withdrawFunds(amount: bigint)`
+
+**P2 - 中优先级（增强功能）**
+- `EndUserClient.getAccountInfo(address: Address)`
+- `EndUserClient.fundWithXPNTs(account: Address, amount: bigint)`
+
+### 回归脚本分析
+需要从以下脚本中提取功能：
+
+**社区相关**
+- ✅ `01_register_community_raw.ts` - 已提取为 `CommunityClient.launch()`
+- 📋 `09_local_test_community_lifecycle.ts` - 社区生命周期完整流程
+
+**运营商相关**
+- 📋 `deploy_paymaster_v4.ts` - Paymaster V4 部署逻辑
+- 📋 `05_test_superpaymaster.ts` - SuperPaymaster 完整设置流程
+  - Line 114-199: `setupOperator` 函数（包含配置和存款）
+
+**用户相关**
+- 📋 `deploy_test_accounts.ts` - AA 账户部署逻辑
+- 📋 `03_test_standard_aa.ts` - AA 交互流程
+
+## 实现路线图
+
+### 阶段 1: 修复当前错误 ✅
+- [x] 修复 account undefined 错误
+- [x] 修复 gToken undefined 错误
+- [x] 确保 SDK 构建成功
+
+### 阶段 2: SDK API 增强 (1-2天)
+- [ ] 实现 P0 状态查询 API
+- [ ] 从回归脚本提取 `setupOperator` 的配置逻辑
+- [ ] 从 `deploy_test_accounts.ts` 提取 AA 部署逻辑
+- [ ] 添加单元测试
+
+### 阶段 3: UI 重构 (2-3天)
+- [ ] 重构 index.html 为左右分栏布局
+- [ ] 实现 Step 1: Account Management
+- [ ] 实现 Step 2: Launch Community（状态查询 + 操作）
+- [ ] 实现 Step 3: Setup Operator（类型选择 + 状态查询）
+- [ ] 实现 Step 4: Onboard End User
+
+### 阶段 4: 集成测试 (1天)
+- [ ] 端到端流程测试
+- [ ] 性能优化
+- [ ] 错误处理完善
+
+## 技术细节
+
+### 前端状态管理
+```javascript
+const demoState = {
+  selectedAccount: null,      // 当前选中的账户
+  currentStep: 1,              // 当前步骤
+  accounts: [],                // 账户列表
+  communityInfo: {},           // 社区信息缓存
+  operatorInfo: {},            // 运营商信息缓存
+  aaAccounts: []               // AA 账户列表
+};
+```
+
+### API 响应格式规范
+所有 SDK API 应返回统一格式：
+```typescript
+interface SDKResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  txHashes?: Hash[];
+}
+```
+
+## 下一步行动
+- ✅ 立即修复: 修复 operator 设置中的地址问题
+- 📝 规划审查: 用户审查本计划，提供反馈
+- 🔨 开始实施: 按阶段实施

package/docs/ENV_SEPOLIA_UPDATE.md

@@ -0,0 +1,68 @@
+# .env.sepolia Configuration Update
+
+## Summary
+Cleaned and updated `.env.sepolia` with latest Sepolia deployment addresses from `SuperPaymaster/script/v3/config/deployed.json`.
+
+## Key Changes
+
+### Removed Duplicates
+- Removed old/duplicate contract addresses (e.g., multiple GTOKEN_ADDRESS entries)
+- Consolidated to single source of truth
+
+### Latest Contract Addresses
+
+#### Paymaster Contracts
+- **PaymasterV4 Proxy**: `0x0F9019Dd30C7Cc5774d4883fba933aA0Caba9424`
+- **PaymasterV4 Implementation**: `0x720472c8ce72c2A2D711333e064ABD3E6BbEAdd3`
+- **SuperPaymaster**: `0x86A2EE8FAf9A840F7a2c64CA3d51209F9A02081D`
+- **Paymaster Factory**: `0x5c74c94173F05dA1720953407cbb920F3DF9f887`
+
+#### Core Contracts
+- **GToken**: `0xfbC22278A96299D91d41C453234d97b4F5Eb9B2d`
+- **Staking**: `0xC9a43158891282A2B1475592D5719c001986Aaec`
+- **Registry**: `0x367761085BF3C12e5DA2Df99AC6E1a824612b8fb`
+- **MySBT**: `0x1c85638e118b37167e9298c2268758e058DdfDA0`
+- **ReputationSystem**: `0xCace1b78160AE76398F486c8a18044da0d66d86D`
+
+#### Token Contracts
+- **aPNTs**: `0x49fd2BE640DB2910c2fAb69bB8531Ab6E76127ff`
+- **xPNTs Factory**: `0xA4899D35897033b927acFCf422bc745916139776`
+
+#### EntryPoint & Validators
+- **EntryPoint V0.7**: `0x2B0d36FACD61B71CC05ab8F3D2355ec3631C0dd5`
+- **BLS Aggregator**: `0xF8e31cb472bc70500f08Cd84917E5A1912Ec8397`
+- **DVT Validator**: `0xD5ac451B0c50B9476107823Af206eD814a2e2580`
+
+#### SimpleAccount Factory
+- **Factory**: `0x4b6aB5F819A515382B0dEB6935D793817bB4af28`
+
+### Test Account Configuration
+- **TEST_SIMPLE_ACCOUNT_A**: `0x11595E52131Ffd571ce5e00C44472FBf94c99937`
+  - ✅ Has PIM tokens deposited
+  - ✅ Ready for Pimlico paymaster tests
+- **TEST_OWNER_EOA_A**: `0xda7f83CafAe1b76Bd4446a4aB2B8e88770CfA927`
+- **TEST_OWNER_KEY_A**: (stored in .env.sepolia)
+
+### Bundler RPC Configuration
+- **Primary RPC**: `SEPOLIA_RPC_URL` (Alchemy)
+- **Bundler RPC**: `SEPOLIA_RPC_URL2` (Alchemy bundler endpoint)
+  - Used for AA UserOp submission
+
+## For Experiment Runner
+
+The experiment runner now uses:
+1. **PAYMASTER_ADDRESS**: `0x0F9019Dd30C7Cc5774d4883fba933aA0Caba9424` (PaymasterV4 Proxy)
+2. **SUPERPAYMASTER_ADDRESS**: `0x86A2EE8FAf9A840F7a2c64CA3d51209F9A02081D`
+3. **SEPOLIA_RPC_URL2**: Alchemy bundler RPC for Groups 3 & 4
+
+## Next Steps
+Run the experiment runner to test all 4 groups:
+```bash
+pnpm tsx scripts/19_sdk_experiment_runner.ts
+```
+
+Expected results:
+- ✅ Group 1 (EOA): Should pass
+- ✅ Group 2 (Pimlico): Should pass with PIM tokens
+- ✅ Group 3 (AOA/PaymasterV4): Should pass with new address
+- ✅ Group 4 (SuperPaymaster): Should pass with new address

package/docs/Faucet_Gasless_Plan.md

@@ -0,0 +1,56 @@
+# Faucet & Gasless Verification Plan (Sepolia)
+
+This document outlines the systematic steps required to verify the Faucet API and SuperPaymaster gasless flow on Sepolia, mapping each step to the corresponding SDK/API capability.
+
+## Overview
+The goal is to provide a "one-click" experience for a new user to:
+1. Receive initial ETH (for account buffer).
+2. Receive a sponsored `ENDUSER` role (stake paid by community).
+3. Receive gas tokens (`cPNTs`).
+4. Execute a gasless transaction via `SuperPaymaster`.
+
+---
+
+## 📋 Step-by-Step Execution Plan
+
+### Phase 1: Infrastructure & Admin Setup
+| Step | Action | API / Contract | Status | Rationale |
+| :--- | :--- | :--- | :--- | :--- |
+| 1.1 | **Supplier Funding** | `supplierWallet.sendTransaction` | ✅ DONE | Ensure Admin has ETH for stakes and gas. |
+| 1.2 | **Community Registration** | `Registry.registerRole` (COMMUNITY) | ✅ DONE | Admin must be a Community to sponsor users. |
+
+### Phase 2: User Preparation (Faucet API)
+| Step | Action | API / Contract | Status | Rationale |
+| :--- | :--- | :--- | :--- | :--- |
+| 2.1 | **ETH Funding** | `SepoliaFaucetAPI.fundETH` | ✅ DONE | Provide seed ETH to the new AA account. |
+| 2.2 | **Sponsored Role** | `Registry.safeMintForRole` | ✅ DONE | Admin pays 0.35 GToken stake for User. |
+| 2.3 | **Gas Token Funding** | `ERC20.transfer` | ✅ DONE | User needs tokens to use as service credit in SuperPaymaster. |
+
+### Phase 3: Gasless Transaction Submission
+| Step | Action | API / Contract | Status | Rationale |
+| :--- | :--- | :--- | :--- | :--- |
+| 3.1 | **Account Calculation** | `AccountFactory.getAddress` (v0.7) | ⚠️ FIXING | Need correct v0.7 salt and factory address. |
+| 3.2 | **InitCode Generation**| `SuperPaymasterClient` | ⚠️ FIXING | Factory call to deploy the AA account on first use. |
+| 3.3 | **Gasless UserOp** | `SuperPaymasterClient.submitGaslessTransaction` | ⏳ PENDING | Submit signed UserOp to the Bundler. |
+| 3.4 | **Final Confirmation** | `bundlerClient.waitForUserOperationReceipt` | ⏳ PENDING | Verify transaction landed on Sepolia. |
+
+---
+
+## 🚫 Current Blockers & Resolution
+
+### 1. `AA13 initCode failed or OOG`
+- **Cause**: The script was using a v0.6 factory address logic with a v0.7 Bundler/EntryPoint. 
+- **Resolution**: I am updating `test-faucet-and-gasless.ts` to use `paymasterFactory` (0xDaC3...) from the config, which is the verified v0.7 SimpleAccountFactory.
+
+### 2. `getAddress` Revert
+- **Cause**: ABI mismatch in the `readContract` call.
+- **Resolution**: Adjusting the ABI to match v0.7 `SimpleAccountFactory` (owner, salt).
+
+---
+
+## 🛠️ API Coverage Audit
+- [x] **Registry.safeMintForRole**: Verified as the correct "Sponsor Mode" API.
+- [x] **SepoliaFaucetAPI**: Successfully handles ETH/Token prep.
+- [x] **SuperPaymasterClient**: Handles V4 gasless submission.
+
+**Next Action**: Apply the v0.7 Factory fix to `test-faucet-and-gasless.ts` and run the final verification.