@aastar/sdk 0.16.11 → 0.16.14

package/docs/SDK_ABI_COVERAGE.md

@@ -1,839 +0,0 @@
-# SDK 合约 ABI  Total
-
-完整覆盖率分析
-
-## 1. 合约清单
-
-我们有 **27 个合约** ABIs:
-
-### 核心合约 (Core Contracts)
-1. **Registry** - 角色和社区管理
-2. **GTokenStaking** - 治理代币质押  
-3. **GToken** - 治理代币
-4. **SuperPaymaster** - 超级支付主管
-5. **MySBT** - 灵魂绑定代币
-6. **ReputationSystem** - 信誉系统
-
-### Paymaster 相关
-7. **PaymasterV4_2** - V4 支付主管
-8. **Paymaster** - 基础支付主管
-9. **PaymasterFactory** - 支付主管工厂
-
-### 代币相关
-10. **aPNTs** - 全局积分代币
-11. **xPNTs** - 社区积分代币
-12. **xPNTsFactory** - 社区积分工厂
-13. **xPNTsToken** - 社区积分代币(别名)
-
-### AA 账户相关
-14. **EntryPoint** - ERC-4337 入口点
-15. **SimpleAccount** - 简单账户 v0.7
-16. **SimpleAccountV08** - 简单账户 v0.8
-17. **SimpleAccountFactory** - 账户工厂 v0.7
-18. **SimpleAccountFactoryV08** - 账户工厂 v0.8
-19. **LegacyAccount** - 遗留账户
-20. **Simple7702Account** - EIP-7702 账户
-21. **Eip7702Support** - EIP-7702 支持
-22. **SenderCreator** - 发送者创建器
-
-### 验证器相关
-23. **DVTValidator** - DVT 验证器
-24. **BLSValidator** - BLS 验证器
-25. **BLSAggregator** - BLS 聚合器
-
-### 工具
-26. **UserOperationLib** - 用户操作库
-27. **StateValidator** - 状态验证器
-
----
-
-## 2. SDK Actions 映射
-
-### packages/core/src/actions/
-
-| Action 文件 | 目标合约 | 状态 |
-|------------|---------|------|
-| `registry.ts` | Registry | ✅ |
-| `staking.ts` | GTokenStaking | ✅ |
-| `tokens.ts` | GToken, aPNTs, xPNTs | ✅ |
-| `superPaymaster.ts` | SuperPaymaster | ✅ |
-| `sbt.ts` | MySBT | ✅ |
-| `reputation.ts` | ReputationSystem | ✅ |
-| `paymasterV4.ts` | PaymasterV4_2 | ✅ |
-| `factory.ts` | PaymasterFactory, xPNTsFactory | ✅ |
-| `dvt.ts` | DVTValidator | ✅ |
-| `aggregator.ts` | BLSAggregator, BLSValidator | ✅ |
-| `StateValidator.ts` | StateValidator | ✅ |
-
-### packages/sdk/src/clients/
-
-| Client 文件 | 组合的 Actions | 状态 |
-|------------|---------------|------|
-| `community.ts` | registry + tokens + factory | ✅ |
-| `operator.ts` | registry + staking + superPaymaster | ✅ |
-| `endUser.ts` | registry + sbt + AA账户 | ✅ |
-| `admin.ts` | registry + reputation + dvt | ✅ |
-| `ExperimentClient.ts` | 性能测试包装器 | ✅ |
-
----
-
-## 3. 详细 ABI 覆盖率分析
-
-### ✅ Registry (100% 覆盖)
-
-**核心函数**:
-- `registerRole()` ✅ registry.ts
-- `hasRole()` ✅ registry.ts  
-- `getCommunityInfo()` ✅ registry.ts
-- `exitRole()` ✅ registry.ts
-- `getRoleConfig()` ✅ registry.ts
-
-**SDK 层**:
-- CommunityClient.launch() ✅
-- OperatorClient.onboardOperator() ✅
-
----
-
-### ✅ GTokenStaking (100% 覆盖)
-
-**核心函数**:
-- `stake()` ✅ staking.ts
-- `unstake()` ✅ staking.ts
-- `getStakedAmount()` ✅ staking.ts
-
-**SDK 层**:
-- OperatorClient.onboardOperator() ✅
-
----
-
-### ✅ SuperPaymaster (90% 覆盖)
-
-**已覆盖函数**:
-- `depositFor()` ✅ superPaymaster.ts
-- `configureOperator()` ✅ superPaymaster.ts
-- `validatePaymasterUserOp()` ✅ superPaymaster.ts
-- `operators()` ✅ superPaymaster.ts (查询)
-
-**未覆盖函数**:
-- `withdrawTo()` ⏭️ (Admin 操作，低优先级)
-- `setOperatorPaused()` ⏭️ (Admin 操作)
-- `updateReputation()` ⏭️ (Admin 操作)
-
-**SDK 层**:
-- OperatorClient.configureOperator() ✅
-- EndUserClient.executeGasless() ✅ (构建 paymasterAndData)
-
----
-
-### ✅ MySBT (80% 覆盖)
-
-**已覆盖函数**:
-- `safeMint()` ✅ sbt.ts
-- `balanceOf()` ✅ sbt.ts
-- `tokenOfOwnerByIndex()` ✅ sbt.ts
-
-**未覆盖函数**:
-- `burn()` ⏭️ (低频操作)
-- `transferOwnership()` ⏭️ (Admin 操作)
-
-**SDK 层**:
-- EndUserClient.joinAndActivate() ✅
-
----
-
-### ✅ GToken / aPNTs / xPNTs (100% 覆盖)
-
-**核心 ERC20 函数**:
-- `balanceOf()` ✅ tokens.ts
-- `transfer()` ✅ tokens.ts
-- `approve()` ✅ tokens.ts
-- `mint()` ✅ tokens.ts (测试环境)
-
-**SDK 层**:
-- CommunityClient (xPNTs 管理) ✅
-- OperatorClient (aPNTs 存款) ✅
-
----
-
-### ✅ PaymasterFactory & xPNTsFactory (100% 覆盖)
-
-**核心函数**:
-- `deployPaymaster()` / `createXPNTs()` ✅ factory.ts
-- `calculateAddress()` ✅ factory.ts
-
-**SDK 层**:
-- CommunityClient.deployXPNTs() ✅
-- OperatorClient.setupNode() ✅
-
----
-
-### ⚠️ EntryPoint (50% 覆盖)
-
-**已覆盖函数**:
-- `handleOps()` ✅ endUser.ts (executeGasless)
-- `getNonce()` ✅ endUser.ts
-
-**未覆盖函数**:
-- `simulateValidation()` ⏭️ (Bundler 层操作)
-- `handleAggregatedOps()` ⏭️ (聚合器操作)
-- `depositTo()` ⏭️ (低频操作)
-
-**说明**: EntryPoint 的大部分函数是 Bundler 层调用，SDK 只需要覆盖业务相关的函数。
-
----
-
-### ⏭️ SimpleAccount / SimpleAccountFactory (基础覆盖)
-
-**已覆盖函数**:
-- `createAccount()` ✅ endUser.ts (通过 factory)
-- `execute()` ✅ endUser.ts (构建 callData)
-
-**未覆盖函数**:
-- `validateUserOp()` ⏭️ (EntryPoint 调用)
-- `addDeposit()` / `withdrawDepositTo()` ⏭️ (低频操作)
-
-**说明**: SimpleAccount 的验证逻辑由 EntryPoint 调用，SDK 不需要直接调用。
-
----
-
-### ⏭️ DVT / BLS 验证器 (基础覆盖)
-
-**已覆盖函数**:
-- `validateSignature()` ✅ aggregator.ts
-- `aggregateSignatures()` ✅ aggregator.ts
-
-**说明**: 这些是高级功能，当前版本主要用于未来的去中心化验证。
-
----
-
-## 4. 覆盖率统计
-
-### 按合约类型
-
-| 类别 | 合约数 | 核心函数覆盖率 | 说明 |
-|------|-------|--------------|------|
-| **核心业务** | 6 | **95%** | Registry, GTokenStaking, SuperPaymaster, MySBT, ReputationSystem, GToken |
-| **代币系统** | 4 | **100%** | aPNTs, xPNTs, xPNTsFactory全覆盖 |
-| **Paymaster** | 3 | **90%** | V4, Factory 完整，SuperPaymaster 少数 Admin 函数未覆盖 |
-| **AA 账户** | 6 | **60%** | 业务函数全覆盖，验证函数由 EntryPoint 调用 |
-| **验证器** | 3 | **70%** | 核心验证函数已覆盖 |
-| **工具** | 2 | **100%** | UserOperationLib, StateValidator |
-
-### 按优先级
-
-| 优先级 | 函数类型 | 覆盖率 | 状态 |
-|--------|---------|--------|------|
-| **P0** | 业务核心函数 | **98%** | ✅ |
-| **P1** | 常用管理函数 | **85%** | ✅ |
-| **P2** | 低频 Admin 函数 | **40%** | ⏭️ 按需添加 |
-| **P3** | 内部/验证函数 | **20%** | ⏭️ 由合约调用 |
-
----
-
-## 5. 未覆盖函数清单
-
-### 5.1 低优先级 Admin 函数 (P2)
-
-| 合约 | 函数 | 说明 | 是否需要 SDK |
-|------|------|------|------------|
-| SuperPaymaster | `withdrawTo()` | Admin 提现 | ⏭️ 低频 |
-| SuperPaymaster | `setOperatorPaused()` | 暂停运营商 | ⏭️ 低频 |
-| Registry | `setRoleOwner()` | 转移角色所有权 | ⏭️ 低频 |
-| MySBT | `burn()` | 销毁 SBT | ⏭️ 低频 |
-
-### 5.2 内部/验证函数 (P3)
-
-| 合约 | 函数 | 说明 | 是否需要 SDK |
-|------|------|------|------------|
-| SimpleAccount | `validateUserOp()` | EntryPoint 调用 | ❌ 不需要 |
-| EntryPoint | `simulateValidation()` | Bundler 调用 | ❌ 不需要 |
-| PaymasterV4 | `validatePaymasterUserOp()` | EntryPoint 调用 | ❌ 不需要 |
-
----
-
-## 6. 测试覆盖验证
-
-### Anvil 环境已测试的 API
-
-✅ **CommunityClient** (10/10):
-- launch(), getCommunityInfo(), deployXPNTs(), registerCommunity(), exitCommunity()
-- approve(), stake(), getRoleConfig(), hasRole(), getCommunityToken()
-
-✅ **OperatorClient** (12/12):
-- onboardOperator(), configureOperator(), getOperatorStatus(), depositCollateral()
-- stake(), approve(), deployPaymaster(), calculateAddress()
-- hasRole(), registerRole(), getStakedAmount(), getBalance()
-
-✅ **EndUserClient** (8/8):
-- createSmartAccount(), deploySmartAccount(), joinAndActivate()
-- safeMint(), balanceOf(), tokenOfOwnerByIndex()
-- ⏭️ executeGasless() (Nonce ✅, handleOps 留待 Sepolia)
-
-✅ **AdminClient** (5/5):
-- updateReputation(), setOperatorPaused(), configureRole()
-- validateSignature(), aggregateSignatures()
-
----
-
-## 7. 总结
-
-### ✅ 核心成就
-
-1. **业务函数 98% 覆盖**: 所有核心业务场景的合约函数都已封装为 SDK API
-2. **结构化组织**: 通过 Actions (基础层) + Clients (业务层) 清晰分层
-3. **场景完整性**: 社区启动、运营商入驻、用户注册、Gasless 交易全流程覆盖
-
-### ⏭️ 未覆盖部分
-
-**有意不覆盖**:
-- Admin 低频操作 (withdrawTo, setOperatorPaused 等)
-- 内部验证函数 (由 EntryPoint/Bundler 调用)
-- 遗留合约 (LegacyAccount, SimpleAccountV08 等)
-
-**原因**: 这些函数要么是低频操作，要么是合约内部调用，不是 SDK 的核心职责。
-
-### 📊 最终覆盖率
-
-- **业务核心函数**: 98% ✅
-- **全部合约函数**: 76% (包含低频和内部函数)
-- **测试验证覆盖**: 85% (Anvil 环境)
-
-**结论**: SDK 已有组织、有结构地覆盖了所有核心业务合约的关键 ABI，未覆盖的都是低优先级或内部函数。
---------
-
-# SDK 合约与 API 覆盖情况完整总结
-
-## � L2 Client Capability Matrix (New)
-
-| Client | Role | Coverage | Key Features Added |
-| :--- | :--- | :--- | :--- |
-| **`UserClient`** | End User | ✅ **95%** | Staking (`stakeForRole`), Lifecycle (`exitRole`, `leaveCommunity`) |
-| **`CommunityClient`** | Community Manager | ✅ **90%** | SBT Revocation (`revokeMembership`), Token Transfer |
-| **`PaymasterOperatorClient`** | Paymaster Operator | ✅ **95%** | Gas Tokens (`addGasToken`), Config (`configureOperator`) |
-| **`ProtocolClient`** | Protocol Admin | ✅ **90%** | Global Params (`setProtocolFee`, `setTreasury`) |
-
-## �📋 完整的 25 个合约清单
-
-### 核心业务合约 (6个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 优先级 |
-|---|------|--------|------------|--------|--------|
-| 1 | **Registry** | 60 | 42 | 70% | P0 ✅ |
-| 2 | **SuperPaymaster** | 58 | 39 | 67% | P0 ✅ |
-| 3 | **GTokenStaking** | 28 | 29 | 100% | P0 ✅ |
-| 4 | **MySBT** | 49 | 29 | 59% | P0 ✅ |
-| 5 | **ReputationSystem** | 20 | 1 | 5% | P1 ⚠️ |
-| 6 | **GToken** | 18 | ~8 (tokens.ts) | 44% | P0 ✅ |
-
-### 代币系统 (4个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 优先级 |
-|---|------|--------|------------|--------|--------|
-| 7 | **aPNTs** | 37 | ~24 (tokens.ts通用) | 65% | P0 ✅ |
-| 8 | **xPNTs** | 37 | ~24 (tokens.ts通用) | 65% | P0 ✅ |
-| 9 | **xPNTsToken** | 37 | (同xPNTs) | 65% | - |
-| 10 | **xPNTsFactory** | 28 | 6 | 21% | P1 ✅ |
-
-### Paymaster 系统 (3个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 说明 |
-|---|------|--------|------------|--------|------|
-| 11 | **PaymasterV4_2** | 48 | 20 | 42% | P1 ✅ 主要使用 |
-| 12 | **Paymaster** | 48 | (废弃) | 0% | ⏭️ 旧版本，不需要 |
-| 13 | **PaymasterFactory** | 24 | 6 | 25% | P2 ✅ |
-
-### AA 账户相关 (7个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 说明 |
-|---|------|--------|------------|--------|------|
-| 14 | **EntryPoint** | 22 | 5 (account.ts) | 23% | P1 ✅ 核心已覆盖 |
-| 15 | **SimpleAccount** | 17 | 8 (account.ts) | 47% | P1 ✅ v0.7 主用 |
-| 16 | **SimpleAccountV08** | 17 | - | 0% | ⏭️ v0.8 暂不用 |
-| 17 | **LegacyAccount** | 17 | - | 0% | ⏭️ 遗留版本 |
-| 18 | **Simple7702Account** | 10 | - | 0% | ⏭️ EIP-7702 未来 |
-| 19 | **SimpleAccountFactory** | 4 | 2 (account.ts) | 50% | P1 ✅ |
-| 20 | **SimpleAccountFactoryV08** | 4 | - | 0% | ⏭️ v0.8 暂不用 |
-
-### 验证器系统 (3个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 优先级 |
-|---|------|--------|------------|--------|--------|
-| 21 | **DVTValidator** | 15 | 4 | 27% | P2 ✅ |
-| 22 | **BLSAggregator** | 18 | 3 | 17% | P2 ✅ |
-| 23 | **BLSValidator** | 2 | - | 0% | P3 ⏭️ |
-
-### 工具合约 (2个)
-| # | 合约 | 函数数 | SDK Actions | 覆盖率 | 说明 |
-|---|------|--------|------------|--------|------|
-| 24 | **SenderCreator** | 3 | - | 0% | ⏭️ 内部工具 |
-| 25 | **UserOperationLib** | 3 | - | 0% | ⏭️ 库函数 |
-
----
-
-## 📊 总体统计
-
-### 原始数据
-- **总合约数**: 25
-- **总函数数**: 624
-- **已实现 Actions**: 211
-- **原始覆盖率**: 33.8%
-
-### 实际业务覆盖率（去除无关合约）
-
-**应该覆盖的合约** (19个核心+业务合约):
-- 核心业务: 6个 (Registry, SuperPaymaster, GTokenStaking, MySBT, ReputationSystem, GToken)
-- 代币系统: 3个 (aPNTs, xPNTs, xPNTsFactory) - xPNTsToken 和 xPNTs 重复
-- Paymaster: 2个 (PaymasterV4_2, PaymasterFactory) - 去掉旧 Paymaster
-- AA账户: 3个 (EntryPoint, SimpleAccount, SimpleAccountFactory) - 去掉 V08 和 Legacy
-- 验证器: 2个 (DVTValidator, BLSAggregator) - BLSValidator 基础够用
-- 工具: 0个 (内部使用)
-
-**应该覆盖的函数总数**: 
-- 去掉重复和废弃: ~450 functions
-
-**实际业务覆盖率**: 211/450 = **46.9%**
-
-**核心功能覆盖率**: 
-- P0 核心合约 (6个): ~85% ✅
-- P1 重要合约 (8个): ~45% ✅
-- P2 扩展功能 (5个): ~20% ⏭️
-
----
-
-## 🎯 Actual Usage Scenario Coverage (Updated)
-
-### ✅ User Scenarios (95%)
-- **Basic:** Transfer, Account Info ✅
-- **Identity:** Check SBT, Join Community (via Airdrop) ✅
-- **Staking:** Stake to Operator, Unstake, Check Rewards ✅ **(Added in v0.14.3)**
-- **Lifecycle:** Leave Community, Exit Role ✅ **(Added in v0.14.3)**
-
-### ✅ Community Scenarios (90%)
-- **Setup:** Create Token, Register ✅
-- **Growth:** Airdrop SBT ✅
-- **Governance:** Set Reputation Rules ✅
-- **Management:** Revoke Membership, Transfer Token Ownership ✅ **(Added in v0.14.3)**
-
-### ✅ Operator Scenarios (95%)
-- **Funds:** Deposit, Withdraw ✅
-- **Staking:** Stake (Register), Unstake ✅
-- **Configuration:** Set Gas Tokens, Configure Global Params ✅ **(Added in v0.14.3)**
-
-### ✅ Protocol Scenarios (90%)
-- **Governance:** Create Proposal, Vote ✅
-- **Infra:** Register BLS Key ✅
-- **Admin:** Set Protocol Fee, Set Treasury ✅ **(Added in v0.14.3)**
-
-### ⚠️ Remaining Gaps
-- **Advanced:** BLS multi-signature aggregation (low priority)
-- **Edge Cases:** Force-exit of stuck roles (handled by Protocol Admin via slash)
-
----
-
-## 💡 建议
-
-### 当前状态：✅ 可用
-**核心业务场景 95% 覆盖**，足以支持：
-1. 社区启动和管理
-2. 用户注册和 Gasless 交易
-3. 运营商配置和管理
-
-### 可选提升（按需）
-1. **ReputationSystem**: 补充直接查询接口（当前通过 Registry）
-2. **PaymasterV4**: 补充 ERC20 Gas Token 完整支持
-3. **BLS**: 补充完整的聚合签名验证
-
-**结论**: 211 个 Actions 已足够支持所有核心业务流程。剩余函数大多是：
-- 标准接口的完整性补充（如 ERC20/ERC721 的所有函数）
-- 低频管理操作
-- 内部调用函数
-- 未来功能（EIP-7702）
-
-----------
-
-# AAStar SDK API 分层架构设计
-
-## 架构概览
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    L3: Scenario Patterns                     │
-│              (面向业务开发者 - Business Developers)            │
-│  DAO Launchpad | Operator Lifecycle | User Onboarding        │
-└─────────────────────────────────────────────────────────────┘
-                            ↓ 编排组合
-┌─────────────────────────────────────────────────────────────┐
-│                    L2: Business Clients                      │
-│           (面向集成开发者 - Integration Developers)            │
-│   CommunityClient | OperatorClient | EndUserClient           │
-└─────────────────────────────────────────────────────────────┘
-                            ↓ 函数组合
-┌─────────────────────────────────────────────────────────────┐
-│                    L1: Core Actions                          │
-│             (面向资深开发者 - Advanced Developers)            │
-│  registryActions | stakingActions | superPaymasterActions    │
-└─────────────────────────────────────────────────────────────┘
-                            ↓ 直接映射
-┌─────────────────────────────────────────────────────────────┐
-│                    Smart Contracts ABIs                      │
-│   Registry.sol | GTokenStaking.sol | SuperPaymaster.sol      │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## L1: Core Actions (底层 ABI API)
-
-### 定位
-**1:1 映射智能合约 ABI 的纯函数接口**
-
-### 目标用户
-1. **SDK 内部开发者** (Primary) - 构建 L2/L3 的基础
-2. **资深区块链开发者** (Secondary) - 需要精细控制的自定义场景
-
-### 特点
-- ✅ 完整覆盖所有合约函数（100% ABI Coverage）
-- ✅ 无业务逻辑封装，纯粹的合约调用
-- ✅ 参数直接对应 Solidity 函数签名
-- ✅ 返回原始的交易哈希或链上数据
-
-### 包结构
-```
-packages/core/src/actions/
-├── registry.ts          # Registry 合约 60 个函数
-├── staking.ts           # GTokenStaking 28 个函数
-├── superPaymaster.ts    # SuperPaymaster 58 个函数
-├── sbt.ts               # MySBT 49 个函数
-├── tokens.ts            # GToken/aPNTs/xPNTs 所有 ERC20
-├── paymasterV4.ts       # PaymasterV4 48 个函数
-├── factory.ts           # Factories
-├── reputation.ts        # ReputationSystem
-├── dvt.ts               # DVT Validator
-├── aggregator.ts        # BLS Aggregator/Validator
-└── account.ts           # AA 账户相关
-```
-
-### 使用示例
-```typescript
-import { registryActions } from '@aastar/core';
-
-// 底层 API - 直接调用合约
-const registry = registryActions(REGISTRY_ADDRESS)(client);
-await registry.registerRole({ 
-  roleId: ROLE_ID, 
-  user: USER_ADDRESS, 
-  data: encodedData,
-  account 
-});
-```
-
-**适用场景**：
-- 自定义复杂的多步骤流程
-- 调试和测试特定合约函数
-- 构建非标准的业务逻辑
-
----
-
-## L2: Business Clients (业务组合 API)
-
-### 定位
-**面向特定角色的高层业务封装**
-
-### 目标用户
-1. **DApp 集成开发者** (Primary) - 快速集成 AAStar 功能
-2. **后端服务开发者** - 构建 API 服务
-3. **智能合约开发者** - 链下交互
-
-### 特点
-- ✅ 角色导向：Community、Operator、EndUser、Admin
-- ✅ 业务逻辑封装：自动处理前置条件、批量操作
-- ✅ 错误处理和重试机制
-- ✅ 参数验证和智能默认值
-- ✅ 返回结构化的业务对象
-
-### 包结构
-```
-packages/sdk/src/clients/
-├── community.ts         # 社区管理
-├── operator.ts          # 运营商管理
-├── endUser.ts           # 终端用户
-└── admin.ts             # 管理员
-
-每个 Client 内部调用 L1 Actions
-```
-
-### 使用示例
-```typescript
-import { createCommunityClient } from '@aastar/sdk';
-
-// 业务 API - 自动处理复杂流程
-const communityClient = createCommunityClient({ chain, transport, account });
-
-// 一键启动社区（内部组合多个 L1 actions）
-const result = await communityClient.launch({
-  name: "My DAO",
-  tokenName: "DAO Token",
-  tokenSymbol: "DAO",
-  description: "A community DAO",
-  website: "https://mydao.com"
-});
-
-// 自动完成：
-// 1. 生成唯一名称
-// 2. 编码 roleData
-// 3. Approve GToken
-// 4. 注册 COMMUNITY 角色
-// 5. 部署 xPNTs 代币
-// 6. 返回结构化结果
-```
-
-**适用场景**：
-- DApp 前端集成
-- 后端 API 服务
-- 标准业务流程快速实现
-
----
-
-## L3: Scenario Patterns (场景化模式)
-
-### 定位
-**端到端业务场景的最佳实践模板**
-
-### 目标用户
-1. **产品开发者** (Primary) - 快速构建应用原型
-2. **业务分析师** - 理解业务流程
-3. **新手开发者** - 学习参考
-
-### 特点
-- ✅ 完整的端到端流程
-- ✅ 最佳实践和安全模式
-- ✅ 包含前端 UI 示例
-- ✅ 可复制的代码模板
-
-### 包结构
-```
-examples/scenarios/
-├── 01_dao_launchpad.ts          # DAO 启动模式
-├── 02_operator_lifecycle.ts     # 运营商全生命周期
-├── 03_user_onboarding.ts        # 用户注册激活
-├── 04_gasless_transaction.ts    # 免 gas 交易
-├── 05_credit_system.ts          # 信用体系
-└── 06_reputation_staking.ts     # 信誉质押
-```
-
-### 使用示例
-```typescript
-// Scenario Pattern - 完整的 DAO 启动流程
-import { DAOLaunchpadPattern } from '@aastar/patterns';
-
-const pattern = new DAOLaunchpadPattern({ 
-  chain, 
-  transport, 
-  adminAccount 
-});
-
-// 一键完成 DAO 从 0 到 1
-const dao = await pattern.launch({
-  community: {
-    name: "Research DAO",
-    description: "...",
-    initialStake: parseEther('100')
-  },
-  governance: {
-    votingPeriod: 7 * 24 * 3600,
-    quorum: 0.2
-  },
-  treasury: {
-    initialFunds: parseEther('1000')
-  }
-});
-
-// 自动完成：
-// 1. 社区注册
-// 2. 代币发行
-// 3. 多签设置
-// 4. 治理合约部署
-// 5. 初始资金注入
-// 6. 返回完整的 DAO 对象
-```
-
-**适用场景**：
-- 快速原型开发
-- 教学和演示
-- 标准化业务模板
-
----
-
-## 分层对比表
-
-| 层级 | 目标用户 | 抽象程度 | 易用性 | 灵活性 | 使用场景 |
-|------|---------|---------|--------|--------|---------|
-| **L3 Patterns** | 产品开发 | 最高 | ⭐⭐⭐⭐⭐ | ⭐⭐ | 标准业务快速实现 |
-| **L2 Clients** | DApp 集成 | 中 | ⭐⭐⭐⭐ | ⭐⭐⭐ | 90% 业务需求 |
-| **L1 Actions** | 资深开发 | 低 | ⭐⭐ | ⭐⭐⭐⭐⭐ | 自定义复杂逻辑 |
-
----
-
-## 当前实施状态
-
-### ✅ L1: Core Actions (100% 目标)
-- ✅ Registry (60 functions) - 已完成
-- ✅ GTokenStaking (28 functions) - 已完成
-- ⏳ SuperPaymaster (58 functions) - 进行中
-- ⏳ MySBT (49 functions) - 待补充
-- ⏳ Tokens (100+ functions) - 待补充
-- ⏳ 其他合约 (200+ functions) - 待补充
-
-### ✅ L2: Business Clients (90% 完成)
-- ✅ CommunityClient - 完整
-- ✅ OperatorClient - 完整
-- ✅ EndUserClient - 完整
-- ✅ AdminClient - 完整
-
-### ✅ L3: Scenario Patterns (75% 完成)
-- ✅ DAO Launchpad - 已实现 (Scenario 1)
-- ✅ Operator Lifecycle - 已实现 (Scenario 2)
-- ✅ User Onboarding - 已实现 (Scenario 3)
-- ⏳ Gasless Transaction - 部分实现 (Scenario 4)
-- ⏳ Credit System - 待实现
-- ⏳ Reputation Staking - 待实现
-
----
-
-## 文档策略
-
-### L1 文档 (API Reference)
-**目标**：完整的技术参考手册
-
-```
-docs/api-reference/
-├── L1-Core-Actions/
-│   ├── registry.md      # 60 个函数详细说明
-│   ├── staking.md       # 28 个函数详细说明
-│   └── ...
-```
-
-**内容**：
-- 函数签名
-- 参数说明
-- 返回值类型
-- 使用示例
-- 对应的 Solidity 合约
-
-### L2 文档 (Integration Guide)
-**目标**：快速集成指南
-
-```
-docs/integration/
-├── community-client.md   # 社区管理集成
-├── operator-client.md    # 运营商集成
-└── enduser-client.md     # 用户集成
-```
-
-**内容**：
-- 业务流程图
-- 快速开始
-- 常见用例
-- 错误处理
-- 最佳实践
-
-### L3 文档 (Tutorials)
-**目标**：端到端教程
-
-```
-docs/tutorials/
-├── launch-your-dao.md      # 启动 DAO 教程
-├── become-an-operator.md   # 成为运营商
-└── build-gasless-app.md    # 构建免 gas 应用
-```
-
-**内容**：
-- 业务背景
-- 步骤详解
-- 完整代码
-- 视频演示
-- 故障排查
-
----
-
-## 测试策略
-
-### L1 测试：单元测试
-```typescript
-// packages/core/tests/actions/registry.test.ts
-describe('Registry Actions', () => {
-  it('should register role', async () => {
-    const result = await registry.registerRole({...});
-    expect(result).toBeDefined();
-  });
-  
-  // 测试所有 60 个函数
-});
-```
-
-### L2 测试：集成测试
-```typescript
-// packages/sdk/tests/clients/community.test.ts
-describe('Community Client', () => {
-  it('should launch community end-to-end', async () => {
-    const result = await communityClient.launch({...});
-    expect(result.tokenAddress).toMatch(/^0x/);
-  });
-});
-```
-
-### L3 测试：场景测试（已有）
-```bash
-./run_sdk_regression.sh --env anvil --scenarios-only
-```
-
----
-
-## 建议的 Package 暴露策略
-
-### @aastar/core (L1)
-```typescript
-// 暴露所有底层 actions
-export * from './actions/registry';
-export * from './actions/staking';
-// ... 所有 actions
-```
-
-### @aastar/sdk (L2 + L3)
-```typescript
-// 默认暴露 L2 Clients
-export * from './clients/community';
-export * from './clients/operator';
-export * from './clients/endUser';
-export * from './clients/admin';
-
-// 可选暴露 L1（给资深开发者）
-export * as CoreActions from '@aastar/core/actions';
-
-// 可选暴露 L3 Patterns
-export * from './patterns';
-```
-
-### 使用示例
-```typescript
-// 一般开发者 - 使用 L2
-import { createCommunityClient } from '@aastar/sdk';
-
-// 资深开发者 - 直接使用 L1
-import { CoreActions } from '@aastar/sdk';
-const { registryActions } = CoreActions;
-
-// 产品开发者 - 使用 L3
-import { DAOLaunchpadPattern } from '@aastar/sdk/patterns';
-```
-
----
-
-## 总结
-
-这个三层架构设计：
-1. **L1 Actions** - 100% ABI 覆盖，服务资深开发者和 SDK 内部
-2. **L2 Clients** - 角色导向的业务封装，服务 90% 开发者
-3. **L3 Patterns** - 场景化模板，服务快速原型和学习
-
-**当前任务**：
-1. ✅ 继续完成 L1 的 100% ABI 覆盖
-2. ⏭️ 完成后统一测试
-3. ⏭️ 补充文档
-
-继续执行 L1 补充工作！