@aastar/sdk 0.16.8 → 0.16.11

package/.github/workflows/gas-analytics-daily.yml

@@ -0,0 +1,52 @@
+name: Gas Analytics Daily Report
+
+on:
+  schedule:
+    # Run every day at 00:00 UTC
+    - cron: '0 0 * * *'
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  analyze-and-report:
+    runs-on: ubuntu-latest
+    
+    env:
+      SEPOLIA_RPC_URL: ${{ secrets.SEPOLIA_RPC_URL }}
+      PRIVATE_KEY_SUPPLIER: ${{ secrets.PRIVATE_KEY_SUPPLIER }} # Needed if any tx is required, though analysis is read-only usually
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Fetch External Data
+        # Ensure we have the latest benchmarks
+        run: npx tsx packages/analytics/src/gas-analyzer-v4.ts --fetch-only || true
+
+      - name: Generate Gas Analytics Report
+        run: |
+          mkdir -p packages/analytics/reports/daily
+          REPORT_NAME="gas_report_$(date +%Y%m%d).md"
+          npx tsx packages/analytics/src/gas-analyzer-v4.ts > packages/analytics/reports/daily/$REPORT_NAME
+          
+          # Also update the latest summary
+          cp packages/analytics/reports/daily/$REPORT_NAME packages/analytics/reports/LATEST.md
+
+      - name: Commit and Push Report
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore(analytics): generate daily gas report [skip ci]"
+          file_pattern: 'packages/analytics/reports/**'

package/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "ext/aastar-shared-config"]
+	path = ext/aastar-shared-config
+	url = https://github.com/AAStarCommunity/aastar-shared-config
+[submodule "ext/permissionless.js"]
+	path = ext/permissionless.js
+	url = https://github.com/pimlicolabs/permissionless.js
+[submodule "lib/shared-config"]
+	path = lib/shared-config
+	url = https://github.com/AAStarCommunity/aastar-shared-config.git

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.16.11] - 2026-01-19
+
+### 📊 Gas Analytics & Reporting (New Package)
+- **[NEW]** Added `@aastar/analytics` package for comprehensive gas analysis.
+- **[FEATURE]** `CostCalculator`: Calculates true L1/L2 gas costs, protocol profit (10% premium + buffer), and user savings.
+- **[FEATURE]** `AttributionAnalyzer`: Simulates L2 costs (Optimism model) to provide "Apple-to-Apple" competitiveness comparisons.
+- **[REPORT]** `gas-analyzer-v4.ts`: Generates detailed reports showing ~28% protocol profit margin and ~400x savings vs. Ethereum L1.
+
+### SDK & Core Enhancements
+- **[FIX]** **Anni Gasless Fix**: Updated `l4-setup.ts` to use `updatePriceDVT` for refreshing stale SuperPaymaster price cache, preventing "UserOperation expired" errors.
+- **[FIX]** **Duplicate Build Fix**: Resolved merge conflicts and duplicate identifiers in `packages/core` actions (e.g., `contracts.ts`, `actions/index.ts`).
+- **[FIX]** **Build System**: Removed residual `*.test.ts` files in modification directories to ensure clean `tsc` builds.
+
+### Regression & Testing
+- **[IMPROVED]** `L4 Regression`: Full automation for Setup -> Funding -> Gasless Transactions -> Analytics.
+- **[FEATURE]** `DVT Price Update`: Integrated DVT signature generation in test setup to simulate authenticated price updates.
+
+- **[BREAKING]** Decoupled development and production build configurations.
+  - Added `tsconfig.build.json` for strictly clean production builds (`pnpm build`).
+  - Updated root `tsconfig.json` to retain `paths` mappings for rapid development (`tsx`).
+  - Updated all `packages/*/tsconfig.json` to extend the build configuration.
+- Fixed `packages/core` build output to correctly generate type definitions (`.d.ts`).
+
+### SDK Core (`@aastar/core`)
+- **[CHANGED]** `BaseClient` visibility update.
+  - Changed `client` and `getStartPublicClient` from `protected` to `public` to allow easier extension and debugging in consuming applications.
+- **[Check]** Standardized ABI exports.
+  - Updated `abis/index.ts` to support both array-based and object-based (`{ abi: [] }`) ABI JSON formats, resolving compatibility issues with external artifacts.
+
+### SDK Operator (`@aastar/operator`)
+- **[FIXED]** ABI Property Access.
+  - Fixed runtime error where `PaymasterOperatorClient` attempted to access `.abi` on a raw ABI array. Now uses the standardized `PaymasterABI` export.
+
+### SDK EndUser (`@aastar/enduser`)
+- **[FIXED]** `UserClient` build failure due to `BaseClient` visibility issues.
+
+### Testing & Regression
+- **[ADDED]** `run_sdk_regression.sh` now supports a strict `sepolia` environment mode with correct `.env` loading (`set -a`).
+- **[ADDED]** `extract_v3_abis.sh` integration for reliable ABI synchronization from the SuperPaymaster project.

