@aastar/sdk 0.14.3 → 0.16.6

package/.eslintrc.cjs

@@ -0,0 +1,30 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['warn', { 
+      argsIgnorePattern: '^_',
+      varsIgnorePattern: '^_'
+    }],
+    'no-console': ['warn', { allow: ['warn', 'error', 'log'] }],
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/ban-ts-comment': 'warn',
+  },
+  ignorePatterns: [
+    'dist/',
+    'node_modules/',
+    '*.js',
+    '*.d.ts',
+    'coverage/',
+  ],
+};

package/README.md

@@ -1,19 +1,19 @@
-# AAStar SDK (Mycelium Network)
-
+# AAStar SDK
+**AAStar: Empower Community, Simplify Development**
 <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;" />
+  <img src="https://img.shields.io/badge/Status-0.16.6-green" alt="Status" style="display:inline-block;" />
 </p>
 
-**Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network**
-**完整的账户抽象基础设施 SDK - 为 Mycelium 网络提供动力**
+**Comprehensive Account Abstraction Infrastructure SDK - Mycelium Network Cornerstone**
+**完整的账户抽象基础设施 SDK - Mycelium 网络基石**
 
 ---
 
 ## 📚 Contents / 目录
 
-- [AAStar SDK (Mycelium Network)](#aastar-sdk-mycelium-network)
+- [AAStar SDK](#aastar-sdk)
   - [📚 Contents / 目录](#-contents--目录)
   - [Introduction / 简介](#introduction--简介)
     - [Core Features / 核心特性](#core-features--核心特性)
@@ -23,8 +23,28 @@
     - [End User Gasless Transaction / 终端用户 Gasless 流程](#end-user-gasless-transaction--终端用户-gasless-流程)
   - [Testing Commands / 测试命令](#testing-commands--测试命令)
     - [SDK Regression (Using SDK Clients)](#sdk-regression-using-sdk-clients)
+    - [ABI Alignment \& Coverage](#abi-alignment--coverage)
     - [Full Protocol Regression (Anvil Dedicated)](#full-protocol-regression-anvil-dedicated)
+  - [Development Guides / 开发指南](#development-guides--开发指南)
+    - [ABI Maintenance / ABI 维护](#abi-maintenance--abi-维护)
+    - [Node.js Usage / Node.js 使用](#nodejs-usage--nodejs-使用)
+  - [Development Workflow / 开发者工作流](#development-workflow--开发者工作流)
+    - [Step 1: Modify Contracts / 修改合约](#step-1-modify-contracts--修改合约)
+    - [Step 2: Local Build \& Deploy (Anvil) / 本地构建与部署](#step-2-local-build--deploy-anvil--本地构建与部署)
+    - [Step 3: Run Local Tests / 运行本地测试](#step-3-run-local-tests--运行本地测试)
+    - [Step 4: Deploy to Sepolia / 部署至 Sepolia](#step-4-deploy-to-sepolia--部署至-sepolia)
+    - [Step 5: Verify on Sepolia / Sepolia 验证](#step-5-verify-on-sepolia--sepolia-验证)
   - [Academic Research / 学术研究](#academic-research--学术研究)
+  - [API Documentation / API 文档](#api-documentation--api-文档)
+    - [📚 Complete API Reference](#-complete-api-reference)
+    - [📊 Documentation Coverage](#-documentation-coverage)
+    - [🔍 Key API Highlights](#-key-api-highlights)
+      - [Core Package (`@aastar/core`)](#core-package-aastarcore)
+      - [Account Package (`@aastar/account`)](#account-package-aastaraccount)
+      - [Paymaster Package (`@aastar/paymaster`)](#paymaster-package-aastarpaymaster)
+      - [Tokens Package (`@aastar/tokens`)](#tokens-package-aastartokens)
+    - [📝 Documentation Features](#-documentation-features)
+    - [🚀 Generate Documentation](#-generate-documentation)
   - [Support / 支援](#support--支援)
 
 ---
@@ -67,22 +87,31 @@ pnpm install @aastar/sdk @aastar/core viem
 ---
 
 ## Quick Start / 快速开始
-
 ### End User Gasless Transaction / 终端用户 Gasless 流程
 
+Recommended way using the new **PaymasterClient** API (Semantic Helpers):
+
 ```typescript
-import { createEndUserClient } from '@aastar/sdk';
-
-const user = createEndUserClient({ 
-  account, 
-  paymasterUrl: 'https://paymaster.aastar.io' 
-});
-
-// Send sponsored transaction / 使用社区信用代付 Gas
-await user.sendGaslessTransaction({
-  to: TARGET_ADDR,
-  data: CALL_DATA
-});
+import { PaymasterClient } from '@aastar/sdk';
+
+// 1. Build CallData (e.g., Transfer Token)
+const callData = PaymasterClient.encodeExecution(
+  tokenAddress,
+  0n,
+  PaymasterClient.encodeTokenTransfer(recipient, amount)
+);
+
+// 2. Submit (Auto Gas Estimation & Signing)
+const hash = await PaymasterClient.submitGaslessUserOperation(
+  client,
+  wallet,
+  aaAccount,
+  entryPoint,
+  paymasterAddress,
+  gasTokenAddress,
+  bundlerUrl,
+  callData
+);
 ```
 
 ---
@@ -94,6 +123,17 @@ await user.sendGaslessTransaction({
 pnpm run test:full_sdk
 ```
 
+### ABI Alignment & Coverage
+```bash
+# Audit ABI alignment between Registry.json and core/actions
+pnpm run audit:abi
+
+# Run unit tests with coverage report
+pnpm run test:coverage
+# or for specific packages
+pnpm exec vitest run packages --coverage
+```
+
 
 ### Full Protocol Regression (Anvil Dedicated)
 ```bash
@@ -102,6 +142,26 @@ pnpm run test:full_anvil
 
 ---
 
+## Development Guides / 开发指南
+
+### ABI Maintenance / ABI 维护
+- [ABI Maintenance Plan](./docs/ABI_MAINTENANCE_PLAN.md) - 合约 ABI 自动同步和维护策略
+- [ABI Change Tracking Workflow](./docs/ABI_Change_Tracking_Workflow.md) - ABI 变动追踪与 SDK 自动化审计流程
+
+---
+
+### Node.js Usage / Node.js 使用
+For server-side or CLI tools needing direct private key management (e.g., `KeyManager`), use the Node-specific export:
+
+```typescript
+import { KeyManager } from '@aastar/sdk/node';
+
+// Generate or load keys securely
+const key = KeyManager.loadFromEnv('PRIVATE_KEY');
+```
+
+---
+
 ## Development Workflow / 开发者工作流
 
 A step-by-step guide for contributors from contract modification to Sepolia deployment.
@@ -162,8 +222,77 @@ The SDK supports doctoral data collection for the SuperPaymaster paper. Official
 
 ---
 
+## API Documentation / API 文档
+
+### 📚 Complete API Reference
+
+The SDK provides comprehensive TypeDoc-generated API documentation for all packages:
+
+- **📖 [Full API Documentation](./docs/api/)** - Complete reference for all packages
+- **🌐 [Online Documentation](https://docs.aastar.io)** - Hosted documentation site
+
+### 📊 Documentation Coverage
+
+| Package | Classes | Functions | Interfaces | Types | Total APIs |
+|---------|---------|-----------|------------|-------|------------|
+| **[@aastar/core](./docs/api/@aastar/core/)** | 7 | 51 | 14 | 20 | **92+** |
+| **[@aastar/account](./docs/api/@aastar/account/)** | 1 | 4 | 2 | 2 | **9** |
+| **[@aastar/paymaster](./docs/api/@aastar/paymaster/)** | 4 | 7 | 4 | 4 | **19** |
+| **[@aastar/tokens](./docs/api/@aastar/tokens/)** | 1 | 15+ | - | - | **16+** |
+| **Total** | **13** | **77+** | **20+** | **26+** | **136+** |
+
+### 🔍 Key API Highlights
+
+#### Core Package (`@aastar/core`)
+- **Configuration Management**: `ContractConfigManager`, `getNetwork()`, `getRpcUrl()`
+- **Role System**: 7 role constants with complete requirements and permissions
+- **Actions**: Registry, Staking, SBT, SuperPaymaster, Token, EntryPoint actions
+- **Validation**: `RequirementChecker`, `StateValidator`, `AAStarValidationError`
+- **Client Base**: `BaseClient` with full viem integration
+
+#### Account Package (`@aastar/account`)
+- **User Operations**: `UserOpClient` for AA account management
+- **Account Creation**: `createEOAWalletClient()`, `toSimpleSmartAccount()`
+- **Utilities**: `getUserOpHash()`, `packUserOpLimits()`
+
+#### Paymaster Package (`@aastar/paymaster`)
+- **Clients**: `PaymasterClient`, `SuperPaymasterClient`, `SuperPaymasterAdminClient`, `PaymasterOperator`
+- **Middleware**: `getPaymasterV4Middleware()`, `getSuperPaymasterMiddleware()`
+- **Utilities**: `checkEligibility()`, `buildPaymasterData()`, `buildSuperPaymasterData()`
+
+#### Tokens Package (`@aastar/tokens`)
+- **Finance Client**: `FinanceClient` with 15+ token operation methods
+- **GToken Operations**: Balance queries, staking, unstaking, rewards
+- **aPNTs Operations**: Minting, burning, wrapping, balance management
+- **Tokenomics**: `getTokenomicsOverview()`, `getCirculatingSupply()`
+
+### 📝 Documentation Features
+
+✅ **Zero Warnings**: Clean documentation generation with no TypeDoc warnings  
+✅ **100% Accuracy**: All API docs verified against source code  
+✅ **Complete Coverage**: All exported APIs documented with types, parameters, and examples  
+✅ **Rich Metadata**: JSDoc comments, usage examples, and source code links  
+✅ **Auto-Generated**: Synchronized with latest codebase via `pnpm run docs:generate`
+
+### 🚀 Generate Documentation
+
+```bash
+# Generate API documentation
+pnpm run docs:generate
+
+# Sync to documentation repository
+pnpm run docs:sync
+```
+
+---
+
 ## Support / 支援
 
+**⭐ If you find this project helpful, please consider giving us a star on GitHub!**  
+**如果您觉得这个项目有帮助，请在 GitHub 上给我们一个 Star！**
+
+[![GitHub stars](https://img.shields.io/github/stars/AAStarCommunity/aastar-sdk?style=social)](https://github.com/AAStarCommunity/aastar-sdk)
+
 - **Documentation**: [docs.aastar.io](https://docs.aastar.io)
 - **GitHub**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
 

package/abis/BLSAggregator.json

@@ -72,19 +72,6 @@
     ],
     "stateMutability": "view"
   },
-  {
-    "type": "function",
-    "name": "VERSION",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "string",
-        "internalType": "string"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "aggregatedSignatures",
@@ -327,6 +314,19 @@
     "outputs": [],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "version",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "pure"
+  },
   {
     "type": "event",
     "name": "BLSPublicKeyRegistered",

package/abis/BLSValidator.json

@@ -22,5 +22,18 @@
       }
     ],
     "stateMutability": "pure"
+  },
+  {
+    "type": "function",
+    "name": "version",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "pure"
   }
 ]

package/abis/DVTValidator.json

@@ -254,6 +254,19 @@
     "outputs": [],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "version",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "pure"
+  },
   {
     "type": "event",
     "name": "OwnershipTransferred",

package/abis/GToken.json

@@ -10,32 +10,6 @@
     ],
     "stateMutability": "nonpayable"
   },
-  {
-    "type": "function",
-    "name": "VERSION",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "string",
-        "internalType": "string"
-      }
-    ],
-    "stateMutability": "view"
-  },
-  {
-    "type": "function",
-    "name": "VERSION_CODE",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "uint256",
-        "internalType": "uint256"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "allowance",
@@ -103,6 +77,37 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "burn",
+    "inputs": [
+      {
+        "name": "value",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "burnFrom",
+    "inputs": [
+      {
+        "name": "account",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
   {
     "type": "function",
     "name": "cap",
@@ -173,6 +178,19 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "remainingMintableSupply",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "renounceOwnership",
@@ -272,6 +290,19 @@
     "outputs": [],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "version",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "pure"
+  },
   {
     "type": "event",
     "name": "Approval",

package/abis/GTokenStaking.json

@@ -15,19 +15,6 @@
     ],
     "stateMutability": "nonpayable"
   },
-  {
-    "type": "function",
-    "name": "BURN_ADDRESS",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "address",
-        "internalType": "address"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "GTOKEN",
@@ -54,32 +41,6 @@
     ],
     "stateMutability": "view"
   },
-  {
-    "type": "function",
-    "name": "VERSION",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "string",
-        "internalType": "string"
-      }
-    ],
-    "stateMutability": "view"
-  },
-  {
-    "type": "function",
-    "name": "VERSION_CODE",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "uint256",
-        "internalType": "uint256"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "authorizedSlashers",
@@ -678,6 +639,19 @@
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "version",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "pure"
+  },
   {
     "type": "event",
     "name": "OwnershipTransferred",

package/abis/MySBT.json

@@ -77,32 +77,6 @@
     ],
     "stateMutability": "view"
   },
-  {
-    "type": "function",
-    "name": "VERSION",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "string",
-        "internalType": "string"
-      }
-    ],
-    "stateMutability": "view"
-  },
-  {
-    "type": "function",
-    "name": "VERSION_CODE",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "uint256",
-        "internalType": "uint256"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "airdropMint",
@@ -965,19 +939,6 @@
     "type": "function",
     "name": "version",
     "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "uint256",
-        "internalType": "uint256"
-      }
-    ],
-    "stateMutability": "pure"
-  },
-  {
-    "type": "function",
-    "name": "versionString",
-    "inputs": [],
     "outputs": [
       {
         "name": "",

package/abis/Paymaster.json

@@ -60,19 +60,6 @@
     ],
     "stateMutability": "view"
   },
-  {
-    "type": "function",
-    "name": "VERSION",
-    "inputs": [],
-    "outputs": [
-      {
-        "name": "",
-        "type": "string",
-        "internalType": "string"
-      }
-    ],
-    "stateMutability": "view"
-  },
   {
     "type": "function",
     "name": "addDeposit",