Production-ready ERC-4337 Account Abstraction Paymaster infrastructure for sponsoring gas fees with policy controls, real EntryPoint v0.6.0 integration, and multi-chain support. Build, validate, and submit UserOperations with whitelist, limits, and token-gating.
Instrucciones de origen · Vista previa de solo lectura
name
Account Abstraction Paymaster
description
Production-ready ERC-4337 Account Abstraction Paymaster infrastructure for sponsoring gas fees with policy controls, real EntryPoint v0.6.0 integration, and multi-chain support. Build, validate, and submit UserOperations with whitelist, limits, and token-gating.
["account abstraction paymaster","sponsor gas fees","erc-4337 paymaster","useroperation builder","entrypoint integration","gas sponsorship","smart wallet paymaster","aa paymaster","sponsor user operations","paymaster policy"]
parameters
[{"name":"rpc_url","type":"str","required":true,"description":"RPC endpoint for target network (e.g., https://eth.llamarpc.com)"},{"name":"paymaster_address","type":"str","required":true,"description":"Deployed ERC-4337 Paymaster contract address"},{"name":"paymaster_owner_key","type":"str","required":true,"description":"Private key for paymaster signing (secure storage required)"},{"name":"bundler_private_key","type":"str","required":false,"description":"Private key for bundler account (optional, for submitting UserOps)"},{"name":"max_gas_per_op","type":"int","default":500000,"description":"Maximum gas units to sponsor per UserOperation"},{"name":"max_cost_per_op_eth","type":"float","default":0.01,"description":"Maximum ETH cost to sponsor per UserOperation"},{"name":"daily_limit_eth","type":"float","default":0.1,"description":"Daily spending limit per user in ETH"}]
requirements
["Python 3.8+","web3>=6.0.0","eth-account>=0.9.0","eth-abi>=4.0.0","Understanding of ERC-4337 Account Abstraction","Deployed Paymaster contract (or use existing one)","RPC endpoint for target network(s)"]
Account Abstraction Paymaster Skill
Skill Description
Implement ERC-4337 Account Abstraction Paymaster to sponsor gas fees for users with comprehensive policy controls, real-time validation, and multi-chain support. Features real EntryPoint v0.6.0 integration tested on Ethereum mainnet with actual contract interactions.
Key Capabilities
Gas Sponsorship - Automatically sponsor transaction fees for eligible users
from web3 import Web3
from paymaster_sponsor import PaymasterSponsor, SponsorshipPolicy
from user_operation_builder import UserOperationBuilder
# Connect to network
w3 = Web3(Web3.HTTPProvider("https://eth.llamarpc.com"))
# Initialize components
builder = UserOperationBuilder(w3)
sponsor = PaymasterSponsor(
w3=w3,
paymaster_address="0xYourPaymaster...",
owner_private_key="0x..."# Signs paymaster data
)
# Build UserOperation
user_op = builder.build_eth_transfer_op(
sender="0xSmartAccount...", # User's AA wallet
recipient="0xRecipient...",
amount_wei=Web3.to_wei(0.1, 'ether')
)
# Define sponsorship policy
policy = SponsorshipPolicy(
enabled=True,
max_gas_per_op=500_000,
max_cost_per_op_eth=0.01,
daily_limit_eth=0.1,
whitelist=["0xSmartAccount..."],
blacklist=[],
require_token_balance=None
)
# Sponsor the operation
result = sponsor.sponsor_user_operation(
user_op=user_op.to_dict(),
policy=policy
)
if result.success:
print(f"✅ Sponsored! Cost: {result.cost_eth} ETH")
print(f" Gas: {result.gas_sponsored:,} units")
else:
print(f"❌ Not eligible: {result.reason}")
Expected Output:
💎 Sponsorship Request
Sender: 0xSmartAccount...
Gas Estimate: 281,196 units
Cost Estimate: 0.000010 ETH
✅ Eligible: Eligible for sponsorship
UserOp Hash: 0x2df8034e...
✅ Paymaster data generated (97 bytes)
📊 Daily spending: 0.000010 / 0.1 ETH
✅ Sponsorship approved!
Example 2: Token-Gated Sponsorship
# Sponsor only users holding specific tokens
policy = SponsorshipPolicy(
enabled=True,
max_gas_per_op=300_000,
max_cost_per_op_eth=0.005,
daily_limit_eth=0.05,
whitelist=[], # Empty = check token balance only
blacklist=[],
require_token_balance=(
"0xYourERC20Token...", # Token address
Web3.to_wei(100, 'ether') # Min 100 tokens
)
)
# Build ERC20 transfer operation
user_op = builder.build_erc20_transfer_op(
sender="0xSmartAccount...",
token="0xUSDC...",
recipient="0xRecipient...",
amount=1_000_000# 1 USDC (6 decimals)
)
# Sponsor
result = sponsor.sponsor_user_operation(user_op.to_dict(), policy)
Expected Output:
📤 Building ERC20 Transfer UserOp
Token: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
To: 0xRecipient...
Amount: 1000000
💎 Sponsorship Request
Sender: 0xSmartAccount...
Gas Estimate: 295,000 units
Cost Estimate: 0.000011 ETH
✅ Eligible: Eligible for sponsorship
✅ Sponsorship approved!
Example 3: Submit UserOperation to EntryPoint
from entrypoint_interaction import EntryPointInteraction
# Initialize EntryPoint interaction
entrypoint = EntryPointInteraction(
w3=w3,
bundler_key="0xBundlerPrivateKey..."
)
# Submit the sponsored UserOperation
receipt = entrypoint.submit_user_operations(
user_ops=[user_op.to_dict()],
beneficiary="0xBundlerAddress...", # Receives bundler fees
wait_for_receipt=True
)
if receipt and receipt.success:
print(f"✅ UserOperation executed!")
print(f" TX Hash: {receipt.tx_hash}")
print(f" Block: {receipt.block_number}")
print(f" Gas Used: {receipt.actual_gas_used:,}")
print(f" Cost: {receipt.actual_gas_cost:.6f} ETH")
# Check for UserOperationEventfor event in receipt.events:
if event['event'] == 'UserOperationEvent':
print(f" ✅ UserOp successful")
print(f" Sender: {event['args']['sender']}")
print(f" Paymaster: {event['args']['paymaster']}")
print(f" Actual Gas: {event['args']['actualGasUsed']:,}")
Expected Output:
🚀 Submitting 1 UserOperation(s)
Beneficiary: 0xBundler...
UserOp #1: 0x5678efab...
✅ Transaction sent: 0xabcd1234...
⏳ Waiting for confirmation...
✅ Confirmed in block 19234567
Gas used: 275,432
💰 Total cost: 0.000551 ETH
✅ UserOperation executed successfully
Actual gas used: 265,123
Actual gas cost: 0.000530 ETH
Example 4: Batch Operations
# Encode multiple calls in one UserOperation
call_data = builder.encode_execute_batch(
targets=[
"0xToken1...", # First call: approve token"0xDEX..."# Second call: swap tokens
],
values=[0, 0], # No ETH sent
datas=[
"0x095ea7b3...", # approve(spender, amount)"0x38ed1739..."# swapExactTokensForTokens(...)
]
)
# Build UserOperation with batch call
user_op = builder.build_user_operation(
sender="0xSmartAccount...",
call_data=call_data
)
# Sponsor and submit
result = sponsor.sponsor_user_operation(user_op.to_dict(), policy)
if result.success:
receipt = entrypoint.submit_user_operations([user_op.to_dict()])
Expected Output:
🔨 Building UserOperation
Sender: 0xSmartAccount...
Nonce: 5 (from chain)
Gas Estimates:
Call: 165,000
Verification: 150,000
Pre-verification: 21,528
Gas Prices:
Max fee: 0.046 gwei
Priority: 0.0035 gwei
Estimated Cost: 0.000015 ETH
✅ UserOperation built successfully
💎 Sponsorship Request
...
✅ Sponsorship approved!
🚀 Submitting 1 UserOperation(s)
...
✅ UserOperation executed successfully
Example 5: Monitor Paymaster Balance
# Check paymaster's deposit in EntryPoint
balance = sponsor.get_paymaster_deposit()
print(f"Paymaster deposit: {balance} ETH")
# Deposit more ETH if neededif balance < 0.1:
print("⚠️ Low balance, depositing 1 ETH...")
tx_hash = entrypoint.deposit_to_entrypoint(
account=sponsor.paymaster_address,
amount_eth=1.0,
from_key="0xOwnerKey..."
)
print(f"✅ Deposited: {tx_hash}")
# Check spending for specific user
user_address = "0xUser..."
daily_spent = sponsor.daily_spending.get(user_address, 0.0)
print(f"User daily spending: {daily_spent:.6f} ETH")
# Reset daily limits (call once per day)
sponsor.reset_daily_limits()
Expected Output:
Paymaster deposit: 0.05 ETH
⚠️ Low balance, depositing 1 ETH...
💰 Depositing to EntryPoint
For: 0xPaymaster...
Amount: 1.0 ETH
From: 0xOwner...
✅ Transaction sent: 0x9876fedc...
✅ Deposit successful!
New balance: 1.05 ETH
User daily spending: 0.002340 ETH
✅ Daily spending limits reset
Testing
Test 1: Build UserOperation
cd scripts
python user_operation_builder.py
Expected Output:
======================================================================
USEROPERATION BUILDER
======================================================================
✅ Connected (chain: 1, block: 24488867)
Gas price: 0.035808439 gwei
✅ UserOperation builder initialized
Chain ID: 1
EntryPoint: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
💸 Building ETH Transfer UserOp
To: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
Amount: 0.1 ETH
🔨 Building UserOperation
Sender: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
Nonce: 0 (from chain)
Gas Estimates:
Call: 109,668
Verification: 150,000
Pre-verification: 21,528
Gas Prices:
Max fee: 0.04655097 gwei
Priority: 0.003580843 gwei
Estimated Cost: 0.000013 ETH
✅ UserOperation built successfully
📋 UserOperation Summary:
Sender: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
Nonce: 0
Total Gas: 281,196
UserOp Hash: 2df8034e1731aced5eed3dddffd3c060f267e7f6f5770d4a058f2ce31b4e7b06
✅ UserOperation ready for signing and submission
Test 2: Sponsorship Validation
python paymaster_sponsor.py
Expected Output:
======================================================================
ACCOUNT ABSTRACTION PAYMASTER - GAS SPONSORSHIP
======================================================================
✅ Connected to network (chain ID: 1)
Block: 24488867
✅ Paymaster initialized
Paymaster: 0x1234567890123456789012345678901234567890
EntryPoint: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
Network: 1
💎 Sponsorship Request
Sender: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
Gas Estimate: 281,196 units
Cost Estimate: 0.000010 ETH
✅ Eligible: Eligible for sponsorship
UserOp Hash: 0x2df8034e1731aced...
✅ Paymaster data generated (97 bytes)
📊 Daily spending: 0.000010 / 0.1 ETH
✅ Sponsorship approved!
📋 Sponsorship Result:
Success: True
Sponsored: True
Gas Sponsored: 281,196 units
Cost: 0.000010 ETH
Reason: Sponsored successfully
✅ UserOperation ready to be submitted with paymaster!
paymasterAndData: 0x12345678901234567890123456789012345...
# Add user to whitelist
policy.whitelist.append("0xNewUser...")
# Or use empty whitelist with token gating
policy = SponsorshipPolicy(
...
whitelist=[], # Empty = no whitelist check
require_token_balance=("0xToken...", min_balance)
)
Issue 2: "Daily limit exceeded"
Problem: User has reached daily spending limit
Solution:
# Check current spendingprint(f"Daily spent: {sponsor.daily_spending.get(user_address, 0)}")
# Increase limit
policy.daily_limit_eth = 0.5# Increase from 0.1 to 0.5# Or reset limits manually
sponsor.reset_daily_limits()
Issue 3: "Insufficient funds for bundler"
Problem: Bundler account has no ETH
Solution:
# Send ETH to bundler address# Or deposit to EntryPoint for paymaster
