AAStar SDK (Mycelium Network)

Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network

🌐 中文版本 / Chinese Version

---

🔗 Integration Infrastructure & Upstream Version Pins

This SDK integrates four upstream AAStar infrastructure stacks. Each MUST be kept in lockstep with that upstream's latest GitHub release — a version mismatch silently breaks on-chain calls (wrong ABI/selector), points at stale contract addresses, or breaks the DVT co-sign wire format.

Upstream	Pinned version	Releases	Source of truth in this SDK
AirAccount (contracts)	v0.20.0	airaccount-contract	ABIs packages/core/src/abis/AAStarAirAccount*.json · addresses packages/core/src/addresses.ts
SuperPaymaster	v5.4.0-beta.1-redeploy	SuperPaymaster	ABIs packages/core/src/abis/{SuperPaymaster,Registry,PolicyRegistry,X402Facilitator,BLSAggregator,…}.json · addresses
KMS	openapi 0.23.2	AirAccount	HTTP client packages/airaccount/src/server/services/kms-*.ts (spec: AirAccount/kms/docs/api/openapi.yaml)
DVT (validator nodes)	v1.5.0	YetAnotherAA-Validator	combined-sig wire packages/core/src/crypto/dvtWire.ts + node /signature/sign client (pending_confirmation surfaced via DvtPendingConfirmationError); on-chain verifier AAStarBLSAlgorithm (the SDK calls DVT nodes to co-sign account UserOps); default testnet nodes DEFAULT_DVT_NODES (packages/core/src/crypto/dvtNodes.ts). v1.5.0 wire-format unchanged vs v1.4.0 (radar-verified in-sync) — v1.5.0 adds the always-on testnet nodes (dvt1/2/3.aastar.io) + clone-and-deploy package; per-IP rate-limit + confirm flow are server-side (#82).

How consistency is guaranteed — the anchors:

1. ABI files — every contract ABI is vendored under packages/core/src/abis/ (ESLint forbids inline parseAbi). The doc-coverage checker (scripts/coverage/check-doc-coverage.ts) asserts 100% of each upstream's ABI/API surface has an SDK wrapper, and an ABI-absent-wrapper audit ensures no wrapper calls a function missing from its ABI.
2. Version pin — the table above + the addresses.ts header comments record the exact upstream version each sync targets.
3. Contract addresses — packages/core/src/addresses.ts (CANONICAL_ADDRESSES) is the single source of truth; pnpm run check:addresses fails if the per-network config.*.json drift from it.
4. API docs — the KMS openapi.yaml is the HTTP-layer contract; the coverage checker asserts every endpoint is referenced by a kms-* service.
5. DVT wire — dvtWire.ts encodes the combined signature in the node/verifier's exact byte format; golden vectors assert it byte-for-byte against live on-chain txs (the node's buildBlsComponents + the deployed AAStarBLSAlgorithm).

Detecting drift: the upstream radar (scripts/upstream/upstream-radar.ts) diffs all four anchors per upstream against the first-hand local repos and exits non-zero on any drift. Run it as pnpm run upstream:check (or pnpm run upstream:rehearse for the gate run + upgrade worklist), via the /upstream-sync Claude Code slash command, or automatically through the daily .github/workflows/upstream-watch.yml. See docs/UPSTREAM-SYNC.md.

⚠️ Every upstream release REQUIRES a sync PR (ABIs + version pin + addresses + API docs) before this SDK can claim compatibility. This is a mandatory release step — see docs/RELEASE-CHECKLIST.md.

---

📚 Contents

• Introduction
• Architecture (L1-L4 Tiers)
• Installation
• Quick Start
• 🧰 Keeper (Service Maintenance)
• Development Workflow
• 📂 Core Documentation Index
• 🛡️ Integrity Verification
• 📝 中文版本 / Chinese Version

---

Introduction

AAStar SDK is a professional-grade toolkit for the Mycelium network. It consolidates fragmented AA infrastructure into a unified, high-performance, and verifiable development experience, specifically designed for gasless community economies and autonomous agent ecosystems.

