ERC-4337 Paymaster Toolkit

Reusable gas sponsorship infrastructure for ADI testnet. Backend-controlled sponsor signer, native-token and ERC20 paymasters, fully ERC-4337 v0.7 compatible.

Sponsorship Model

Backend signer signs auth bound to sender + chainId + entryPoint + expiry. No msg.sender reliance.

Native Paymaster

Covers gas in ADI from its EntryPoint deposit. Zero-balance accounts can transact.

ERC20 Paymaster

Collects ERC20 from account post-execution. Paymaster covers native gas, user pays in tokens.

Contract Deployments

Flow A: Native Sponsorship

Zero-balance account · Sponsored by NativePaymaster

Flow

1.Generate fresh owner key
2.Compute counterfactual smart account
3.Build UserOperation (initCode + callData)
4.Get sponsorship signature from backend
5.Submit via EntryPoint.handleOps
6.Verify paymaster balance decreased

Logs will appear here when the flow runs...

Flow B: ERC20 Sponsorship

Account has ERC20 only · Gas paid in tokens

Flow

1.Generate fresh owner key
2.Mint ERC20 to counterfactual account
3.Build UserOp: approve ERC20Paymaster
4.Get ERC20 sponsorship signature
5.Submit via EntryPoint.handleOps
6.Verify ERC20 deducted from account

Logs will appear here when the flow runs...

Security & Reusability

Sponsorship authorisation

• Signature bound to sender + chainId + entryPoint + expiry + userOpHash
• No reliance on msg.sender or bundler identity
• Sigs expire after validUntil — replay impossible
• Owner can rotate sponsor signer at any time

How to reuse in your dApp

1. Deploy paymasters via node scripts/erc4337/deploy.js
2. Call POST /api/erc4337/sponsor to get paymasterAndData
3. Attach to your UserOp before signing
4. Submit to any ERC-4337 bundler

CLI Reference

Deploy all contractsnode scripts/erc4337/deploy.js

E2E native flownode scripts/erc4337/e2e-native.js

E2E ERC20 flownode scripts/erc4337/e2e-erc20.js

Failure casesnode scripts/erc4337/e2e-failures.js

Generate paymasterAndDatanode scripts/erc4337/sponsorship.js native <args...>