@aastar/sdk 0.16.11 → 0.16.12

package/docs/SDK_COVERAGE_STRATEGY.md

@@ -1,397 +0,0 @@
-# SDK 合约分类与覆盖策略
-
-## 📋 合约分类体系
-
-### ✅ 第一类：自研业务合约（已完成 93%+ 覆盖）
-
-**核心系统** (11个合约，355 functions)
-
-| # | 合约 | 函数数 | 说明 | 最终覆盖 | 状态 |
-|---|------|--------|------|---------|------|
-| 1 | **Registry** | 60 | 角色和社区注册中心 | 73/60 (121%) | ✅ 完成 |
-| 2 | **SuperPaymaster** | 58 | 超级支付主管 | 61/58 (105%) | ✅ 完成 |
-| 3 | **MySBT** | 49 | 灵魂绑定代币 | 58/49 (118%) | ✅ 完成 |
-| 4 | **GTokenStaking** | 28 | 治理代币质押 | 29/28 (104%) | ✅ 完成 |
-| 5 | **xPNTsFactory** | 28 | 社区代币工厂 | 22/28 (79%) | ✅ 完成 |
-| 6 | **PaymasterFactory** | 24 | Paymaster 工厂 | 16/24 (67%) | ✅ 完成 |
-| 7 | **ReputationSystem** | 20 | 信誉系统 | 20/20 (100%) | ✅ 完成 |
-| 8 | **GToken** | 18 | 治理代币 (ERC20) | 20/18 (111%) | ✅ 完成 |
-| 9 | **BLSAggregator** | 18 | BLS 签名聚合 | 18/18 (100%) | ✅ 完成 |
-| 10 | **DVTValidator** | 15 | DVT 验证器 | 20/15 (133%) | ✅ 完成 |
-| 11 | **aPNTs** | 37 | 全局积分代币 | 34/37 (92%) | ✅ 完成 |
-
-**小计**: 355 functions, **331/355 = 93.2% 覆盖** ✅
-
-**成果**: **所有自研合约达到 90%+ 覆盖目标！**
-
----
-
-### ✅ 第二类：第三方标准合约（关键功能覆盖）
-
-**ERC-4337 基础设施** (仅覆盖业务必需)
-
-| # | 合约 | 函数数 | 需要覆盖 | 当前覆盖 | 说明 |
-|---|------|--------|---------|---------|------|
-| 12 | **EntryPoint** | 22 | 5 | 5/5 ✅ | handleOps, getNonce, getUserOpHash, getDepositInfo |
-| 17 | **SimpleAccount** | 17 | 8 | 8/8 ✅ | execute, executeBatch, owner, entryPoint, getNonce |
-| 21 | **SimpleAccountFactory** | 4 | 4 | 2/4 | createAccount, getAddress |
-
-**小计**: 17 functions 需要覆盖, **15/17 = 88% 覆盖** ✅
-
----
-
-### ⚠️ 第三类：模板/实例合约（按需覆盖）
-
-| # | 合约 | 函数数 | 覆盖策略 | 当前覆盖 |
-|---|------|--------|---------|---------|
-| 4 | **Paymaster** (模板) | 48 | ❌ 不需要 SDK | 0 |
-| 5 | **PaymasterV4_2** (实例) | 48 | ✅ 基础 API (20个) | 20/48 ✅ |
-
-**说明**: 
-- Paymaster 是抽象模板，供合约开发者参考
-- PaymasterV4_2 是具体实例，SDK 提供基础 API 即可
-- 社区可以基于 Paymaster 模板创建自定义 Paymaster
-
----
-
-### ❌ 第四类：重复/遗留合约（不覆盖）
-
-| # | 合约 | 函数数 | 说明 | 决策 |
-|---|------|--------|------|------|
-| 7 | ~~xPNTs~~ | 37 | 与 aPNTs 同接口 | ❌ 不单独实现 |
-| 8 | ~~xPNTsToken~~ | 37 | 与 aPNTs 同接口 | ❌ 不单独实现 |
-| 16 | ~~LegacyAccount~~ | 17 | **旧版 AA 账户** | ❌ 已废弃 |
-| 18 | ~~SimpleAccountV08~~ | 17 | v0.8 版本 | ❌ 暂不支持 |
-| 20 | ~~Simple7702Account~~ | 10 | EIP-7702 (未来) | ❌ 预留 |
-| 22 | ~~SimpleAccountFactoryV08~~ | 4 | v0.8 工厂 | ❌ 暂不支持 |
-| 23 | ~~SenderCreator~~ | 3 | 内部工具 | ❌ 不需要 |
-| 24 | ~~UserOperationLib~~ | 3 | 库函数 | ❌ 不需要 |
-| 25 | ~~BLSValidator~~ | 2 | 基础验证器 | ❌ BLSAggregator 已够用 |
-
-**说明**:
-- **LegacyAccount**: 早期版本的 SimpleAccount，已被 v0.7 SimpleAccount 替代
-- **xPNTs/xPNTsToken**: 都是使用 `xPNTsToken` ABI，通过 `tokens.ts` 的通用接口调用不同地址即可
-
----
-
-## 🎯 最终覆盖率统计
-
-### 实际完成情况
-
-| 类别 | 合约数 | 总函数数 | 目标覆盖 | 实际覆盖 | 达成率 |
-|------|-------|---------|---------|---------|--------|
-| **自研业务** | 11 | 355 | 320 (90%) | 331 (93.2%) | ✅ 103% |
-| **第三方标准** | 3 | 43 | 17 (40%) | 15 (88%) | ✅ 88% |
-| **模板实例** | 1 | 48 | 20 (42%) | 20 (100%) | ✅ 100% |
-| **合计** | **15** | **446** | **357 (80%)** | **366 (82%)** | ✅ **102%** |
-
-**起始覆盖率**: 186/446 = **41.7%**  
-**最终覆盖率**: 366/446 = **82.0%** ✅  
-**新增函数**: **180 functions**
-
----
-
-## 💡 核心设计原则
-
-### 1. **通用性优先** - 基于地址调用
-
-所有 actions 都支持传入任意合约地址，确保通用性：
-
-```typescript
-// ✅ 正确：通用接口，支持任何部署实例
-const factory = xPNTsFactoryActions(FACTORY_ADDRESS)(client);
-const tokenA = await factory.getTokenAddress({ community: COMMUNITY_A });
-const tokenB = await factory.getTokenAddress({ community: COMMUNITY_B });
-
-// aPNTs, bPNTs, cPNTs... 都能用同一套 tokenActions
-const apnts = tokenActions(APNTS_ADDRESS)(client);
-const bpnts = tokenActions(BPNTS_ADDRESS)(client);
-```
-
-### 2. **自研合约全覆盖**
-
-所有 11 个自研合约均达到 90%+ 覆盖：
-- Registry: 121% (73/60)
-- SuperPaymaster: 105% (61/58)
-- MySBT: 118% (58/49)
-- GTokenStaking: 104% (29/28)
-- ReputationSystem: 100% (20/20)
-- BLSAggregator: 100% (18/18)
-- DVTValidator: 133% (20/15)
-- GToken: 111% (20/18)
-- aPNTs: 92% (34/37)
-- xPNTsFactory: 79% (22/28)
-- PaymasterFactory: 67% (16/24)
-
-**平均覆盖率**: 93.2% ✅
-
-### 3. **不重复**
-
-- xPNTs, xPNTsToken, aPNTs 使用同一套通用 `tokenActions` 接口
-- 不同地址实例调用同一套 API，避免代码重复
-- Paymaster template vs instance: 只实现 instance API
-
-### 4. **关联合约按需覆盖**
-
-- EntryPoint: 23% (5/22) - 只覆盖 handleOps, getNonce 等业务必需
-- SimpleAccount: 47% (8/17) - 只覆盖 execute, owner 等常用函数
-- 其他标准函数按实际业务需求补充
-
----
-
-## 📝 合约说明补充
-
-### LegacyAccount vs SimpleAccount
-
-- **LegacyAccount** (17 functions): 
-  - SuperPaymaster v3.0 之前使用的账户实现
-  - 基于早期的 ERC-4337 草案
-  - **已废弃**，被 SimpleAccount v0.7 替代
-
-- **SimpleAccount** (17 functions):
-  - 当前主要使用的 v0.7 账户实现
-  - 符合最新的 ERC-4337 规范
-  - ✅ **SDK 主要支持**
-
-### xPNTs 系列说明
-
-- **xPNTs.json**: 社区积分代币 ABI（通用模板）
-- **xPNTsToken.json**: 同上（别名）
-- **aPNTs.json**: 全局积分代币 ABI
-
-**SDK 策略**: 
-- 使用 `tokens.ts` 中的通用接口
-- 通过传入不同的 token 地址来操作不同的代币
-- 不需要为每个代币类型创建单独的 actions
-
----
-
-## ✅ 完成总结
-
-### 🎉 目标达成
-
-- ✅ **自研合约覆盖**: 93.2% (超额完成 90% 目标)
-- ✅ **总体覆盖率**: 82.0% (超额完成 80% 目标)
-- ✅ **新增函数**: 180 functions
-- ✅ **编译状态**: 全部通过
-- ✅ **代码质量**: 遵循通用性原则，类型安全
-
-### 📦 交付物
-
-**Actions 文件**:
-- `registry.ts` - 73 actions (827 lines)
-- `superPaymaster.ts` - 61 actions (720 lines)
-- `sbt.ts` - 58 actions (671 lines)
-- `staking.ts` - 29 actions (已有)
-- `tokens.ts` - 通用 ERC20/xPNTs (已有)
-- `gtokenExtended.ts` - 12 actions (144 lines)
-- `factory.ts` - 38 actions (468 lines)
-- `reputation.ts` - 20 actions (237 lines)
-- `validators.ts` - 38 actions (441 lines)
-- `account.ts` - 13 actions (已有)
-- `paymasterV4.ts` - 20 actions (已有)
-
-**总代码量**: ~4,900 lines
-
-### 🚀 下一步
-
-L1 Core Actions 已完整，可以开始：
-
-1. **L1 全回归测试** - 验证所有 API 与区块链交互
-2. **L2 Business Clients** - 角色导向的高层 API
-3. **L3 Scenario Patterns** - 端到端业务场景模板
-4. **文档完善** - API 文档 + 使用示例
-
-**核心价值**: L1 提供完整的底层 ABI 封装，为上层抽象打下坚实基础。
-
-
-## 📋 合约分类体系
-
-### ✅ 第一类：自研业务合约（100% 覆盖）
-
-**核心系统** (11个合约，~350 functions)
-
-| # | 合约 | 函数数 | 说明 | 当前覆盖 |
-|---|------|--------|------|---------|
-| 1 | **Registry** | 60 | 角色和社区注册中心 | 42/60 (70%) |
-| 2 | **SuperPaymaster** | 58 | 超级支付主管 | 39/58 (67%) |
-| 3 | **MySBT** | 49 | 灵魂绑定代币 | 29/49 (59%) |
-| 4 | **GTokenStaking** | 28 | 治理代币质押 | 29/28 (100%) ✅ |
-| 5 | **xPNTsFactory** | 28 | 社区代币工厂 | 6/28 (21%) |
-| 6 | **PaymasterFactory** | 24 | Paymaster 工厂 | 6/24 (25%) |
-| 7 | **ReputationSystem** | 20 | 信誉系统 | 1/20 (5%) |
-| 8 | **GToken** | 18 | 治理代币 (ERC20) | 8/18 (44%) |
-| 9 | **BLSAggregator** | 18 | BLS 签名聚合 | 3/18 (17%) |
-| 10 | **DVTValidator** | 15 | DVT 验证器 | 4/15 (27%) |
-| 11 | **aPNTs** | 37 | 全局积分代币 | 24/37 (65%) |
-
-**小计**: 355 functions, **151/355 = 42.5% 覆盖**
-
-**目标**: 提升到 **90%+** (约 320 functions)
-
----
-
-### ✅ 第二类：第三方标准合约（关键功能覆盖）
-
-**ERC-4337 基础设施** (仅覆盖业务必需)
-
-| # | 合约 | 函数数 | 需要覆盖 | 当前覆盖 | 说明 |
-|---|------|--------|---------|---------|------|
-| 12 | **EntryPoint** | 22 | 5 | 5/5 ✅ | handleOps, getNonce, getUserOpHash, getDepositInfo |
-| 17 | **SimpleAccount** | 17 | 8 | 8/8 ✅ | execute, executeBatch, owner, entryPoint, getNonce |
-| 21 | **SimpleAccountFactory** | 4 | 4 | 2/4 | createAccount, getAddress |
-
-**小计**: 17 functions 需要覆盖, **15/17 = 88% 覆盖** ✅
-
----
-
-### ⚠️ 第三类：模板/实例合约（按需覆盖）
-
-| # | 合约 | 函数数 | 覆盖策略 | 当前覆盖 |
-|---|------|--------|---------|---------|
-| 4 | **Paymaster** (模板) | 48 | ❌ 不需要 SDK | 0 |
-| 5 | **PaymasterV4_2** (实例) | 48 | ✅ 基础 API (20个) | 20/48 ✅ |
-
-**说明**: 
-- Paymaster 是抽象模板，供合约开发者参考
-- PaymasterV4_2 是具体实例，SDK 提供基础 API 即可
-- 社区可以基于 Paymaster 模板创建自定义 Paymaster
-
----
-
-### ❌ 第四类：重复/遗留合约（不覆盖）
-
-| # | 合约 | 函数数 | 说明 | 决策 |
-|---|------|--------|------|------|
-| 7 | ~~xPNTs~~ | 37 | 与 aPNTs 同接口 | ❌ 不单独实现 |
-| 8 | ~~xPNTsToken~~ | 37 | 与 aPNTs 同接口 | ❌ 不单独实现 |
-| 16 | ~~LegacyAccount~~ | 17 | **旧版 AA 账户** | ❌ 已废弃 |
-| 18 | ~~SimpleAccountV08~~ | 17 | v0.8 版本 | ❌ 暂不支持 |
-| 20 | ~~Simple7702Account~~ | 10 | EIP-7702 (未来) | ❌ 预留 |
-| 22 | ~~SimpleAccountFactoryV08~~ | 4 | v0.8 工厂 | ❌ 暂不支持 |
-| 23 | ~~SenderCreator~~ | 3 | 内部工具 | ❌ 不需要 |
-| 24 | ~~UserOperationLib~~ | 3 | 库函数 | ❌ 不需要 |
-| 25 | ~~BLSValidator~~ | 2 | 基础验证器 | ❌ BLSAggregator 已够用 |
-
-**说明**:
-- **LegacyAccount**: 早期版本的 SimpleAccount，已被 v0.7 SimpleAccount 替代
-- **xPNTs/xPNTsToken**: 都是使用 `xPNTsToken` ABI，通过 `tokens.ts` 的通用接口调用不同地址即可
-
----
-
-## 🎯 修正后的覆盖目标
-
-### 第一优先级：自研合约 100% 覆盖
-
-**需要补充** (~170 functions):
-
-1. **Registry** (18 functions): 
-   - 补充社区管理函数 (communityByENS, createNewRole)
-   - 补充角色锁定函数 (roleLockDurations, setRoleLockDuration)
-
-2. **SuperPaymaster** (19 functions):
-   - 补充完整的 Operator 管理
-   - 补充 Credit 系统查询
-
-3. **MySBT** (20 functions):
-   - 补充完整的 ERC721 Enumerable
-   - 补充批量铸造功能
-
-4. **xPNTsFactory** (22 functions):
-   - 补充完整的创建和查询接口
-
-5. **ReputationSystem** (19 functions):
-   - 补充信誉规则配置
-   - 补充积分计算接口
-
-6. **GToken** (10 functions):
-   - 补充完整的 ERC20 标准接口
-
-7. **BLSAggregator** (15 functions):
-   - 补充签名验证接口
-   - 补充密钥管理
-
-8. **DVTValidator** (11 functions):
-   - 补充提案管理
-   - 补充验证器管理
-
-9. **aPNTs** (13 functions):
-   - 补充债务管理
-   - 补充自动授权功能
-
-### 第二优先级：标准合约关键功能
-
-**SimpleAccountFactory** (2 functions):
-- 补充 createAccount 的其他变体
-
----
-
-## 📊 最终覆盖率目标
-
-| 类别 | 合约数 | 总函数数 | 目标覆盖 | 当前覆盖 | 差距 |
-|------|-------|---------|---------|---------|------|
-| **自研业务** | 11 | 355 | 320 (90%) | 151 (42.5%) | +169 |
-| **第三方标准** | 3 | 43 | 17 (40%) | 15 (88%) | +2 |
-| **模板实例** | 1 | 48 | 20 (42%) | 20 (100%) | 0 ✅ |
-| **合计** | **15** | **446** | **357** | **186** | **+171** |
-
-**当前实际覆盖率**: 186/446 = **41.7%**  
-**目标覆盖率**: 357/446 = **80%**
-
----
-
-## 💡 执行建议
-
-### ✅ 立即执行
-
-1. **补充自研合约剩余 70% 函数** (~170 functions)
-   - 按优先级：Registry → SuperPaymaster → MySBT → Factories → Reputation → Validators
-
-2. **测试验证**
-   - 每完成一个合约，立即编译测试
-   - 确保所有自研合约 API 可用
-
-### ⏭️ 未来扩展
-
-- EIP-7702 支持 (Simple7702Account)
-- v0.8 兼容性 (SimpleAccountV08)
-- 自定义 Paymaster 模板指南
-
----
-
-## 📝 合约说明补充
-
-### LegacyAccount vs SimpleAccount
-
-- **LegacyAccount** (17 functions): 
-  - SuperPaymaster v3.0 之前使用的账户实现
-  - 基于早期的 ERC-4337 草案
-  - **已废弃**，被 SimpleAccount v0.7 替代
-
-- **SimpleAccount** (17 functions):
-  - 当前主要使用的 v0.7 账户实现
-  - 符合最新的 ERC-4337 规范
-  - ✅ **SDK 主要支持**
-
-### xPNTs 系列说明
-
-- **xPNTs.json**: 社区积分代币 ABI（通用模板）
-- **xPNTsToken.json**: 同上（别名）
-- **aPNTs.json**: 全局积分代币 ABI
-
-**SDK 策略**: 
-- 使用 `tokens.ts` 中的通用接口
-- 通过传入不同的 token 地址来操作不同的代币
-- 不需要为每个代币类型创建单独的 actions
-
----
-
-## ✅ 结论
-
-**精简后需要覆盖的合约**: 15 个  
-**精简后需要覆盖的函数**: 446 个  
-**当前已实现**: 186 个 (41.7%)  
-**目标**: 357 个 (80%)  
-**还需补充**: 171 个函数
-
-**核心价值**: 专注自研业务合约 100% 覆盖，确保完整的业务能力。