package/README.md

@@ -1,150 +1,199 @@
-# AAstar SDK
+# AAStar SDK (Mycelium Network)
 
-The ultimate TypeScript SDK for the AAstar Protocol - a decentralized, community-driven Account Abstraction ecosystem.  
-AAstar 协议的终极 TypeScript 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>
+
+**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 | 简介
+## Introduction / 简介
 
-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.
+**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.
 
-AAstar SDK 提供了一套完整的工具集用于交互 AAstar 协议。它采用了 **"先检查，后执行"** 的设计理念，帮助开发者构建低错误率、健壮的去中心化应用。
+**AAStar SDK** 是 Mycelium 网络的高集成度开发工具包。我们将原有的 17 个碎片化模块重构为 7 个专业核心包，旨在提供统一、高性能且易于维护的开发体验。
 
-### Core Modules | 核心模块
+### Core Features / 核心特性
 
-- **`@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. (智能账户工具)
+- ✅ **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. (**科学可复现**)
 
 ---
 
-## 📦 Installation | 安装
+## SDK v2 Architecture / 架构设计
+
+AAStar SDK v2 采用 **「装饰器 (Actions-Decorator)」** 模式。它将低层次的合约交互与高层次的业务逻辑解耦，为生态系统中的四种角色提供专属的 Client 封装。
+
+| 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 add @aastar/sdk viem
-# or
-npm install @aastar/sdk viem
+pnpm install @aastar/sdk @aastar/core viem
 ```
 
 ---
 
-## 🚀 Usage | 使用指南
+## Quick Start / 快速开始
 
-### 1. Initialize Client | 初始化客户端
+### End User Gasless Transaction / 终端用户 Gasless 流程
 
 ```typescript
-import { createPublicClient, createWalletClient, http } from 'viem';
-import { sepolia } from 'viem/chains';
-import { CommunityClient, OperatorClient } from '@aastar/sdk';
+import { createEndUserClient } from '@aastar/sdk';
 
-// 1. Setup VIEM clients
-const publicClient = createPublicClient({ chain: sepolia, transport: http() });
-const walletClient = createWalletClient({ chain: sepolia, transport: http() });
+const user = createEndUserClient({ 
+  account, 
+  paymasterUrl: 'https://paymaster.aastar.io' 
+});
 
-// 2. Initialize AAstar Clients
-const communityClient = new CommunityClient(publicClient, walletClient);
-const operatorClient = new OperatorClient(publicClient, walletClient);
+// Send sponsored transaction / 使用社区信用代付 Gas
+await user.sendGaslessTransaction({
+  to: TARGET_ADDR,
+  data: CALL_DATA
+});
 ```
 
-### 2. "Pre-check" Pattern | "预检查" 模式
+---
 
-Avoid reverts and save gas by checking requirements off-chain first.  
-通过链下预检查避免交易回滚并节省 Gas。
+## Testing Commands / 测试命令
 
-```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"
-    });
-}
+### SDK Regression (Using SDK Clients)
+```bash
+pnpm run test:full_sdk
 ```
 
-### 3. Key Scenarios | 核心场景
 
-#### 🏛️ For Community Owners (社区创建者)
-
-```typescript
-// Configure SBT rules for your community
-await communityClient.configureSBTRules({
-    communityId: myCommunityId,
-    rule: {
-        minScore: 100,
-        requiredTags: ["OG"]
-    }
-});
+### Full Protocol Regression (Anvil Dedicated)
+```bash
+pnpm run test:full_anvil
 ```
 
