@aastar/sdk 0.16.8 → 0.16.11

package/docs/SEPOLIA_ENV_REFERENCE.md

@@ -0,0 +1,51 @@
+# Sepolia Environment Configuration Reference
+
+Copy this configuration to your `.env.sepolia` file in `aastar-sdk/scripts/experiment/stage3/`:
+
+```bash
+# Sepolia Testnet Configuration
+SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/Bx4QRW1-vnwJUePSAAD7N
+ETHERSCAN_API_KEY=<your-etherscan-key>
+
+# EntryPoint & Bundler
+ENTRYPOINT_ADDRESS=0x0000000071727De22E5E9d8BAf0edAc6f37da032
+BUNDLER_URL=https://sepolia.g.alchemy.com/v2/Bx4QRW1-vnwJUePSAAD7N
+
+# V3 Core Components
+GTOKEN_ADDRESS=0xbf0DD4c529cA321bCa8FBE23644a64eFA1BeaeB6
+GTOKENSTAKING_ADDRESS=0x5D5d930C295630e8f4130fef037E23105BE17B84
+MYSBT_ADDRESS=0x44088fE0Fc39FEE323aFc8a760E79C45D3c2fcF6
+REGISTRY_ADDRESS=0x0b72441C61D97D6c48F080E29F8Cd507A62Ce674
+
+# V3 Factory & SuperPaymaster
+XPNTS_FACTORY_ADDRESS=0xD127976771547966e1a86d5DdFA10756ae682c34
+APNTS_ADDRESS=0x7e4ACE9e0DACf6e1Bb86A53B1b12a825568273c7
+SUPERPAYMASTER_V3_ADDRESS=0x2D8Bb69A570c96E86F6A0F774975A90C30534d44
+
+# Auxiliary Modules
+REPUTATION_SYSTEM_ADDRESS=0xddF0b0283E88D809E711AA5CFcab1D5fA835c2Ca
+BLS_AGGREGATOR_ADDRESS=0x77D381AE02C12cD826e14BC7642D43a85F9aB035
+DVT_VALIDATOR_ADDRESS=0xCD6d236D638a9991b423433BFF0C737112A0D4fB
+BLS_VALIDATOR_ADDRESS=0xD6932C92d75be024a90002feDaFD4EE8768298e5
+
+# V4 Paymaster Suite
+PAYMASTER_FACTORY_V4_ADDRESS=0x81178D2CB3f4BB8b4020923b082a8bddbb27aFf0
+PAYMASTER_V4_IMPL_ADDRESS=0x8400209ADC02125747cfF360b7E4ABA83941DcA3
+PAYMASTER_V4_INSTANCE_ADDRESS=0xfBDAac70E9e1e978651A2dd40469C221096b7533
+
+# Stage 3 Experiment Keys (NEVER COMMIT TO GIT)
+ADMIN_PRIVATE_KEY=<your-admin-key>
+EOA_PRIVATE_KEY=<your-eoa-key>
+AA_OWNER_PRIVATE_KEY=<your-aa-owner-key>
+
+# Pimlico (for Group B - Standard AA)
+PIMLICO_API_KEY=<your-pimlico-key>
+```
+
+## Quick Setup
+
+```bash
+cd /Users/jason/Dev/mycelium/my-exploration/projects/aastar-sdk/scripts/experiment/stage3
+cp .env.sepolia.example .env.sepolia
+# Then fill in the private keys and API keys
+```

package/docs/STAGE3.md

