Decentralized Payment & Gas Sponsorship Infrastructure for ERC-4337
v5.3.3-beta.2 (Security-Hardened Beta · Core Gasless) — Sepolia Testnet Live · Release Notes · Integration Guide · Coverage Report
SuperPaymaster is a multi-mode payment infrastructure for the ERC-4337 Account Abstraction ecosystem. It goes beyond simple gas sponsorship — combining gasless transactions, x402 resource payments, micropayment channels, and AI agent economy into a unified on-chain settlement layer.
Research paper: Huifeng Jiao, Nathapon Udomlertsakul. "SuperPaymaster: Eliminating Centralized Signer Authority via Asset-Oriented Abstraction to Reconcile Usability and Decentralization in Account Abstraction" — arXiv:2605.05774. Introduces Asset-Oriented Abstraction (AOA), anchoring sponsorship authority in on-chain Gas Cards instead of off-chain signers; ~49% gas reduction vs. commercial baselines on Optimism Mainnet.
- Communities: Sponsor gas fees for members using community tokens (xPNTs)
- AI Agents: Discover and pay for on-chain services via ERC-8004 identity + x402
- Developers: Integrate gasless UX, micropayments, or x402 settlement with battle-tested contracts
- Operators: Run decentralized paymaster nodes with DVT/BLS consensus
SuperPaymaster supports 4 payment channels in a single contract system:
| Mode | Protocol | Description | Since |
|---|---|---|---|
| Gas Sponsorship | ERC-4337 | Operators pre-fund aPNTs; users pay zero gas, repay in xPNTs (community tokens) | V3 |
| x402 Settlement (contracts live; SDK signing integrating) | HTTP 402 + EIP-3009 | Single-payment resource purchases — client pays USDC/xPNTs per request | V5.1 |
| Micropayment Channel | EIP-712 Vouchers | Streaming micro-charges with off-chain signing and batch on-chain settlement | V5.2 |
| Agent Sponsorship | ERC-8004 | Reputation-driven tiered gas sponsorship for registered AI agents | V5.3 |
- AOA+ Mode (SuperPaymaster): Shared multi-operator paymaster with Registry-based community management
- AOA Mode (PaymasterV4): Independent per-community paymasters deployed via EIP-1167 minimal proxy factory
┌──────────────────────────────────┐
│ EntryPoint v0.7 │
│ (ERC-4337 Standard) │
└──────────┬───────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌───────────┐ ┌──────────────────┐
│ SuperPaymaster │ │ Paymaster │ │ MicroPayment │
│ (AOA+ Shared) │ │ V4 (AOA) │ │ Channel │
│ ┌──────────────┐ │ │ EIP-1167 │ │ EIP-712 Vouchers │
│ │ Gas Sponsor │ │ │ Proxies │ │ Batch Settle │
│ │ x402 Settle │ │ └───────────┘ └──────────────────┘
│ │ Agent Policy │ │
│ │ Credit/Debt │ │
│ └──────────────┘ │
└────────┬──────────┘
│
┌────────┼──────────────────────────────────┐
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ │
│ │Registry │ │ MySBT │ │ GToken │ │
│ │ (UUPS) │ │ (SBT) │ │ Staking │ │
│ └─────────┘ └─────────┘ └───────────┘ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────────┐ │
│ │xPNTs │ │ Reputation │ │
│ │Factory │ │ System │ │
│ └──────────┘ └──────────────┘ │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │DVT │ │ BLS │ │
│ │Validator │ │ Aggregator │ │
│ └──────────┘ └──────────────┘ │
└───────────────────────────────────────────┘
Supporting Contracts
| Contract | Version | Type | Role |
|---|---|---|---|
| SuperPaymaster | 5.3.0 | UUPS Proxy | AOA+ shared paymaster — gas sponsorship, x402, agent policies, credit/debt |
| Registry | 4.1.0 | UUPS Proxy | Community/node registration, role management, BLS replay protection, slashing |
| PaymasterV4 | 4.3.0 | EIP-1167 Proxy | AOA independent paymaster per community |
| GToken | 2.0.0 | ERC20 | Governance token (21M cap, mintable, burnable) |
| GTokenStaking | 3.2.0 | Immutable | Role-based staking with burn mechanism, DVT/governance slashing |
| MySBT | 3.1.3 | ERC721 (Soulbound) | Identity + reputation, community membership, SBT-gated sponsorship |
| xPNTsFactory | 2.0.0 | Clones | Deploys per-community xPNTs gas tokens |
| ReputationSystem | 1.0.0 | — | Community-rule-based reputation scoring |
| BLSAggregator | 1.0.0 | — | BLS12-381 threshold signature aggregation |
| DVTValidator | 1.0.0 | — | Distributed validator consensus (7-of-13 quorum) |
| PaymasterFactory | 1.0.0 | — | EIP-1167 proxy factory for PaymasterV4 instances |
V5.1 — x402 Settlement (contracts live; @aastar/x402 SDK signing integrating — aastar-sdk#39)
settleX402Payment()— EIP-3009transferWithAuthorizationfor USDC-native settlement; recipient bound into the nonce (C-03)settleX402PaymentDirect()— xPNTs settle gated by a payer EIP-712X402PaymentAuthorizationsignature (C-02) + factory/facilitator whitelistchargeMicroPayment()(off-path metered charge) — designed, not deployed; the session/limited-payment use case is covered by AirAccount Session Keys at the account layer (see division of labor below)
V5.2 — Micropayment Channel
MicroPaymentChannelcontract — open/sign/settle streaming sessions- EIP-712 cumulative voucher signing with dispute window
- Batch settlement for high-frequency micro-charges
V5.3 — Agent Economy (ERC-8004)
- Dual-channel eligibility: SBT holders OR registered AI agents
AgentSponsorshipPolicy— per-operator tiered BPS rates + daily USD cap_submitSponsorshipFeedback()— on-chain reputation feedback loop- EIP-1153 transient storage cache for same-operator batch optimization
SuperPaymaster is the settlement & gas-sponsorship layer — it pairs with AirAccount (the account layer) rather than duplicating it:
| Concern | Layer | Owner |
|---|---|---|
| WHO can sign & WITH what limits (passkey, session keys, target/selector/velocity/quota, recovery) | Account | AirAccount |
| WHO pays gas & HOW it settles (gasless sponsorship, xPNTs credit/debt, reputation pricing, x402 + channel settlement) | Settlement | SuperPaymaster |
This is why SuperPaymaster does not implement spending-limit or session-payment logic — those
are enforced by AirAccount Session Keys at the account, and SuperPaymaster sponsors & settles.
Announcement copy (Twitter / Discord / blog): docs/announcements/.
- UUPS Upgradeable Proxies for Registry and SuperPaymaster
- ReentrancyGuard on all state-changing functions
- Two-tier slashing: aPNTs (operational) + GToken stake (governance)
- DVT/BLS consensus: 7-of-13 Byzantine quorum for validator operations
- Chainlink oracle with staleness check, price bounds ($100–$100K), and keeper cache
- Zero-address guards on all setter functions (L-04 audit fix)
- BLS replay protection with non-zero proposalId enforcement (H-02 audit fix)
- CEI order in postOp with nonReentrant double protection (H-01 audit fix)
v5.3.3-beta.2 security hardening (6 audit fixes, all on-chain-verified — see Coverage Report):
- C-01 balance-aware credit ceiling · C-02 signed x402 direct settle (EIP-712
X402PaymentAuthorization) - C-03 recipient-bound EIP-3009 nonce · C-04 postOp out-of-gas floor (
MIN_POST_OP_GAS) - H-01 chunked
retryPendingDebt· H-02 PoP-gated permissionless BLS registration (switch default OFF)
# Clone and init submodules
git clone https://github.com/AAStarCommunity/SuperPaymaster.git
cd SuperPaymaster
./init-submoduel.sh
# Build
forge build
# Run all tests (400+ tests)
forge test
# Run specific test suite
forge test --match-path contracts/test/v3/Registry.t.sol
# Run with gas report
forge test --gas-report
# Echidna fuzz testing
echidna . --config echidna.yaml# Deploy to local Anvil
./deploy-core anvil
# Deploy to Sepolia
./deploy-core sepolia
# Prepare test accounts
./prepare-test sepolia
# Run E2E gasless tests
cd script/gasless-tests && pnpm install && ./run-all-tests.shFor secure mainnet deployment with Foundry Keystore, see Deployment Guide.
v5.3.3-beta.2deployment. Always read live addresses fromdeployments/config.sepolia.json.
| Contract | Proxy | Implementation |
|---|---|---|
| Registry | 0xB5Fb8920F7AcD8b395934bd1F21222b32A30eF1A |
0xC931F91D134A16cCDfe4bf37EdEff217c9f193F1 |
| SuperPaymaster | 0xFb090E82bD041C6e9787eDEbE1D3BE55b3c7266a |
0x52C1E6f039eb9BA50ac9Ad0D041cB07Dcf4C9AA0 |
| ReputationSystem | — | 0xDD4D6162F426998E8B8FC97D0a8a5912cd70e6E0 |
| GToken | — | 0x46B82966f8a40f0Bbb8C13aCfBA746631CC2ec72 |
| GTokenStaking | — | 0x574820E26Acb7D9a1202708C6183d6A8aC957dA6 |
| MySBT | — | 0x754CeB687aCFC72136B02a1cb7cE2F911B63F1f8 |
| xPNTsFactory | — | 0xC4f5A121c426734CC1c0DbE57f6A2Dd764E278e4 |
| PaymasterFactory | — | 0x60B8f728Abca14B82a4EC72f00Ff5437e0702e90 |
| BLSAggregator | — | 0x7ec72505220a13040c80EF2B895Bf3405b6ed3e9 |
| DVTValidator | — | 0xB60C82158734def92D0d2163C93927cf19b86a95 |
| MicroPaymentChannel | — | 0xbD1807328Dd654512B13d6320C9Cc78685a405Ed |
EntryPoint v0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032
Mainnet: Pending audit — deployment after Beta stabilization.
- Contract Architecture — Dependency graph, data structures, constructor params
- UUPS Upgrade Guide — Storage layout, upgrade flow, security analysis, knowledge base
- DVT + BLS Architecture — Decentralized validator technology & BLS signature aggregation
- Oracle Failover Mechanism — Chainlink degradation & DVT auto-switch
- Price Cache Technical Reference — Price cache implementation details
- Registry Role Mechanism — Role configuration, management, exit fees
- Admin Configuration Rights — Permission matrix for admin operations
- Credit System Design — User credit/debt system architecture
- Contract Version Map — On-chain version mapping & governance roadmap
- V5 Design Document —
_consumeCredit(), x402 settlement, ERC-8004 integration - V5 Roadmap — Evolution from gas sponsorship to Agent Economy
- V5 Implementation Plan — 16-week schedule, worktree strategy, milestone tracking
- V5.1 Plan — Agent-Native Gas Sponsorship &
chargeMicroPayment() - V5.2 Plan — x402 Facilitator + MicroPaymentChannel
- V5.3 Plan — ERC-8004 Agent Discovery + SKILL.md + CLI
- V5 Acceptance Report — Feature verification & test results
- x402 Ecosystem Research — Coinbase x402, Cloudflare Workers, settlement methods
- Agent + x402 + Micropayment Research — Agent economy & payment channel design
- Spores Protocol Design — Decentralized revenue sharing network
- Beta Integration Guide (v5.3.3-beta.2) — beta entry: ready vs pending (x402), prerequisites,
dryRunValidationpre-flight - Developer Integration Guide — Gasless, x402, micropayment scenarios
- SDK x402 Integration — EIP-3009 + direct settle signing (post-C-02)
- SDK E2E Scenario Guide — 7 complete user scenarios
- Ecosystem Services Setup — Operator node, facilitator, keeper
- Registry v4.1 SDK Migration — Interface changes, viem examples, error mapping
- Deployment Guide — Secure deployment with Foundry Keystore
- MySBT User Guide — Minting and managing SBT tokens
- Community Registration — Registering your community
- Paymaster Operator Guide — Operating AOA/AOA+ paymasters
- SuperPaymaster API (V5.3.0)
- Registry API (V4.1.0)
- MySBT API
- Security Policy — Vulnerability reporting
- Security PGP — PGP keys & bug bounty
- Challenger Review — Adversarial review report
- Kimi AI Audit Report — Full security audit
- Codeex Audit — Static analysis & doc consistency audit
- Anvil Testing Guide — Local Anvil environment setup
- E2E Test Guide — End-to-end Sepolia test suite
- Gasless Test Guide — Testing gasless transactions
SuperPaymaster/
├── contracts/
│ ├── src/
│ │ ├── paymasters/
│ │ │ ├── superpaymaster/v3/ # SuperPaymaster (UUPS)
│ │ │ └── v4/ # PaymasterV4 (AOA mode)
│ │ ├── core/
│ │ │ ├── Registry.sol # Community registry (UUPS)
│ │ │ ├── GTokenStaking.sol # Staking + slashing
│ │ │ └── PaymasterFactory.sol # EIP-1167 factory
│ │ ├── tokens/
│ │ │ ├── GToken.sol # Governance token
│ │ │ ├── MySBT.sol # Soulbound identity
│ │ │ ├── xPNTsFactory.sol # Community token factory
│ │ │ └── xPNTsToken.sol # Community gas token
│ │ ├── modules/
│ │ │ ├── validators/ # BLS validator
│ │ │ ├── monitoring/ # DVT + BLS aggregator
│ │ │ └── reputation/ # Reputation system
│ │ └── interfaces/ # Contract interfaces
│ ├── test/ # 400+ Foundry tests
│ ├── script/ # Forge deployment scripts
│ └── lib/ # Dependencies (OZ, Chainlink, Solady)
├── script/
│ └── gasless-tests/ # E2E Sepolia test suite
├── deployments/ # Config per network
├── docs/ # All documentation
├── abis/ # Extracted ABI JSONs
└── subgraph/ # The Graph indexing
- 400+ Foundry tests passing (including UUPS upgrade, V5 feature, fuzz tests)
- Echidna property-based fuzzing
- Internal adversarial review completed
- External audit pending for mainnet deployment
Report a Vulnerability: jason@aastar.io or david@aastar.io — see Security Policy
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Run tests:
forge test - Commit:
git commit -m 'feat: Add amazing feature' - Open a Pull Request
Code style: forge fmt — Solidity 0.8.33, comments in English.
- Website: aastar.io
- Dashboard: superpaymaster.aastar.io
- GitHub: AAStarCommunity
- Registry Frontend: AAStarCommunity/registry
This project is licensed under the Apache License, Version 2.0.
Copyright 2024-present MushroomDAO Contributors.
See NOTICE · TRADEMARK.md · LICENSE-zh.md · TRADEMARK-zh.md for details.
Beta 0.22 (内部版本: V5.3) — Sepolia 测试网运行中
SuperPaymaster 是 ERC-4337 账户抽象生态的多模式支付基础设施。它不仅仅是 Gas 赞助——而是将无 Gas 交易、x402 资源支付、微支付通道和 AI Agent 经济统一到一个链上结算层中。
研究论文: Huifeng Jiao, Nathapon Udomlertsakul. "SuperPaymaster: Eliminating Centralized Signer Authority via Asset-Oriented Abstraction to Reconcile Usability and Decentralization in Account Abstraction" — arXiv:2605.05774。提出资产导向抽象 (AOA),将 Gas 赞助权限锚定在链上 Gas Card 而非链下签名服务;在 Optimism 主网相比商业基线降低约 49% gas 成本。
- 社区: 用社区代币 (xPNTs) 为成员赞助 Gas 费
- AI Agent: 通过 ERC-8004 身份 + x402 发现并支付链上服务
- 开发者: 集成无 Gas UX、微支付或 x402 结算
- 运营商: 运行去中心化 Paymaster 节点(DVT/BLS 共识)
| 模式 | 协议 | 描述 | 版本 |
|---|---|---|---|
| Gas 赞助 | ERC-4337 | 运营商预存 aPNTs,用户零 Gas 交易,以 xPNTs 偿还 | V3 |
| x402 结算 | HTTP 402 + EIP-3009 | 单次资源购买 — USDC/xPNTs 按请求付费 | V5.1 |
| 微支付通道 | EIP-712 凭证 | 流式微额扣费,链下签名 + 批量链上结算 | V5.2 |
| Agent 赞助 | ERC-8004 | 基于声誉的分级 Gas 赞助(注册 AI Agent) | V5.3 |
- AOA+ 模式 (SuperPaymaster): 共享多运营商 Paymaster,Registry 管理社区
- AOA 模式 (PaymasterV4): 每社区独立 Paymaster,EIP-1167 最小代理工厂部署
| 合约 | 版本 | 类型 | 职责 |
|---|---|---|---|
| SuperPaymaster | 5.3.0 | UUPS 代理 | AOA+ 共享 Paymaster — Gas 赞助、x402、Agent 策略、信用/债务 |
| Registry | 4.1.0 | UUPS 代理 | 社区/节点注册、角色管理、BLS 重放保护、惩罚 |
| PaymasterV4 | 4.3.0 | EIP-1167 代理 | AOA 独立 Paymaster |
| GToken | 2.0.0 | ERC20 | 治理代币(2100 万上限,限量发行) |
| GTokenStaking | 3.2.0 | 不可变 | 基于角色的质押 + 燃烧机制,DVT/治理惩罚 |
| MySBT | 3.1.3 | ERC721(灵魂绑定) | 身份 + 声誉,社区会员,SBT 门控赞助 |
| xPNTsFactory | 2.0.0 | Clones | 部署每社区 xPNTs Gas 代币 |
| ReputationSystem | 1.0.0 | — | 基于社区规则的声誉评分 |
| BLSAggregator | 1.0.0 | — | BLS12-381 阈值签名聚合 |
| DVTValidator | 1.0.0 | — | 分布式验证者共识(7/13 拜占庭法定人数) |
V5.1 — x402 精确结算
settleX402Payment()— EIP-3009 USDC 原生结算(节省 19% Gas)settleX402PaymentDirect()— xPNTs 直接转账(工厂自动授权)
V5.2 — 微支付通道
MicroPaymentChannel合约 — 开通/签名/结算流式会话- EIP-712 累计凭证签名 + 争议窗口
V5.3 — Agent 经济 (ERC-8004)
- 双通道资格:SBT 持有者 或 注册 AI Agent
AgentSponsorshipPolicy— 每运营商分级 BPS 费率 + 每日 USD 上限- 声誉反馈闭环 + EIP-1153 瞬态存储优化
# 克隆并初始化子模块
git clone https://github.com/AAStarCommunity/SuperPaymaster.git
cd SuperPaymaster && ./init-submoduel.sh
# 构建
forge build
# 运行所有测试(400+)
forge test
# 部署到本地 Anvil
./deploy-core anvil
# 部署到 Sepolia
./deploy-core sepolia| 合约 | 代理地址 | 实现地址 |
|---|---|---|
| Registry | 0xD88CF531... |
0x84bB9e3C... |
| SuperPaymaster | 0x829C3178... |
0xf4d022Ea... |
| ReputationSystem | — | 0x3384317D... |
EntryPoint v0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032
完整地址见 deployments/config.sepolia.json
- 合约架构 — 依赖图、数据结构、构造参数
- UUPS 升级指南 — 存储布局、升级流程、安全分析
- DVT + BLS 架构 — 去中心化验证者 & BLS 签名聚合
- 预言机降级机制 — Chainlink 降级 & DVT 切换
- 价格缓存技术参考 — 价格缓存实现
- 角色机制 — 角色配置、管理、退出费用
- 管理权限矩阵 — 管理操作权限
- 信用系统设计 — 用户信用/债务系统
- 合约版本映射 — 链上版本号 & 治理路线图
- V5 设计文档 —
_consumeCredit()、x402、ERC-8004 集成 - V5 路线图 — 从 Gas 代付到 Agent Economy 的演进
- V5 实施计划 — 16 周进度、Worktree 并行策略
- V5.1 计划 — Agent-Native Gas &
chargeMicroPayment() - V5.2 计划 — x402 Facilitator + MicroPaymentChannel
- V5.3 计划 — ERC-8004 Agent Discovery + SKILL.md + CLI
- V5 验收报告 — 功能验证 & 测试结果
- x402 生态研究 — Coinbase x402、Cloudflare Workers
- Agent + x402 + 微支付研究 — Agent 经济 & 支付通道
- Spores 协议设计 — 去中心化分润网络
- 开发者集成指南 — 无 Gas、x402、微支付场景
- SDK E2E 场景指南 — 7 个完整用户场景
- 生态服务部署 — Operator 节点、Facilitator、Keeper
- Registry v4.1 SDK 迁移 — 接口变更、viem 示例
- 部署指南 — Foundry Keystore 安全部署
- MySBT 用户指南 — 铸造和管理 SBT 代币
- 社区注册指南 — 注册你的社区
- Paymaster 运营指南 — 运营 AOA/AOA+ Paymaster
- SuperPaymaster API (V5.3.0)
- Registry API (V4.1.0)
- MySBT API
- Anvil 测试指南 — 本地环境
- E2E 测试指南 — Sepolia 端到端测试
- Gasless 测试指南 — 无 Gas 交易测试
- 400+ Foundry 测试通过(含 UUPS 升级、V5 特性、模糊测试)
- Echidna 属性测试
- 内部对抗性审查完成
- 外部审计待主网部署前完成
报告漏洞: jason@aastar.io 或 david@aastar.io
本项目使用 Apache 许可证 2.0 版(英文原版,具有法律效力)。
中文参考译本见 LICENSE-zh.md(非官方,不具法律效力)。
版权归属见 NOTICE。