Skip to content

AAStarCommunity/SuperPaymaster

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1,009 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

SuperPaymaster

License: Apache 2.0 arXiv

Decentralized Payment & Gas Sponsorship Infrastructure for ERC-4337

English | 中文

v5.3.3-beta.2 (Security-Hardened Beta · Core Gasless) — Sepolia Testnet Live · Release Notes · Integration Guide · Coverage Report


What is SuperPaymaster?

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.

Who is it for?

  • 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

Payment Modes

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

Two Operating Modes

  • 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

Architecture

                    ┌──────────────────────────────────┐
                    │         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

Core 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 Feature Highlights

V5.1 — x402 Settlement (contracts live; @aastar/x402 SDK signing integrating — aastar-sdk#39)

  • settleX402Payment() — EIP-3009 transferWithAuthorization for USDC-native settlement; recipient bound into the nonce (C-03)
  • settleX402PaymentDirect() — xPNTs settle gated by a payer EIP-712 X402PaymentAuthorization signature (C-02) + factory/facilitator whitelist
  • chargeMicroPayment() (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

  • MicroPaymentChannel contract — 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

AAStar Stack & Division of Labor

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

Security Architecture

  • 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)

Quick Start

Prerequisites

Build & Test

# 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

# 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.sh

For secure mainnet deployment with Foundry Keystore, see Deployment Guide.


Contract Addresses (Sepolia)

v5.3.3-beta.2 deployment. Always read live addresses from deployments/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.


Documentation

Architecture & Design

V5 Design & Roadmap

Research

Developer Guides

User Guides

API References

Security & Audits

Testing


Repository Structure

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

Security

  • 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


Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Run tests: forge test
  4. Commit: git commit -m 'feat: Add amazing feature'
  5. Open a Pull Request

Code style: forge fmt — Solidity 0.8.33, comments in English.


Links


License

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.


SuperPaymaster — 去中心化支付与 Gas 赞助基础设施

English | 中文

Beta 0.22 (内部版本: V5.3) — Sepolia 测试网运行中

SuperPaymaster 是什么?

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 特性

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

合约地址(Sepolia 测试网)

合约 代理地址 实现地址
Registry 0xD88CF531... 0x84bB9e3C...
SuperPaymaster 0x829C3178... 0xf4d022Ea...
ReputationSystem 0x3384317D...

EntryPoint v0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032

完整地址见 deployments/config.sepolia.json


文档

架构与设计

V5 设计与路线图

研究

开发者指南

用户指南

API 参考

安全与审计

测试


安全

  • 400+ Foundry 测试通过(含 UUPS 升级、V5 特性、模糊测试)
  • Echidna 属性测试
  • 内部对抗性审查完成
  • 外部审计待主网部署前完成

报告漏洞: jason@aastar.iodavid@aastar.io


许可证

本项目使用 Apache 许可证 2.0 版(英文原版,具有法律效力)。
中文参考译本见 LICENSE-zh.md(非官方,不具法律效力)。
版权归属见 NOTICE

About

A decentralized paymaster: remove traditional off-chain paymaster signature server to provide permissionless and decentralized service with on-chain contract.

Topics

Resources

License

Apache-2.0, Unknown licenses found

Licenses found

Apache-2.0
LICENSE
Unknown
LICENSE-zh.md

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors