Architettura ERC-4337: EntryPoint, bundler e paymaster senza complicazioni

L’account abstraction su Ethereum ha due indirizzi canonici che vale la pena memorizzare. EntryPoint v0.6 si trova all’indirizzo 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789. EntryPoint v0.7, distribuito all’inizio del 2024, si trova all’indirizzo 0x0000000071727De22E5E9d8BAf0edAc6f37da032. Ogni transazione ERC-4337 su mainnet, Arbitrum, Optimism, Base, Polygon e sulla maggior parte delle altre chain EVM passa da uno di questi due singleton. Se capisci cosa fanno questi contratti e quali sono gli altri cinque ruoli che ruotano loro attorno, hai capito ERC-4337.

Questa è la seconda parte della nostra serie sugli Smart Account. Nella prima parte abbiamo spiegato perché gli EOA non sono una buona scelta predefinita. Qui entriamo nel dettaglio: i sei ruoli, la struct UserOperation, cosa succede davvero quando fai swap di un token da uno smart account, le differenze tra v0.6 e v0.7, i paymaster, gli alt-mempool pubblici rispetto ai bundler privati e i costi aggiuntivi da aspettarsi.

I sei ruoli in un unico schema

ERC-4337 suddivide in sei attori che collaborano ciò che un EOA fa in un solo passaggio. Per nessuno di loro è stato necessario un hard fork di Ethereum: l’intero sistema è composto da contratti e infrastrutture off-chain.

• Sender (lo smart account): un wallet sotto forma di contratto che custodisce i tuoi asset e implementa validateUserOp. Per qualsiasi DApp con cui interagisce, svolge il ruolo di msg.sender. Esempi: Safe, Kernel, Biconomy Nexus, Coinbase Smart Wallet e Light Account di Alchemy.
• UserOperation: una struct simile a una transazione (non una vera transazione Ethereum) che descrive l’azione che il sender vuole eseguire. Gli utenti firmano le UserOp, non le transazioni.
• Bundler: un nodo off-chain che raccoglie le UserOp da un mempool, le simula, le raggruppa in un’unica chiamata handleOps e paga il gas L1. I bundler guadagnano la differenza tra quanto rimborsa il sender (o il paymaster) e quanto pagano al validatore.
• EntryPoint: il contratto singleton fidato che scorre il bundle, chiama validateUserOp di ciascun sender, esegue i dati della chiamata e gestisce rimborsi e revert. Su ogni chain esiste esattamente un EntryPoint per ciascuna versione.
• Paymaster (facoltativo): un contratto che accetta di pagare il gas per conto di un sender, tramite sponsorizzazione (gratuita per l’utente) oppure in cambio di un token ERC-20 come USDC.
• Aggregator (facoltativo): un contratto che convalida molte UserOp con un solo controllo della firma; è utile per gli schemi BLS o le prove zk. Oggi viene usato raramente in produzione.

Tieni a mente questi ruoli. Il resto dell’articolo mostra semplicemente come interagiscono.

La struct UserOperation

Una UserOperation è un insieme di campi compatibile con JSON-RPC che, una volta firmato, esprime un’intenzione senza ancora inviarla su L1. La struttura v0.7 comprende 11 campi logici:

• sender — l’indirizzo dello smart account.
• nonce — un valore a 256 bit, in cui i 192 bit più significativi identificano una chiave (una corsia per nonce paralleli) e i 64 bit meno significativi indicano una sequenza. È così che ERC-4337 supporta i nonce paralleli, a differenza degli EOA, che serializzano tutto.
• factory e factoryData — per la prima distribuzione tramite CREATE2; dopo la distribuzione sono null.
• callData — la chiamata che lo smart account deve eseguire dopo la convalida.
• callGasLimit, verificationGasLimit, preVerificationGas — tre budget di gas distinti.
• maxFeePerGas, maxPriorityFeePerGas — hanno la stessa semantica EIP-1559 di una normale transazione.
• paymasterAndData (v0.6), suddiviso in paymaster, paymasterVerificationGasLimit, paymasterPostOpGasLimit, paymasterData (v0.7).
• signature — byte opachi che lo smart account interpreta secondo il proprio validateUserOp.

Lo schema di firma dipende dal wallet. ECDSA su secp256k1 è comune, ma la verifica P-256/passkey, il multisig, le soglie di recupero social e i firmatari con chiavi di sessione funzionano tutti tramite la stessa interfaccia. È proprio questa flessibilità il punto di tutto il sistema.

