Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network
- Introduction
- Architecture (L1-L4 Tiers)
- Installation
- Quick Start
- 🧰 Keeper (Service Maintenance)
- Development Workflow
- 📂 Core Documentation Index
- 🛡️ Integrity Verification
- 📝 中文版本 / Chinese Version
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.
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. |
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 (YAAAClient / YAAAServerClient): ERC-4337 smart accounts with KMS WebAuthn passkeys, BLS aggregate signatures, and tiered signature routing for AI agents and dApps.
pnpm install @aastar/sdk @aastar/core viem
# For AI Agent / AirAccount features (browser or server)
pnpm install @aastar/airaccountimport { 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
});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'
});import { YAAAClient } from '@aastar/airaccount';
const yaaa = new YAAAClient({
apiURL: 'https://api.your-backend.com/v1',
tokenProvider: () => localStorage.getItem('token'),
bls: { seedNodes: ['https://signer1.aastar.io'] },
});
// Register with KMS-backed passkey (biometric)
const { user, token } = await yaaa.passkey.register({
email: 'user@example.com',
username: 'JohnDoe',
});
// Verify a transaction with passkey
const verification = await yaaa.passkey.verifyTransaction({
to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
value: '0.01',
});import { YAAAServerClient, MemoryStorage, LocalWalletSigner } from '@aastar/airaccount/server';
const client = new YAAAServerClient({
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
scripts/keeper.ts is a production-grade price keeper used to automatically trigger updatePrice() when the on-chain price cache is near expiration.
- Dynamic Monitoring: Checks
cachedPrice()vs. Chainlink timestamps. - Background Execution: Supports
--backgroundmode with logging. - Alerting: Optional Telegram notifications for health beats and anomalies.
# 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 600A step-by-step guide for contributors from contract modification to Sepolia deployment.
Edit Solidity files in superpaymaster/contracts/src.
cd projects/aastar-sdk
./run_full_regression.sh --env anvil./run_sdk_regression.shConfigure .env.sepolia and run:
cd projects/SuperPaymaster/contracts
forge script script/DeployV3FullSepolia.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify --resumeTo 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
- 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 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
- 🚀 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
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.19.0): b39aef2a020061c37725d0e80295774dadadc7ff964fef723287bfc71520dbb5
git ls-files -z | grep -zvE '\.md$' | xargs -0 sha256sum | sha256sum综合账户抽象基础设施 SDK - 为 Mycelium 网络提供核心动力
AAStar SDK 是 Mycelium 网络的高集成度专业工具包。它将分散的 AA 基础设施整合为统一、高性能、可验证的开发体验，专为免 Gas 社区经济及自主代理（AI Agents）生态设计。
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 (YAAAClient / YAAAServerClient): 面向 AI Agent 与 Web3 应用，提供 KMS WebAuthn Passkey 认证、BLS 聚合签名、分层签名路由与 ERC-4337 智能账户。
pnpm install @aastar/sdk @aastar/core viem
# AI Agent / AirAccount 功能（浏览器或服务端）
pnpm install @aastar/airaccountimport { createEndUserClient } from '@aastar/sdk';
const user = createEndUserClient({ account, paymasterUrl: '...' });
// 通过基于名誉的信用限额执行免 Gas 交易
await user.submitGaslessUserOperation({
target: TARGET_ADDR,
data: CALL_DATA,
operator: SP_OPERATOR_ADDR
});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'
});import { YAAAClient } from '@aastar/airaccount';
const yaaa = new YAAAClient({
apiURL: 'https://api.your-backend.com/v1',
tokenProvider: () => localStorage.getItem('token'),
bls: { seedNodes: ['https://signer1.aastar.io'] },
});
// 使用 KMS Passkey（生物识别）注册
const { user, token } = await yaaa.passkey.register({
email: 'user@example.com',
username: 'JohnDoe',
});
// 使用 Passkey 验证交易
const verification = await yaaa.passkey.verifyTransaction({
to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
value: '0.01',
});import { YAAAServerClient, MemoryStorage, LocalWalletSigner } from '@aastar/airaccount/server';
const client = new YAAAServerClient({
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 大额 / 高价值
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 部署的逐步指南。
在 superpaymaster/contracts/src 中编辑 Solidity 文件。
cd projects/aastar-sdk
./run_full_regression.sh --env anvil./run_sdk_regression.sh配置 .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
- SDK 架构基准与 API 参考 (L1-L4)
- L2 业务客户端演进计划
- L3 全生命周期模式设计
- L3 开发者指南
- L3 完整演练指南
- L3 业务场景与缺口分析
- 首发账户初始化指南
- Demo 重构计划
- 技术架构演进方案
- 文档建设体系计划
- 环境配置与哈希同步机制 (Configuration Sync) (含版本哈希防篡改机制说明)
- L4 级别回归测试方案 (免 Gas 验证器) (项目最重要的测试准则)
- SDK 回归测试与 API 计划
- SDK 测试覆盖率策略
- 待办：SDK 测试覆盖
- 手动调试速查表
- 环境配置更新指南 (Sepolia)
- 合约 ABI 维护计划
- Sepolia 已验证合约地址 / OP-Sepolia 已验证合约地址
Important
安全第一：为确保您使用的是官方发布版本并保护您的私钥，请务必验证 SDK 源码的完整性。
当前代码哈希 (v0.17.2)：9b02e91aaae2081b68b8ddfcf4c3dd52d450b4f368a8746b5896e0024e441db7
git ls-files -z | grep -zvE '\.md$' | xargs -0 sha256sum | sha256sumMIT © AAStar Community / AAStar 社区