@aastar/sdk 0.14.0 → 0.16.6

package/docs/zh/guide/concepts/account-abstraction.md

@@ -0,0 +1,95 @@
+# Account Abstraction
+
+Understanding Account Abstraction (ERC-4337) in AAStar SDK.
+
+## What is Account Abstraction?
+
+Account Abstraction (AA) allows users to use smart contract wallets instead of traditional Externally Owned Accounts (EOAs). This enables advanced features like:
+
+- **Gasless Transactions**: Users don't need ETH for gas
+- **Social Recovery**: Recover accounts without seed phrases
+- **Session Keys**: Temporary permissions for DApps
+- **Batch Transactions**: Multiple operations in one transaction
+- **Custom Validation**: Flexible signature schemes
+
+## ERC-4337 Overview
+
+ERC-4337 is the standard for Account Abstraction. Key components:
+
+### UserOperation
+
+A pseudo-transaction object that represents a user's intent:
+
+```typescript
+interface UserOperation {
+  sender: Address;           // Smart account address
+  nonce: bigint;            // Anti-replay protection
+  callData: Hex;            // Actual transaction data
+  paymasterAndData: Hex;    // Paymaster info (for gasless tx)
+  signature: Hex;           // User signature
+  // ... gas fields
+}
+```
+
+### EntryPoint
+
+The singleton contract that processes UserOperations.
+
+### Bundler
+
+Off-chain service that bundles UserOperations and submits them to the EntryPoint.
+
+### Paymaster
+
+Contract that sponsors gas fees for users.
+
+## AAStar Implementation
+
+AAStar SDK provides a complete AA infrastructure:
+
+### Smart Accounts
+
+```typescript
+import { createSmartAccount } from '@aastar/account';
+
+const account = await createSmartAccount({
+  owner: ownerAddress,
+  salt: 0n,
+  factoryAddress: CONTRACTS.sepolia.simpleAccountFactory,
+});
+```
+
+### Gasless Transactions
+
+```typescript
+import { createEndUserClient } from '@aastar/core';
+
+const user = createEndUserClient({...});
+
+// Check eligibility
+const eligible = await user.checkEligibility(communityAddress);
+
+if (eligible) {
+  // Send gasless transaction
+  await sendGaslessTransaction();
+}
+```
+
+## Benefits
+
+1. **Better UX**: Users don't need to understand gas or hold ETH
+2. **Security**: Smart contract wallets are more secure than EOAs
+3. **Flexibility**: Custom validation logic and recovery mechanisms
+4. **Programmability**: Wallets can have complex logic
+
+## Learn More
+
+- [ERC-4337 Specification](https://eips.ethereum.org/EIPS/eip-4337)
+- [Account Module API](/api/modules/account)
+- [End User API](/api/roles/enduser)
+
+## Next Steps
+
+- [SuperPaymaster (AOA+)](/guide/concepts/superpaymaster)
+- [Quick Start](/guide/quick-start)
+- [Examples](/examples/)

package/docs/zh/guide/concepts/rainbow-bridge.md

@@ -0,0 +1,68 @@
+# EOA Rainbow Bridge
+
+Seamlessly bridge between traditional EOA wallets and smart contract accounts.
+
+## Overview
+
+The EOA Rainbow Bridge enables users to:
+- Use existing EOA wallets
+- Upgrade to smart accounts
+- Maintain backward compatibility
+- Seamless transition
+
+## How It Works
+
+```
+EOA Wallet → Rainbow Bridge → Smart Account
+     ↓              ↓              ↓
+  Private Key   Ownership     Advanced Features
+```
+
+## Implementation
+
+```typescript
+import { createSmartAccount } from '@aastar/account';
+import { privateKeyToAccount } from 'viem/accounts';
+
+// 1. Start with EOA
+const eoaAccount = privateKeyToAccount(process.env.PRIVATE_KEY);
+
+// 2. Create smart account owned by EOA
+const smartAccount = await createSmartAccount({
+  owner: eoaAccount.address,
+  salt: 0n,
+  factoryAddress: CONTRACTS.sepolia.simpleAccountFactory,
+});
+
+// 3. Use smart account for advanced features
+const user = createEndUserClient({
+  chain: sepolia,
+  transport: http(),
+  account: smartAccount,
+});
+
+// Now user has:
+// - Gasless transactions
+// - Social recovery
+// - Session keys
+// - Batch operations
+```
+
+## Benefits
+
+1. **No Learning Curve**: Users keep their familiar wallets
+2. **Gradual Adoption**: Upgrade when needed
+3. **Best of Both Worlds**: EOA simplicity + smart account features
+4. **Backward Compatible**: Works with existing DApps
+
+## Use Cases
+
+- Onboarding new users
+- Migrating existing users
+- Multi-wallet support
+- Progressive enhancement
+
+## Related
+
+- [Account Module](/api/modules/account)
+- [Account Abstraction](/guide/concepts/account-abstraction)

package/docs/zh/guide/concepts/reputation.md

@@ -0,0 +1,95 @@
+# Reputation System
+
+On-chain reputation tracking with customizable rules and scoring.
+
+## Overview
+
+The Reputation System enables:
+- On-chain reputation tracking
+- Customizable scoring rules
+- Community-specific metrics
+- Credit limit calculation
+
+## Architecture
+
+```
+User Actions → Metrics → Reputation Score → Credit Limit
+```
+
+## Components
+
+### 1. Metrics
+
+Measurable user activities:
+- Code contributions
+- Community engagement
+- Governance participation
+- Transaction history
+
+### 2. Scoring Rules
+
+Community-defined weights:
+
+```typescript
+await community.setReputationRules({
+  rules: [
+    { metric: 'contributions', weight: 40 },
+    { metric: 'engagement', weight: 30 },
+    { metric: 'governance', weight: 30 },
+  ],
+});
+```
+
+### 3. Reputation Score
+
+Calculated from metrics and weights:
+
+```
+score = (metric1 * weight1) + (metric2 * weight2) + ...
+```
+
+### 4. Credit Limit
+
+Based on reputation:
+
+```
+creditLimit = baseLimit * (reputationScore / 1000)
+```
+
+## Usage
+
+```typescript
+import { getReputationScore } from '@aastar/identity';
+
+// Get user's reputation
+const score = await getReputationScore(
+  client,
+  userAddress,
+  communityAddress
+);
+
+console.log('Reputation:', score.toString());
+
+// Higher reputation = higher credit limit
+const credit = await user.getCreditLimit();
+```
+
+## Benefits
+
+1. **Trustless**: On-chain, verifiable
+2. **Customizable**: Each community sets rules
+3. **Fair**: Transparent scoring
+4. **Dynamic**: Updates with user activity
+
+## Use Cases
+
+- Gas credit limits
+- Governance voting power
+- Access control
+- Reward distribution
+
+## Related
+
+- [Identity Module](/api/modules/identity)
+- [Community API](/api/roles/community)
+- [End User API](/api/roles/enduser)

package/docs/zh/guide/concepts/superpaymaster.md

@@ -0,0 +1,141 @@
+# SuperPaymaster (AOA+)
+
+Advanced On-chain Accounting Paymaster with credit system.
+
+## Overview
+
+SuperPaymaster is AAStar's innovative gas sponsorship solution that enables truly gasless transactions through an on-chain credit system.
+
+## Key Features
+
+### 1. Credit-Based System
+
+Users get gas credit based on:
+- **SBT Ownership**: Community membership tokens
+- **Reputation Score**: On-chain reputation
+- **Historical Behavior**: Past transaction patterns
+- **Community Rules**: Custom eligibility criteria
+
+### 2. Operator Network
+
+Decentralized network of Paymaster operators who:
+- Stake GTokens to participate
+- Deposit funds for gas sponsorship
+- Earn fees from communities
+- Get slashed for misbehavior
+
+### 3. Community Governance
+
+Communities can:
+- Set their own eligibility rules
+- Configure credit limits
+- Manage operator selection
+- Customize fee structures
+
+## How It Works
+
+```mermaid
+sequenceDiagram
+    User->>SuperPaymaster: Request gasless tx
+    SuperPaymaster->>Registry: Check eligibility
+    Registry->>SuperPaymaster: Return credit limit
+    SuperPaymaster->>Operator: Sponsor gas
+    Operator->>EntryPoint: Pay gas
+    EntryPoint->>User: Execute transaction
+    User->>SuperPaymaster: Repay debt (later)
+```
+
+## Architecture
+
+### Components
+
+1. **SuperPaymaster Contract**: Core logic for gas sponsorship
+2. **Registry**: Manages communities, operators, and users
+3. **GTokenStaking**: Operator stake management
+4. **ReputationSystem**: On-chain reputation tracking
+
+### Credit Calculation
+
+```typescript
+credit = baseCreditLimit 
+  * reputationMultiplier 
+  * communityBonus 
+  - outstandingDebt
+```
+
+## Usage Example
+
+```typescript
+import { createEndUserClient } from '@aastar/core';
+import { getPaymasterAndData } from '@aastar/paymaster';
+
+// 1. Check eligibility
+const user = createEndUserClient({...});
+const eligible = await user.checkEligibility(communityAddress);
+
+if (!eligible) {
+  throw new Error('Not eligible for gasless transactions');
+}
+
+// 2. Get credit limit
+const creditLimit = await user.getCreditLimit();
+console.log('Available credit:', formatEther(creditLimit));
+
+// 3. Create UserOperation with paymaster data
+const paymasterAndData = getPaymasterAndData(userOp, {
+  paymasterAddress: CONTRACTS.sepolia.superPaymaster,
+  communityAddress,
+  xPNTsAddress: CONTRACTS.sepolia.xPNTsToken,
+  verificationGasLimit: 100000n,
+  postOpGasLimit: 50000n,
+});
+
+// 4. Submit gasless transaction
+const txHash = await submitUserOperation({
+  ...userOp,
+  paymasterAndData,
+});
+```
+
+## Benefits
+
+### For Users
+- ✅ No need to hold ETH for gas
+- ✅ Seamless transaction experience
+- ✅ Credit-based system (pay later)
+- ✅ Community-specific benefits
+
+### For Communities
+- ✅ Attract more users
+- ✅ Customizable rules
+- ✅ Better user retention
+- ✅ Governance control
+
+### For Operators
+- ✅ Earn fees from gas sponsorship
+- ✅ Decentralized network
+- ✅ Stake-based participation
+- ✅ Performance incentives
+
+## Comparison with Traditional Paymasters
+
+| Feature | Traditional Paymaster | SuperPaymaster (AOA+) |
+|---------|----------------------|----------------------|
+| Gas Sponsorship | ✅ | ✅ |
+| Credit System | ❌ | ✅ |
+| Decentralized | ❌ | ✅ |
+| Community Governance | ❌ | ✅ |
+| Reputation-Based | ❌ | ✅ |
+| Operator Network | ❌ | ✅ |
+
+## Learn More
+
+- [Operator API](/api/roles/operator) - Become an operator
+- [Community API](/api/roles/community) - Set up gas sponsorship
+- [End User API](/api/roles/enduser) - Use gasless transactions
+
+## Next Steps
+
+- [EOA Rainbow Bridge](/guide/concepts/rainbow-bridge)
+- [Reputation System](/guide/concepts/reputation)
+- [Quick Start](/guide/quick-start)

package/docs/zh/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>
+
+**完整的账户抽象基础设施 SDK - 为 Mycelium 网络提供动力**
+
+---
+
+## 📚 目录
+
+- [简介](#简介)
+- [SDK v2 架构设计](#sdk-v2-架构设计)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [测试命令](#测试命令)
+- [开发指南](#开发指南)
+- [学术研究](#学术研究)
+
+---
+
+## 简介 (Introduction)
+
+**AAStar SDK** 是 Mycelium 网络的高集成度开发工具包。我们将原有的 17 个碎片化模块重构为 7 个专业核心包，旨在提供统一、高性能且易于维护的开发体验。
+
+### 核心特性
+
+- ✅ **角色化客户端**: 为终端用户、社区、运营商和协议管理员提供专属 API
+- ✅ **基础设施就绪**: 深度集成 SuperPaymaster 与 EOA Rainbow Bridge
+- ✅ **无感交互体验**: 基于社区信用系统的 Gasless 交易
+- ✅ **DVT 安全模块**: 去中心化验证与聚合签名
+- ✅ **科学可复现**: 锁定依赖版本，支持学术论文数据采集
+
+---
+
+## SDK v2 架构设计
+
+AAStar SDK v2 采用 **「装饰器 (Actions-Decorator)」** 模式（借鉴自 `viem` 与 `permissionless.js`）。它将低层次的合约交互与高层次的业务逻辑解耦，为生态系统中的四种角色提供专属的 Client 封装。
+
+### 核心理念
+
+- **语义化 Action**: 将复杂流程（如「运营商入驻」）封装为单次 SDK 调用
+- **Provider 无关性**: 完美适配任何 `viem` 传输层（Pimlico, Alchemy 或本地 Anvil）
+- **安全加固**: 锁定依赖版本并实施自动化供应链审计
+
+### 角色化 API 矩阵
+
+| 客户端 | 目标开发者 | 核心职责 |
+| :--- | :--- | :--- |
+| **`EndUserClient`** | dApp 开发者 | 核心账户抽象交互、Gasless UX、查询信用状态 |
+| **`CommunityClient`** | 社区/DAO 管理者 | 自动化入驻、部署 xPNTs 代币、配置 SBT 规则 |
+| **`OperatorClient`** | 节点/运营商 | SuperPaymaster 注册与质押、资金池管理 |
+| **`AdminClient`** | 协议维护者 | 提交 DVT 聚合签名、执行奖惩、调整全局参数 |
+
+---
+
+## 安装 (Installation)
+
+```bash
+pnpm install @aastar/sdk @aastar/core viem
+```
+
+---
+
+## 快速开始 (Quick Start)
+
+### 基础示例 (Operator)
+
+```typescript
+import { createOperatorClient } from '@aastar/sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { foundry } from 'viem/chains';
+import { http } from 'viem';
+
+// 创建运营商客户端
+const operatorClient = createOperatorClient({
+  chain: foundry,
+  transport: http('http://127.0.0.1:8545'),
+  account: privateKeyToAccount('0x...'),
+});
+
+// 一键入驻 SuperPaymaster（质押 + 存款）
+await operatorClient.onboardToSuperPaymaster({
+  stakeAmount: parseEther('50'),
+  depositAmount: parseEther('50')
+});
+```
+
+---
+
+## 核心测试场景 (Core Testing)
+
+本项目提供两套完整的回归测试。
+
+### SDK 回归测试（使用 SDK 客户端）
+
+```bash
+pnpm run test:full_sdk
+```
+
+- **测试场景**:
+  - ✅ Operator Staking (质押)
+  - ✅ Paymaster Deposit (存款)
+  - ✅ Community Registration (社区注册)
+  - ✅ SBT Minting (SBT 铸造)
+  - ✅ Admin Slashing (惩罚)
+  - ✅ Credit Query (信用查询)
+
+### 完整协议回归测试（Anvil 专用，72 场景）
+
+```bash
+pnpm run test:full_anvil
+```
+
+---
+
+## 学术研究 (Research)
+
+本 SDK 支撑了 SuperPaymaster 论文的博士实验数据采集：
+
+- **`scripts/19_sdk_experiment_runner.ts`**: 官方实验记录器
+- **覆盖率**: 95% 用户用例分支，72 个完整场景
+
+---
+
+## 支持与贡献 (Support)
+
+- **代码仓库**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
+- **Discord**: [加入我们的社区](https://discord.gg/aastar)
+- **许可证**: MIT

package/docs/zh/guide/installation.md

@@ -0,0 +1,107 @@
+# 安装 (Installation)
+
+## 包管理器
+
+AAStar SDK 可通过 npm 获得。为了获得最佳体验，我们推荐使用 **pnpm**。
+
+### 使用 pnpm (推荐)
+
+```bash
+pnpm add @aastar/sdk
+```
+
+### 使用 npm
+
+```bash
+npm install @aastar/sdk
+```
+
+### 使用 yarn
+
+```bash
+yarn add @aastar/sdk
+```
+
+## 独立安装包
+
+你也可以根据需求安装特定模块：
+
+```bash
+# 核心工具与客户端创建
+pnpm add @aastar/core
+
+# 账户抽象 (Account Abstraction)
+pnpm add @aastar/account
+
+# Paymaster 與贊助邏輯
+pnpm add @aastar/paymaster
+
+# 代幣工具 (GToken, xPNTs, SBT)
+pnpm add @aastar/tokens
+
+# 身份與聲譽系統
+pnpm add @aastar/identity
+
+# React Hook 支持
+pnpm add @aastar/dapp
+```
+
+## 同行依赖 (Peer Dependencies)
+
+SDK 需要以下同行依赖：
+
+```bash
+pnpm add viem@^2.43.0
+```
+
+## TypeScript 配置
+
+为了获得最佳的 TypeScript 体验，请在 `tsconfig.json` 中添加以下设置：
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## 环境配置
+
+创建一个 `.env` 文件用于存储配置：
+
+```bash
+# 网络 RPC 节点
+RPC_URL=https://rpc.sepolia.org
+
+# 你的私钥 (千万不要提交此文件！)
+PRIVATE_KEY=0x...
+
+# 合约地址 (可选，SDK 默认提供官方地址)
+REGISTRY_ADDRESS=0x...
+PAYMASTER_ADDRESS=0x...
+```
+
+## 验证安装
+
+编写一段简单的代码验证安装是否成功：
+
+```typescript
+import { getNetwork, CONTRACTS } from '@aastar/core';
+
+const network = getNetwork('sepolia');
+console.log('Network:', network.name);
+console.log('Chain ID:', network.chainId);
+console.log('Registry:', CONTRACTS.sepolia.registry);
+```
+
+## 下一步
+
+- [快速开始](/guide/quick-start)
+- [核心概念](/guide/concepts/account-abstraction)
+- [API 参考](/api/)