Dall’inizio alla fine: cosa succede quando uno smart account fa swap di USDC in ETH

Seguiamo uno swap reale per vedere i ruoli entrare in azione nell’ordine giusto.

1. L’utente tocca «Swap» nell’interfaccia del wallet. Il wallet crea una UserOperation: sender = 0xUserSafe, callData = swapUSDCforETH(amount) con Uniswap come destinazione.
2. Stima del gas. Il wallet chiama eth_estimateUserOperationGas tramite un endpoint RPC di un bundler. Il bundler simula l’operazione con EntryPoint e restituisce i tre limiti di gas.
3. L’utente firma. Il wallet calcola l’hash della UserOp usando l’indirizzo di EntryPoint e l’ID della chain, chiede all’utente di firmare (con passkey, chiave hardware o altro) e aggiunge la firma.
4. Invio. La UserOp firmata viene inviata tramite eth_sendUserOperation a uno o più bundler. Entra nell’alt-mempool, una rete P2P separata dal normale mempool delle transazioni di Ethereum.
5. Simulazione del bundler. Il bundler esegue di nuovo la simulazione con eth_call contro simulateValidation. Controlla le regole di accesso allo storage di ERC-7562: durante la convalida una UserOp può accedere solo al proprio storage; in caso contrario, il bundler rischia attacchi di griefing.
6. Raggruppamento. Il bundler inserisce questa UserOp insieme ad altre, fino a circa 10, in un’unica chiamata handleOps([...userOps], beneficiary) a EntryPoint.
7. Esecuzione on-chain. EntryPoint scorre le operazioni: per ognuna chiama validateUserOp sul sender, detrae il prefondo e poi esegue callData. Lo swap su Uniswap parte dallo smart account.
8. Rimborso. EntryPoint rimborsa al sender (o al paymaster) il gas non utilizzato e paga l’indirizzo beneficiario del bundler.

Se la simulazione al passaggio 5 non va a buon fine, il bundler scarta l’operazione e l’utente vede un codice di errore AAxx. I più comuni sono AA21 (prefondo non pagato), AA23 (errore di firma), AA25 (nonce non valido), AA33 (revert del paymaster) e AA40 (limite di gas per la verifica superato). Memorizza questa tabella: ti capiterà di vederli.

EntryPoint v0.6 e v0.7 a confronto

v0.6 è stato rilasciato a marzo 2023 all’indirizzo 0x5FF1…2789. Funzionava, ma aveva tre problemi ricorrenti: un unico blocco paymasterAndData che riuniva tre dimensioni del gas, un raggruppamento initCode poco pratico e un calcolo del gas che faceva pagare troppo ai sender. v0.7 ha risolto tutti e tre.

Ecco le principali novità di v0.7:

• Indirizzo: 0x0000000071727De22E5E9d8BAf0edAc6f37da032 (nota gli zeri iniziali: è un indirizzo vanity, scelto dopo una ricerca per ridurre il costo del gas dei calldata, dato che ogni byte zero costa 4 unità di gas contro le 16 di un byte non zero).
• Campi del paymaster separati: paymaster, paymasterVerificationGasLimit, paymasterPostOpGasLimit e paymasterData ora sono separati. Sono più semplici da stimare e riducono il rischio di dimenticare un budget.
• Separazione della factory: stesso principio: factory e factoryData sono campi separati, anziché far parte di un initCode raggruppato.
• Penale per il gas inutilizzato: ai sender viene addebitato il 10% del valore inutilizzato di callGasLimit/paymasterPostOpGasLimit, così sono scoraggiati dal sovrastimare ampiamente le operazioni.
• Compatibilità con EIP-7702: v0.7 ha aggiunto i componenti che consentono a un normale EOA di delegare temporaneamente a un’implementazione di smart account. Sono diventati la base del percorso di aggiornamento EIP-7702 introdotto con Pectra.

v0.6 è ancora attivo e in uso: molti wallet non hanno distribuito un modulo compatibile con v0.7 fino a ben dentro il 2024. Sulla maggior parte delle chain le due versioni di EntryPoint funzionano in parallelo per anni.

Paymaster: chi paga il gas

Un paymaster è un contratto che mantiene uno stake in ETH presso EntryPoint e accetta di coprire il gas delle UserOp conformi alla propria policy. Esistono soprattutto tre tipi:

