@aastar/sdk 0.16.6 → 0.16.8

package/docs/guide/TEST_COMMANDS.md

@@ -1,320 +0,0 @@
-# 🚀 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/concepts/account-abstraction.md

@@ -1,95 +0,0 @@
-# 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/guide/concepts/rainbow-bridge.md

@@ -1,68 +0,0 @@
-# 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/guide/concepts/reputation.md

@@ -1,95 +0,0 @@
-# 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/guide/concepts/superpaymaster.md

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