@aastar/sdk 0.16.8 → 0.16.11

package/docs/DOCUMENTATION_PLAN.md

@@ -0,0 +1,455 @@
+# 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)。

package/docs/ENV_SEPOLIA_UPDATE.md

@@ -0,0 +1,68 @@
+# .env.sepolia Configuration Update
+
+## Summary
+Cleaned and updated `.env.sepolia` with latest Sepolia deployment addresses from `SuperPaymaster/script/v3/config/deployed.json`.
+
+## Key Changes
+
+### Removed Duplicates
+- Removed old/duplicate contract addresses (e.g., multiple GTOKEN_ADDRESS entries)
+- Consolidated to single source of truth
+
+### Latest Contract Addresses
+
+#### Paymaster Contracts
+- **PaymasterV4 Proxy**: `0x0F9019Dd30C7Cc5774d4883fba933aA0Caba9424`
+- **PaymasterV4 Implementation**: `0x720472c8ce72c2A2D711333e064ABD3E6BbEAdd3`
+- **SuperPaymaster**: `0x86A2EE8FAf9A840F7a2c64CA3d51209F9A02081D`
+- **Paymaster Factory**: `0x5c74c94173F05dA1720953407cbb920F3DF9f887`
+
+#### Core Contracts
+- **GToken**: `0xfbC22278A96299D91d41C453234d97b4F5Eb9B2d`
+- **Staking**: `0xC9a43158891282A2B1475592D5719c001986Aaec`
+- **Registry**: `0x367761085BF3C12e5DA2Df99AC6E1a824612b8fb`
+- **MySBT**: `0x1c85638e118b37167e9298c2268758e058DdfDA0`
+- **ReputationSystem**: `0xCace1b78160AE76398F486c8a18044da0d66d86D`
+
+#### Token Contracts
+- **aPNTs**: `0x49fd2BE640DB2910c2fAb69bB8531Ab6E76127ff`
+- **xPNTs Factory**: `0xA4899D35897033b927acFCf422bc745916139776`
+
+#### EntryPoint & Validators
+- **EntryPoint V0.7**: `0x2B0d36FACD61B71CC05ab8F3D2355ec3631C0dd5`
+- **BLS Aggregator**: `0xF8e31cb472bc70500f08Cd84917E5A1912Ec8397`
+- **DVT Validator**: `0xD5ac451B0c50B9476107823Af206eD814a2e2580`
+
+#### SimpleAccount Factory
+- **Factory**: `0x4b6aB5F819A515382B0dEB6935D793817bB4af28`
+
+### Test Account Configuration
+- **TEST_SIMPLE_ACCOUNT_A**: `0x11595E52131Ffd571ce5e00C44472FBf94c99937`
+  - ✅ Has PIM tokens deposited
+  - ✅ Ready for Pimlico paymaster tests
+- **TEST_OWNER_EOA_A**: `0xda7f83CafAe1b76Bd4446a4aB2B8e88770CfA927`
+- **TEST_OWNER_KEY_A**: (stored in .env.sepolia)
+
+### Bundler RPC Configuration
+- **Primary RPC**: `SEPOLIA_RPC_URL` (Alchemy)
+- **Bundler RPC**: `SEPOLIA_RPC_URL2` (Alchemy bundler endpoint)
+  - Used for AA UserOp submission
+
+## For Experiment Runner
+
+The experiment runner now uses:
+1. **PAYMASTER_ADDRESS**: `0x0F9019Dd30C7Cc5774d4883fba933aA0Caba9424` (PaymasterV4 Proxy)
+2. **SUPERPAYMASTER_ADDRESS**: `0x86A2EE8FAf9A840F7a2c64CA3d51209F9A02081D`
+3. **SEPOLIA_RPC_URL2**: Alchemy bundler RPC for Groups 3 & 4
+
+## Next Steps
+Run the experiment runner to test all 4 groups:
+```bash
+pnpm tsx scripts/19_sdk_experiment_runner.ts
+```
+
+Expected results:
+- ✅ Group 1 (EOA): Should pass
+- ✅ Group 2 (Pimlico): Should pass with PIM tokens
+- ✅ Group 3 (AOA/PaymasterV4): Should pass with new address
+- ✅ Group 4 (SuperPaymaster): Should pass with new address