---

Architecture (L1-L4 Tiers)

The SDK follows a layered abstraction model to balance control and ease of use:

Tier	Name	Target	Description
L1	Base API	Protocol Engineers	Raw contract wrappers (Registry, Paymaster, SBT).
L2	Workflows	Integrators	Atomic tasks (e.g., onboardOperator, deployXPNTs).
L3	Scenarios	dApp Developers	End-to-end journeys (e.g., submitGaslessUserOperation).
L4	Regression	QA / Researchers	Full system lifecycle verification on Anvil or Optimism Mainnet.

Specialized Role Clients

• EndUserClient: Gasless UX, Smart Account management, Credit queries.
• CommunityClient: Auto-onboarding, xPNTs deployment, SBT & Reputation management.
• OperatorClient: SuperPaymaster registration, Staking, Pool management.
• AdminClient: DVT aggregations, Slashing, Global protocol parameters.
• AirAccount (AirAccountClient / AirAccountServerClient): ERC-4337 smart accounts with KMS WebAuthn passkeys, BLS aggregate signatures, and tiered signature routing for AI agents and dApps.

---

Installation

pnpm install @aastar/sdk viem

@aastar/sdk is the single published package — it bundles the whole SDK and exposes everything through subpaths (the per-package @aastar/core, @aastar/airaccount, … are private and NOT published separately; do not install them):

import { createEndUserClient, CANONICAL_ADDRESSES } from '@aastar/sdk';        // core + clients
import { coseToP256XY, airAccountExtensionActions } from '@aastar/sdk';         // P-256 guardian surface
import { AirAccountClient } from '@aastar/sdk/airaccount';                       // AirAccount client
import { AccountManager } from '@aastar/sdk/kms';                               // KMS server-client
// other subpaths: @aastar/sdk/core · /paymaster · /identity · /tokens · /dapp · /enduser · /operator · /admin · /x402 · /channel

---

Quick Start

1. End User: Gasless Transaction

import { createEndUserClient } from '@aastar/sdk';

const user = createEndUserClient({ account, paymasterUrl: '...' });

// Execute gasless via reputation-backed credit
await user.submitGaslessUserOperation({
  target: TARGET_ADDR,
  data: CALL_DATA,
  operator: SP_OPERATOR_ADDR
});

2. Operator: Onboarding & Staking

import { createOperatorClient } from '@aastar/sdk';

const operator = createOperatorClient({ account, chain });

// Handles GToken approval, staking, and paymaster deposit in one L2 workflow
await operator.onboardOperator({
  stakeAmount: parseEther('100'),
  depositAmount: parseEther('10'),
  roleId: 'PAYMASTER_SUPER_ROLE_ID'
});

3. AirAccount: Smart Account with Passkey (Browser)

import { AirAccountClient } from '@aastar/sdk/airaccount';

// `apiURL` is the passkey RP backend. AAStar's official hosted RP will be
// `https://auth.aastar.io` (served by aNode); you can also point at your own.
const air = new AirAccountClient({
  apiURL: 'https://auth.aastar.io',
  tokenProvider: () => localStorage.getItem('token'),
  bls: { seedNodes: ['https://signer1.aastar.io'] },
});

// Register with KMS-backed passkey (biometric)
const { user, token } = await air.passkey.register({
  email: 'user@example.com',
  username: 'JohnDoe',
});

// Verify a transaction with passkey
const verification = await air.passkey.verifyTransaction({
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  value: '0.01',
});

4. AirAccount: Smart Account with Tiered Signatures (Server / AI Agent)

import { AirAccountServerClient, MemoryStorage, LocalWalletSigner } from '@aastar/sdk/kms';

const client = new AirAccountServerClient({
  rpcUrl: 'https://optimism.rpc-url',
  bundlerRpcUrl: 'https://bundler-url',
  chainId: 10,
  entryPoints: {
    v07: {
      entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
      factoryAddress: '0x914db0a849f55e68a726c72fd02b7114b1176d88',
    },
  },
  defaultVersion: '0.7',
  storage: new MemoryStorage(),
  signer: new LocalWalletSigner('0xYOUR_PRIVATE_KEY'),
});

