@aastar/sdk 0.14.0 → 0.16.6

package/docs/guide/getting-started.md

@@ -0,0 +1,133 @@
+# Getting Started
+
+<p align="left">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" style="display:inline-block; margin-right: 10px;" />
+  <img src="https://img.shields.io/badge/TypeScript-5.0-blue" alt="TypeScript" style="display:inline-block; margin-right: 10px;" />
+  <img src="https://img.shields.io/badge/Status-0.14.0-green" alt="Status" style="display:inline-block;" />
+</p>
+
+**Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network**
+**完整的账户抽象基础设施 SDK - 为 Mycelium 网络提供动力**
+
+---
+
+## 📚 Table of Contents / 目录
+
+- [Introduction / 简介](#introduction--简介)
+- [SDK v2 Architecture / 架构设计](#sdk-v2-architecture--架构设计)
+- [Installation / 安装](#installation--安装)
+- [Quick Start / 快速开始](#quick-start--快速开始)
+- [Testing Commands / 测试命令](#testing-commands--测试命令)
+- [Academic Research / 学术研究](#academic-research--学术研究)
+
+---
+
+## Introduction / 简介
+
+**AAStar SDK** is a high-integration toolkit for the Mycelium network. We've refactored 17 fragmented modules into 7 professional core packages, aimed at providing a unified, high-performance, and easy-to-maintain development experience.
+
+**AAStar SDK** 是 Mycelium 网络的高集成度开发工具包。我们将原有的 17 个碎片化模块重构为 7 个专业核心包，旨在提供统一、高性能且易于维护的开发体验。
+
+### Core Features / 核心特性
+
+- ✅ **Role-Based Clients**: Specific APIs for End Users, Communities, Operators, and Admins. (**角色化客户端**)
+- ✅ **Infrastructure Ready**: Deep integration with SuperPaymaster and EOA Bridge. (**基础设施就绪**)
+- ✅ **Seamless User Experience**: Gasless transactions via community credit system. (**无感交互体验**)
+- ✅ **DVT Security Module**: Decentralized verification and aggregate signatures. (**DVT 安全模块**)
+- ✅ **Scientific Reproducibility**: Version-locked for academic research and data collection. (**科学可复现**)
+
+---
+
+## SDK v2 Architecture / 架构设计
+
+AAStar SDK v2 采用 **「装饰器 (Actions-Decorator)」** 模式（借鉴自 `viem` 与 `permissionless.js`）。它将低层次的合约交互与高层次的业务逻辑解耦，为生态系统中的四种角色提供专属的 Client 封装。
+
+### Core Concepts / 核心理念
+
+- **Semantic Actions**: Encapsulate complex flows (e.g., "Operator Onboarding") into a single SDK call. (**语义化 Action**)
+- **Provider Agnostic**: Perfectly fits any `viem` transport layer (Pimlico, Alchemy, or local Anvil). (**Provider 无关性**)
+- **Security Hardened**: Locked dependency versions and automated supply chain audits. (**安全加固**)
+
+### Role-Based API Matrix / 角色化 API 矩阵
+
+| Client / 客户端 | Targeted Developer / 目标开发者 | Core Responsibility / 核心职责 |
+| :--- | :--- | :--- |
+| **`EndUserClient`** | dApp Developer | Gasless UX, Smart Account management, Credit queries |
+| **`CommunityClient`** | Community/DAO Admin | Auto-onboarding, xPNTs deployment, SBT & Reputation |
+| **`OperatorClient`** | Node/Operator | SuperPaymaster registration, Staking, Pool management |
+| **`AdminClient`** | Protocol Admin | DVT aggregations, Slashing, Global parameters |
+
+---
+
+## Installation / 安装
+
+```bash
+pnpm install @aastar/sdk @aastar/core viem
+```
+
+---
+
+## Quick Start / 快速开始
+
+### Basic Example (Operator) / 基础示例 (运营商)
+
+```typescript
+import { createOperatorClient } from '@aastar/sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { foundry } from 'viem/chains';
+import { http } from 'viem';
+
+// Create Operator Client
+const operatorClient = createOperatorClient({
+  chain: foundry,
+  transport: http('http://127.0.0.1:8545'),
+  account: privateKeyToAccount('0x...'),
+});
+
+// One-click Onboarding to SuperPaymaster (Stake + Deposit)
+// 一键入驻 SuperPaymaster（质押 + 存款）
+await operatorClient.onboardToSuperPaymaster({
+  stakeAmount: parseEther('50'),
+  depositAmount: parseEther('50')
+});
+```
+
+---
+
+## Testing Commands / 测试命令
+
+本项目提供两套完整的回归测试。
+
+### SDK Regression (Using SDK Clients) / SDK 回归测试
+```bash
+pnpm run test:full_sdk
+```
+
+- **Scenario**:
+  - ✅ Operator Staking (质押)
+  - ✅ Paymaster Deposit (存款)
+  - ✅ Community Registration (社区注册)
+  - ✅ SBT Minting (SBT 铸造)
+  - ✅ Admin Slashing (奖励)
+  - ✅ Credit Query (信用查询)
+
+### Full Protocol Regression (Anvil Dedicated) / 完整协议回归测试
+```bash
+pnpm run test:full_anvil
+```
+
+---
+
+## Academic Research / 学术研究
+
+The SDK supports doctoral data collection for the SuperPaymaster paper. Official experiment logger is available at `scripts/19_sdk_experiment_runner.ts`.
+
+本 SDK 支撑了 SuperPaymaster 论文的博士实验数据采集。官方实验记录器位于 `scripts/19_sdk_experiment_runner.ts`。
+
+---
+
+## Support & Contributing / 支持与贡献
+
+- **Repository / 代码仓库**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
+- **Discord**: [Join our community / 加入我们的社区](https://discord.gg/aastar)
+- **License / 许可证**: MIT

package/docs/guide/installation.md

@@ -0,0 +1,40 @@
+# Installation
+
+The AAStar SDK is built with TypeScript and can be used in any Node.js or browser environment. We recommend using `pnpm` for package management.
+
+## Install the Main Package
+
+The `@aastar/sdk` package provides the easiest entry point by grouping all core functionalities.
+
+```bash
+pnpm add @aastar/sdk viem@2.x
+```
+
+## Modular Installation (Optional)
+
+If you only need specific functionalities, you can install individual packages to keep your bundle size small:
+
+```bash
+# Core utilities and types
+pnpm add @aastar/core
+
+# Account Abstraction and 7702 support
+pnpm add @aastar/account
+
+# Paymaster and sponsorship logic
+pnpm add @aastar/paymaster
+
+# Finance and GToken utilities
+pnpm add @aastar/finance
+```
+
+## Prerequisites
+
+- **Node.js**: v18 or higher.
+- **TypeScript**: v5.0 or higher (recommended for type safety).
+- **Viem**: v2.43 or higher.
+
+## Next Steps
+
+- Choose your role and create a [Client](./quick-start).
+- Explore the [Core Concepts](../concepts/account-abstraction).

package/docs/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/guide/quick-start.md

@@ -0,0 +1,52 @@
+# Quick Start
+
+Get up and running with the AAStar SDK in less than 5 minutes.
+
+## 1. Environment Setup
+
+Create a `.env` file with your private key and RPC provider:
+
+```bash
+PRIVATE_KEY_JASON=0x...
+SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/...
+```
+
+## 2. Basic Initialization
+
+Initialize the SDK by choosing a role-based client. Most developers start with the `EndUserClient`.
+
+```typescript
+import { createEndUserClient } from '@aastar/sdk';
+import { http } from 'viem';
+import { sepolia } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY_JASON);
+
+const user = createEndUserClient({
+  chain: sepolia,
+  transport: http(process.env.SEPOLIA_RPC_URL),
+  account
+});
+```
+
+## 3. Execute a Gasless Transaction
+
+Enable your users to interact with your dapp without holding native gas tokens.
+
+```typescript
+// Send a sponsored transaction via SuperPaymaster
+const hash = await user.sendGaslessTransaction({
+  to: '0x...',
+  data: '0x...',
+  communityAddress: '0x...', // Your registered community
+});
+
+console.log(`Transaction sent: ${hash}`);
+```
+
+## 4. Next Steps
+
+- **Manage Communities**: Use the [CommunityClient](../api/roles/community) to set reputation rules.
+- **Become a Provider**: Use the [OperatorClient](../api/roles/operator) to stake and sponsor gas.
+- **Advanced Features**: Explore the [API Reference](../api/) for deep customization.

package/docs/guide/task_breakdown.md

@@ -0,0 +1,121 @@
+# SuperPaymaster Experiment Task Breakdown
+
+Based on the PhD research requirements and the "Three-Step" (Prepare, Test, Analyze) strategy.
+
+## Phase 0: Foundation & Configuration
+
+- [x] **0.1. Environment Setup (`.env.v3`)**
+    - [x] Create `projects/env/.env.v3`.
+    - [x] Populate RPC variables (`SEPOLIA_RPC_URL`, `ALCHEMY_BUNDLER_RPC_URL`).
+    - [x] Populate Account Key in .env.v3
+    - [x] Populate Contract Addresses (Superseding `.env` if needed, but prioritizing `@aastar/shared-config`).
+
+- [x] **0.2. SDK Architecture Refinement**
+    - [x] Validate `@aastar/shared-config` integration for addresses (`SuperPaymaster`, `MySBT`, `GToken`).
+    - [x] Ensure `@aastar/core` exports `viem` clients configured for Sepolia and all networks.
+
+
+## Phase 1: Preparation (The "Ammo")
+
+- [x] **1.1. Automated Preparation (The "Ammo") (`scripts/01_prepare_all.ts`)**
+    - [x] **Unified Script**: Runs all checks below.
+    - [x] **Account Check**: Computes addresses for A, B, C.
+    - [x] **ETH Check**: Funds 0.05 ETH from Supplier if low.
+    - [x] **Identity Check**: Checks MySBT balance for SuperPaymaster User (C). Mints if missing.
+    - [x] **Asset Check**: Checks xPNTs (GToken) balance for SuperPaymaster User (C). Transfers if low.
+
+## Phase 2: Testing (The Execution)
+1. Transfer ERC20 Test in sepolia, op sepolia and op mainnet.
+2. Perform 48 times ERC20 Transfers, 2 times per hour in random time in one hour.
+3. Use Alchemy bundler RPC in .env.v3 as default bundler.
+4. Use PIM as erc20 gas token in pimlico paymaster test.
+5. Make all scripts for every test and use run_daily_experiment.ts to orchestrate the above scripts.
+6. Transfer any ERC20(use aPNTs, get it from supplier) to target receiver: TEST_RECEIVER_ADDRESS in .env.v3.
+
+- [/] **2.1. Baseline 1: EOA Transfers (`scripts/02_test_eoa.ts`)**
+    - [ ] Use `PRIVATE_KEY_RELAYER` as test EOA, address: 0xb5600060e6de5E11D3636731964218E53caadf0E.
+    - [ ] Log metrics.
+
+- [ ] **2.2. Baseline 2: Standard AA (`scripts/03_test_standard_aa.ts`)**
+    - [ ] Use `TEST_SIMPLE_ACCOUNT_A` + `pimlico/permissionless` ,https://docs.pimlico.io/references/bundler/endpoints/eth_sendUserOperation, use PIM as erc20 gas token, get it from supplier, token address: 0xFC3e86566895Fb007c6A0d3809eb2827DF94F751, use Alchemy bundler RPC in .env.v3
+    - [ ] Perform 48 UserOps in 24 hours.
+    - [ ] Log metrics.
+
+- [ ] **2.3. Experiment: SuperPaymaster (`scripts/04_test_superpaymaster.ts`)**
+    *Core of the PhD contribution.*
+    - [ ] Use `TEST_SIMPLE_ACCOUNT_B` +Alchemy bundler + Paymaster (Verifying Paymaster V4.1，来自于@aastar/shared-config).
+    - [ ] Use `TEST_SIMPLE_ACCOUNT_C` + `@aastar/superpaymaster` get address from @aastar/shared-config, use Alchemy bundler.
+    - [ ] Construct UserOp with `paymasterAndData` (V3 format).
+    - [ ] Send to Bundler.
+    - [ ] Log metrics (Gas Used, L1 Fee, Time).
+
+- [ ] **2.4. Automation Runner (`scripts/run_daily_experiment.ts`)**
+    - [ ] Orchestrate the above scripts.
+    - [ ] Add random delays (simulation of real usage).
+    - [ ] Output to `data/raw_experiment_data.csv`.
+
+## Phase 3: Analysis (The Result)
+
+- [ ] **3.1. Data Analysis (`scripts/05_analyze_data.ts`)**
+    - [ ] Read CSV.
+    - [ ] Compute Averages & Standard Deviation.
+    - [ ] Compare Cost vs Baseline.
+    - [ ] Compare Time vs Baseline.
+    - [ ] Generate Markdown Table for Thesis.
+
+## Phase 4: 特性验证与联动测试 [/]
+
+### Phase 5: Staking 退出与 Slash 测试 (12_*.ts) [⚠️ Debugging]
+- [ ] unlock → withdraw 正常流程 (Fixed: Slash deduction bug)
+- [ ] Slash 参数验证（罚没、国库、退款）
+- [ ] 时间锁测试（提前退出拒绝）
+  - [ ] 在 Registry 中增加 roleLockDurations 映射
+- [ ] Debug Registry.sol registration logic (RoleNotGranted)
+- [ ] Fix syntax errors and add raw error logging in 13_test_sbt_burn_linkage.ts
+- [ ] Verify active SBT burn and exit linkage
+
+### Phase 6: MySBT Burn & Linkage Integration (Active Debugging)
+- [ ] 实现 Registry.exitRole 与 MySBT 销毁/停用联动
+  - [ ] 在 IMySBTV3 中添加 deactivateMembership 接口
+  - [ ] 在 MySBT 中实现权限受控的 deactivateMembership
+  - [ ] 在 Registry.exitRole 中增加对 ROLE_ENDUSER 的 SBT 联动调用
+- [ ] 验证 `13_test_sbt_burn_linkage.ts`
+  - [ ] 完整流程 (正在解决 Anvil Revert)
+  - [ ] 同步最新合约 ABI 到 SDK
+- [ ] 解决 registerRoleSelf 报错 (正在排查 Eve 地址与角色状态)
+- [ ] 确保 getMemberships 在角色退出后返回 isActive: false
+
+### Phase 7: 集成与覆盖率报告
+- [ ] 更新 test:local 脚本包含所有新测试
+- [ ] 生成覆盖率报告（目标 80%+）
+- [ ] 执行完整回归并验证通过
+
+## Phase 8: SDK 架构演进与对齐 [⚠️ 暂停]
+
+> **WARNING**: 优先级调整：在达到 80% 测试覆盖率之前，暂停以下工作：
+> - SDK 标准化封装（SuperPaymasterClient）
+> - 链上数据采集与基准测试
+
+### 阶段一：架构标准化 (v0.4.x)
+- [ ] 基于 viem 与 AirAccount (Permissionless-style) 的架构重构
+- [ ] 定义 SuperPaymasterClient 与语义化 Error Mapper
+
+### 阶段二：生产力工具 (v0.5.x)
+- [ ] UserOp Factory 与基线/对比测试数据导出 (CSV)
+
+### 阶段三：UI 集成 (v0.6.x)
+- [ ] React Hooks 与评价面板组件
+
+## Phase 9: 论文量化评估准备 [⚠️ 暂停]
+- [ ] 搭建基线测试 (EOA vs Pimlico) 脚本
+- [ ] 自动化 CSV 采集与绘图数据预处理
+
+## Appendix: Account Roles & Keys
+
+| Role | Variable | Purpose |
+| :--- | :--- | :--- |
+| **Supplier** | `SUPPLIER_KEY` | Holds test ETH & GTokens. Funds others. |
+| **Operator** | `OPERATOR_JASON_KEY` | Admin of AAStar. Mints SBTs. |
+| **Relayer** | `RELAYER_KEY` | Performs EOA baseline tests. |
+| **AA User 1**| `OWNER_JASON_KEY` | Controls SuperPaymaster AA. |
+| **AA User 2**| `OWNER_ANNI_KEY` | Controls Standard Paymaster AA. |

package/docs/guide/use-cases/community-management.md

@@ -0,0 +1,141 @@
+# Community Management Guide
+
+Complete guide for managing DAOs and communities with AAStar SDK.
+
+## Overview
+
+This guide shows how to:
+- Register a community
+- Manage members with SBTs
+- Configure reputation systems
+- Deploy community tokens
+- Set up gas sponsorship
+
+---
+
+## Prerequisites
+
+- Community admin account
+- Basic understanding of DAOs
+- Testnet ETH for transactions
+
+---
+
+## Step 1: Register Community
+
+```typescript
+import { createCommunityClient } from '@aastar/core';
+import { http } from 'viem';
+import { sepolia } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const community = createCommunityClient({
+  chain: sepolia,
+  transport: http(process.env.RPC_URL),
+  account: privateKeyToAccount(process.env.COMMUNITY_KEY),
+});
+
+// Register community
+const txHash = await community.registerCommunity({
+  name: 'DevDAO',
+  metadata: 'ipfs://QmCommunityMetadata...',
+});
+
+console.log('Community registered:', txHash);
+```
+
+---
+
+## Step 2: Deploy Community Token
+
+```typescript
+import { parseEther } from 'viem';
+
+const tokenAddress = await community.deployXPNTs({
+  name: 'DevDAO Points',
+  symbol: 'DDP',
+  initialSupply: parseEther('1000000'),
+});
+
+console.log('Token deployed at:', tokenAddress);
+```
+
+---
+
+## Step 3: Configure Reputation System
+
+```typescript
+await community.setReputationRules({
+  rules: [
+    { metric: 'code_contributions', weight: 40 },
+    { metric: 'community_engagement', weight: 30 },
+    { metric: 'governance_participation', weight: 30 },
+  ],
+});
+```
+
+---
+
+## Step 4: Manage Members
+
+```typescript
+// Mint membership SBT
+await community.mintSBT({
+  to: memberAddress,
+  tokenId: 1n,
+  metadata: 'ipfs://QmMembershipBadge...',
+});
+
+// Distribute points
+import { mintXPNTs } from '@aastar/tokens';
+
+await mintXPNTs(community, memberAddress, parseEther('100'));
+```
+
+---
+
+## Complete Example
+
+```typescript
+async function setupCommunity() {
+  const community = createCommunityClient({...});
+
+  // 1. Register
+  await community.registerCommunity({
+    name: 'DevDAO',
+    metadata: 'ipfs://...',
+  });
+
+  // 2. Deploy token
+  const tokenAddress = await community.deployXPNTs({
+    name: 'DevDAO Points',
+    symbol: 'DDP',
+    initialSupply: parseEther('1000000'),
+  });
+
+  // 3. Set reputation rules
+  await community.setReputationRules({
+    rules: [
+      { metric: 'contributions', weight: 50 },
+      { metric: 'engagement', weight: 50 },
+    ],
+  });
+
+  // 4. Onboard members
+  const members = ['0x...', '0x...'];
+  for (const member of members) {
+    await community.mintSBT({ to: member, tokenId: 1n });
+    await mintXPNTs(community, member, parseEther('100'));
+  }
+
+  console.log('Community setup complete!');
+}
+```
+
+---
+
+## Related
+
+- [Community API](/api/roles/community)
+- [Tokens Module](/api/modules/tokens)
+- [Identity Module](/api/modules/identity)

package/docs/guide/use-cases/gasless-transactions.md

@@ -0,0 +1,71 @@
+# Gasless Transactions Guide
+
+Complete guide for implementing gasless transactions with SuperPaymaster.
+
+## Overview
+
+Enable users to send transactions without holding ETH for gas fees.
+
+---
+
+## Prerequisites
+
+- User has community SBT
+- Community has gas sponsorship enabled
+- User within credit limit
+
+---
+
+## Implementation
+
+```typescript
+import { createEndUserClient } from '@aastar/core';
+import { getPaymasterAndData, checkEligibility } from '@aastar/paymaster';
+
+async function sendGaslessTransaction() {
+  const user = createEndUserClient({...});
+
+  // 1. Check eligibility
+  const eligible = await checkEligibility(
+    user.account.address,
+    communityAddress,
+    process.env.RPC_URL
+  );
+
+  if (!eligible) {
+    throw new Error('Not eligible');
+  }
+
+  // 2. Check credit
+  const credit = await user.getCreditLimit();
+  console.log('Credit:', formatEther(credit));
+
+  // 3. Create UserOperation
+  const userOp = {...};
+
+  // 4. Get paymaster data
+  const paymasterAndData = getPaymasterAndData(userOp, {
+    paymasterAddress: CONTRACTS.sepolia.superPaymaster,
+    communityAddress,
+    xPNTsAddress: CONTRACTS.sepolia.xPNTsToken,
+    verificationGasLimit: 100000n,
+    postOpGasLimit: 50000n,
+  });
+
+  // 5. Submit
+  const txHash = await submitUserOperation({
+    ...userOp,
+    paymasterAndData,
+  });
+
+  console.log('Gasless TX:', txHash);
+}
+```
+
+---
+
+## Related
+
+- [End User API](/api/roles/enduser)
+- [Paymaster Module](/api/modules/paymaster)
+- [SuperPaymaster Concept](/guide/concepts/superpaymaster)