EntryPoint Contract

The EntryPoint is a singleton contract deployed once per chain, serving as the single trust anchor for all UserOperations. It performs critical functions:

• Bundler Coordination: Accepts batches of UserOperations from bundlers.
• Validation: Calls the validateUserOp function on each smart contract wallet.
• Execution: Calls the execute function on wallets that pass validation.
• Paymaster Handling: Manages gas sponsorship and token payment logic.

The EntryPoint decouples gas payment from the transaction sender, enabling gas abstraction. It acts as the intermediary for paymasters, which can:

• Sponsor gas fees for users.
• Accept payment in ERC-20 tokens via a deposit/withdraw system.
• Implement custom validation logic (e.g., whitelists). The contract holds deposited funds from paymasters and settles balances after execution, refunding unused gas.

The EntryPoint's handleOps function processes UserOperations in an atomic batch. This means:

• If any single operation in the batch fails its validation, the entire batch reverts, preventing partial execution.
• This atomicity protects bundlers from losing gas on invalid ops and ensures system integrity.
• Operations are simulated via eth_call by bundlers before submission to guarantee they will succeed.

To prevent spam and ensure honest behavior, the EntryPoint enforces a stake and deposit system for paymasters and, optionally, wallets.

• Deposit: Entities lock ETH (or other tokens) in the contract to pay for gas.
• Stake: A separate, locked deposit that can be slashed for malicious actions, securing the network.
• This economic security model is crucial for enabling unstoppable transactions where a third party (the paymaster) pays fees.

The EntryPoint defines strict simulation rules that wallets and paymasters must follow during the validateUserOp phase to be compatible with bundlers. Key rules include:

• Ban on state changes: Validation cannot modify persistent storage.
• Ban on forbidden opcodes: Cannot use GASPRICE, NUMBER, etc.
• Gas limit compliance: Must stay within defined limits. These rules allow bundlers to safely simulate operations off-chain without risk.

The contract emits standardized events that are essential for off-chain monitoring and indexing. The primary events are:

• UserOperationEvent: Logs the success/failure, sender, paymaster, and actual gas cost of each operation.
• UserOperationRevertReason: Emits the revert reason if execution fails.
• DepositUpdated & Withdrawn: Track changes to paymaster and wallet deposits. These events form the backbone for block explorers, dashboards, and bundler profitability calculations.

Optional contracts that sponsor transaction fees, enabling gasless transactions or payment in ERC-20 tokens. The EntryPoint interacts with a paymaster's validatePaymasterUserOp and postOp functions.

• Sponsorship Models: Contract pays (gasless), user pays with ERC-20 token.
• Use Case: Onboarding users without native ETH, subscription services.
• Security: Must be staked in the EntryPoint to prevent abuse.

Contracts that optimize signature verification for batches of UserOperations. Instead of each operation verifying a signature individually, an aggregator validates a single aggregated signature for the entire batch, significantly reducing gas costs.

• Function: Implements validateSignatures and aggregateSignatures.
• Benefit: Essential for scaling smart account adoption by minimizing on-chain verification overhead.
• Interaction: Called by the EntryPoint during the validation phase.

Not a separate contract, but a critical logical component within the Smart Contract Wallet. The EntryPoint calls the wallet's validateUserOp function, which must implement the signature verification logic.

• Flexibility: Can verify EOA ECDSA signatures, multi-sigs, BLS signatures, or off-chain attestations.
• Core Duty: Returns a validationData payload indicating success, failure, or a time delay for the operation.

The EntryPoint is designed as a singleton—a single, trusted, and audited contract deployed per chain. All UserOperations for ERC-4337 on that chain are routed through this single instance.

• Purpose: Ensures security and consistency; wallets and paymasters only need to trust one address.
• Upgradability: The singleton can be replaced via a social consensus migration, but its address and interface are immutable for deployed wallets.

The EntryPoint is a singleton contract deployed once per chain. It defines the standard interface for UserOperations and manages the interaction between Bundlers, Paymasters, and Smart Contract Accounts. Its primary functions are:

• handleOps(): The main entry point for Bundlers to submit batches of operations.
• simulateValidation(): Allows Bundlers to simulate op validity without executing it.
• getUserOpHash(): Computes the canonical hash for a UserOperation.

The EntryPoint processes each UserOperation through a strict, two-phase pattern to ensure atomicity and security:

1. Validation: Calls the target Smart Contract Account's validateUserOp function to verify the signature and pay for upfront gas.
2. Execution: If validation passes, it calls the account's execute function to run the intended logic. This separation prevents invalid operations from consuming execution gas.

The EntryPoint enables gas abstraction by coordinating with Paymaster contracts. It handles the financial settlement where a Paymaster can sponsor a user's transaction fees. Key mechanisms include:

• Pre-funding: Paymasters must stake and deposit funds into the EntryPoint.
• Post-op verification: After execution, the EntryPoint ensures the Paymaster is correctly compensated for any sponsored gas, deducting from its deposit.

The contract implements critical security patterns to protect Bundlers and the system:

• Deposit and Stake: All participants (Accounts, Paymasters) must deposit ETH, which can be slashed for malicious behavior.
• Revert on Invalid Ops: The entire batch reverts if any single UserOperation fails validation, protecting Bundlers.
• Reputation System: Tracks entities that cause reverts during simulation, allowing Bundlers to filter out abuse.

To ensure longevity, the EntryPoint contract is designed to be upgradeable. A single, trusted address can trigger a migration to a new EntryPoint contract address. This allows for critical bug fixes and protocol improvements without breaking existing Smart Contract Accounts, which reference the EntryPoint address in their immutable storage.

The EntryPoint is the economic engine for Bundlers (block builders in ERC-4337). It ensures Bundlers are profitably compensated:

• Bundlers call handleOps() and pay the base layer gas fees.
• The EntryPoint aggregates all gas payments from users and Paymasters.
• After successful execution, it refunds the Bundler, ensuring their net profit is the priority fee (maxPriorityFee) for the bundle.