// Create a smart account for an AI agent
const account = await client.accounts.createAccount('agent-001');

// Execute a gasless transfer (Tier 1: ECDSA for small amounts)
const result = await client.transfers.executeTransfer('agent-001', {
  to: '0xRecipient',
  amount: '0.01',
  usePaymaster: true,
});

Signature Tiers (M4 AirAccount)

Tier	Components	Use Case
1	Raw ECDSA	Small transactions
2	P256 + BLS aggregate	Medium transactions
3	P256 + BLS + Guardian	Large / high-value

---

🧰 Keeper (Service Maintenance)

scripts/keeper.ts is a production-grade price keeper used to automatically trigger updatePrice() when the on-chain price cache is near expiration.

Key Features

• Dynamic Monitoring: Checks cachedPrice() vs. Chainlink timestamps.
• Background Execution: Supports --background mode with logging.
• Alerting: Optional Telegram notifications for health beats and anomalies.

Common Commands

# Dry run check (No transaction)
pnpm exec tsx scripts/keeper.ts --network op-sepolia --once --dry-run

# Continuous polling (Every 30s)
pnpm exec tsx scripts/keeper.ts --network op-sepolia --poll-interval 30 --safety-margin 600

---

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.

Step 2: Local Build & Deploy (Anvil)

cd projects/aastar-sdk
./run_full_regression.sh --env anvil

Step 3: Run Local Tests

./run_sdk_regression.sh

Step 4: Deploy to Sepolia

Configure .env.sepolia and run:

cd projects/SuperPaymaster/contracts
forge script script/DeployV3FullSepolia.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify --resume

---

📂 Core Documentation Index

To ensure seamless navigation and rapid reference, all critical documentation is stored locally in the docs/ folder instead of requiring external web access.

🌐 Online Documentation Site: For a fully structured and searchable reading experience, you can also visit: docs.aastar.io

🏛 Architecture & APIs

• SDK API Reference & Architecture (L1-L4)
• L2 Business Clients Plan
• L3 Lifecycle Patterns Design
• L3 Lifecycle Developer Guide
• L3 Complete Walkthrough
• L3 Use Case Analysis
• Account Initialization Guide
• Demo Refactor Plan
• Technical Architecture Plan
• Documentation Plan

🧪 Configuration & Testing

• Configuration Sync Guide (Explains Integrity Hash generation)
• Full L4 Test Regression Plan (Gasless Verifier workflow)
• SDK Regression & API Plan
• SDK Coverage Strategy
• TODO: SDK Coverage
• Manual Test CheatSheet
• Environment Update Guide (Sepolia)
• ABI Maintenance Plan
• Sepolia Verified Contracts / OP-Sepolia Verified Contracts

📊 Gas Analytics & Research

• 🚀 OP Mainnet Gas Analysis Report
• Reputation-to-Credit Mapping Whitepaper
• DAO Mining Distribution Plan
• Academic Application: Paper Data Collection
• Stage 3 Scenario Experiment Plan / Stage 3 Analysis

---

🛡️ Integrity Verification

Important

Security First: To ensure you are using an official release and protect your private keys, always verify the integrity of the SDK code.

Current Code Integrity Hash (v0.26.6): 335319fc7df9dcfaf5e6072fe8862455cf4fb5314fd712909d779ae78f572d40

git ls-files -z | grep -zvE '\.md$' | xargs -0 sha256sum | sha256sum

---

---

📝 中文版本 / Chinese Version

综合账户抽象基础设施 SDK - 为 Mycelium 网络提供核心动力

---

📚 目录

• 简介
• 架构设计 (L1-L4 分层)
• 安装
• 快速开始
• 🧰 Keeper (服务维护)
• 开发工作流
• 📂 核心文档索引
• 🛡️ 源码完整性校验

---

简介