package/docs/SDK_Optimization_Evaluation_Plan.md

@@ -1,51 +0,0 @@
-# SDK & Contract Optimization Evaluation Plan (GBT5.2 Recommendations)
-
-## 概述
-本方案针对 GBT5.2 对 `aastar-sdk` 及相关合约 ABI 扫描后给出的建议进行评估，并制定后续优化计划。我们将建议分为 **SDK 优化**、**合约安全加固** 以及 **架构对齐** 三个维度，并根据优先级划定动作：**优化 (Optimize)**、**置之不理 (Ignore)** 或 **更好的方案 (Better Solution)**。
-
----
-
-## 评估与动作列表
-
-### 1. SDK 侧建议评估 (packages/superpaymaster & core)
-
-| 建议点 | 评估 | 动作 | 理由/方案 |
-| :--- | :--- | :--- | :--- |
-| **`getPaymasterAndData` 输入上界校验** | 高 | **优化 (Optimize)** | `uint128` 溢出或格式错误会导致 Bundler 端不可预测的失败。应在 SDK 侧拦截并抛出清晰错误。 |
-| **`checkEligibility` 移除硬编码 Sepolia** | 中 | **优化 (Optimize)** | 支持多链是 SDK 的基本要求。应允许用户传入 `chainId` 或从 `provider` 自动获取。 |
-| **`formatUserOpToBundlerV07` 字段长度严格断言** | 高 | **优化 (Optimize)** | V0.7 格式对字节长度（如 `0x...` 字符串长度）有严格要求，由于 JS 没有原生固定长度字节类型，SDK 必须代劳检查。 |
-
-### 2. 合约侧（基于 ABI 反推）建议评估
-
-| 建议点 | 评估 | 动作 | 理由/方案 |
-| :--- | :--- | :--- | :--- |
-| **`PaymasterV4` 价格预言机新鲜度与权限校验** | 极高 | **优化 (Optimize)** | 关键安全路径。需确认合约源码中是否有 `updatedAt` 和 `roundId` 校验。SDK 侧无法修正，需同步到合约端。 |
-| **`SuperPaymasterV3` 债务隔离与 Slash 路径** | 高 | **优化 (Optimize)** | 多运营方模式下，用户债务必须隔离。Slash 逻辑需严格绑定 BLS 证明，防止误伤或攻击。 |
-| **`BLS/DVT` 聚合签名实操验证** | 极高 | **更好的方案 (Better Solution)** | 若目前仅为逻辑占位，主网前必须实现完整的 BLS 配对验证，或先行降级为多签治理方案以保安全。 |
-| **`Registry` 重放攻击防御 (Epoch/Nonce)** | 中 | **优化 (Optimize)** | Reputation 同步必须单调递增或带 Nonce，防止过期状态覆盖新状态。 |
-| **`ReputationSystemV3` 数组上限与 NFT 真实性** | 中 | **优化 (Optimize)** | 防止 Gas DoS 攻击。NFT Boost 必须做 `balanceOf` 校验而非仅仅依赖输入数组。 |
-
----
-
-## 执行计划与优先级
-
-### 第一阶段：SDK 鲁棒性增强 (Priority: P0)
-**目标**：确保 SDK 生成的 Payload 100% 符合规范，并能拦截低级输入错误。
-- [ ] 在 `getPaymasterAndData` 中增加 `uint128` 范围检查与地址合法性检查。
-- [ ] 重构 `checkEligibility`，支持从配置或环境中读取 `chainId`。
-- [ ] 为 `formatUserOpToBundlerV07` 增加对 `Hex` 长度的显式断言。
-
-### 第二阶段：合约安全与逻辑核对 (Priority: P1)
-**目标**：将 ABI 发现的高风险点在合约源码中进行逐一核对与修复。
-- [ ] 对接 `SuperPaymaster` 仓库，核对 `PaymasterV4` 和 `SuperPaymasterV3` 的关键权限代码。
-- [ ] 评估 `BLS/DVT` 的实现深度，并给出迁移/补全方案。
-
-### 第三阶段：文档与标准对齐 (Priority: P2)
-**目标**：更新技术文档，确保 SDK 行为与合约逻辑完全一致。
-- [ ] 更新 `projects/aastar-sdk/docs` 下的各组件文档。
-
----
-
-## 备注
-> [!IMPORTANT]
-> 由于本仓库仅包含 ABI 且当前处于 SDK 开发模式，上述合约侧建议需在切换至合约仓库时强制执行。SDK 的优化可即刻开始。