@@ -0,0 +1,191 @@
+# Stage 3 Sepolia Experiment & Orchestration Pattern Design
+
+## 1. 背景与目标 (Context & Objectives)
+
+在 Phase 2 (Local Anvil) 阶段，我们验证了所有 17 个基础回归用例。进入 Phase 3 (Sepolia)，我们的重点将从“功能验证”转向“**场景化业务流验证**”和“**基准性能评估**”。
+
+本计划旨在通过四个核心业务场景，沉淀出 SDK 的**高阶抽象模式 (Orchestration Patterns)**，并为 SuperPaymaster 论文提供可信的实验数据。
+
+---
+## 2. 实验分组与基准 (Experiment 呃，那个spoliia的回归已经完成了。那我们现在转入另外一个话题，就是SDK。首先呢我们要check一下SDK当前是不是能够正常的build。呃，然后呢包括我们规划的这个API是不是都正常实现了，进行一次全回归的测试和检查，包括它的设计目标是不是都实现了。嗯，这个需要啊两个维度，一个是基础的这种AABI的或者是reite contract的封装。呃，另外一个就是业务层面。业务层面的高维度，业务原语的封装。这个角度呢就是我们已经在进行带测试和这个整体的设计可能需要不断的迭代。嗯它的带。底层可能是SDK呃本身的一些API或者我们调用其他合约的ABI对，那这是我的一个背景信息。我希望你去查看我们这三个相关的文档。然后呢梳理一下之后给出一个完整的规划来，然后从基础的AAPI的回归到业务原API的完善和回归测试啊，包括啊这几个文档的整体规划的目标的实现。Groups & Baselines)
+
+为了评估 SuperPaymaster 的竞争力，我们将对比三组账户：
+
+| 分组 | 身份标识 | 支付机制 | 核心组件 | 预期优势 |
+| :--- | :--- | :--- | :--- | :--- |
+| Group A: EOA | Standard EOA | Self-pay (ETH) | WalletClient | Baseline (Min Overhead) |
+| **Group B: Standard AA** | SimpleAccount v0.7 | 3rd Party Sponsor | Alchemy/Pimlico | Industry Standard |
+| **Group C1: Paymaster V4** | SimpleAccount v0.7 | Token-based (v4) | PaymasterV4 Contract | Basic Token Sponsorship |
+| **Group C2: SuperPaymaster** | SimpleAccount v0.7 | Asset-based Gasless | SuperPaymaster V3 | Fully Decoupled & Credit Flow |
+
+---
+
+## 3. 场景化测试用例 (Scenario-driven Test Cases)
+
+我们不仅测试单个 API，而是测试完整的“业务链路”。
+
+### 3.1 场景一：社区启动 (DAO Launchpad Pattern)
+- **业务逻辑**: 协议管理员批准 -> 社区管理员注册项目 -> 初始质押 GToken -> 部署专属 xPNTs 代币。
+- **SDK 沉淀**: `CommunityClient.onboardCommunity()` 组合操作。
+- **验证点**: 注册事件监听、xPNTs 部署地址验证、质押状态同步。
+
+### 3.2 场景二：运营商运维 (Operator Lifecycle)
+- **业务逻辑**: 运营商质押 -> 获取节点经营权 -> 通过 Factory 部署私有 Paymaster -> 激活 SuperPaymaster 路由。
+- **SDK 沉淀**: `OperatorClient.setupNode()` 模式。
+- **验证点**: 合约确定性部署 (CREATE2)、SuperPaymaster 权限映射、国库充值流转。
+
+### 3.3 场景三：终端用户旅程 (User Onboarding & Credit)
+- **业务逻辑**: 用户加入社区 -> 铸造 SBT (Auto-stake) -> 信用额度激活 -> 查看实时 Reputation。
+- **SDK 沉淀**: `EndUserClient.joinAndActivate()`。
+- **验证点**: SBT 余额、信用上限计算逻辑、信用恢复速度。
+
+### 3.4 场景四：极致 Gasless 体验 (High-Frequency UX)
+- **业务逻辑**: 用户在无 ETH 状态下，连续发送 10 笔跨协议交互。
+- **SDK 沉淀**: `EndUserClient.sendGaslessTransaction()`。
+- **数据采集**: Gas消耗明细、UserOp 处理耗时、Paymaster 扣费准确性。
+
+---
+
+## 4. 实施规划 (Implementation Roadmap)
+
+### 4.1 目录结构
+在 `aastar-sdk` 下建立独立目录：
+```text
+scripts/experiment/stage3/
+├── .env.sepolia          # Sepolia 环境专用私钥与地址
+├── 01_dao_launch.ts      # 场景一脚本
+├── 02_operator_setup.ts  # 场景二脚本
+├── 03_user_onboarding.ts # 场景三脚本
+├── 04_benchmarking.ts    # 场景四 (数据采集)
+└── setup.ts              # 分组账号初始化与资金分发
+```
+
+### 4.2 开发与执行顺序
+1. **环境初始化**: 部署 V3.3.0 核心合约至 Sepolia -> 填充 `.env.sepolia`。
+2. **场景脚本编写**: 按照 3.1-3.4 逐步实现，优先关注“组合 API”的开发。
+3. **数据采集**: 运行 `04_benchmarking.ts` 至少 30 组数据，生成 JSON 报告。
+4. **模式沉淀**: 将脚本中重复的 Orchestration 逻辑提取到 `packages/sdk` 的高阶函数中。
+
+---
+
+## 5. 预期交付物
+
+1. **`docs/STAGE_3_SCENARIO_EXP_PLAN.md`**: 详细的业务用例设计方案（即本文件）。
+2. **`scripts/experiment/stage3/`**: 完整的可运行测试代码库。
+3. **`docs/STAGE_3_REPORT.json`**: 包含三组对比数据的实验报告。
+4. **SDK Patterns**: 在 `docs/guide/patterns.md` 中更新高阶业务开发模式。
+
+
+-------
+
+
+# SDK 场景化案例设计 (User Case Design)
+
+本文档借鉴 `registry` 前端项目的用户交互逻辑，提取核心业务链路，设计了 SDK 在 Phase 3 (Sepolia) 阶段的场景化测试用例。我们的目标是**参考前端体验、沉淀 SDK 模式 (Orchestration Patterns)**，而非简单的接口复用。
+
+## 场景角色定义
+
+1.  **Protocol Admin (协议管理员)**: 部署时期是一个EOA，完成部署后交接给多签Safe账户，进行后续的全局配置、DVT 验证器管理、治理代币发行等。
+2.  **Community Admin (社区管理员)**: 部署时期是一个EOA，完成部署后交接给多签Safe账户，负责社区注册、xPNTs 发行、SBT 会员规则设定。
+3.  **PM Operator (Paymaster 操作员)**: 部署时期是一个EOA，完成部署后，**可选**交接给多签Safe账户，负责 Paymaster 节点运维、质押充值、费用管理等。多数时候，早期社区管理员和Operator是一个EOA。
+4.  **SuperPaymaster Operator**: 注册时期是一个EOA，完成部署后，**可选**交接给多签Safe账户，负责 SuperPaymaster参数配置和国库管理。多数时候，早期社区管理员和Operator是一个EOA。
+5.  **DVT(Node) Operator**: 部署时期是一个EOA，完成部署后，**可选**交接给其他EOA或者自动Rotate 账户，负责 DVT 参数配置和治理代币管理。
+6.  **EndUser (终端用户)**: 参与社区、获取 SBT 身份、使用社区信用进行 Gasless 交易。
+
+---
+
+## 核心测试用例 (Business Scenarios)
+背景信息：
+- GToken在测试阶段，来自于协议Admin直接铸造空投。
+- 未来GToken来自于独立的阶梯价格销售（Mint）合约/应用。
+- xPNTs在测试阶段，来自于社区Admin铸造空投。
+- 未来xPNTs来自于社区发行+Reputation机制+任务广场。
+- SBT在测试阶段，来自于社区Admin铸造空投或者自行Mint。
+- 未来SBT来自于社区Shops+Reputation机制+任务广场。
+- NFT在测试阶段，来自于社区Admin铸造空投或者自行Mint。
+- 未来NFT来自于社区Shops+Reputation机制+任务广场。  
+
+### 用例 1：社区“全流程”自动化 (DAO Launchpad Pattern)
+**参考自**: `RegisterCommunity.tsx`
+- **设计思路**: 前端是分步引导，SDK 应提供“原子组合”能力。模拟社区从 0 到 1 的全过程：授权 -> 质押 -> 基准配置 -> 关联 SBT。
+- **SDK 验证重点**:
+    - 组合调用：`GTokenClient` 与 `RegistryClient` 的无缝状态桥接。
+    - `RegistryClient.registerCommunityWithAutoStake`
+    - 验证 `ContractConfigManager` 是否正确识别新注册的社区配置。
+    - 社区发行自己的xPNTs，NFT。
+
+### 用例 2：Paymaster 节点部署向导 (Operator Wizard)
+**原型参考**: `DeployWizard.tsx` (3-Step Flow)
+- **业务流程**: 操作员选择模式（AOA/AOA+）-> 资源自检（GToken 余额、质押状态）-> 部署合约并充值。
+- **SDK 验证重点**:
+    - `OperatorClient.checkResources` (模拟前端资源自检逻辑)
+    - `PaymasterFactory.deployPaymaster`
+    - `OperatorClient.depositCollateral`
+- **预期结果**: 完成后，Operator拥有独立的`Paymaster`节点和 Gas Token（xPNTs），或者在 `SuperPaymaster` 的 aPNTs 余额可见且可用于支持自己社区成员使用xPNTs代付。
+
+### 用例 3：用户身份获取与信誉激活 (SBT & Reputation)
+**原型参考**: `GetSBT.tsx`, `MySBT.tsx`
+- **业务流程**: 用户选择社区 -> 自动质押 0.4 GT -> 铸造 MySBT -> 查看全局信誉分。
+- **SDK 验证重点**:
+    - `EndUserClient.mintSBT` (包含 auto-stake 逻辑)
+    - `ReputationClient.getGlobalReputation`
+    - `RegistryClient.getCreditLimit` (验证信誉分是否正确转化为信用额度)
+
+### 用例 4：纯净 Gasless 交易体验 (Ultimate Gasless UX)
+这也是我们PhD paper获取实验数据的阶段，包括baseline（EOA和Pimlico Paymaster，以及业界平均统计成本）和两个对比实验（Paymaster V4和SuperPaymaster）。
+**原型参考**: `DeveloperPortal.tsx` (集成示例)
+- **业务流程**: 一个没有任何 ETH 的新账户，使用社区发放的 SBT 凭证，通过 SDK 发送一笔交易。
+- **SDK 验证重点**:
+    - `createEndUserClient` 初始化（无私钥签名模式或智能账户模式）
+    - `getSuperPaymasterMiddleware` 后台自动构建 `userOp.paymasterAndData`
+    - 验证 `SuperPaymaster` 的 `postOp` 阶段是否正确扣除用户信用或 xPNTs 代币。
+
+
+### 基础用例整合（后续TODO）
+我们期望能够整合基础用例，给用户（社区）提供自主自助的launchpad以及管理平台。
+🎫
+Get GToken
+Get protocol access permission GToken, become protocol member, join permissionless, quit anytime freely
+
+Get →
+🏛️
+Register Community
+Create and register your community on the AAstar Network
+
+Register →
+💎
+Deploy xPNTs
+Create your community gas token for payment abstraction
+
+Deploy →
+🚀
+Launch Paymaster
+Deploy your Paymaster contract and start serving gasless transactions to your community
+
+Launch Paymaster → →
+
+### 用例 X：更多用例，持续加入（后续TODO，不加入开发）
+    用例 5：危机管理与 DVT 治理 (Governance & Slashing)
+**原型参考**: `AdminBatchMint.tsx` (管理入口)
+- **业务流程**: 管理员发现恶意行为 -> DVT 节点投票 -> 执行对社区质押额的 Slash。
+- **SDK 验证重点**:
+    - `DVTClient.proposeSlash`
+    - `DVTClient.signSlash` (模拟多节点聚合签名)
+    - `AdminClient.executeSlash`
+---
+
+## 开发计划 (Implementation Plan - 阶段 3)
+
+### 第一步：Sepolia 环境就绪
+- 部署全套合约 (V3.3.0+) 至 Sepolia。
+- 使用 `forge verify-contract` 完成 Etherscan 验证。
+- 更新 SDK `constants.ts` 中的 Sepolia 合约地址。
+
+### 第二步：场景化示例开发
+- 在 `examples/` 目录下按上述 4 个用例创建独立的 目录和TS 脚本。
+- 编写配套的中文文档注释，确保其作为“开发者指南”的使用价值。
+- 结合SuperPaymaster Readme中的数据收集计划，完成PhD paper的数据收集。这部分可以独立目录。
+
+### 第三步：全流程冒烟测试
+- 运行 `pnpm run test:sepolia` (新增脚本)。
+- 输出场景执行记录，作为 Phase 3 的交付证明。

