@aastar/sdk 0.14.3 → 0.16.8

package/README.md

@@ -1,170 +1,150 @@
-# AAStar SDK (Mycelium Network)
+# AAstar SDK
 
-<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>
+The ultimate TypeScript SDK for the AAstar Protocol - a decentralized, community-driven Account Abstraction ecosystem.  
+AAstar 协议的终极 TypeScript SDK —— 构建去中心化、社区驱动的账户抽象生态系统。
 
-**Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network**
-**完整的账户抽象基础设施 SDK - 为 Mycelium 网络提供动力**
+[![npm version](https://img.shields.io/npm/v/@aastar/sdk.svg)](https://www.npmjs.com/package/@aastar/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## 📚 Contents / 目录
-
-- [AAStar SDK (Mycelium Network)](#aastar-sdk-mycelium-network)
-  - [📚 Contents / 目录](#-contents--目录)
-  - [Introduction / 简介](#introduction--简介)
-    - [Core Features / 核心特性](#core-features--核心特性)
-  - [SDK v2 Architecture / 架构设计](#sdk-v2-architecture--架构设计)
-  - [Installation / 安装](#installation--安装)
-  - [Quick Start / 快速开始](#quick-start--快速开始)
-    - [End User Gasless Transaction / 终端用户 Gasless 流程](#end-user-gasless-transaction--终端用户-gasless-流程)
-  - [Testing Commands / 测试命令](#testing-commands--测试命令)
-    - [SDK Regression (Using SDK Clients)](#sdk-regression-using-sdk-clients)
-    - [Full Protocol Regression (Anvil Dedicated)](#full-protocol-regression-anvil-dedicated)
-  - [Academic Research / 学术研究](#academic-research--学术研究)
-  - [Support / 支援](#support--支援)
-
----
-
-## Introduction / 简介
-
-**AAStar SDK** is a high-integration toolkit for the Mycelium network. We've refactored 17 fragmented modules into 7 professional core packages, providing a unified, high-performance, and easy-to-maintain development experience.
+## 🌟 Introduction | 简介
 
-**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. (**科学可复现**)
-
----
+AAstar SDK provides a complete suite of tools to interact with the AAstar Protocol. It is designed with a **"Pre-check first, Action second"** philosophy, helping developers build robust dApps with minimal errors.
 
-## SDK v2 Architecture / 架构设计
+AAstar SDK 提供了一套完整的工具集用于交互 AAstar 协议。它采用了 **"先检查，后执行"** 的设计理念，帮助开发者构建低错误率、健壮的去中心化应用。
 
-AAStar SDK v2 采用 **「装饰器 (Actions-Decorator)」** 模式。它将低层次的合约交互与高层次的业务逻辑解耦，为生态系统中的四种角色提供专属的 Client 封装。
+### Core Modules | 核心模块
 
-| 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 |
+- **`@aastar/community`**: Launch & manage DAOs. (启动和管理 DAO)
+- **`@aastar/operator`**: Run Paymasters & earn rewards. (运行 Paymaster 并赚取收益)
+- **`@aastar/enduser`**: Join communities & enjoy gasless txs. (加入社区并享受免 Gas 交易)
+- **`@aastar/analytics`**: Monitor ecosystem data. (监控生态系统数据)
+- **`@aastar/tokens`**: GToken & XPNTs finance tools. (GToken 和 XPNTs 金融工具)
+- **`@aastar/identity`**: Reputation & SBT management. (声誉和 SBT 管理)
+- **`@aastar/account`**: Smart Account (ERC-4337) utilities. (智能账户工具)
 
 ---
 
-## Installation / 安装
+## 📦 Installation | 安装
 
 ```bash
-pnpm install @aastar/sdk @aastar/core viem
+pnpm add @aastar/sdk viem
+# or
+npm install @aastar/sdk viem
 ```
 
 ---
 
-## Quick Start / 快速开始
+## 🚀 Usage | 使用指南
 
-### End User Gasless Transaction / 终端用户 Gasless 流程
+### 1. Initialize Client | 初始化客户端
 
 ```typescript
-import { createEndUserClient } from '@aastar/sdk';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { sepolia } from 'viem/chains';
+import { CommunityClient, OperatorClient } from '@aastar/sdk';
 
-const user = createEndUserClient({ 
-  account, 
-  paymasterUrl: 'https://paymaster.aastar.io' 
-});
+// 1. Setup VIEM clients
+const publicClient = createPublicClient({ chain: sepolia, transport: http() });
+const walletClient = createWalletClient({ chain: sepolia, transport: http() });
 
-// Send sponsored transaction / 使用社区信用代付 Gas
-await user.sendGaslessTransaction({
-  to: TARGET_ADDR,
-  data: CALL_DATA
-});
+// 2. Initialize AAstar Clients
+const communityClient = new CommunityClient(publicClient, walletClient);
+const operatorClient = new OperatorClient(publicClient, walletClient);
 ```
 
----
+### 2. "Pre-check" Pattern | "预检查" 模式
 
-## Testing Commands / 测试命令
+Avoid reverts and save gas by checking requirements off-chain first.  
+通过链下预检查避免交易回滚并节省 Gas。
 
-### SDK Regression (Using SDK Clients)
-```bash
-pnpm run test:full_sdk
+```typescript
+// ❌ Old Way (Prone to errors)
+// await communityClient.launchCommunity(...); 
+
+// ✅ New AAstar Way
+const check = await communityClient.checkLaunchRequirements(myAddress, parseEther("33"));
+
+if (!check.hasEnoughGToken) {
+    console.error(`Missing Requirements: ${check.missingRequirements.join(', ')}`);
+    // Output: "Need 33 GT, have 10 GT"
+} else {
+    // Safe to execute
+    await communityClient.launchCommunity({
+        name: "My DAO",
+        tokenSymbol: "MDAO"
+    });
+}
 ```
 
+### 3. Key Scenarios | 核心场景
 
-### Full Protocol Regression (Anvil Dedicated)
-```bash
-pnpm run test:full_anvil
-```
-
----
+#### 🏛️ For Community Owners (社区创建者)
 
-## Development Workflow / 开发者工作流
+```typescript
+// Configure SBT rules for your community
+await communityClient.configureSBTRules({
+    communityId: myCommunityId,
+    rule: {
+        minScore: 100,
+        requiredTags: ["OG"]
+    }
+});
+```
 
-A step-by-step guide for contributors from contract modification to Sepolia deployment.
+#### ⚙️ For Operators (运营商)
 
-### Step 1: Modify Contracts / 修改合约
-Edit Solidity files in `superpaymaster/contracts/src`.
-```bash
-cd projects/SuperPaymaster
-# Edit .sol files...
+```typescript
+// Check if you are ready to be a Super Paymaster
+const status = await operatorClient.checkResources(myAddress);
+
+if (status.hasRole) {
+    await operatorClient.withdrawCollateral(parseEther("50"));
+} else {
+    console.log(status.recommendations); 
+    // "Fund aPNTs for collateral", "Stake GToken"
+}
 ```
 
-### Step 2: Local Build & Deploy (Anvil) / 本地构建与部署
-Auto-start Anvil, compile contracts, deploy, and sync config to SDK.
-```bash
-cd projects/aastar-sdk
-# Runs Anvil + Deploy + Sync .env.anvil
-./run_full_regression.sh --env anvil
-```
+#### 📊 For Analysts (分析师)
 
-### Step 3: Run Local Tests / 运行本地测试
-Validate your changes with the full regression suite.
-```bash
-# Run all SDK & Protocol tests
-./run_sdk_regression.sh
-```
+```typescript
+import { AnalyticsClient } from '@aastar/sdk';
 
-### Step 4: Deploy to Sepolia / 部署至 Sepolia
-1. Configure `aastar-sdk/.env.sepolia` with `ADMIN_KEY` and `SEPOLIA_RPC_URL`.
-2. Run the deployment script (with resume capability).
-```bash
-cd projects/SuperPaymaster/contracts
-# Deploy Core + Modules
-export $(grep -v '^#' ../../aastar-sdk/.env.sepolia | xargs) && \
-export PRIVATE_KEY=$ADMIN_KEY && \
-forge script script/DeployV3FullSepolia.s.sol \
-  --rpc-url $SEPOLIA_RPC_URL \
-  --broadcast --verify --slow --resume
-```
-3. Update `aastar-sdk/.env.sepolia` with new contract addresses from `script/v3/config.json`.
+const analytics = new AnalyticsClient(publicClient);
 
-### Step 5: Verify on Sepolia / Sepolia 验证
-Run the regression suite against the live testnet.
-```bash
-cd projects/aastar-sdk
-./run_full_regression.sh --env sepolia
+// Get real-time GToken metrics
+const metrics = await analytics.getSupplyMetrics();
+console.log(`Deflation Rate: ${metrics.deflationRate}%`);
 ```
 
-
 ---
 
-## Academic Research / 学术研究
+## 🔧 Architecture | 架构
 
-The SDK supports doctoral data collection for the SuperPaymaster paper. Official experiment logger is available at `scripts/19_sdk_experiment_runner.ts`.
+AAstar SDK is built on top of **viem**, ensuring lightweight and type-safe interactions. It abstracts complex contract logic into intuitive business primitives.
 
-本 SDK 支撑了 SuperPaymaster 论文的博士实验数据采集。官方实验记录器位于 `scripts/19_sdk_experiment_runner.ts`。
+AAstar SDK 基于 **viem** 构建，确保轻量级和类型安全的交互。它将复杂的合约逻辑抽象为直观的业务原语。
 
-- [Stage 3 Scenario Experiment Plan](./docs/STAGE_3_SCENARIO_EXP_PLAN.md)
+| Package | Functionality (功能) |
+|---------|---------------------|
+| `@aastar/core` | Shared logic, Roles, RequirementChecker |
+| `@aastar/community` | DAO Registry, XPNTs issuance |
+| `@aastar/operator` | Paymaster ops, Staking management |
+| `@aastar/enduser` | User onboarding, SBT minting |
+| `@aastar/tokens` | Finance, Tokenomics, Approval flows |
+| `@aastar/identity` | Reputation, Credit limits, ZK Proofs |
 
 ---
 
-## Support / 支援
+## 🤝 Contributing | 贡献
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.  
+欢迎贡献！更多详情请参考 [贡献指南](CONTRIBUTING.md)。
 
-- **Documentation**: [docs.aastar.io](https://docs.aastar.io)
-- **GitHub**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
+---
 
-MIT © AAStar Community
+<p align="center">
+  Built with ❤️ by the AAstar Community
+</p>

package/dist/account/src/accounts/simple.d.ts

@@ -0,0 +1,18 @@
+import { type Address, type Hex, type LocalAccount } from 'viem';
+export type SimpleSmartAccount = LocalAccount & {
+    signUserOperation: (userOp: any) => Promise<Hex>;
+    getInitCode: () => Promise<Hex>;
+    getDummySignature: () => Promise<Hex>;
+    entryPoint: Address;
+};
+export declare function toSimpleSmartAccount(parameters: {
+    client: any;
+    owner: LocalAccount;
+    factoryAddress: Address;
+    entryPoint: {
+        address: Address;
+        version: '0.6' | '0.7';
+    };
+    salt?: bigint;
+    index?: bigint;
+}): Promise<SimpleSmartAccount>;

package/{packages/account/src/accounts/simple.ts → dist/account/src/accounts/simple.js}

@@ -1,34 +1,8 @@
-import { 
-    type Address, 
-    type Hex, 
-    type LocalAccount, 
-    type SignableMessage, 
-    type TypedDataDefinition,
-    type Hash,
-    concatHex, 
-    encodeFunctionData, 
-    keccak256,
-} from 'viem';
+import { concatHex, encodeFunctionData, } from 'viem';
 import { SimpleAccountFactoryABI } from '@aastar/core';
 import { getUserOpHash } from '../index.js';
-
-export type SimpleSmartAccount = LocalAccount & {
-    signUserOperation: (userOp: any) => Promise<Hex>;
-    getInitCode: () => Promise<Hex>;
-    getDummySignature: () => Promise<Hex>;
-    entryPoint: Address;
-};
-
-export async function toSimpleSmartAccount(parameters: {
-    client: any;
-    owner: LocalAccount;
-    factoryAddress: Address;
-    entryPoint: { address: Address; version: '0.6' | '0.7' };
-    salt?: bigint;
-    index?: bigint;
-}): Promise<SimpleSmartAccount> {
+export async function toSimpleSmartAccount(parameters) {
     const { client, owner, factoryAddress, entryPoint, index = 0n, salt = 0n } = parameters;
-    
     // Calculate initCode
     const factoryData = encodeFunctionData({
         abi: SimpleAccountFactoryABI,
@@ -36,49 +10,40 @@ export async function toSimpleSmartAccount(parameters: {
         args: [owner.address, salt]
     });
     const initCode = concatHex([factoryAddress, factoryData]);
-
     // Calculate counterfactual address
     const address = await client.readContract({
-         address: factoryAddress,
-         abi: SimpleAccountFactoryABI,
-         functionName: 'getAddress',
-         args: [owner.address, salt]
+        address: factoryAddress,
+        abi: SimpleAccountFactoryABI,
+        functionName: 'getAddress',
+        args: [owner.address, salt]
     });
-
     return {
         address,
         publicKey: owner.address,
-        source: 'custom', 
+        source: 'custom',
         type: 'local',
         entryPoint: entryPoint.address,
-        
-        async signMessage({ message }: { message: SignableMessage }): Promise<Hex> {
+        async signMessage({ message }) {
             // validating signature for smart account usually involves EIP-1271, 
             // but here we just sign with owner for SimpleAccount which validates owner sig
             return owner.signMessage({ message });
         },
-
-        async signTypedData(typedData: TypedDataDefinition): Promise<Hex> {
+        async signTypedData(typedData) {
             return owner.signTypedData(typedData);
         },
-
-        async signTransaction(transaction: any): Promise<Hex> {
+        async signTransaction(transaction) {
             throw new Error('Smart Accounts cannot sign transactions directly. Use UserOperations.');
         },
-        
-        async signUserOperation(userOp: any): Promise<Hex> {
+        async signUserOperation(userOp) {
             const chainId = client.chain?.id || 31337; // Default to local anvil if not found
             const hash = getUserOpHash(userOp, entryPoint.address, chainId);
             return owner.signMessage({ message: { raw: hash } });
         },
-        
         async getInitCode() {
             return initCode;
         },
-
         async getDummySignature() {
             return '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
         }
-
-    } as any as SimpleSmartAccount;
+    };
 }

package/dist/account/src/eoa.d.ts

@@ -0,0 +1,10 @@
+import { type WalletClient, type Address, type Chain, type Transport, type Hash, type Hex } from 'viem';
+export type EOAWalletClient = WalletClient & {
+    sendTransaction: (args: {
+        to: Address;
+        value?: bigint;
+        data?: Hex;
+    }) => Promise<Hash>;
+    getAddress: () => Address;
+};
+export declare const createEOAWalletClient: (privateKey: Hex, chain: Chain, transport?: Transport) => EOAWalletClient;

package/dist/account/src/eoa.js

@@ -0,0 +1,21 @@
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+export const createEOAWalletClient = (privateKey, chain, transport = http()) => {
+    const account = privateKeyToAccount(privateKey);
+    const client = createWalletClient({
+        account,
+        chain,
+        transport
+    });
+    const baseSendTransaction = client.sendTransaction.bind(client);
+    return Object.assign(client, {
+        async sendTransaction(args) {
+            return baseSendTransaction({
+                ...args,
+                account,
+                chain
+            });
+        },
+        getAddress: () => account.address
+    });
+};

package/dist/account/src/index.d.ts

@@ -0,0 +1,19 @@
+import { type Hex, type Address } from 'viem';
+export * from './eoa.js';
+export * from './accounts/simple.js';
+/**
+ * Common Pack Logic for v0.7 UserOperations
+ */
+export declare function packUserOpLimits(high: bigint, low: bigint): Hex;
+/**
+ * Local implementation of EntryPoint v0.7 getUserOpHash
+ */
+export declare function getUserOpHash(op: any, ep: Address, chainId: number): Hex;
+/**
+ * UserOperation Client for handling high-level flows
+ */
+export declare class UserOpClient {
+    static estimateGas(bundler: any, op: any, entryPoint: Address): Promise<any>;
+    static sendUserOp(bundler: any, op: any, entryPoint: Address): Promise<any>;
+    static getReceipt(bundler: any, hash: Hex): Promise<any>;
+}

package/dist/account/src/index.js

@@ -0,0 +1,49 @@
+import { encodeAbiParameters, keccak256 } from 'viem';
+export * from './eoa.js';
+export * from './accounts/simple.js';
+/**
+ * Common Pack Logic for v0.7 UserOperations
+ */
+export function packUserOpLimits(high, low) {
+    return `0x${((high << 128n) | low).toString(16).padStart(64, '0')}`;
+}
+/**
+ * Local implementation of EntryPoint v0.7 getUserOpHash
+ */
+export function getUserOpHash(op, ep, chainId) {
+    const packed = encodeAbiParameters([
+        { type: 'address' }, { type: 'uint256' }, { type: 'bytes32' }, { type: 'bytes32' },
+        { type: 'bytes32' }, { type: 'uint256' }, { type: 'bytes32' }, { type: 'bytes32' }
+    ], [
+        op.sender, BigInt(op.nonce),
+        keccak256(op.initCode && op.initCode !== "0x" ? op.initCode : '0x'),
+        keccak256(op.callData),
+        op.accountGasLimits, BigInt(op.preVerificationGas), op.gasFees,
+        keccak256(op.paymasterAndData)
+    ]);
+    const enc = encodeAbiParameters([{ type: 'bytes32' }, { type: 'address' }, { type: 'uint256' }], [keccak256(packed), ep, BigInt(chainId)]);
+    return keccak256(enc);
+}
+/**
+ * UserOperation Client for handling high-level flows
+ */
+export class UserOpClient {
+    static async estimateGas(bundler, op, entryPoint) {
+        return bundler.request({
+            method: 'eth_estimateUserOperationGas',
+            params: [op, entryPoint]
+        });
+    }
+    static async sendUserOp(bundler, op, entryPoint) {
+        return bundler.request({
+            method: 'eth_sendUserOperation',
+            params: [op, entryPoint]
+        });
+    }
+    static async getReceipt(bundler, hash) {
+        return bundler.request({
+            method: 'eth_getUserOperationReceipt',
+            params: [hash]
+        });
+    }
+}