package/docs/SDK_REGRESSION_AND_API_PLAN.md

@@ -1,98 +0,0 @@
-# SDK 重构与回归测试计划 (SDK Regression & API Plan)
-
-## 1. 项目目标与原则
-**核心目标**: 验证 SDK 构建完整性，基于分层架构完善 API（满足 Phase 3 场景），并执行全量回归测试。
-
-**开发原则**:
-1.  **API 分层原则 (Layering)**:
-    *   优先使用 **基础层 API (Base/Core SDK)** 构建 **业务层 API (Business API)**。
-    *   如果基础层缺失，**先补充基础层**，再构建业务层。
-    *   *例外情况*: 仅在性能瓶颈或极特殊逻辑下直接调用合约 ABI，且必须在代码中注释说明原因。
-2.  **数据收集优先 (Data First)**:
-    *   集成博士论文所需的数据收集模块 (`TestCountManager`)。
-    *   提供独立的 API 套件用于实验数据采集（Gas 消耗、TPS、成功率等）。
-3.  **合约稳定性**:
-    *   基于 `SuperPaymaster` 项目提供的稳定 Sepolia 合约地址 (`.env.sepolia`)。
-    *   仅在发现合约初始化缺陷时才回溯修改合约。
-
-## 2. API 架构与差距分析 (Gap Analysis)
-
-### 2.1 基础层 API (Base Layer) - `packages/core`, `packages/contracts`
-*封装底层合约交互、类型定义、基础工具。*
-
-*   **P0 (缺失/需增强)**:
-    *   [ ] `StateValidator.getAccountBalances(addresses[])`: 批量获取 ETH/GToken/aPNTs 余额。
-    *   [ ] `ContractConfigManager`: 适配 V3.1.1 配置读取（从 `.env` 或 Config 合约）。
-    *   [ ] `TestCountManager`: 封装实验计数器与数据打点基础方法。
-
-### 2.2 业务层 API (Business Layer) - `packages/sdk`
-*基于基础层构建，面向最终开发者场景。*
-
-*   **P0 (状态查询 - Read)**:
-    *   [ ] `CommunityClient.getCommunityInfo(account)`: 返回角色、Token 地址、元数据。
-    *   [ ] `OperatorClient.getOperatorInfo(account)`: 返回 Operator 类型 (Super/V4)、国库状态、质押额。
-    *   [ ] `ExperimentClient.collectMetrics(txHash)`: **(新增)** 收集单笔交易的实验数据（Gas, Cost, Status）。
-
-*   **P1 (核心写操作 - Write)**:
-    *   [ ] `EndUserClient.deployAccount(owner, salt?)`: 封装 `SimpleAccountFactory` 部署逻辑。
-    *   [ ] `EndUserClient.mintSBT(account)`: 封装 "自动质押 + Mint" 的组合逻辑。
-    *   [ ] `OperatorClient.depositFunds(amount)` & `withdrawFunds()`: 简化质押金管理。
-    *   [ ] `ExperimentClient.recordBenchmark(scenarioId)`: **(新增)** 记录场景基准数据。
-
-*   **P2 (增强功能)**:
-    *   [ ] `EndUserClient.fundWithXPNTs()`: 社区 Token 分发辅助方法。
-
-## 3. 回归测试策略 (Scenarios)
-我们将现有的散乱脚本重构为 **标准化场景测试 (Scenarios)**，位于 `tests/scenarios/`。
-
-### 场景 1: 社区生命周期 (DAO Launchpad)
-*   **目标**: 注册社区 -> 发行 xPNTs -> 初始配置。
-*   **原脚本**: `09_local_test_community_lifecycle.ts`
-*   **新测试**: `01_community_launch.test.ts`
-*   **API 验证**: `CommunityClient`, `RegistryClient` (Base)。
-
-### 场景 2: 运营商入驻向导 (Operator Wizard)
-*   **目标**: 注册 SuperPaymaster Operator -> 质押 GToken -> 存入 aPNTs。
-*   **原脚本**: `05_test_superpaymaster.ts`
-*   **新测试**: `02_operator_setup.test.ts`
-*   **API 验证**: `OperatorClient`, `FundingManager` (Base)。
-
-### 场景 3: 终端用户体验 (Gasless UX)
-*   **目标**: 新 EOA -> 部署 AA 账户 -> 领取 SBT -> 发送 Gasless 交易。
-*   **原脚本**: `03_test_standard_aa.ts`
-*   **新测试**: `03_end_user_gasless.test.ts`
-*   **API 验证**: `EndUserClient`, `PaymasterClient` (Base).
-
-### 场景 4: 实验数据收集 (PhD Data Collection)
-*   **目标**: 运行基准测试 (Baseline) vs 实验组，自动记录数据。
-*   **原脚本**: `collect_industry_baseline.ts`
-*   **新测试**: `04_data_collection.test.ts`
-*   **API 验证**: `ExperimentClient`, `TestCountManager`.
-
-## 4. 执行计划 (Work Plan)
-
-### 阶段 1: 基础层与实验工具建设 (1-2天)
-1.  完善 `packages/core` 中的基础读取方法。
-2.  **重点**: 实现 `ExperimentClient` 和 `TestCountManager`，确保数据收集通道畅通。
-
-### 阶段 2: 业务 API 实现 (2-3天)
-1.  按 P0 -> P1 顺序实现 `packages/sdk` 中的业务方法。
-2.  严格遵守“基础层优先”原则，代码 Review 重点检查是否绕过 SDK 直接调用合约。
-
-### 阶段 3: 场景回归与数据验证 (2天)
-1.  迁移脚本至 `tests/scenarios/`。
-2.  运行全量回归：`pnpm test:scenarios`。
-3.  验证产生的实验数据格式是否符合论文要求。
-
-### 阶段 4: Demo 重构 (P2 优先级)
-*   在 `projects/aastar-sdk-demo` 仓库中进行。
-*   基于已验证的 SDK API 改造前端逻辑。
-
-## 5. 启动指令
-```bash
-# 1. 检查构建
-pnpm build
-
-# 2. 运行特定场景 (开发中)
-pnpm test:scenarios --filter=01_community
-```