package/docs/Script_Comparison_Report.md

@@ -0,0 +1,91 @@
+# 回归测试脚本对比验证
+
+## 对比结果
+
+### scripts/run_regression.sh (旧脚本)
+**测试内容**:
+```
+scripts/v2_regression/00_validate_env.ts
+scripts/v2_regression/01_setup_and_fund.ts
+scripts/v2_regression/02_operator_onboarding.ts
+scripts/v2_regression/03_community_registry.ts
+scripts/v2_regression/04_enduser_flow.ts
+scripts/v2_regression/05_admin_audit.ts
+```
+**特点**: 简单、仅运行V2回归测试、不处理Anvil启动
+
+---
+
+### run_full_regression.sh (新主脚本)
+**测试内容** (包含上述所有6个 + 更多):
+```
+✅ scripts/v2_regression/00_validate_env.ts
+✅ scripts/v2_regression/01_setup_and_fund.ts
+✅ scripts/v2_regression/02_operator_onboarding.ts
+✅ scripts/v2_regression/03_community_registry.ts
+✅ scripts/v2_regression/04_enduser_flow.ts
+✅ scripts/v2_regression/05_admin_audit.ts
+   scripts/06_local_test_v3_admin.ts
+   scripts/06_local_test_v3_funding.ts
+   ...共24个测试
+```
+**特点**: 
+- ✅ 包含所有v2_regression测试
+- ✅ 自动启动Anvil
+- ✅ 自动部署合约
+- ✅ 支持Sepolia模式
+
+---
+
+### run_sdk_regression.sh (SDK独立测试)
+**测试内容**:
+```
+22_test_bls_signing.ts
+23_test_middleware.ts
+20_sdk_full_capability.ts
+18_sdk_e2e_verification.ts
+19_sdk_experiment_runner.ts
+```
+**特点**: 
+- SDK层面测试
+- 不依赖Anvil
+- 不与scripts/run_regression.sh重复
+
+---
+
+## ✅ 验证结论
+
+**scripts/run_regression.sh** 的所有功能已100%包含在:
+- ✅ `run_full_regression.sh` (包含全部6个v2_regression测试)
+
+**无遗漏内容**: 
+- run_full_regression.sh 是 scripts/run_regression.sh 的**超集**
+- 包含完全相同的测试 + 额外18个高级测试
+
+**可以安全删除**: 
+- ✅ scripts/run_regression.sh (冗余)
+
+---
+
+## 推荐使用
+
+**V2回归测试** (仅6个基础测试):
+```bash
+# 直接在Sepolia运行
+REVISION_ENV=sepolia SDK_ENV_PATH=.env.sepolia \
+  ./run_full_regression.sh --env sepolia --skip-deploy
+```
+
+**完整回归测试** (24个测试):
+```bash
+# Anvil本地
+./run_full_regression.sh
+
+# Sepolia
+./run_full_regression.sh --env sepolia
+```
+
+**SDK独立测试**:
+```bash
+./run_sdk_regression.sh
+```

