@aastar/sdk 0.16.8 → 0.16.11

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 文件来集成这些工具。

package/docs/guide/TEST_COMMANDS.md

@@ -0,0 +1,320 @@
+# 🚀 AAStar SDK 测试命令完整指南
+
+本文档提供所有测试命令的详细说明，包括如何在不同网络间切换。
+
+---
+
+## 📋 快速参考
+
+### 主要测试命令
+
+| 命令 | 用途 | 网络依赖 | 时间 |
+|------|------|---------|------|
+| `pnpm run test:full_anvil` | 完整协议回归（72场景） | Anvil专用 | 5-10分钟 |
+| `pnpm run test:full_sdk` | SDK功能验证（6场景） | **任意网络** | ~30秒 |
+| `pnpm run test:init` | 环境初始化 | Anvil | ~2分钟 |
+
+---
+
+## 🌐 网络切换指南（适用于 `test:full_sdk`）
+
+`test:full_sdk` 可以在任意EVM网络上运行，只需修改配置文件：
+
+### 方法1: 使用不同的 `.env` 文件
+
+#### 步骤1: 创建网络专用配置文件
+
+```bash
+# Sepolia测试网配置
+cp .env.v3 .env.sepolia
+
+# Mainnet配置
+cp .env.v3 .env.mainnet
+```
+
+#### 步骤2: 编辑配置文件
+
+**`.env.sepolia` 示例**:
+```bash
+# 网络RPC
+RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
+
+# 管理员私钥（请从加密存储中读取，不要硬编码！）
+ADMIN_KEY=0x...
+
+# Sepolia上的合约地址
+REGISTRY_ADDRESS=0x1234...
+GTOKEN_ADDRESS=0x5678...
+GTOKEN_STAKING_ADDRESS=0x9abc...
+SUPER_PAYMASTER_ADDRESS=0xdef0...
+APNTS_ADDRESS=0x1111...
+MYSBT_ADDRESS=0x2222...
+```
+
+**`.env.mainnet` 示例**:
+```bash
+# Mainnet RPC
+RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
+
+# 管理员私钥
+ADMIN_KEY=0x...
+
+# Mainnet合约地址
+REGISTRY_ADDRESS=0xMainnetRegistry...
+GTOKEN_ADDRESS=0xMainnetGToken...
+GTOKEN_STAKING_ADDRESS=0xMainnetStaking...
+SUPER_PAYMASTER_ADDRESS=0xMainnetPaymaster...
+APNTS_ADDRESS=0xMainnetAPNTs...
+MYSBT_ADDRESS=0xMainnetSBT...
+```
+
+#### 步骤3: 运行测试时指定配置
+
+修改 `scripts/99_final_v2_regression.ts` 第26行：
+
+```typescript
+// 默认（Anvil本地）
+dotenv.config({ path: path.resolve(process.cwd(), '.env.v3') });
+
+// 切换到Sepolia
+dotenv.config({ path: path.resolve(process.cwd(), '.env.sepolia') });
+
+// 切换到Mainnet
+dotenv.config({ path: path.resolve(process.cwd(), '.env.mainnet') });
+```
+
+---
+
+### 方法2: 使用环境变量覆盖（推荐）
+
+无需修改代码，直接在命令行传递参数：
+
+```bash
+# Sepolia测试
+RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY \
+ADMIN_KEY=0xYourKey \
+REGISTRY_ADDRESS=0x... \
+pnpm run test:full_sdk
+
+# Mainnet测试（只读操作）
+RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY \
+ADMIN_KEY=0xYourKey \
+REGISTRY_ADDRESS=0x... \
+pnpm run test:full_sdk
+```
+
+---
+
+### 方法3: 创建网络专用脚本（最佳实践）
+
+在 `package.json` 中添加：
+
+```json
+{
+  "scripts": {
+    "test:sdk:sepolia": "dotenv -e .env.sepolia -- tsx scripts/99_final_v2_regression.ts",
+    "test:sdk:mainnet": "dotenv -e .env.mainnet -- tsx scripts/99_final_v2_regression.ts"
+  }
+}
+```
+
+然后安装 `dotenv-cli`:
+```bash
+pnpm add -D dotenv-cli
+```
+
+使用：
+```bash
+pnpm run test:sdk:sepolia
+pnpm run test:sdk:mainnet
+```
+
+---
+
+## 📝 详细命令说明
+
+### 1. **完整协议回归测试** - `test:full_anvil`
+
+```bash
+pnpm run test:full_anvil
+```
+
+**特点**:
+- 🔄 自动重启Anvil（干净状态）
+- 📦 自动部署所有合约
+- 🔄 自动同步配置和ABI
+- 🧪 运行17个独立测试脚本
+- ⚠️ **仅支持Anvil**（使用 `anvil_setBalance`, `anvil_impersonateAccount` 等特殊功能）
+
+**覆盖范围**:
+- 72个完整场景
+- 95%分支覆盖率
+- 包含所有协议功能（Admin、Staking、Slashing、Credit、DVT、SBT等）
+
+**适用场景**:
+- 本地开发验证
+- CI/CD集成测试
+- 完整功能回归
+
+---
+
+### 2. **SDK功能验证** - `test:full_sdk`
+
+```bash
+pnpm run test:full_sdk
+```
+
+**特点**:
+- 🌐 **支持任意EVM网络**（Anvil/Sepolia/Mainnet）
+- 🚀 快速执行（~30秒）
+- 🔍 验证SDK核心架构
+- ✅ 自动初始化（检测Anvil，自动运行 `test:init`）
+
+**测试场景** (6个核心):
+1. ✅ Operator Staking (质押)
+2. ✅ Paymaster Deposit (存款-Push模式)
+3. ✅ Community Registration (社区注册)
+4. ✅ SBT Minting (SBT铸造)
+5. ✅ Admin Slashing (惩罚)
+6. ✅ Credit Query (信用查询)
+
+**网络切换**: 参见上方 [🌐 网络切换指南](#🌐-网络切换指南（适用于-test_full_sdk）)
+
+---
+
+### 3. **环境初始化** - `test:init`
+
+```bash
+pnpm run test:init
+```
+
+**功能**:
+- 重启Anvil节点
+- 部署所有合约到本地
+- 提取ABI到 `packages/core/src/abis/`
+- 同步配置到 `.env.v3`
+
+**用途**:
+- 手动调试前的环境准备
+- 合约更新后重新部署
+
+---
+
+### 4. **专项测试命令**
+
+#### 协议管理测试
+```bash
+pnpm run test:admin
+```
+测试角色配置、费用设置、暂停等管理功能。
+
+#### 信用系统测试
+```bash
+pnpm run test:credit
+```
+测试信用限额、债务跟踪、自动还款。
+
+#### 重入攻击测试
+```bash
+pnpm run test:reentrancy
+```
+测试重入保护机制。
+
+---
+
+## 🔧 常见问题排查
+
+### 问题1: SDK测试失败，提示 "Contract not found"
+
+**原因**: 合约地址在目标网络上不存在
+
+**解决**:
+```bash
+# 1. 检查.env配置
+cat .env.v3
+
+# 2. 验证合约是否部署
+cast code $REGISTRY_ADDRESS --rpc-url $RPC_URL
+
+# 3. 如果未部署，需先部署合约（Sepolia/Mainnet）
+cd ../SuperPaymaster
+forge script script/v3/DeployV3Sepolia.s.sol --rpc-url $SEPOLIA_RPC --broadcast
+```
+
+### 问题2: RPC速率限制
+
+**解决**: 使用付费RPC节点（Alchemy/Infura）或降低并发：
+
+```typescript
+// 在测试脚本中添加延迟
+await new Promise(resolve => setTimeout(resolve, 1000)); // 1秒延迟
+```
+
+### 问题3: Gas不足（Sepolia/Mainnet）
+
+**解决**: 确保测试账户有足够ETH：
+
+```bash
+# 查看余额
+cast balance $ADMIN_ADDRESS --rpc-url $RPC_URL
+
+# Sepolia水龙头
+# https://sepoliafaucet.com/
+# https://www.alchemy.com/faucets/ethereum-sepolia
+```
+
+---
+
+## 📊 测试覆盖率对比
+
+| 测试套件 | 场景数 | 分支覆盖 | 网络支持 | 执行时间 |
+|---------|-------|---------|---------|---------|
+| `test:full_anvil` | 72 | 95% | Anvil | 5-10分钟 |
+| `test:full_sdk` | 6 | SDK核心 | **任意** | ~30秒 |
+| 专项测试 | 1-5/个 | 特定功能 | 视情况 | 10-60秒 |
+
+---
+
+## 🎯 推荐工作流
+
+### 本地开发
+```bash
+# 1. 启动环境
+pnpm run test:init
+
+# 2. 快速SDK验证
+pnpm run test:full_sdk
+
+# 3. 完整回归（发版前）
+pnpm run test:full_anvil
+```
+
+### 测试网验证
+```bash
+# 1. 配置Sepolia环境
+cp .env.v3 .env.sepolia
+# 编辑 .env.sepolia，填入Sepolia合约地址
+
+# 2. 运行SDK测试
+dotenv -e .env.sepolia -- pnpm run test:full_sdk
+```
+
+### 生产环境只读验证
+```bash
+# 仅查询，不执行交易
+RPC_URL=https://eth-mainnet.g.alchemy.com/v2/KEY \
+REGISTRY_ADDRESS=0xMainnetAddr \
+pnpm run test:full_sdk
+```
+
+---
+
+## 🔗 相关资源
+
+- **SDK开发指南**: [`README.md`](../README.md)
+- **合约部署**: [`../SuperPaymaster/README.md`](../../SuperPaymaster/README.md)
+- **架构设计**: [`docs/task_breakdown.md`](./task_breakdown.md)
+
+---
+
+**由 AAStarCommunity 维护 | 最后更新: 2025-12-24**

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" 章節中說明。