AAStar SDK 是 Mycelium 网络的高集成度专业工具包。它将分散的 AA 基础设施整合为统一、高性能、可验证的开发体验，专为免 Gas 社区经济及自主代理（AI Agents）生态设计。

---

架构设计 (L1-L4 分层)

SDK 采用分层抽象模型，平衡了控制灵活性与易用性：

层级	名称	目标群体	描述
L1	基础 API	协议工程师	原始合约包装器 (Registry, Paymaster, SBT)，直接映射 Solidity 函数。
L2	工作流	集成方	组合多个调用的原子任务 (如：onboardOperator, deployXPNTs)。
L3	业务场景	DApp 开发者	端到端用户流程 (如：submitGaslessUserOperation)。
L4	回归测试	QA / 研究员	在 Anvil 或 Optimism 主网进行的系统全生命周期验证。

角色化客户端

• EndUserClient: 面向 DApp 开发者，提供免 Gas 交互、智能账户管理与信用查询。
• CommunityClient: 面向社区/DAO 管理员，支持自动入驻、xPNTs 部署与身份名誉管理。
• OperatorClient: 面向节点运营方，支持 SuperPaymaster 注册、质押与资金池管理。
• AdminClient: 面向协议管理方，支持 DVT 聚合、罚没机制与全局参数调整。
• AirAccount (AirAccountClient / AirAccountServerClient): 面向 AI Agent 与 Web3 应用，提供 KMS WebAuthn Passkey 认证、BLS 聚合签名、分层签名路由与 ERC-4337 智能账户。

---

安装

pnpm install @aastar/sdk viem

@aastar/sdk 是唯一发布的包——它打包了整个 SDK,通过子路径暴露全部能力(各子包 @aastar/core、 @aastar/airaccount… 均为 private、不单独发布,请勿安装):@aastar/sdk/airaccount(AirAccount 客户端)、 @aastar/sdk/kms(KMS server-client)、@aastar/sdk/core、/paymaster、/dapp 等。

---

快速开始

1. End User: 免 Gas 交易

import { createEndUserClient } from '@aastar/sdk';
const user = createEndUserClient({ account, paymasterUrl: '...' });

// 通过基于名誉的信用限额执行免 Gas 交易
await user.submitGaslessUserOperation({
  target: TARGET_ADDR,
  data: CALL_DATA,
  operator: SP_OPERATOR_ADDR
});

2. Operator: 入驻与质押

import { createOperatorClient } from '@aastar/sdk';
const operator = createOperatorClient({ account, chain });

// 在一个 L2 工作流中完成 GToken 授权、质押和 Paymaster 存款
await operator.onboardOperator({
  stakeAmount: parseEther('100'),
  depositAmount: parseEther('10'),
  roleId: 'PAYMASTER_SUPER_ROLE_ID'
});

3. AirAccount: Passkey 智能账户（浏览器）

import { AirAccountClient } from '@aastar/sdk/airaccount';

// `apiURL` 为 passkey RP 后端。AAStar 官方托管 RP 将是 `https://auth.aastar.io`
// （由 aNode 提供）；你也可以指向自建后端。
const air = new AirAccountClient({
  apiURL: 'https://auth.aastar.io',
  tokenProvider: () => localStorage.getItem('token'),
  bls: { seedNodes: ['https://signer1.aastar.io'] },
});

// 使用 KMS Passkey（生物识别）注册
const { user, token } = await air.passkey.register({
  email: 'user@example.com',
  username: 'JohnDoe',
});

// 使用 Passkey 验证交易
const verification = await air.passkey.verifyTransaction({
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  value: '0.01',
});

4. AirAccount: 分层签名智能账户（服务端 / AI Agent）

import { AirAccountServerClient, MemoryStorage, LocalWalletSigner } from '@aastar/sdk/kms';

const client = new AirAccountServerClient({
  rpcUrl: 'https://optimism.rpc-url',
  bundlerRpcUrl: 'https://bundler-url',
  chainId: 10,
  entryPoints: {
    v07: {
      entryPointAddress: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
      factoryAddress: '0x914db0a849f55e68a726c72fd02b7114b1176d88',
    },
  },
  defaultVersion: '0.7',
  storage: new MemoryStorage(),
  signer: new LocalWalletSigner('0xYOUR_PRIVATE_KEY'),
});

