@aastar/sdk 0.14.3 → 0.16.8

package/docs/api/README.md

@@ -1,6 +0,0 @@
-## Packages
-
-- [@aastar/account](@aastar/account/README.md)
-- [@aastar/core](@aastar/core/README.md)
-- [@aastar/paymaster](@aastar/paymaster/README.md)
-- [@aastar/tokens](@aastar/tokens/README.md)

package/docs/examples/community-flow.md

@@ -1,28 +0,0 @@
-# Community Flow Example
-
-This example demonstrates how to manage a community, issue SBTs, and configure reputation.
-
-## Steps
-
-1. **Registration**: Register your community name and metadata on-chain.
-2. **SBT Issuance**: Mint Soul-Bound Tokens to members to define their roles.
-3. **Reputation Setup**: Define rules that calculate member reputation based on activity.
-
-## Code Preview
-
-```typescript
-import { createCommunityClient } from '@aastar/core';
-
-const community = createCommunityClient({ ... });
-
-// Register Community
-await community.registerCommunity({
-  name: 'Alpha DAO',
-});
-
-// Mint SBT
-await community.mintSBT({
-  to: memberAddress,
-  tokenId: 1n,
-});
-```

package/docs/examples/enduser-flow.md

@@ -1,24 +0,0 @@
-# End User Flow Example
-
-This example demonstrates how an end user sends a gasless transaction using community credit.
-
-## Steps
-
-1. **Eligibility Check**: Verify the user has sufficient reputation or SBTs to use community sponsorship.
-2. **UserOperation Construction**: Create a signed UserOperation targeting a dapp contract.
-3. **Paymaster Sponsorship**: Request the SuperPaymaster to sign the UserOperation for gasless execution.
-
-## Code Preview
-
-```typescript
-import { createEndUserClient } from '@aastar/core';
-
-const user = createEndUserClient({ ... });
-
-// Send Gasless Transaction
-const hash = await user.sendTransaction({
-  to: dappAddress,
-  data: callData,
-  communityAddress: '0x...', // Community to sponsor gas
-});
-```

package/docs/examples/index.md