package/docs/Sepolia_Latest_Deployment.md

@@ -0,0 +1,117 @@
+# Sepolia最新合约部署总结
+
+**部署时间**: 2025-12-31  
+**部署者**: Admin (0xb5600060e6de5E11D3636731964218E53caadf0E)
+
+---
+
+## 已部署合约 ✅
+
+| 合约 | 地址 | 版本 | 状态 |
+|------|------|------|------|
+| **GToken** | `0x8c76a083B38093dC690bcEa422Ec560a81fFA59b` | **v2.1.0** | ✅ Burn升级 |
+| **GTokenStaking** | `0x3aB9151B57D05c8c98F55e5729E25057ecF6CEE8` | **v3.1.0** | ✅ Burn升级 |
+| **Registry** | `0xd8168f6e9410fc0A1e727B271991709ae484d1dc` | v3.1.1 | ✅ |
+| **MySBT** | `0x08f65A2Eebb28342990d41094c278990fFBC6BF7` | - | ✅ |
+| **ReputationSystem** | `0x7b617Bad6fa7A7f9Bd34640170586F8C12c88278` | - | ✅ |
+| **aPNTs** | `0x1a93Bb78e7DF973d2A0f6aba3c40A81aAddA8A70` | - | ✅ |
+| **SuperPaymaster** | `0x62Eb2A9693CEF22d07Ea311E0d44d5A617EEDde3` | v3.1.1 | ✅ |
+| **BLSAggregator** | `0xcC93E8dac22e6C63C1A0a6D47D8da87901b44ab1` | - | ✅ |
+| **DVTValidator** | `0x6C1233Dd301459B5DD5653c5059669f5bf666889` | - | ✅ |
+| **BLSValidator** | `0xD455A42de3b8d49a64A7329ce4782D6e9632aAd8` | - | ✅ |
+| **xPNTsFactory** | `0x9f831C6B825f4Eef04F92050B1B43A6446abAE78` | - | ✅ |
+| **PaymasterV4** | `0x90E793Aa46d11239cdC10625d59252F311338a12` | - | ✅ |
+| **PaymasterFactory** | `0xD63C1305223Cc505f0c2D9b70cCC623870DEbdcf` | - | ✅ |
+
+---
+
+## 🔥 核心升级: GToken Burn机制
+
+### GToken v2.1.0
+**新增功能**:
+- ✅ `ERC20Burnable` 继承(真实销毁)
+- ✅ `remainingMintableSupply()` 查询函数
+- ✅ `_update()` 多重继承覆盖
+
+**链上验证**:
+```bash
+cast call 0x8c76a083B38093dC690bcEa422Ec560a81fFA59b "VERSION()(string)" \
+  --rpc-url https://ethereum-sepolia-rpc.publicnode.com
+# 输出: "2.1.0" ✅
+```
+
+### GTokenStaking v3.1.0
+**升级内容**:
+- ✅ Entry burn使用真实销毁(替代黑洞转账)
+- ✅ totalSupply自动减少
+- ✅ Gas优化76% (8,180 vs 34,900)
+
+**链上验证**:
+```bash
+cast call 0x3aB9151B57D05c8c98F55e5729E25057ecF6CEE8 "VERSION()(string)" \
+  --rpc-url https://ethereum-sepolia-rpc.publicnode.com
+# 输出: "3.1.0" ✅
+```
+
+---
+
+## 测试验证 ✅
+
+### V2回归测试: 6/6通过
+```
+✅ 00_validate_env
+✅ 01_setup_and_fund
+✅ 02_operator_onboarding
+✅ 03_community_registry
+✅ 04_enduser_flow
+✅ 05_admin_audit
+```
+
+### 运行命令
+```bash
+REVISION_ENV=sepolia SDK_ENV_PATH=.env.sepolia \
+  ./run_full_regression.sh --env sepolia
+```
+
+---
+
+## 初始化状态
+
+### 测试账户aPNTs余额
+| 账户 | 地址 | aPNTs余额 |
+|------|------|-----------|
+| Operator | `0x0376a69C8128190734cCbEa038F47e59e9dEc49F` | 100 aPNTs |
+| Community | `0x060b0A80557069B72D8A16bcEf5F8ba9716bFFF5` | 100 aPNTs |
+| User | `0x3E3b5CA4C41Ab87c8043960e3c7eB89267740198` | 100 aPNTs |
+
+---
+
+## 浏览器验证
+
+**Sepolia Etherscan**:
+- GToken: https://sepolia.etherscan.io/address/0x8c76a083B38093dC690bcEa422Ec560a81fFA59b
+- GTokenStaking: https://sepolia.etherscan.io/address/0x3aB9151B57D05c8c98F55e5729E25057ecF6CEE8
+- Registry: https://sepolia.etherscan.io/address/0xd8168f6e9410fc0A1e727B271991709ae484d1dc
+
+---
+
+## 配置文件
+
+所有地址已更新到:
+- ✅ `.env.sepolia` (SDK配置)
+- ✅ 部署日志: `broadcast/DeployV3FullSepolia.s.sol/11155111/run-latest.json`
+
+---
+
+## 总结
+
+✅ **全新部署完成**
+✅ **Burn机制升级已上链**
+✅ **所有测试通过**
+✅ **环境已初始化**
+
+Sepolia测试网环境已完全就绪,可用于:
+- 前端集成测试
+- 用户验收测试
+- 合约交互验证
+- Burn机制展示