@aastar/sdk 0.14.3 → 0.16.6

package/docs/refactor/2026-01-13-audit-report-v0.17.0.md

@@ -0,0 +1,74 @@
+# AAStar SDK Audit Report & Production Verification (v0.17.0)
+
+**Date**: 2026-01-13
+**Time**: 14:30 UTC
+**Auditor**: Gemini Agent (Antigravity)
+**Version Reviewed**: v0.17.0 (Post-Refactor)
+
+## 1. Executive Summary
+
+This audit verifies the completion of the "Phase 4" remediation plan. The critical technical debts in `EndUserClient` and `CommunityClient` have been **fully resolved**. The codebase now exhibits a uniform standard of safety, maintainability, and error handling across all client modules.
+
+**Status**: 🟢 **Production Ready** (v0.17.0)
+
+## 2. Comprehensive Code Audit
+
+### 2.1 Safety & Validation (P0)
+*   **Requirement**: All user inputs must be validated before touching the network.
+*   **Verification**:
+    *   `EndUserClient.executeGasless`: Now validates `target` (Address) and `operator` (Address). Validates `value` is positive.
+    *   `EndUserClient.onboard`: Validates `community` and `roleId`.
+    *   `CommunityClient.launch`: Enforces presence of `name`, `tokenName`, `tokenSymbol` with `AAStarError`.
+*   **Result**: ✅ **Passed**. The "Fail Fast" principle is correctly implemented.
+
+### 2.2 ABI Management (P0)
+*   **Requirement**: No hardcoded ABIs in client files.
+*   **Verification**:
+    *   `EndUserClient.ts`:
+        *   Removed: Manual `parseAbi` for EntryPoint and SimpleAccount.
+        *   Added: Imports `EntryPointABI`, `SimpleAccountFactoryABI` from `@aastar/core`.
+    *   `CommunityClient.ts`:
+        *   Removed: Manual ABI for xPNTsFactory.
+        *   Added: Import `xPNTsFactoryABI` from `@aastar/core`.
+*   **Result**: ✅ **Passed**. The system is now resilient to contract upgrades (single source of truth in `packages/core`).
+
+### 2.3 Error Handling (P1)
+*   **Requirement**: Consistent use of `AAStarError`.
+*   **Verification**:
+    *   `EndUserClient`: Replaces generic `Error` with `AAStarError` (Type: `CONTRACT_ERROR`, `VALIDATION_ERROR`).
+    *   `CommunityClient`: Similar adoption.
+    *   **Note**: The error messages now include decoded contract revert reasons (via `decodeContractError`), significantly improving debugging (e.g., showing "InsufficientBalance" instead of "Execution reverted").
+*   **Result**: ✅ **Passed**.
+
+### 2.4 Code Quality & Structure
+*   **Observation**:
+    *   Imports are clean and organized.
+    *   `createClient` factories consistently extend base actions.
+    *   Helper logic (like encoding `UserOp`) is still slightly verbose in `EndUserClient`, but strictly typed and safe.
+*   **Result**: ✅ **Passed**.
+
+---
+
+## 3. Comparison: v0.16.2 vs v0.17.0
+
+| Feature | v0.16.2 (Previous) | v0.17.0 (Current) | Status |
+| :--- | :--- | :--- | :--- |
+| **EndUser Safety** | ❌ Unchecked Inputs | ✅ Validated Inputs | Fixed |
+| **ABI Source** | ⚠️ Hardcoded / Mixed | ✅ Unified (@aastar/core) | Fixed |
+| **Error Types** | ⚠️ Generic Error | ✅ AAStarError (Typed) | Fixed |
+| **Community Launch** | ⚠️ Risky Defaults | ✅ Validated Config | Fixed |
+
+---
+
+## 4. Final Verdict
+
+The AAStar SDK has successfully transitioned from an "Advanced MVP" to a **Production-Grade Library**. The architecture is robust, the inputs are guarded, and the dependencies are clean.
+
+**Recommendation**:
+1.  **Tag Release**: Tag this state as `v0.17.0`.
+2.  **Publish**: Safe to publish to NPM.
+3.  **Documentation**: Update the `API_REFERENCE.md` to reflect that methods now throw `AAStarError` specifically, allowing developers to catch specific error codes (e.g., `VALIDATION_ERROR`).
+
+**Audit Sign-off**:
+*Signature*: Gemini Agent (Antigravity)
+*Timestamp*: 2026-01-13T14:30:00Z