@@ -1,18 +0,0 @@
-# Complete Examples Overview
-
-This section contains complete, end-to-end examples of how to use the AAStar SDK for various roles and use cases.
-
-## Available Examples
-
-- **[Operator Flow](./operator-flow)**: Staking and managing a SuperPaymaster.
-- **[Community Flow](./community-flow)**: Registering a community and setting up reputation rules.
-- **[End User Flow](./enduser-flow)**: Sending gasless transactions using community credit.
-- **[Multi-Chain Setup](./multi-chain)**: Configuring and using the SDK across different networks.
-
-## Running Examples Locally
-
-Most examples can be run against a local Anvil instance. Ensure you have the [AAStar Contracts](https://github.com/AAStarCommunity/SuperPaymaster) deployed locally first.
-
-```bash
-pnpm run example:local
-```

package/docs/examples/multi-chain.md

@@ -1,31 +0,0 @@
-# Multi-Chain Setup Example
-
-This example demonstrates how to configure and switch between different networks using the AAStar SDK.
-
-## Supported Networks
-
-- **Ethereum Sepolia**: Recommended for testing.
-- **Optimism**: Low cost production environment.
-- **Anvil**: Local development and rapid prototyping.
-
-## Code Preview
-
-```typescript
-import { createPublicClient, http } from 'viem';
-import { sepolia, optimism } from 'viem/chains';
-import { getNetwork } from '@aastar/core';
-
-// Switch to Sepolia
-const sepoliaConfig = getNetwork('sepolia');
-const sepoliaClient = createPublicClient({
-  chain: sepolia,
-  transport: http(sepoliaConfig.rpcUrl),
-});
-
-// Switch to Optimism
-const opConfig = getNetwork('optimism');
-const opClient = createPublicClient({
-  chain: optimism,
-  transport: http(opConfig.rpcUrl),
-});
-```

package/docs/examples/operator-flow.md

@@ -1,28 +0,0 @@
-# Operator Flow Example
-
-This example demonstrates how to set up and manage a SuperPaymaster as an Operator.
-
-## Steps
-
-1. **Staking**: Deposit GTokens into the staking contract to become an authorized operator.
-2. **Paymaster Deposit**: Add ETH or other tokens to the SuperPaymaster's deposit pool for gas sponsorship.
-3. **Monitoring**: Track gas usage and reputation metrics.
-
-## Code Preview
-
-```typescript
-import { createOperatorClient } from '@aastar/core';
-import { parseEther } from 'viem';
-
-const operator = createOperatorClient({ ... });
-
-// Stake GTokens
-await operator.stake({
-  amount: parseEther('100'),
-});
-
-// Deposit Gas Funds
-await operator.deposit({
-  amount: parseEther('10'),
-});
-```

package/docs/guide/CLI_GUIDE.md

@@ -1,65 +0,0 @@
-# SuperPaymaster V3 SDK 测试指南 (CLI)
-
-本文档面向开发者，提供 SuperPaymaster V3 系统在本地 Anvil 环境下的各种测试和初始化命令。
-
-## 🛠 准备工作
-在开始任何测试前，请确保：
-1. 本地 `anvil` 已启动 (`anvil`)。
-2. 位于 `projects/aastar-sdk` 目录。
-3. `.env.v3` 文件存在（如果不存在，运行初始化脚本会自动创建）。
-
----
-
-## 🚀 常用指令集
-
-### 1. 初始化运行 (Init & Setup)
-**场景**: 第一次运行测试，或者 Anvil 重启后需要重新同步合约状态。
-```bash
-./run_full_regression.sh --init-only
-# 或者直接运行全量回归，它会自动包含初始化
-pnpm run test:full
-```
-
-### 2. 快速回归测试 (Fast Test / Pre-commit)
-**场景**: 日常开发中，快速验证核心安全逻辑（权限检查、影子账户等）。这也集成在 Git Pre-commit Hook 中。
-```bash
-pnpm run test:fast
-```
-*运行脚本: `scripts/99_bug_hunting_fast.ts`*
-
-### 3. 全量场景回归 (Full Regression)
-**场景**: 发布前验收，验证全部 72 个真实业务场景。包括重新部署、同步配置和运行所有核心测试脚本。
-```bash
-pnpm run test:full
-```
-*包含脚本: 01, 06, 08, 09, 10, 11, 12, 13, 14, 98, 99 系列*
-
-### 4. 特定模块测试 (Module Specific)
-如果你只想测试某个特定模块，可以使用以下快捷命令：
-
-- **核心管理流程 (Registry/Admin)**:
-  ```bash
-  pnpm run test:admin
-  ```
-- **信用与还款系统**:
-  ```bash
-  pnpm run test:credit
-  ```
-- **安全与重入攻击**:
-  ```bash
-  pnpm run test:reentrancy
-  ```
-
----
-
-## 📊 测试报告解析
-测试完成后，你会看到一个统一的报告。
-
-> [!IMPORTANT]
-> **报喜也报忧**: 我们的测试套件会截获每个脚本的内部 Revert。如果脚本输出中包含 "reverted" 或 "Error"，即便脚本没退出，回归套件也会将其标记为 **FAILED**。
-
----
-
-## 🔍 故障排查
-- **Panic: Allocated too much memory**: 这是 Anvil 在处理复杂 `roleData` 时的已知限制。如果遇到此错误，请尝试减小 `roleData` 中的字符串长度或清空 Anvil 重新运行。
-- **DepositNotVerified**: 确保在调用 `notifyDeposit` 前，对应账户已向 Paymaster 合约转入足够的 aPNTs 代币。

package/docs/guide/DOCUMENTATION_PLAN.md

@@ -1,455 +0,0 @@
-# AAStar SDK 文档生成和发布方案
-
-## 概述
-
-本文档定义了AAStar SDK的完整文档生成、维护和发布流程。
-
----
-
-## 1. 技术栈选择
-
-### 推荐方案: VitePress
-
-**优势**:
-- ⚡ 基于Vite,构建速度极快
-- 📝 原生Markdown支持
-- 🎨 Vue组件集成
-- 🔍 内置全文搜索
-- 📱 响应式设计
-- 🚀 零配置部署到GitHub Pages/Vercel
-
-**替代方案**: Docusaurus (React生态)
-
----
-
-## 2. 仓库架构
-
-### 2.1 SDK仓库 (`aastar-sdk`)
-
-```
-aastar-sdk/
-├── packages/                    # SDK源码
-│   ├── core/
-│   ├── account/
-│   ├── paymaster/
-│   └── ...
-├── docs/                        # 文档源文件
-│   ├── guide/                   # 手写指南
-│   │   ├── getting-started.md
-│   │   ├── concepts.md
-│   │   └── use-cases/
-│   │       ├── community-management.md
-│   │       ├── gasless-transactions.md
-│   │       └── operator-staking.md
-│   ├── api/                     # 自动生成的API文档
-│   │   ├── core.md
-│   │   ├── account.md
-│   │   └── ...
-│   └── examples/                # 完整示例
-│       ├── operator-flow.md
-│       ├── community-flow.md
-│       └── enduser-flow.md
-├── scripts/
-│   ├── generate-api-docs.ts    # API文档生成脚本
-│   └── sync-to-docs-repo.sh    # 同步到文档仓库
-└── package.json
-```
-
-### 2.2 文档仓库 (`aastar-docs`)
-
-```
-aastar-docs/
-├── .vitepress/
-│   ├── config.ts               # VitePress配置
-│   ├── theme/                  # 自定义主题
-│   └── components/             # Vue组件
-├── public/                     # 静态资源
-│   ├── logo.svg
-│   └── images/
-├── index.md                    # 首页
-├── guide/                      # 从SDK repo同步
-├── api/                        # 从SDK repo同步
-├── examples/                   # 从SDK repo同步
-└── package.json
-```
-
----
-
-## 3. 自动化工作流
-
-### 3.1 API文档自动生成
-
-使用 **TypeDoc** 或 **API Extractor** 从TypeScript源码提取API文档。
-
-**脚本**: `scripts/generate-api-docs.ts`
-
-```typescript
-import { Application } from 'typedoc';
-
-async function generateAPIDocs() {
-  const app = new Application();
-  
-  app.options.addReader(new TypeDocReader());
-  app.bootstrap({
-    entryPoints: ['packages/*/src/index.ts'],
-    out: 'docs/api',
-    plugin: ['typedoc-plugin-markdown'],
-  });
-
-  const project = app.convert();
-  await app.generateDocs(project, 'docs/api');
-}
-```
-
-### 3.2 文档同步流程
-
-文档同步使用 `scripts/extract-docs.sh` 腳本，手動調用命令為 `pnpm run docs:sync`。
-
-**流程**:
-1. 在 `aastar-sdk` 運行 `pnpm run docs:generate` 生成最新 API 文檔。
-2. 運行 `pnpm run docs:sync` 將 `docs/` 文件夾內容同步到 `aastar-docs`。
-3. 同步過程會保持相同的目錄結構 (`guide/`, `api/`, `examples/`)。
-
-**Shell 腳本核心邏輯**:
-\`\`\`bash
-# 同步 Guide
-cp -r "$SDK_REPO/docs/guide/"* "$DOCS_REPO/guide/"
-# 同步 API
-cp -r "$SDK_REPO/docs/api/"* "$DOCS_REPO/api/"
-# 同步 Examples
-cp -r "$SDK_REPO/docs/examples/"* "$DOCS_REPO/examples/"
-\`\`\`
-
-
-
-### 3.3 文档站点部署
-
-Use docs repo shell to deploy.
----
-
-## 4. 文档结构设计
-
-### 4.1 首页 (index.md)
-
-```markdown
-# AAStar SDK
-
-> Build Your Own Protocol (YOP) with Account Abstraction
-
-## Features
-- 🚀 Gasless Transactions (SuperPaymaster AOA+)
-- 🌈 EOA Rainbow Bridge
-- 🏛️ Community Management
-- 🎯 Reputation System
-
-## Quick Start
-[Get Started →](/guide/getting-started)
-```
-
-### 4.2 指南结构
-
-```
-guide/
-├── index.md                    # 指南概览
-├── getting-started.md          # 快速开始
-├── concepts/
-│   ├── account-abstraction.md
-│   ├── superpaymaster.md
-│   └── reputation-system.md
-├── use-cases/
-│   ├── community-management.md
-│   ├── gasless-transactions.md
-│   ├── operator-staking.md
-│   └── rainbow-bridge.md
-└── advanced/
-    ├── custom-paymaster.md
-    └── multi-chain.md
-```
-
-### 4.3 API文档结构 (按角色组织)
-
-```
-api/
-├── index.md                    # API概览
-├── roles/
-│   ├── operator.md             # Operator角色API
-│   ├── community.md            # Community角色API
-│   ├── enduser.md              # EndUser角色API
-│   └── admin.md                # Admin角色API
-├── modules/
-│   ├── core.md                 # Core模块
-│   ├── account.md              # Account模块
-│   ├── paymaster.md            # Paymaster模块
-│   ├── tokens.md               # Tokens模块
-│   └── identity.md             # Identity模块
-└── types/
-    ├── common.md               # 通用类型
-    └── errors.md               # 错误类型
-```
-
----
-
-## 5. API文档模板
-
-### 5.1 模块文档模板
-
-```markdown
-# @aastar/core
-
-Core configuration and client creation utilities.
-
-## Installation
-
-\`\`\`bash
-pnpm add @aastar/core
-\`\`\`
-
-## Exports
-
-- [Networks](#networks)
-- [Contracts](#contracts)
-- [Clients](#clients)
-- [Constants](#constants)
-
----
-
-## Networks
-
-### getNetwork()
-
-Get network configuration for a supported network.
-
-**Signature:**
-\`\`\`typescript
-function getNetwork(network: SupportedNetwork): NetworkConfig
-\`\`\`
-
-**Parameters:**
-| Name | Type | Description |
-|------|------|-------------|
-| network | `SupportedNetwork` | Network name ('sepolia' \| 'optimism' \| 'anvil') |
-
-**Returns:**
-| Type | Description |
-|------|-------------|
-| `NetworkConfig` | Network configuration object |
-
-**Type Definitions:**
-\`\`\`typescript
-type SupportedNetwork = 'sepolia' | 'optimism' | 'optimism-sepolia' | 'anvil';
-
-interface NetworkConfig {
-  chainId: number;
-  name: string;
-  rpcUrl: string;
-  blockExplorer: string;
-  nativeCurrency: {
-    name: string;
-    symbol: string;
-    decimals: number;
-  };
-}
-\`\`\`
-
-**Example:**
-\`\`\`typescript
-import { getNetwork } from '@aastar/core';
-
-const network = getNetwork('sepolia');
-console.log(network.chainId); // 11155111
-console.log(network.rpcUrl);  // 'https://rpc.sepolia.org'
-\`\`\`
-
-**Errors:**
-- Throws if network is not supported
-
-**See Also:**
-- [getTxUrl()](#gettxurl)
-- [getChainId()](#getchainid)
-```
-
-### 5.2 角色文档模板
-
-```markdown
-# Operator API
-
-API reference for Paymaster operators.
-
-## Overview
-
-Operators are responsible for:
-- Staking GTokens
-- Depositing to Paymaster
-- Managing withdrawals
-- Monitoring performance
-
-## Client Creation
-
-### createOperatorClient()
-
-Create a client for Paymaster operators.
-
-[详细文档...]
-
-## Actions
-
-### stake()
-
-Stake GTokens to become an operator.
-
-**Context:** Use this when you want to register as a Paymaster operator.
-
-**Prerequisites:**
-- Must have GTokens
-- Must approve GTokenStaking contract
-
-**Signature:**
-\`\`\`typescript
-stake(params: StakeParams): Promise<Hash>
-\`\`\`
-
-**Parameters:**
-| Name | Type | Description |
-|------|------|-------------|
-| params.amount | `bigint` | Amount to stake (in wei) |
-
-**Returns:**
-| Type | Description |
-|------|-------------|
-| `Promise<Hash>` | Transaction hash |
-
-**Example:**
-\`\`\`typescript
-import { createOperatorClient } from '@aastar/core';
-import { parseEther } from 'viem';
-
-const operator = createOperatorClient({...});
-
-// Approve first
-await operator.approveGToken({
-  spender: CONTRACTS.sepolia.gTokenStaking,
-  amount: parseEther('100'),
-});
-
-// Then stake
-const txHash = await operator.stake({
-  amount: parseEther('100'),
-});
-\`\`\`
-
-**Errors:**
-- `InsufficientBalance` - Not enough GTokens
-- `InsufficientAllowance` - Need to approve first
-- `MinimumStakeNotMet` - Amount below minimum
-
-**Events Emitted:**
-- `Staked(operator, amount)`
-
-**See Also:**
-- [deposit()](#deposit)
-- [withdraw()](#withdraw)
-```
-
----
-
-## 6. 实施步骤
-
-### Phase 1: 基础设施搭建 (1-2天)
-
-- [ ] 创建`aastar-docs`仓库
-- [ ] 安装VitePress并配置
-- [ ] 设置GitHub Actions自动部署
-- [ ] 配置自定义域名`docs.aastar.io`
-
-### Phase 2: API文档生成 (2-3天)
-
-- [ ] 安装TypeDoc和相关插件
-- [ ] 编写`generate-api-docs.ts`脚本
-- [ ] 为每个模块生成API文档
-- [ ] 添加类型定义和错误说明
-
-### Phase 3: 指南编写 (3-5天)
-
-- [ ] 编写快速开始指南
-- [ ] 编写核心概念文档
-- [ ] 编写用例文档(社区管理、无Gas交易等)
-- [ ] 编写高级主题文档
-
-### Phase 4: 角色文档 (2-3天)
-
-- [ ] 按角色组织API文档
-- [ ] 为每个角色编写完整工作流
-- [ ] 添加实际代码示例
-- [ ] 添加最佳实践
-
-### Phase 5: 自动化和优化 (1-2天)
-
-- [ ] 设置自动同步workflow
-- [ ] 添加文档搜索功能
-- [ ] 优化移动端显示
-- [ ] 添加代码playground (可选)
-
----
-
-## 7. 维护流程
-
-### 日常维护
-
-1. **代码变更时**:
-   - 开发者提交PR
-   - CI自动运行`pnpm run docs:generate`
-   - 检查API文档变更
-   - 合并后自动同步到docs repo
-
-2. **手动文档更新**:
-   - 在SDK repo的`docs/`目录编辑
-   - 提交后自动同步
-
-3. **版本发布**:
-   - 打tag时自动生成版本化文档
-   - 保留历史版本文档
-
-### 质量保证
-
-- [ ] 文档链接检查
-- [ ] 代码示例可运行性测试
-- [ ] TypeScript类型检查
-- [ ] Markdown格式检查
-
----
-
-## 8. 工具和脚本
-
-### package.json scripts
-
-```json
-{
-  "scripts": {
-    "docs:generate": "tsx scripts/generate-api-docs.ts",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "docs:sync": "bash scripts/sync-to-docs-repo.sh"
-  }
-}
-```
-
----
-
-## 9. 参考资源
-
-- [VitePress官方文档](https://vitepress.dev)
-- [TypeDoc文档](https://typedoc.org)
-- [Viem文档](https://viem.sh) (参考其文档结构)
-- [Ethers.js文档](https://docs.ethers.org) (参考其API组织方式)
-
----
-
-## 11. 論文數據採集指南 (PhD Data collection)
-
-詳細指南請參見: [paper-data-collection.md](file:///Users/jason/Dev/mycelium/my-exploration/projects/aastar-sdk/docs/paper-data-collection.md)
-
-**核心要點**:
-- 所有實驗必須使用 `aastar-sdk` 實作。
-- 使用 `run_automated_experiment.sh` 進行自動化運行。
-- 數據採集涵蓋: Gas Usage, Latency, Throughput (TPS), Cost (USD)。