-#### ⚙️ For Operators (运营商)
+---
 
-```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"
-}
+## Development Guides / 开发指南
+
+### ABI Maintenance / ABI 维护
+- [ABI Maintenance Plan](./docs/ABI_MAINTENANCE_PLAN.md) - 合约 ABI 自动同步和维护策略
+
+---
+
+## Development Workflow / 开发者工作流
+
+A step-by-step guide for contributors from contract modification to Sepolia deployment.
+
+### Step 1: Modify Contracts / 修改合约
+Edit Solidity files in `superpaymaster/contracts/src`.
+```bash
+cd projects/SuperPaymaster
+# Edit .sol files...
 ```
 
-#### 📊 For Analysts (分析师)
+### 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
+```
 
-```typescript
-import { AnalyticsClient } from '@aastar/sdk';
+### Step 3: Run Local Tests / 运行本地测试
+Validate your changes with the full regression suite.
+```bash
+# Run all SDK & Protocol tests
+./run_sdk_regression.sh
+```
 
-const analytics = new AnalyticsClient(publicClient);
+### 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`.
 
-// Get real-time GToken metrics
-const metrics = await analytics.getSupplyMetrics();
-console.log(`Deflation Rate: ${metrics.deflationRate}%`);
+### 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
 ```
 
+
 ---
 
-## 🔧 Architecture | 架构
+## 📊 Gas Analytics & Reporting | Gas 分析与报表
+The SDK includes a powerful **Gas Analytics Module** for analyzing Paymaster efficiency, tracking costs, and generating industry comparison reports.
+SDK 包含一个强大的 **Gas 分析模块**，用于分析 Paymaster 效率、追踪成本并生成行业对比报告。
 
-AAstar SDK is built on top of **viem**, ensuring lightweight and type-safe interactions. It abstracts complex contract logic into intuitive business primitives.
+### Quick Start | 快速开始
+Generate a real-time analysis of recent Sepolia transactions:
+生成最近 Sepolia 交易的实时分析：
+```bash
+npx tsx packages/analytics/src/gas-analyzer-v4.ts
+```
 
-AAstar SDK 基于 **viem** 构建，确保轻量级和类型安全的交互。它将复杂的合约逻辑抽象为直观的业务原语。
+### Key Features | 核心功能
+- **Double-Layer Analysis (双层分析)**: Intrinsic EVM Efficiency vs. Economic USD Costs
+- **Industry Benchmarking (行业对标)**: Compare AAStar vs. Optimism, Alchemy, Pimlico
+- **Profit Tracking (利润追踪)**: Transparent breakdown of Protocol Revenue & Profit
+- **L2 Simulation (L2 模拟)**: Estimate savings for migrating UserOps to Optimism
 
-| 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 |
+👉 **[View Full Analytics Documentation | 查看完整分析文档](./packages/analytics/README.md)**
 
 ---
 
-## 🤝 Contributing | 贡献
+## Academic Research / 学术研究
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.  
-欢迎贡献！更多详情请参考 [贡献指南](CONTRIBUTING.md)。
+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`。
+
+- [Stage 3 Scenario Experiment Plan](./docs/STAGE_3_SCENARIO_EXP_PLAN.md)
+- [Reputation-to-Credit Mapping Whitepaper](./docs/Reputation-to-Credit_Mapping_Whitepaper.md) - 声誉与信用体系映射技术白皮书
 
 ---
 
-<p align="center">
-  Built with ❤️ by the AAstar Community
-</p>
+## Support / 支援
+
+- **Documentation**: [docs.aastar.io](https://docs.aastar.io)
+- **GitHub**: [AAStarCommunity/aastar-sdk](https://github.com/AAStarCommunity/aastar-sdk)
+
+MIT © AAStar Community

package/aastar-sdk.code-workspace

@@ -0,0 +1,14 @@
+{
+	"folders": [
+		{
+			"path": "."
+		},
+		{
+			"path": "../DSR-Research-Flow"
+		},
+		{
+			"path": "../SuperPaymaster"
+		}
+	],
+	"settings": {}
+}