package/docs/refactor/2026-01-13-cursor-refactor.md

@@ -0,0 +1,511 @@
+# AAStar SDK Comprehensive Refactor Plan (2026-01-13)
+
+**Expert Analysis**: TypeScript SDK Master, Web3 Architect, Account Abstraction Specialist
+**Audit Date**: January 13, 2026
+**Current SDK Version**: 0.16.2
+**Previous Audits Reviewed**: GPT-5.2 (Security & Quality), Gemini CLI (DX & Architecture)
+
+## Executive Summary
+
+After conducting a comprehensive audit of the AAStar SDK, I find it in a **transitional state** - substantial foundational work has been completed, but critical gaps remain that prevent it from achieving production-grade status. The SDK demonstrates sophisticated account abstraction capabilities with gasless transaction support, but suffers from architectural inconsistencies and incomplete security hardening.
+
+**Key Findings:**
+- ✅ **Strong Foundation**: Core validation, ABI loading, and package consolidation completed
+- ⚠️ **Critical Gaps**: Incomplete validation integration, inconsistent error handling, type safety issues
+- 🎯 **Opportunity**: Transform from "Advanced MVP" to "Production SDK" with focused architectural improvements
+
+## 1. Current Architecture Assessment
+
+### 1.1 Package Structure Analysis
+
+**Current State:**
+```
+packages/
+├── core/           # ✅ Well-structured foundation layer
+├── sdk/            # ⚠️ Mixed responsibilities (clients + utils)
+├── paymaster/      # ✅ Clean separation maintained
+├── account/        # ✅ Isolated account abstractions
+├── dapp/           # ⚠️ React components mixed with core logic
+├── identity/       # ✅ Focused on SBT/reputation
+├── tokens/         # ✅ Token utilities
+└── analytics/      # ⚠️ Uncertain scope/purpose
+```
+
+**Assessment:**
+- **Strength**: Core package provides solid foundation with validation, ABIs, and actions
+- **Issue**: SDK package is a "catch-all" with mixed concerns (clients, utils, types, errors)
+- **Recommendation**: Implement strict separation of concerns with clear boundaries
+
+### 1.2 Client Architecture Review
+
+**OperatorClient Analysis:**
+```typescript
+// Current: Mixed extensibility patterns
+const client = createClient({ chain, transport, account })
+  .extend(publicActions)
+  .extend(walletActions);
+
+const spActions = superPaymasterActions(usedAddresses.superPaymaster)(client as any);
+const regActions = registryActions(usedAddresses.registry)(client as any);
+// ... more extensions with 'as any' casting
+```
+
+**Issues Identified:**
+1. **Type Safety Degradation**: Extensive `as any` usage breaks TypeScript guarantees
+2. **Inconsistent Validation**: `validateAddress()`, `validateAmount()` exist but not consistently applied
+3. **Error Handling Fragmentation**: Mix of `throw Error`, `decodeContractError`, and custom handling
+
+### 1.3 Security & Validation Audit
+
+**Implemented Security Measures:**
+- ✅ `validateAddress()` with checksum normalization
+- ✅ `validateAmount()` with bounds checking
+- ✅ `validateUint128()` for paymaster parameters
+- ✅ `AAStarValidationError` for consistent error types
+
+**Critical Gaps:**
+- **Paymaster Vulnerability**: Gas limits and exchange rates not validated before contract calls
+- **ERC20 Approval Checks**: Missing validation for token allowances
+- **Address Spoofing**: No validation of operator/admin addresses against known registries
+
+### 1.4 Error Handling & Result Pattern
+
+**Current State:**
+```typescript
+// SDKResult<T> defined but inconsistently used
+export type SDKResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: AAStarError };
+
+// Some methods use it, others throw directly
+export async function safeSDKCall<T>(promise: Promise<T>): Promise<SDKResult<T>>
+```
+
+**Assessment:**
+- **Strength**: `SDKResult<T>` pattern established for functional error handling
+- **Issue**: Inconsistent application across the codebase
+- **Gap**: No standardized error codes for different failure modes
+
+### 1.5 Testing Infrastructure
+
+**Current State:**
+- ✅ Vitest configured with basic validation tests
+- ✅ Unit test coverage for validation utilities (100%)
+- ⚠️ Missing integration tests for client orchestration
+- ❌ No contract interaction testing
+- ❌ No gasless flow E2E tests
+
+## 2. Critical Architecture Issues
+
+### 2.1 Type Safety Degradation
+
+**Problem:** The extensibility pattern breaks TypeScript's type guarantees:
+
+```typescript
+// Current problematic pattern
+const spActions = superPaymasterActions(usedAddresses.superPaymaster)(client as any);
+const regActions = registryActions(usedAddresses.registry)(client as any);
+```
+
+**Impact:** Developers lose autocomplete, error checking, and refactoring safety.
+
+### 2.2 Validation Layer Disconnect
+
+**Problem:** Validation functions exist but aren't integrated into business logic:
+
+```typescript
+// Validation exists but not used
+export function validateAddress(address: string): `0x${string}`
+// But in clients:
+async onboardFully(args: { stakeAmount: bigint, depositAmount: bigint }) {
+    // ❌ No validation of addresses or amounts
+    // Direct pass-through to contracts
+}
+```
+
+### 2.3 Gasless Transaction Complexity
+
+**Problem:** The core value proposition (gasless transactions) has complex orchestration that lacks proper abstraction:
+
+```typescript
+// Current: Manual orchestration required
+const result = await client.onboardFully({
+  stakeAmount: 1000000000000000000n, // 1 ETH - magic number
+  depositAmount: 5000000000000000000n, // 5 ETH - magic number
+  roleId: '0x...', // Hex string requirements unclear
+});
+```
+
+**Required:** Clear, validated, and well-documented gasless flows.
+
+### 2.4 Package Responsibility Confusion
+
+**Problem:** SDK package contains everything from clients to utilities to error handling:
+
+```
+packages/sdk/src/
+├── clients/      # Client implementations
+├── errors/       # Error types
+├── types/        # Type definitions
+├── utils/        # Utility functions
+└── index.ts      # Everything exported
+```
+
+**Impact:** Hard to understand, maintain, and test.
+
+## 3. Production-Grade Requirements Analysis
+
+### 3.1 Account Abstraction SDK Standards
+
+For a production AA SDK, the following are mandatory:
+
+1. **Type Safety**: 100% TypeScript coverage with no `as any`
+2. **Input Validation**: All external inputs validated before contract calls
+3. **Error Handling**: Consistent error patterns with actionable messages
+4. **Gas Estimation**: Accurate gas estimation for AA operations
+5. **Security**: Comprehensive input sanitization and bounds checking
+
+### 3.2 Gasless Transaction Requirements
+
+**Current Gap:** The SDK supports gasless transactions but lacks:
+- Clear pricing models
+- Fee estimation APIs
+- Transaction simulation
+- Gasless flow validation
+
+### 3.3 Multi-Role Architecture Requirements
+
+**Current State:** Three distinct client types (Operator, Community, EndUser) with different capabilities.
+
+**Required:**
+- Clear permission boundaries
+- Role validation
+- Cross-role operation safety
+- Administrative override capabilities
+
+## 4. Comprehensive Refactor Plan
+
+### Phase 1: Foundation Consolidation (Week 1-2)
+
+#### 1.1 Type System Reformation
+**Objective:** Eliminate all `as any` usage and establish strict typing.
+
+**Implementation:**
+```typescript
+// New: Strongly typed client composition
+interface AAStarClientConfig {
+  chain: Chain;
+  transport: Transport;
+  account?: Account;
+  addresses: AddressConfig;
+}
+
+export function createAAStarClient(config: AAStarClientConfig): AAStarClient {
+  // Type-safe composition without 'as any'
+  return baseClient
+    .extend(() => publicActions)
+    .extend(() => walletActions)
+    .extend(() => aastarActions(config.addresses));
+}
+```
+
+#### 1.2 Validation Integration
+**Objective:** Apply validation to all client methods.
+
+**Implementation:**
+```typescript
+// New: Validation-first approach
+export class ValidatedOperatorClient {
+  async onboardFully(args: OnboardArgs): Promise<SDKResult<OnboardResult>> {
+    // Validate all inputs first
+    const validatedArgs = await this.validateOnboardArgs(args);
+
+    // Then execute with validated data
+    return safeSDKCall(this.executeOnboardFlow(validatedArgs));
+  }
+
+  private async validateOnboardArgs(args: OnboardArgs): Promise<ValidatedOnboardArgs> {
+    return {
+      stakeAmount: validateAmount(args.stakeAmount, 'Stake Amount', 0n, MAX_STAKE),
+      depositAmount: validateAmount(args.depositAmount, 'Deposit Amount', 0n, MAX_DEPOSIT),
+      roleId: validateHex(args.roleId, 'Role ID'),
+      xPNTsToken: validateAddress(args.xPNTsToken, 'xPNTs Token'),
+    };
+  }
+}
+```
+
+#### 1.3 Package Structure Reformation
+**Objective:** Implement clear separation of concerns.
+
+**New Structure:**
+```
+packages/
+├── core/           # Foundation: ABIs, validation, basic actions
+├── clients/        # NEW: Unified client implementations
+├── types/          # NEW: Shared type definitions
+├── utils/          # NEW: Pure utilities and helpers
+├── paymaster/      # Paymaster-specific logic
+├── account/        # Account abstraction
+└── examples/       # Usage examples
+```
+
+### Phase 2: Business Logic Hardening (Week 3-4)
+
+#### 2.1 Gasless Flow Standardization
+**Objective:** Create validated, documented gasless transaction flows.
+
+**Implementation:**
+```typescript
+// New: Gasless transaction builder
+export class GaslessTransactionBuilder {
+  constructor(private client: AAStarClient) {}
+
+  async buildOnboardFlow(params: OnboardParams): Promise<GaslessTransaction> {
+    // Validate economic parameters
+    await this.validateEconomicViability(params);
+
+    // Estimate total gas cost
+    const gasEstimate = await this.estimateTotalGas(params);
+
+    // Build optimized transaction sequence
+    return this.buildOptimizedSequence(params, gasEstimate);
+  }
+
+  private async validateEconomicViability(params: OnboardParams): Promise<void> {
+    // Check if gasless transaction makes economic sense
+    const gasCost = await this.client.estimateGas(params);
+    const serviceFee = this.calculateServiceFee(params);
+
+    if (gasCost > serviceFee * 0.8) {
+      throw new AAStarError(
+        'Gasless transaction not economically viable',
+        AAStarErrorCode.ECONOMIC_INVIABILITY,
+        { gasCost, serviceFee }
+      );
+    }
+  }
+}
+```
+
+#### 2.2 Error Handling Standardization
+**Objective:** Implement consistent error handling across all operations.
+
+**Implementation:**
+```typescript
+// New: Standardized error handling
+export enum AAStarErrorCode {
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  CONTRACT_ERROR = 'CONTRACT_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  ECONOMIC_INVIABILITY = 'ECONOMIC_INVIABILITY',
+  INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+}
+
+// Error factory for consistent error creation
+export class AAStarErrorFactory {
+  static validation(message: string, field: string): AAStarError {
+    return new AAStarError(
+      `Validation failed for ${field}: ${message}`,
+      AAStarErrorCode.VALIDATION_ERROR,
+      { field }
+    );
+  }
+
+  static contract(revertReason: string, contract: string): AAStarError {
+    return new AAStarError(
+      `Contract ${contract} reverted: ${revertReason}`,
+      AAStarErrorCode.CONTRACT_ERROR,
+      { contract, revertReason }
+    );
+  }
+}
+```
+
+### Phase 3: Testing & Quality Assurance (Week 5-6)
+
+#### 3.1 Comprehensive Test Suite
+**Objective:** Achieve >90% code coverage with meaningful tests.
+
+**Test Strategy:**
+```typescript
+// Unit Tests
+describe('OperatorClient', () => {
+  describe('onboardFully', () => {
+    it('should validate all inputs before execution', async () => {
+      const invalidArgs = { stakeAmount: -1n };
+      await expect(client.onboardFully(invalidArgs)).rejects.toThrow(AAStarValidationError);
+    });
+
+    it('should execute complete onboarding flow', async () => {
+      // Mock all contract interactions
+      const result = await client.onboardFully(validArgs);
+      expect(result.success).toBe(true);
+      expect(result.data.txs).toHaveLength(4); // approve, stake, approve, deposit
+    });
+  });
+});
+
+// Integration Tests
+describe('Gasless Flow E2E', () => {
+  it('should complete full operator onboarding', async () => {
+    // Deploy contracts, fund accounts, execute flow
+    const result = await runFullOnboardingFlow();
+    expect(result.operatorRegistered).toBe(true);
+    expect(result.paymasterConfigured).toBe(true);
+  });
+});
+```
+
+#### 3.2 Performance & Gas Optimization
+**Objective:** Optimize for gas efficiency and execution speed.
+
+**Implementation:**
+```typescript
+// Gas estimation and optimization
+export class GasOptimizer {
+  async estimateAndOptimize(txs: UserOperation[]): Promise<OptimizedUserOperation[]> {
+    // Estimate gas for each operation
+    const estimates = await Promise.all(txs.map(tx => this.estimateGas(tx)));
+
+    // Optimize execution order for gas efficiency
+    return this.optimizeExecutionOrder(txs, estimates);
+  }
+
+  private optimizeExecutionOrder(
+    txs: UserOperation[],
+    estimates: GasEstimate[]
+  ): OptimizedUserOperation[] {
+    // Sort by gas cost descending (expensive first)
+    // Bundle related operations
+    // Minimize state changes between calls
+    return txs.sort((a, b) => estimates[b.index].gas - estimates[a.index].gas);
+  }
+}
+```
+
+### Phase 4: Documentation & Developer Experience (Week 7-8)
+
+#### 4.1 API Documentation Reformation
+**Objective:** Create comprehensive, usable documentation.
+
+**Implementation:**
+```typescript
+/**
+ * Complete operator onboarding with gasless transaction support.
+ *
+ * This method orchestrates the full operator setup process including:
+ * 1. GToken approval and staking
+ * 2. Role registration with the registry
+ * 3. aPNTs approval and deposit to SuperPaymaster
+ *
+ * @param params - Onboarding configuration
+ * @param params.stakeAmount - Amount to stake (minimum: 1 ETH, maximum: 100 ETH)
+ * @param params.depositAmount - Amount to deposit for gasless operations
+ * @param params.roleId - Hex-encoded role identifier
+ * @param params.xPNTsToken - Address of the xPNTs token contract
+ * @param params.gasTokens - Optional array of accepted gas tokens
+ *
+ * @returns Promise resolving to transaction results or error
+ *
+ * @example
+ * ```typescript
+ * const result = await operatorClient.onboardFully({
+ *   stakeAmount: parseEther('10'),
+ *   depositAmount: parseEther('50'),
+ *   roleId: '0x1234...',
+ *   xPNTsToken: '0x5678...'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Onboarding complete:', result.data);
+ * } else {
+ *   console.error('Onboarding failed:', result.error.message);
+ * }
+ * ```
+ */
+onboardFully(params: OnboardParams): Promise<SDKResult<OnboardResult>>
+```
+
+## 5. Implementation Priority Matrix
+
+| Priority | Component | Effort | Risk | Impact |
+|----------|-----------|--------|------|---------|
+| P0 | Type Safety Fixes | Medium | Low | High |
+| P0 | Input Validation Integration | High | Low | Critical |
+| P1 | Package Structure Reform | High | Medium | High |
+| P1 | Error Handling Standardization | Medium | Low | High |
+| P2 | Gasless Flow Optimization | High | Medium | Medium |
+| P2 | Testing Infrastructure | High | Low | High |
+| P3 | Documentation Overhaul | Medium | Low | Medium |
+
+## 6. Risk Assessment & Mitigation
+
+### 6.1 Technical Risks
+
+**Type Safety Regression:**
+- **Risk**: Introducing new `as any` usage during refactor
+- **Mitigation**: Strict ESLint rules, code reviews, gradual migration
+
+**Validation Gaps:**
+- **Risk**: Missing validation in new code paths
+- **Mitigation**: Comprehensive test coverage, validation middleware
+
+**Breaking Changes:**
+- **Risk**: Existing integrations break during refactor
+- **Mitigation**: Semantic versioning, migration guides, backward compatibility
+
+### 6.2 Business Risks
+
+**Timeline Delays:**
+- **Risk**: Underestimating complexity of multi-phase refactor
+- **Mitigation**: Incremental releases, feature flags, rollback plans
+
+**Developer Experience:**
+- **Risk**: Temporary DX degradation during transition
+- **Mitigation**: Clear migration documentation, dual API support
+
+## 7. Success Metrics
+
+### 7.1 Technical Metrics
+- ✅ **Type Safety**: 0 `as any` usage in production code
+- ✅ **Test Coverage**: >90% code coverage
+- ✅ **Validation Coverage**: 100% of external inputs validated
+- ✅ **Error Consistency**: All methods return `SDKResult<T>`
+
+### 7.2 Quality Metrics
+- ✅ **Documentation**: Complete API documentation with examples
+- ✅ **Performance**: Gas optimization within 10% of optimal
+- ✅ **Security**: Zero critical vulnerabilities in audit
+
+### 7.3 Adoption Metrics
+- ✅ **Developer Experience**: SDK usage reduces boilerplate by 80%
+- ✅ **Integration Success**: All existing integrations migrate successfully
+- ✅ **Community Feedback**: Positive feedback on DX improvements
+
+## 8. Next Steps
+
+### Immediate Actions (This Week)
+1. **Create Type Safety Task Force**: Establish strict typing guidelines
+2. **Audit All `as any` Usage**: Create comprehensive list and fix plan
+3. **Design Validation Middleware**: Create reusable validation patterns
+4. **Setup Testing Infrastructure**: Configure CI/CD for comprehensive testing
+
+### Short-term Goals (2 Weeks)
+1. **Phase 1 Completion**: Type safety and validation integration
+2. **Package Restructure**: Implement new package boundaries
+3. **Error Handling Migration**: Standardize all error patterns
+
+### Long-term Vision (2 Months)
+1. **Production-Ready SDK**: Complete all phases with comprehensive testing
+2. **Documentation Excellence**: World-class developer experience
+3. **Community Adoption**: Successful migration and positive feedback
+
+---
+
+**Expert Recommendation**: This refactor transforms the AAStar SDK from a sophisticated prototype into a production-grade platform. The focus on type safety, validation, and consistent error handling will establish it as the gold standard for account abstraction SDKs. The gasless transaction capabilities position it uniquely in the Web3 ecosystem.
+
+**Timeline**: 8 weeks to production-grade status
+**Risk Level**: Medium (well-understood technical challenges)
+**Business Impact**: High (enables mass adoption of gasless AA transactions)

package/docs/refactor/2026-01-13-refactor-plan.md

@@ -0,0 +1,88 @@
+# AAStar SDK 重构实施计划 (2026-Jan) [v3.0 - Comprehensive]
+
+**目标**: 打造一个既**安全健壮** (GPT-5.2) 又**极致易用** (Gemini CLI) 的生产级 SDK。
+**来源**: 基于 `docs/refactor/2026-01-13-audit-analysis.md` 的综合评估。
+**核心约束**: **Gasless 核心能力零退化**。所有阶段必须通过 `run_sdk_regression.sh`。
+
+---
+
+## 阶段 0: 全局安全加固 (Week 1 - P0)
+*来源: GPT-5.2 安全建议*
+*目标: 在不改变任何 API 结构的前提下，通过增加验证逻辑堵住安全漏洞。*
+
+### 0.1 建立重构基准
+- [ ] 锁定 `main` 分支代码，基于 `refactor-sdk-Jan-13` 分支工作。
+- [ ] 确认当前全回归测试通过。
+- [ ] **技术债务偿还**: 统一 ABI 导出机制 (消除 `{ "abi": ... }` 差异)，确保后续 Typechain 能正常工作。
+
+### 0.2 输入验证体系 (Security Hardening)
+- [ ] **创建验证层**: `packages/utils/src/validation.ts`。
+    - 实现 `validateAddress`, `validateAmount` (防止负数/溢出), `validateChainId`。
+- [ ] **Paymaster 深度防御**:
+    - 在 `PaymasterUtils.ts` (V4) 中增加 `paymasterAndData` 构造时的参数边界检查 (uint128)。
+    - **防止 Revert**: 在 SDK 层拦截非法参数，而不是等到链上 `AA23`。
+- [ ] **API 守门员**:
+    - 在 `SuperPaymasterClient.submitGaslessTransaction` 等高危写入口添加校验。
+
+---
+
+## 阶段 1: 架构重整与命名空间 (Week 2 - P1)
+*来源: Gemini CLI 架构建议*
+*目标: 解决“包碎片化”和“API 扁平化”问题。*
+
+### 1.1 包结构物理合并 (Consolidation)
+- [ ] **3-Package 结构**:
+    - 🔄 **`packages/sdk`**: 吞噬 `enduser`, `community`, `admin` 等业务包。
+    - 🔄 **`packages/paymaster`**: 吞噬 `superpaymaster` (物理合并，逻辑分离)。
+    - 🔄 **`packages/react`**: 接管原 `dapp`。
+    - 📦 **`packages/core`**: 保留作为 L0 基础层。
+
+### 1.2 Admin 体系重构 (Namespacing)
+- [ ] **实施命名空间**:
+    - 将 `AdminClient` 的 50+ 方法按功能分类：
+        - `admin.system.*` (Config, Upgrade)
+        - `admin.operators.*` (Slash, Manage)
+        - `admin.finance.*` (Fees, Revenue)
+- [ ] **兼容性处理**: 短期内保留旧的一级方法作为 `@deprecated`，通过调用新方法实现。
+
+---
+
+## 阶段 2: 业务逻辑融合 (Week 3 - P1)
+*来源: Gemini CLI "Thick Client" 建议*
+*目标: 让 SDK 变得“好用”，消灭 `packages/patterns`。*
+
+### 2.1 逻辑下沉 (Logic Fusion)
+- [ ] **OperatorClient 进化**:
+    - 移植 `OperatorLifecycle` -> `opClient.onboard()`。
+    - 实现**智能连击**: `approve` -> `stake` -> `deposit` 一气呵成。
+- [ ] **CommunityClient 进化**:
+    - 移植 `CommunityLaunchpad` -> `commClient.launch()`。
+- [ ] **交互优化**:
+    - 所有涉及 ERC20 的 Action (deposit, stake)，增加 `autoApprove` 逻辑。
+
+### 2.2 废弃 Patterns
+- [ ] ❌ Delete: `packages/patterns`。彻底移除这个中间层。
+
+---
+
+## 阶段 3: 质量与标准化 (Week 4 - P2)
+*来源: GPT-5.2 质量建议*
+*目标: 统一错误处理与测试体系。*
+
+### 3.1 错误处理 (Error Handling)
+- [ ] 定义 `AAStarError` (含 Error Code)。
+- [ ] 定义 `SDKResult<T> = { success, data, error }`。
+- [ ] 全局替换 `console.error` 为标准抛错或返回 Result。
+
+### 3.2 测试分层 (Testing)
+- [ ] 引入 `Vitest`.
+- [ ] 单元测试: 覆盖 `utils/validation` 和 `PaymasterUtils`。
+- [ ] 集成测试: 固化 `scripts/test-kms-gasless.ts` 为标准 Test Case。
+
+---
+
+## 立即执行项 (Next Actions)
+
+1. [ ] 创建 `packages/utils/src/validation.ts` (Phase 0)。
+2. [ ] 在 `SuperPaymasterClient` 中应用验证 (Phase 0)。
+3. [ ] 解决 ABI 加载格式不一致的技术债务 (Phase 0)。