@aastar/sdk 0.14.0 → 0.16.6

package/docs/guide/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/guide/Security-solution.md

@@ -0,0 +1,106 @@
+除了 `pnpm audit`（主要针对已知 CVE 漏洞），一个健壮的 npm/TypeScript 项目还需要在**供应链安全**、**代码静态分析**、**密钥管理**和**CI/CD 集成**这几个维度建立防线。
+
+针对你作为资深开发者的背景（Web3/Rust/Node），以下是更进阶的**最佳实践和工具推荐**：
+
+### 1. 供应链安全防御 (Supply Chain Security)
+
+`pnpm audit` 只能告诉你依赖包有没有“已知漏洞”，但无法检测**恶意代码注入**（如 typosquatting 或被劫持的包）。
+
+* **Socket.dev (强烈推荐)**
+* **作用：** 它不仅检查 CVE，还分析包的“行为”。比如：一个 UI 库突然开始读取环境变量或发送网络请求，Socket 会报警。
+* **集成：** 有 GitHub App，也可以作为 CLI 运行。它能拦截包含恶意 install script 的包。
+
+
+* **OSSF Scorecard**
+* **作用：** Google 开源的工具，给依赖项打分。它会检查维护状态、是否有 CI、是否进行代码审查等，帮助你判断引入一个库是否“健康”。
+
+
+* **Lockfile 锁定**
+* **实践：** 在 CI/CD 环境中必须使用 `pnpm install --frozen-lockfile`。这确保了 CI 构建使用的版本与你本地完全一致，防止在构建时悄悄拉取了被篡改的补丁版本。
+
+
+
+### 2. 静态代码分析 (SAST)
+
+利用工具在代码运行前发现逻辑漏洞。
+
+* **ESLint Security Plugins**
+* 不要只用标准的 lint 规则，需添加安全专用插件：
+* `eslint-plugin-security`: 识别潜在的热点（如正则表达式 DoS 攻击 ReDoS、不安全的 `eval` 等）。
+* `eslint-plugin-no-secrets`: 防止意外提交密钥。
+
+
+* **CodeQL (GitHub Native)**
+* **作用：** 如果你的项目在 GitHub 上，开启 **Code Scanning**。CodeQL 是一种语义代码分析引擎，能发现数据流中的漏洞（如 SQL 注入、NoSQL 注入、XSS），比正则匹配更深入。
+
+
+* **SonarQube / SonarCloud**
+* 企业级的代码质量和安全扫描，对于 TypeScript 的支持非常好，能发现复杂的逻辑漏洞（Code Smells）。
+
+
+
+### 3. TypeScript 专有安全配置
+
+TypeScript 本身就是第一道防线，但需要正确配置：
+
+* **启用 `strict: true**`
+* 这是基础。除此之外，开启 `noImplicitAny` 和 `strictNullChecks` 可以消除绝大多数 `undefined` 导致的运行时崩溃（DoS 风险）。
+
+
+* **避免类型断言 (`as`) 和 `any**`
+* 使用 `zod` 或 `io-ts` 进行**运行时数据验证 (Runtime Validation)**。不要盲目相信 API 返回的数据就是 TS 定义的类型。
+* **Bad:** `const data = await res.json() as User;`
+* **Good:** `const data = UserSchema.parse(await res.json());` (这在 Web3 数据处理中尤为重要，防止恶意构造的 Payload 导致逻辑错误)。
+
+
+
+### 4. 脚本与权限控制 (Scripts & Permissions)
+
+npm 的 `postinstall` 脚本是恶意软件最常见的入侵途径。
+
+* **禁用 Install Scripts**
+* 在 `.npmrc` 中设置 `ignore-scripts=true`。
+* 如果是必须运行脚本的依赖（如 `husky`, `esbuild`），使用 `pnpm approve-builds` (pnpm 特有功能) 或 `allow-scripts` 插件来**白名单**放行特定包。
+
+
+* **LavaMoat (进阶)**
+* 由 MetaMask 团队开发（很适合你的背景）。它可以为每个 npm 包生成策略文件，限制某个包只能访问 `fs` 模块，或者只能访问特定的全局变量。
+
+
+
+### 5. 密钥与硬编码扫描
+
+Web3 项目最怕泄露私钥或 API Key。
+
+* **GitGuardian / TruffleHog**
+* **作用：** 在 commit 之前（pre-commit hook）或 CI 阶段扫描代码库，寻找像 AWS Key、Private Key、Infura Key 这种高熵字符串。
+
+
+* **Dotenv 最佳实践**
+* 强制将 `.env` 加入 `.gitignore`。
+* 使用 `dotenv-safe` 或 `envalid` 库，在应用启动时校验必要的环境变量是否存在且符合格式，否则直接报错退出。
+
+
+
+### 6. 自动化依赖更新 (Bot)
+
+* **Renovate Bot (优于 Dependabot)**
+* 相比 Dependabot，Renovate 配置更灵活。你可以设置策略：补丁版本(Patch)自动合并，次要版本(Minor)需人工 Review。保持依赖最新可以大大减少被利用已知漏洞的窗口期。
+
+
+
+### 总结：一份推荐的 CI/CD 安全检查清单
+
+在你的 GitHub Actions / GitLab CI 中，建议包含以下步骤：
+
+1. **Checkout**
+2. **Secret Scan:** 运行 `trufflehog` 检查本次 commit 是否包含密钥。
+3. **Dependency Integrity:** `pnpm install --frozen-lockfile --ignore-scripts`。
+4. **SCA Scan:** 运行 `socket` (Socket.dev) 或 `snyk test` 检查依赖风险。
+5. **Linting:** `pnpm lint` (包含 `eslint-plugin-security`)。
+6. **Build:** 确保构建成功（利用 TS 类型检查）。
+7. **Test:** 单元测试覆盖核心业务逻辑。
+
+### 下一步
+
+如果你对 **Socket.dev** 或 **LavaMoat** 感兴趣，我可以为你提供一个具体的配置示例，或者帮你写一个 GitHub Action 的 workflow 文件来集成这些工具。