package/docs/SDK_STAGE3_PLAN.md

@@ -1,151 +0,0 @@
-# SDK Stage 3: 全面回归测试与场景验证计划
-
-## 当前状态总结 (Current Status)
-
-### ✅ 已完成的工作
-1. **工作区清理与配置修复**：
-   - 清理了所有外部参考仓库的编译产物
-   - 恢复了 `.eslintrc.js`，加固了 `tsconfig.json` 和 `.gitignore`
-   - 配置了 `paths` 支持 IDE 代码跳转
-
-2. **Anvil 环境回归测试**：
-   - ✅ Scenario 1: 社区注册（Onboard Community）
-   - ✅ Scenario 2: 运营商入驻（Onboard Operator）
-   - ✅ Scenario 3: 用户注册（Onboard User）
-   - ⚠️ Scenario 4: Gasless 交易流（getNonce 已修复，但 handleOps 仍失败）
-
-3. **SDK 基础层优化**：
-   - 修复了 `EndUserClient.executeGasless` 的 nonce 获取逻辑
-   - 实现了 `ExperimentClient` 用于性能数据采集
-   - 同步了最新的 SuperPaymasterV3 ABIs
-
-### ⚠️ 待解决的问题
-1. **Scenario 4 handleOps 回滚**：
-   - 问题：EntryPoint.handleOps 执行失败
-   - 可能原因：Paymaster 验证失败、签名不正确或 Gas 参数问题
-   - 影响：无法完成 Anvil 环境的完整 Gasless 流程验证
-
-2. **Sepolia 环境测试**：
-   - 需要验证 Sepolia 环境的完整流程
-   - 需要确认所有合约地址已正确同步到SDK
-
----
-
-## Stage 3 执行计划 (Implementation Roadmap)
-
-基于 `STAGE3.md` 文档，我们将分三个阶段完成SDK的全面验证：
-
-### 阶段 1: 基础层回归测试 (Base Layer Regression)
-
-#### 1.1 SDK 构建验证
-- [ ] 验证 `pnpm build` 正常完成
-- [ ] 检查所有 packages 的依赖关系
-- [ ] 确认类型声明文件正确生成
-
-#### 1.2 核心 API 验证
-- [ ] **RegistryActions**: 
-  - `registerCommunity`, `joinCommunity`, `getCommunityInfo`
-- [ ] **SuperPaymasterActions**: 
-  - `validatePaymasterUserOp`, `postOp` payment logic
-- [ ] **GTokenStakingActions**: 
-  - `stake`, `unstake`, `getStakedAmount`
-- [ ] **PaymasterFactoryActions**: 
-  - `deployPaymaster`, `calculateAddress`
-
-#### 1.3 ABI 同步验证
-- [ ] 确认所有 V3.1.1 合约的 ABI 已同步
-- [ ] 验证自定义错误解码器正常工作
-- [ ] 测试事件监听和解析
-
----
-
-### 阶段 2: 业务层回归测试 (Business Layer Regression)
-
-#### 2.1 CommunityClient 验证
-- [ ] `onboardCommunity()` 组合操作
-- [ ] `getCommunityInfo()` 状态查询
-- [ ] `deployXPNTs()` 代币发行
-
-#### 2.2 OperatorClient 验证
-- [ ] `setupNode()` 节点配置
-- [ ] `depositCollateral()` 质押充值
-- [ ] `getOperatorStatus()` 状态查询
-
-#### 2.3 EndUserClient 验证
-- [ ] `joinAndActivate()` 用户注册
-- [ ] `deploySmartAccount()` AA 账户部署
-- [ ] `executeGasless()` 无 Gas 交易（**需修复**）
-
----
-
-### 阶段 3: 场景化测试 (Scenario Verification)
-
-#### 3.1 Anvil 环境场景测试
-- [x] Scenario 1: DAO Launchpad Pattern
-- [x] Scenario 2: Operator Lifecycle
-- [x] Scenario 3: User Onboarding & Credit
-- [/] Scenario 4: High-Frequency Gasless UX (**handleOps 待修复**)
-
-#### 3.2 Sepolia 环境场景测试
-- [ ] 部署完整的 V3.1.1 合约栈
-- [ ] 验证 4 个核心场景在 Sepolia 上的执行
-- [ ] 采集性能数据（Gas 消耗、延迟等）
-
-#### 3.3 对比实验数据采集
-- [ ] Group A: EOA Baseline
-- [ ] Group B: Pimlico/Alchemy Paymaster
-- [ ] Group C1: Paymaster V4
-- [ ] Group C2: SuperPaymaster V3
-
----
-
-## 优先级排序 (Priority Queue)
-
-### P0 - 紧急修复
-1. **修复 Scenario 4 的 handleOps 问题**
-   - 调试 EntryPoint 验证逻辑
-   - 检查 paymasterAndData 格式
-   - 验证 UserOp 签名
-
-### P1 - 核心功能验证
-2. **完成 Anvil 环境的 4 个场景测试**
-3. **验证 SDK 构建流程**
-4. **确认所有核心 API 正常工作**
-
-### P2 - Sepolia 环境部署
-5. **部署 V3.1.1 合约至 Sepolia**
-6. **运行 Sepolia 场景测试**
-
-### P3 - 数据采集与文档
-7. **采集对比实验数据**
-8. **编写开发者指南**
-9. **完成 Stage 3 报告**
-
----
-
-## 立即行动项 (Immediate Actions)
-
-1. ✅ 创建本计划文档
-2. ⏭️ 修复 Scenario 4 的 handleOps 问题
-3. ⏭️ 验证 SDK 构建流程
-4. ⏭️ 运行基础层 API 回归测试
-
----
-
-## 预期交付物 (Deliverables)
-
-1. **测试报告**: 
-   - `docs/STAGE_3_REGRESSION_REPORT.md`
-   - 包含所有测试用例的执行结果
-
-2. **性能数据**: 
-   - `docs/STAGE_3_BENCHMARK_DATA.json`
-   - 包含 4 组对比实验的详细数据
-
-3. **开发者指南**: 
-   - `docs/guide/patterns.md`
-   - 沉淀的 SDK Orchestration Patterns
-
-4. **修复记录**: 
-   - `walkthrough.md`
-   - 记录所有发现和修复的问题