• Paymaster con verifica (sponsorizzato). Un backend firma un’autorizzazione off-chain; il paymaster ne verifica la firma on-chain e paga. Lo usano le app che vogliono offrire un onboarding senza costi di gas: Coinbase Smart Wallet, Farcaster Frames e la maggior parte dei conii di NFT.
• Paymaster ERC-20. L’utente paga in USDC, USDT o DAI; il paymaster li scambia in ETH in background (oppure mantiene una riserva di ETH). Pimlico, Biconomy e Stackup offrono tutti servizi pubblici di questo tipo.
• Paymaster con token e permit. Usa il permit EIP-2612, così l’utente firma la UserOp e l’autorizzazione del token con un’unica firma.

La funzione validatePaymasterUserOp del paymaster viene eseguita durante la fase di convalida di EntryPoint. Se effettua un revert, ricevi AA33. Se lo stake si esaurisce, EntryPoint lo slasha e il bundler si fa carico della perdita; per questo i bundler mantengono elenchi di reputazione dei paymaster. ERC-7562 codifica queste regole di reputazione, così il mempool dei bundler resta resistente allo spam. Gli stessi elementi di base spiegano perché le buone pratiche per le approvazioni DeFi e il multisig si applicano bene anche al mondo 4337: le minacce sono le stesse, cambia il livello che le avvolge.

Mempool alternativo pubblico e bundler privato

Esistono due modi per portare una UserOp on-chain.

Mempool alternativo pubblico: i bundler conformi a ERC-7562 diffondono le UserOp su una rete libp2p. Chiunque esegua un nodo Pimlico, Stackup, Alchemy, Etherspot o Voltaire può includere la tua. Questo sistema è permissionless e resistente alla censura, ma ti espone agli stessi rischi MEV delle normali transazioni Ethereum: i searcher possono vedere la tua operazione prima che venga inclusa.

Bundler privato: invii eth_sendUserOperation direttamente all’RPC di un provider. Il provider simula, raggruppa e invia le operazioni in privato (spesso tramite Flashbots). È più veloce e protegge dal MEV, ma devi fidarti che il bundler non censuri le operazioni né faccia front-running. Nel 2026, la maggior parte dei wallet consumer usa bundler privati per impostazione predefinita.

Il compromesso è simile a quello tra il mempool pubblico e Flashbots Protect per le normali transazioni. Se dai tempi di L1 non hai più consultato la procedura di una transazione, questa guida spiega cosa cambia quando interviene il bundler.

Aggregator, adozione e costi complessivi

Gli aggregator sono contratti che convalidano batch con un solo controllo della firma. Il caso d’uso più comune è BLS: si raccolgono 50 UserOp firmate con BLS, si aggregano le firme in un unico controllo pairing e si risparmia circa il 95% del gas per le firme. La diffusione è stata lenta perché creare wallet che firmano con BLS è difficile e il risparmio di gas conviene solo a volumi elevati. A metà 2026, meno dell’1% delle UserOp su mainnet usa gli aggregator.

Dati sull’adozione (Q1 2026, da bundlebear.com): circa 380 milioni di UserOp complessive su tutte le chain, con Base, Polygon e Arbitrum che rappresentano la maggioranza. La quota di mainnet è circa il 6–8%: la più bassa per volume, ma la più alta per valore trasferito. Coinbase Smart Wallet, Farcaster e Argent dominano l’attività consumer.

Costi aggiuntivi: una UserOp v0.7 costa circa 30.000–40.000 gas in più rispetto alla transazione EOA equivalente: si tratta del ciclo di EntryPoint, della convalida e della gestione del bundle. Su mainnet, a 20 gwei, il costo è una frazione di dollaro per operazione. La prima distribuzione di un account tramite factoryData aggiunge circa 250.000 gas. Sulle L2, dove i dati di calldata rappresentano la voce di costo principale, l’aumento percentuale è a una sola cifra. Le UserOp sponsorizzate trasferiscono questo costo alla dApp: per questo le transazioni sono gratuite nelle app consumer, ma non nei progetti DeFi più seri. La guida alle commissioni di transazione spiega più in generale come questo costo aggiuntivo si rifletta sui diversi mercati delle commissioni.

In breve: ERC-4337 comprende sei ruoli (sender, UserOp, bundler, EntryPoint, paymaster e aggregator), una struct, due indirizzi EntryPoint da imparare a memoria e circa 30–40k gas di costi aggiuntivi. In cambio, offre schemi di firma arbitrari, sponsorizzazione del gas, batching e nonce paralleli. La parte 3 di questa serie passa a EIP-7702, il percorso parallelo di Pectra che permette al tuo EOA esistente di usare questi stessi meccanismi senza cambiare indirizzo.