// 为 AI Agent 创建智能账户
const account = await client.accounts.createAccount('agent-001');

// 执行免 Gas 转账（Tier 1：小额 ECDSA）
const result = await client.transfers.executeTransfer('agent-001', {
  to: '0xRecipient',
  amount: '0.01',
  usePaymaster: true,
});

M4 AirAccount 分层签名说明

层级	签名组合	适用场景
Tier 1	原始 ECDSA	小额交易
Tier 2	P256 + BLS 聚合	中等金额
Tier 3	P256 + BLS + Guardian	大额 / 高价值

---

🧰 Keeper (服务维护)

scripts/keeper.ts 是生产级的价格守护进程，用于在链上价格缓存临近过期时自动触发 updatePrice()。

核心特性

• 动态监控：检查 cachedPrice() 与 Chainlink 时间戳。
• 后台运行：支持 --background 模式并记录日志。
• 预警通知：支持通过 Telegram 发送心跳通知与异常告警。

常用命令

# 只读检查 (不发送交易)
pnpm exec tsx scripts/keeper.ts --network op-sepolia --once --dry-run

# 持续轮询 (每 30 秒)
pnpm exec tsx scripts/keeper.ts --network op-sepolia --poll-interval 30 --safety-margin 600

---

开发工作流

本文档为贡献者提供了从合约修改到 Sepolia 部署的逐步指南。

第 1 步：修改合约

在 superpaymaster/contracts/src 中编辑 Solidity 文件。

第 2 步：本地构建与部署 (Anvil)

cd projects/aastar-sdk
./run_full_regression.sh --env anvil

第 3 步：运行本地测试

./run_sdk_regression.sh

第 4 步：部署到 Sepolia

配置 .env.sepolia 并运行：

cd projects/SuperPaymaster/contracts
forge script script/DeployV3FullSepolia.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify --resume

---

📂 核心文档索引

为了确保您可以快速查阅与定位问题，所有核心文档均直接保存在项目本地的 docs/ 文件夹中。您无需跳转外部链接即可深入了解 SDK 的底层机制。

🌐 在线文档站点： 若需更完善的侧边栏索引与搜索体验，您也可以访问官方站点：docs.aastar.io

🏛 架构与 API

• SDK 架构基准与 API 参考 (L1-L4)
• L2 业务客户端演进计划
• L3 全生命周期模式设计
• L3 开发者指南
• L3 完整演练指南
• L3 业务场景与缺口分析
• 首发账户初始化指南
• Demo 重构计划
• 技术架构演进方案
• 文档建设体系计划

🧪 配置与测试

• 环境配置与哈希同步机制 (Configuration Sync) (含版本哈希防篡改机制说明)
• L4 级别回归测试方案 (免 Gas 验证器) (项目最重要的测试准则)
• SDK 回归测试与 API 计划
• SDK 测试覆盖率策略
• 待办：SDK 测试覆盖
• 手动调试速查表
• 环境配置更新指南 (Sepolia)
• 合约 ABI 维护计划
• Sepolia 已验证合约地址 / OP-Sepolia 已验证合约地址

📊 Gas 数据与学术研究

• 🚀 OP 主网 Gas 数据分析报告
• 名誉到信用映射白皮书
• DAO 挖矿与分发机制设计
• 学术研究：论文数据采集
• Stage 3 场景实验计划 / Stage 3 结论分析

---

🛡️ 源码完整性校验

Important

安全第一：为确保您使用的是官方发布版本并保护您的私钥，请务必验证 SDK 源码的完整性。

当前代码哈希 (v0.17.2)：9b02e91aaae2081b68b8ddfcf4c3dd52d450b4f368a8746b5896e0024e441db7

git ls-files -z | grep -zvE '\.md$' | xargs -0 sha256sum | sha256sum

---

MIT © AAStar Community / AAStar 社区

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.