@aastar/sdk 0.14.0 → 0.16.6

package/docs/zh/guide/paper-data-collection.md

@@ -0,0 +1,69 @@
+# 论文数据采集指南 (PhD Data Collection Guide)
+
+本文档为 AAStar 系统论文中的数据采集提供标准化指南。所有实验数据必须通过 `aastar-sdk` 获取，以确保真实性与可重复性。
+
+## 1. 实验设置 (Environmental Setup)
+
+### 网络环境
+- **Local**: 使用 `anvil` 进行基准测试（无网络延迟）。
+- **Testnet**: 使用 `Sepolia` 进行公链环境验证。
+- **L2**: 使用 `Optimism` (或 OP Sepolia) 进行低 Gas 性能测试。
+
+### 账户准备
+确保 `.env.v3` 中配置了以下地址：
+- `TEST_SIMPLE_ACCOUNT_A`: 标准 AA 账户。
+- `TEST_SIMPLE_ACCOUNT_B`: AOA (V4) 实验账户。
+- `TEST_SIMPLE_ACCOUNT_C`: SuperPaymaster 实验账户。
+
+---
+
+## 2. 核心指标 (Key Metrics)
+
+实验脚本会自动采集以下维度：
+
+| 指标 | 英文名称 | 采集方式 |
+| :--- | :--- | :--- |
+| **Gas 消耗** | Gas Usage | `receipt.gasUsed` |
+| **延迟** | Latency | `Date.now() - start` (毫秒) |
+| **交易成本** | Tx Cost | `gasUsed * effectiveGasPrice` |
+| **吞吐量** | Throughput | 批量运行时的 `count / total_time` |
+
+---
+
+## 3. 自动化运行 (Automation)
+
+直接使用统一脚本运行：
+
+```bash
+# 运行所有配置的网络（推荐）
+./scripts/run_automated_experiment.sh all
+
+# 仅运行本地测试
+./scripts/run_automated_experiment.sh local
+
+# 仅运行 Sepolia 测试
+./scripts/run_automated_experiment.sh sepolia
+```
+
+## 4. 数据导出与处理
+
+数据会自动保存至 `sdk_experiment_data.csv`。
+
+**建议流程**:
+1. 每个场景运行 30 次 (`EXPERIMENT_RUNS=30`) 以获取统计显著性。
+2. 使用 `pandas` 或 `Excel` 计算均值 (Mean) 与标准差 (Std Dev)。
+3. 使用 `scripts/collect_industry_baseline.ts` 获取对比组（EOA, Pimlico）数据。
+
+---
+
+## 5. 常规检查清单
+
+- [ ] RPC 节点是否连通。
+- [ ] 实验账户是否有足够的 Gas 余额 (或代币)。
+- [ ] `PRIVATE_KEY_JASON` 是否已在本地导出。
+- [ ] 是否已清理旧的 CSV 数据。
+
+---
+
+> [!IMPORTANT]
+> **严禁**手动修改 CSV 数据。所有偏差应在论文的 "Limitations" 或 "Discussion" 章节中说明。

package/docs/zh/guide/quick-start.md

