AAStar SDK (Mycelium Network)

Comprehensive Account Abstraction Infrastructure SDK - Powering the Mycelium Network

🌐 中文版本 / Chinese Version

📚 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.

Installation

pnpm install @aastar/sdk @aastar/core viem

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'
});

🧰 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

🧪 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

🛡️ 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.16.23): 9b02e91aaae2081b68b8ddfcf4c3dd52d450b4f368a8746b5896e0024e441db7

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

📝 中文版本 / Chinese Version

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

简介

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 聚合、罚没机制与全局参数调整。

安装

pnpm install @aastar/sdk @aastar/core viem

快速开始

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'
});

🧰 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

🧪 配置与测试

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

📊 Gas 数据与学术研究

🛡️ 源码完整性校验

Important

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 521 Commits
.githooks		.githooks
backup		backup
config/networks		config/networks
data		data
docs		docs
examples		examples
ext		ext
lib		lib
packages		packages
scripts		scripts
tests		tests
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.gitmodules		.gitmodules
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
aastar-sdk-registry-demo-plugin.code-workspace		aastar-sdk-registry-demo-plugin.code-workspace
aastar-sdk.code-workspace		aastar-sdk.code-workspace
check-op-setup-result.sh		check-op-setup-result.sh
config.anvil.json		config.anvil.json
config.op-mainnet.json		config.op-mainnet.json
config.op-sepolia.json		config.op-sepolia.json
config.sepolia.json		config.sepolia.json
dry-run-publish.sh		dry-run-publish.sh
env.template		env.template
get_eoa_fast.ts		get_eoa_fast.ts
get_eoa_simulate.ts		get_eoa_simulate.ts
get_industry_l1gas.ts		get_industry_l1gas.ts
l4-setup.sh		l4-setup.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
publish.sh		publish.sh
run-keeper-main.sh		run-keeper-main.sh
run-optimism-tx-data.sh		run-optimism-tx-data.sh
run_l4_gasless_regression.sh		run_l4_gasless_regression.sh
run_sdk_regression.sh		run_sdk_regression.sh
sdk-abi-coverage.sh		sdk-abi-coverage.sh
sdk-build-and-test.sh		sdk-build-and-test.sh
sdk-test-coverage.sh		sdk-test-coverage.sh
simple-test-paymaster.sh		simple-test-paymaster.sh
simple-test-superpaymaster.sh		simple-test-superpaymaster.sh
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
update-version.sh		update-version.sh
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

AAStar SDK (Mycelium Network)

📚 Contents

Introduction

Architecture (L1-L4 Tiers)

Specialized Role Clients

Installation

Quick Start

1. End User: Gasless Transaction

2. Operator: Onboarding & Staking

🧰 Keeper (Service Maintenance)

Key Features

Common Commands

Development Workflow

Step 1: Modify Contracts

Step 2: Local Build & Deploy (Anvil)

Step 3: Run Local Tests

Step 4: Deploy to Sepolia

📂 Core Documentation Index

🏛 Architecture & APIs

🧪 Configuration & Testing

📊 Gas Analytics & Research

🛡️ Integrity Verification

📝 中文版本 / Chinese Version

📚 目录

简介

架构设计 (L1-L4 分层)

角色化客户端

安装

快速开始

1. End User: 免 Gas 交易

2. Operator: 入驻与质押

🧰 Keeper (服务维护)

核心特性

常用命令

开发工作流

第 1 步：修改合约

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

第 3 步：运行本地测试

第 4 步：部署到 Sepolia

📂 核心文档索引

🏛 架构与 API

🧪 配置与测试

📊 Gas 数据与学术研究

🛡️ 源码完整性校验

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages