Skip to content

v5.3.3-beta.2-integration-guide.md

Latest commit

 

History

History
135 lines (104 loc) · 6.78 KB

v5.3.3-beta.2-integration-guide.md

File metadata and controls

135 lines (104 loc) · 6.78 KB
Raw

SuperPaymaster v5.3.3-beta.2 — Beta Integration Guide (Sepolia)

Entry point for integrating the security-hardened SuperPaymaster beta on Sepolia (release v5.3.3-beta.2, contract SuperPaymaster-5.3.3, UUPS). For detailed step-by-step flows + viem pseudo-code, see SDK-E2E-Scenario-Guide.md; for x402, see integration/sdk-x402-integration.md.

What's ready vs. pending in this beta

Capability Status
Core gasless sponsorship — AOA+ (SuperPaymaster credit/debt + xPNTs) and AOA (PaymasterV4) ✅ Ready on Sepolia
Dual-channel eligibility (SBT holder or registered agent) ✅ Ready
Reputation-gated sponsorship, credit tiers, oracle pricing ✅ Ready
x402 / agent settlement (settleX402Payment, settleX402PaymentDirect) ✅ Available — contracts live + SDK signing shipped in @aastar/sdk@0.29.0 (@aastar/sdk/x402). aastar-sdk#39 closed.

Contract addresses (Sepolia · EntryPoint v0.7)

Contract Address
SuperPaymaster (proxy) 0x030025f40d509b1a99547bAEb3795bD27F7182b7
Registry 0x3F920B25f8b65988359C372F66F036E48adFc556
GToken 0x20a051502a7AE6e40cfFd6EBe59057538E698984
GTokenStaking 0x3B363598746Ea57314d4869B160940948c569D48
MySBT 0x072A0D12f4212B6baD7c6d0A633eaffbDE9105bF
xPNTsFactory 0xCec3655525a112882E74Fb7C26AcB267a07724cb
aPNTs (sample xPNTs) 0x9e66B457E0ABb1F139FD8A596d00f784eBA2873b
PaymasterFactory 0x0Aa06EA5295eeD4D48c93c594Db1CBf3626971A5
ReputationSystem 0x7fEd690E1663755e24a1C9d6164336809d68a578
MicroPaymentChannel 0x405851A141Cde827E33247d4D4089Af2814c2FF5
EntryPoint v0.7 0x0000000071727De22E5E9d8BAf0edAc6f37da032

Always read live addresses from deployments/config.sepolia.json (synced to the SDK via @aastar/core config.sepolia.json) rather than hardcoding.

Prerequisites — the two failures every integrator hits first

These are the exact issues we root-caused in beta E2E; provisioning them up front avoids opaque AA34 paymaster failures.

1. The user must be eligible for sponsorship

Sponsorship requires isEligibleForSponsorship(user) == true, i.e. the user is an SBT holder OR a registered agent:

isEligibleForSponsorship(user) = sbtHolders[user] || isRegisteredAgent(user)

A fresh AA account is neither → validation fails with USER_NOT_ELIGIBLE. Register the account as an ENDUSER (which sets SBT status) before sponsoring — updateSBTStatus is Registry-gated, so go through the Registry (safeMintForRole(ROLE_ENDUSER, account, data) from the community owner, e.g. contracts/script/v3/RegisterEnduser.s.sol).

2. The price cache must be fresh, the operator funded, credit not exhausted

Before submitting, pre-flight with dryRunValidation — it returns the exact reason code the on-chain validation would, so you never burn a UserOp on a predictable revert:

import { createPublicClient, http } from 'viem'
import { sepolia } from 'viem/chains'

const pub = createPublicClient({ chain: sepolia, transport: http(RPC_URL) })

const [ok, reasonCode] = await pub.readContract({
  address: SUPER_PAYMASTER,
  abi: superPaymasterAbi,
  functionName: 'dryRunValidation',
  args: [packedUserOp, maxCost],
})
// ok=false → reasonCode tells you why, in this priority order:
//   STALE_PRICE          → run the price keeper to refresh the cache
//   INSUFFICIENT_BALANCE → operator has too few aPNTs; depositFor / top up
//   CREDIT_EXCEEDED      → user debt + this charge > credit limit; repay first
//   USER_NOT_ELIGIBLE    → see prerequisite #1 above
if (!ok) throw new Error(`paymaster would reject: ${reasonCode}`)
  • STALE_PRICE: the SuperPaymaster/PaymasterV4 price cache expires; run the keeper (keeper run keep in the AAStar SDK) before a test batch.
  • CREDIT_EXCEEDED: the AOA+ credit/debt model caps sponsored spend at the user's credit limit. When a user holds enough xPNTs balance, the charge is taken from balance and the credit ceiling does not apply; with no balance it falls back to debt up to the limit. Clear debt by minting/transferring xPNTs to the user (xPNTs auto-repay on mint).

Core gasless flow (AOA+ SuperPaymaster)

  1. Ensure prerequisites above (eligibility + fresh price + funded operator).
  2. Build the v0.7 PackedUserOperation; set paymasterAndData = SUPER_PAYMASTER ‖ pmVerGas ‖ pmPostGas ‖ context. Give postOp a real gas budget — the C-04 fix enforces a 200k postOp floor.
  3. dryRunValidation pre-flight (above).
  4. Submit via the bundler / EntryPoint v0.7.
  5. In postOp the paymaster charges aPNTs: burns from the user's xPNTs balance if available, else records debt up to the credit limit.

Reference implementation: script/gasless-tests/test-case-2/3/4-*.js (SuperPaymaster xPNTs + credit/debt paths).

Core gasless flow (AOA PaymasterV4)

Independent per-community paymaster deployed via PaymasterFactory (EIP-1167). The community funds it with xPNTs (depositFor), users hold the community's xPNTs, and the paymaster sponsors directly without the shared credit/debt ledger. Reference: script/gasless-tests/test-case-1-paymasterv4.js and test-group-P2-paymasterv4-lifecycle.js.

x402 / agent settlement — status

Both settlement paths are live and SDK-ready as of @aastar/sdk@0.29.0 (aastar-sdk#39 closed):

  • EIP-3009 path (settleX402Payment, USDC-native): SDK derives the recipient-bound nonce keccak256(abi.encode(payee, salt)) automatically (C-03). Use X402Client from @aastar/sdk/x402.
  • Direct path (settleX402PaymentDirect, xPNTs): SDK signs the EIP-712 X402PaymentAuthorization(from,to,asset,amount,maxFee,validBefore,nonce) over the X402Facilitator's domain (C-02). The asset must be a factory-minted xPNTs and the facilitator must be on the token's approvedFacilitators.

Raw EIP-712 reference examples (no SDK): script/gasless-tests/test-x402-eip3009-settlement.js and test-x402-direct-settle.js.

Security fixes in this beta

C-01 balance-aware credit ceiling · C-02 signed x402 direct settle · C-03 recipient-bound EIP-3009 nonce · C-04 postOp OOG floor · H-01 chunked retryPendingDebt · H-02 PoP-gated permissionless BLS registration (switch default OFF). Full verification: docs/coverage-report-2026-06-02.md.

Operational note (testers)

The Sepolia deployer is an EIP-7702-delegated account; the RPC caps in-flight txs for delegated accounts, so batch forge script broadcasts silently fail after simulation prints success. Run multi-tx scripts with --slow and verify state on-chain, not from simulation logs.