@@ -0,0 +1,134 @@
+# 快速开始 (Quick Start)
+
+在 5 分钟内上手使用 AAStar SDK。
+
+## 第一步：安装 SDK
+
+```bash
+pnpm add @aastar/sdk viem
+```
+
+## 第二步：设置环境
+
+创建一个 `.env` 文件：
+
+```bash
+RPC_URL=https://rpc.sepolia.org
+PRIVATE_KEY=your_private_key_here
+```
+
+## 第三步：创建你的第一个客户端
+
+根据你的角色选择客户端：
+
+### 针对终端用户 (dApp 开发者)
+
+```typescript
+import { createEndUserClient } from '@aastar/core';
+import { http } from 'viem';
+import { sepolia } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const client = createEndUserClient({
+  chain: sepolia,
+  transport: http(process.env.RPC_URL),
+  account: privateKeyToAccount(process.env.PRIVATE_KEY),
+});
+
+// 查询信用额度
+const credit = await client.getCreditLimit();
+console.log('可用信用余额:', credit);
+```
+
+### 针对运营商 (Paymaster 提供者)
+
+```typescript
+import { createOperatorClient, CONTRACTS } from '@aastar/core';
+import { parseEther } from 'viem';
+
+const operator = createOperatorClient({
+  chain: sepolia,
+  transport: http(process.env.RPC_URL),
+  account: privateKeyToAccount(process.env.OPERATOR_KEY),
+});
+
+// 质押 GTokens
+await operator.stake({
+  amount: parseEther('100'),
+});
+
+// 向 Paymaster 存款
+await operator.deposit({
+  amount: parseEther('10'),
+});
+```
+
+### 针对社区 (DAO 管理者)
+
+```typescript
+import { createCommunityClient } from '@aastar/core';
+
+const community = createCommunityClient({
+  chain: sepolia,
+  transport: http(process.env.RPC_URL),
+  account: privateKeyToAccount(process.env.COMMUNITY_KEY),
+});
+
+// 注册社区
+await community.registerCommunity({
+  name: 'MyAwesomeDAO',
+  metadata: 'ipfs://...',
+});
+
+// 为成员铸造 SBT
+await community.mintSBT({
+  to: memberAddress,
+  tokenId: 1n,
+});
+```
+
+## 第四步：运行代码
+
+```bash
+tsx your-script.ts
+```
+
+## 常见模式
+
+### 检查网络配置
+
+```typescript
+import { getNetwork, CONTRACTS } from '@aastar/core';
+
+const network = getNetwork('sepolia');
+console.log('Chain ID:', network.chainId);
+console.log('RPC URL:', network.rpcUrl);
+console.log('Registry 地址:', CONTRACTS.sepolia.registry);
+```
+
+### 异常处理
+
+```typescript
+try {
+  await operator.stake({ amount: parseEther('100') });
+} catch (error) {
+  if (error.message.includes('insufficient balance')) {
+    console.error('GToken 余额不足');
+  } else {
+    console.error('质押失败:', error);
+  }
+}
+```
+
+## 下一步
+
+- [了解账户抽象](/guide/concepts/account-abstraction)
+- [探索使用场景](/guide/use-cases/community-management)
+- [阅读完整的 API 参考](/api/)
+- [尝试完整示例](/examples/)
+
+## 需要帮助？
+
+- [GitHub Issues](https://github.com/AAStarCommunity/aastar-sdk/issues)
+- [Discord](https://discord.gg/aastar)
+- [官方文档站](https://docs.aastar.io)

package/docs/zh/guide/sdk-readme.md

@@ -0,0 +1,253 @@
+# AAStar SDK (Mycelium 网络)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![Status](https://img.shields.io/badge/Status-Beta%20v2.0-green)](https://github.com/AAStarCommunity/aastar-sdk)
+
+**完整的账户抽象基础设施SDK - 为Mycelium网络提供动力**
+
+---
+
+## 📚 目录
+
+- [简介](#简介)
+- [SDK v2 架构设计](#sdk-v2-架构设计)
+- [快速开始](#快速开始)
+- [测试命令](#测试命令)
+- [开发指南](#开发指南)
+- [学术研究](#学术研究)
+
+---
+
+## 简介
+
+**AAStar SDK** 是 Mycelium 网络的高集成度开发工具包。我们将原有的17个碎片化模块重构为7个专业核心包，旨在提供统一、高性能且易于维护的开发体验。
+
+### 核心特性
+
+- ✅ **角色化客户端**: 为终端用户、社区、运营商和协议管理员提供专属API
+- ✅ **账户对象支持**: 完整兼容 `viem` v2.x Account 架构
+- ✅ **零Gas体验**: 基于信用系统的无感Gas支付
+- ✅ **DVT安全模块**: 去中心化验证与聚合签名
+- ✅ **科学可复现**: 锁定依赖版本，支持学术论文数据采集
+
+---
+
+## SDK v2 架构设计
+
+AAStar SDK v2 采用 **「装饰器 (Actions-Decorator)」** 模式（借鉴自 `viem` 与 `permissionless.js`）。它将低层次的合约交互与高层次的业务逻辑解耦，为生态系统中的四种角色提供专属的 Client 封装。
+
+### 核心理念
+
+- **语义化 Action**: 将复杂流程（如「运营商入驻」）封装为单次 SDK 调用
+- **Provider 无关性**: 完美适配任何 `viem` 传输层（Pimlico, Alchemy 或本地 Anvil）
+- **安全加固**: 锁定依赖版本并实施自动化供应链审计，防范安全漏洞
+
+### 角色化 API 矩阵
+
+| 客户端 | 目标开发者 | 核心职责 |
+| :--- | :--- | :--- |
+| **`EndUserClient`** | dApp 开发者 | 实现无感 Gas UX、管理智能账户、查询信用/债务状态 |
+| **`CommunityClient`** | 社区/DAO 管理者 | 自动化入驻、部署 xPNTs 代币、配置SBT & 声誉规则 |
+| **`OperatorClient`** | 节点/运营商 | SuperPaymaster 注册与质押、资金池(ETH/aPNTs)管理 |
+| **`AdminClient`** | 协议维护者 | 提交 DVT 聚合签名、执行奖惩 Slashing、调整全局参数 |
+
+### 预览：终端用户 Gasless 流程
+
+```typescript
+import { createEndUserClient } from '@aastar/sdk';
+
+const user = createEndUserClient({ 
+  account, 
+  paymasterUrl: 'https://paymaster.aastar.io' 
+});
+
+// 使用社区信用代付 Gas，无需持有 ETH
+await user.sendGaslessTransaction({
+  to: TARGET_ADDR,
+  data: CALL_DATA
+});
+```
+
+详细测试命令和网络切换指南，请参考 **[📖 测试命令完整指南](./docs/TEST_COMMANDS.md)**
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+pnpm install @aastar/sdk @aastar/core viem
+```
+
+### 基础示例
+
+```typescript
+import { createOperatorClient } from '@aastar/sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { foundry } from 'viem/chains';
+import { http } from 'viem';
+
+// 创建运营商客户端
+const operatorClient = createOperatorClient({
+  chain: foundry,
+  transport: http('http://127.0.0.1:8545'),
+  account: privateKeyToAccount('0x...'),
+  addresses: {
+    registry: '0x...',
+    gToken: '0x...',
+    // ...更多合约地址
+  }
+});
+
+// 一键入驻 SuperPaymaster（质押 + 存款）
+await operatorClient.onboardToSuperPaymaster({
+  stakeAmount: parseEther('50'),
+  depositAmount: parseEther('50')
+});
+```
+
+---
+
+## 测试命令
+
+本项目提供两套完整的回归测试。详细说明请参考 **[📖 测试命令完整指南](./docs/TEST_COMMANDS.md)**
+
+### 快速开始
+
+```bash
+# SDK回归测试（支持任意网络）
+pnpm run test:full_sdk
+
+# 完整协议回归（Anvil专用，72场景）
+pnpm run test:full_anvil
+```
+
+### 网络切换
+
+`test:full_sdk` 可在任意网络运行，只需修改配置：
+
+```bash
+# 方法1: 使用环境变量
+RPC_URL=https://eth-sepolia.g.alchemy.com/v2/KEY \
+REGISTRY_ADDRESS=0xSepoliaAddress \
+pnpm run test:full_sdk
+
+# 方法2: 创建专用配置文件
+cp .env.v3 .env.sepolia  # 编辑填入Sepolia地址
+dotenv -e .env.sepolia -- pnpm run test:full_sdk
+```
+
+完整网络切换指南（包括Mainnet配置）请查看 [测试命令文档](./docs/TEST_COMMANDS.md#🌐-网络切换指南)。
+
+### 1. 完整协议回归测试（不使用SDK）
+
+```bash
+pnpm run test:full_anvil
+```
+
+- **说明**: 运行17个独立测试脚本，覆盖72个场景
+- **用途**: 完整的协议功能验证（直接使用viem）
+- **特点**: 自动重启Anvil、部署合约、同步配置
+- **预期时间**: 5-10分钟
+
+### 2. SDK回归测试（使用SDK客户端）
+
+```bash
+pnpm run test:full_sdk
+```
+
+- **说明**: 验证SDK核心功能（使用四种专属客户端）
+- **用途**: SDK v2架构验证
+- **特点**: 自动检测Anvil并初始化环境
+- **预期时间**: ~30秒
+- **测试场景**:
+  - ✅ Operator Staking (质押)
+  - ✅ Paymaster Deposit (存款)
+  - ✅ Community Registration (社区注册)
+  - ✅ SBT Minting (SBT铸造)
+  - ✅ Admin Slashing (惩罚)
+  - ✅ Credit Query (信用查询)
+
+### 3. 仅初始化环境
+
+```bash
+pnpm run test:init
+```
+
+- **说明**: 重启Anvil + 部署合约 + 同步配置（不运行
+
+测试）
+- **用途**: 手动调试前的环境准备
+
+详细文档请参考：[`docs/TEST_COMMANDS.md`](./docs/TEST_COMMANDS.md)
+
+---
+
+## 开发指南
+
+### 项目结构
+
+```
+aastar-sdk/
+├── packages/
+│   ├── core/           # 核心Actions和ABI定义
+│   ├── sdk/            # 四种角色化客户端
+│   ├── shared-config/  # 共享配置和常量
+│   └── finance/        # xPNTs代币工厂
+├── scripts/            # 测试和实验脚本
+├── docs/               # 完整文档
+└── run_full_regression.sh  # 自动化回归测试
+```
+
+### 构建
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建所有包
+pnpm run build
+
+# 运行测试
+pnpm run test:full_sdk
+```
+
+---
+
+## 学术研究
+
+本 SDK 支撑了 SuperPaymaster 论文的博士实验数据采集：
+
+- **`scripts/19_sdk_experiment_runner.ts`**: 官方实验记录器
+- **安全策略**: 严格版本锁定，确保数据的可重复性
+- **覆盖率**: 95%用户用例分支，72个完整场景
+
+---
+
+## 许可证
+
+MIT License - 详见 [LICENSE](./LICENSE)
+
+---
+
+## 贡献
+
+欢迎提交Issues和Pull Requests！请确保：
+
+1. 所有测试通过 (`pnpm run test:full`)
+2. 代码符合TypeScript规范
+3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)
+
+---
+
+## 相关链接
+
+- **SuperPaymaster 论文**: [最新版本](../SuperPaymaster/docs/)
+- **Mycelium 网络**: [项目主页](https://github.com/AAStarCommunity)
+- **开发者文档**: [`docs/TEST_COMMANDS.md`](./docs/TEST_COMMANDS.md)
+
+---
+
+**由 AAStarCommunity 维护 | Powered by Mycelium Network**

package/docs/zh/guide/task_breakdown.md

@@ -0,0 +1,76 @@
+# SuperPaymaster 实验任务分解 (Task Breakdown)
+
+基于博士研究需求和“三步走”（准备、测试、分析）策略。
+
+## 阶段 0: 基础与配置
+
+- [x] **0.1. 环境设置 (`.env.v3`)**
+    - [x] 创建 `projects/env/.env.v3`。
+    - [x] 填充 RPC 变量 (`SEPOLIA_RPC_URL` 等)。
+    - [x] 填充账户私钥。
+    - [x] 配置合约地址（优先使用 `@aastar/shared-config`）。
+
+- [x] **0.2. SDK 架构优化**
+    - [x] 验证 `@aastar/shared-config` 的集成。
+    - [x] 确保 `@aastar/core` 导出适配各网络的客户端。
+
+
+## 阶段 1: 准备 (储备“弹药”)
+
+- [x] **1.1. 自动化准备 (`scripts/01_prepare_all.ts`)**
+    - [x] **统一脚本**: 运行以下所有检查。
+    - [x] **账户检查**: 计算 A、B、C 账户地址。
+    - [x] **ETH 检查**: 余额不足时从 Supplier 节点注资。
+    - [x] **身份检查**: 检查 C 账户 MySBT 余额，缺失时自动铸造。
+    - [x] **资产检查**: 检查 C 账户 xPNTs (GToken) 余额，不足时自动转账。
+
+## 阶段 2: 测试 (执行阶段)
+
+1. 在 Sepolia, OP Sepolia 和 OP Mainnet 进行 ERC20 转账测试。
+2. 每小时随机进行 2 次转账，24 小时共 48 次。
+3. 默认使用 Alchemy Bundler RPC。
+4. 在 Pimlico Paymaster 测试中使用 PIM 作为 ERC20 Gas 代币。
+5. 使用 `run_daily_experiment.ts` 编排所有脚本。
+
+- [/] **2.1. 基准 1: EOA 转账 (`scripts/02_test_eoa.ts`)**
+    - [ ] 使用 `PRIVATE_KEY_RELAYER` 作为测试 EOA。
+    - [ ] 记录各项指标。
+
+- [ ] **2.2. 基准 2: 标准 AA (`scripts/03_test_standard_aa.ts`)**
+    - [ ] 使用 `TEST_SIMPLE_ACCOUNT_A` + Pimlico Paymaster。
+    - [ ] 记录各项指标。
+
+- [ ] **2.3. 实验组: SuperPaymaster (`scripts/04_test_superpaymaster.ts`)**
+    *博士论文贡献的核心。*
+    - [ ] 使用 `TEST_SIMPLE_ACCOUNT_C` + AAStar SuperPaymaster。
+    - [ ] 构造 UserOp 并发送给 Bundler。
+    - [ ] 记录指标 (Gas Used, L1 Fee, Time)。
+
+## 阶段 3: 分析 (结果产出)
+
+- [ ] **3.1. 数据分析 (`scripts/05_analyze_data.ts`)**
+    - [ ] 读取 CSV 结果。
+    - [ ] 计算均值与标准差。
+    - [ ] 对比成本与耗时。
+    - [ ] 生成用于论文的 Markdown 表格。
+
+## 阶段 4: 特性验证与联动测试 [/]
+
+### 阶段 5: Staking 退出与 Slash 测试 (12_*.ts)
+- [ ] unlock → withdraw 正常流程
+- [ ] Slash 参数验证（罚没、国库、退款）
+- [ ] 时间锁测试（提前退出拒绝）
+
+### 阶段 6: MySBT 销毁与联动集成
+- [ ] 实现 Registry.exitRole 与 MySBT 销毁联动
+- [ ] 确保角色退出后成员资格失效
+
+## 附录: 账户角色与私钥
+
+| 角色 | 变量名称 | 用途 |
+| :--- | :--- | :--- |
+| **Supplier** | `SUPPLIER_KEY` | 持有测试 ETH 和 GTokens，负责注资 |
+| **Operator** | `OPERATOR_JASON_KEY` | 管理员，负责铸造 SBT |
+| **Relayer** | `RELAYER_KEY` | 执行 EOA 基准测试 |
+| **AA User 1** | `OWNER_JASON_KEY` | 控制 SuperPaymaster AA 账户 |
+| **AA User 2** | `OWNER_ANNI_KEY` | 控制标准 Paymaster AA 账户 |