# ERC-4337 Account Abstraction - Silius (bundler implementation in Rust)
The following document provides architecture, design, and specifications for the [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) (Account Abstraction - AA) bundler implementation in Rust - **Silius**. This project was started in the [Ethereum Protocol Fellowship - The Third Cohort](https://blog.ethereum.org/2022/09/01/ethereum-protocol-fellowship-third) but is still being actively developed.
One of the essential components of the ERC-4337 AA is bundlers, which play the infrastructure or node/client role. Most of the heavy processing and calculations are done by them, and they have several responsibilities:
- receiving user operations from smart contract wallets,
- verifying and simulating user operations,
- managing the reputation of different entities - accounts, factories, paymasters, signature aggregators,
- maintaining public mempool of user operations over a P2P network with other bundlers,
- bundling multiple user operations into transactions and submitting them to execution clients.
GitHub repository: https://github.com/Vid201/silius/
Contributors: [Vid Kersic](https://github.com/Vid201), [WillQ](https://github.com/zsluedem)
## High-level architecture
The architecture and its decomposition are heavily inspired by the [Erigon](https://erigon.substack.com/p/architecture-of-erigon-separable) architecture (and [here](https://github.com/ledgerwatch/interfaces/blob/master/_docs/README.md)). All main components, i.e., ETH RPC API server, user operation mempool (named UoPool), and Bundler Core, are separable components and can be run as standalone processes. Bundler is implemented in a way that supports multiple entry points and mempools.
**Only the ETH RPC API server is exposed to the public internet.**
<br />
<div style="text-align:center"><img src="https://hackmd.io/_uploads/BywMZAMnh.png" alt="High-level architecture for Bundler" /></div>
<br />
1. Users send user operations from ERC-4337 compatible wallets to the RPC API endpoint as JSON-RPC requests. They can also retrieve supported entry points, chain id, estimate user operation gas, etc.
2. ETH RPC API connects to UoPool to add new user operations to mempool, retrieve supported entry points, chain id, estimate user operation gas, etc.
3. UoPool connects to the ETH client to retrieve information about Ethereum accounts (balances, stake/deposit info, etc.). ETH client should have debug namespace enabled since calls to `debug_traceCall` are necessary for simulating user operation. UoPool also connects to other bundlers in the P2P network to broadcast received user operations and retrieve other user operations.
4. The Bundler Core component retrieves user operations from UoPool over gRPC to create bundles of user operations.
5. The Bundler Core connects to the ETH Client to fetch information about the accounts and the Ethereum network.
6. The Bundler Core component sends constructed bundles (regular Ethereum transactions) to the ETH client, a block producer, or sends them to Flashbots services. In the production, bundles should not be directly inserted into the public tx pool due to the front-running.
Bundlers are standalone node components that can be spun up and operated without running Ethereum execution/consensus clients (bundlers connect to the ETH clients over gRPC). Possible tighter integrations into Rust-based execution clients are being considered (such as [Reth](https://github.com/paradigmxyz/reth)), either running alongside Reth or reusing some of its components/packages (e.g., P2P library for listening for included user operations in the blocks).
## Specification
### ETH RPC API endpoints
| JSON-RPC API Method | Input | Output | Description
| -------- | -------- | -------- | --------
| eth_chainId | / | chain ID | ID of the chain the bundler is operating on. E.g., 1 for mainnet.
| eth_supportedEntryPoints | / | List\<Address\> | List of smart contracts addresses of supported entry points. E.g., ["0x0576a174D229E3cFA37253523E645A78A0C91B57"].
| eth_sendUserOperation | User operation and entry point | Response (user operation hash or failure reason) | Endpoint for sending user operations. User operation is added to the mempool if it passes sanity checks and simulation.
| eth_estimateUserOperationGas | User operation and entry point | preVerificationGas, verificationGasLimit, callGasLimit | Endpoint for estimating the gas values for user operations.
| eth_getUserOperationReceipt | User operation hash | Response(user operation receipt or null) | Endpoint for retrieving receipt for user operations based on their hash (which is returned by the endpoint eth_sendUserOperation).
| eth_getUserOperationByHash | User operation hash | Response(user operation (with the addition of entry point, block number, block hash, and transaction hash) or null) | Endpoint for retrieving user operations based on their hash (which is returned by the endpoint eth_sendUserOperation).
> There are also several DEBUG RPC API endpoints, but they are not described due to being used only for testing purposes.
### UoPool gRPC methods
| gRPC Method | Input | Output | Description
| -------- | -------- | -------- | --------
| Add | User operation and entry point | Response (user operation hash or failure reason) | User operation is added to the mempool if it passes sanity checks and simulation. The same method is also used for replacing user operations (user operation with the same nonce but higher gas prices).
| Get sorted | Entry point and count | List\<UserOperations\> | Returns the list of user operations sorted by max priority fee per gas.
| Remove | User operation hash | Response (result=true/false) | Removes user operation from the mempool.
| Chain id | / | chain ID | ID of the chain the bundler is operating on. E.g., 1 for mainnet.
| Supported entry points | / | List\<Address\> | List of smart contracts addresses of supported entry points. E.g., ["0x0576a174D229E3cFA37253523E645A78A0C91B57"].
| Estimate user operation gas | User operation and entry point | preVerificationGas, verificationGasLimit, callGasLimit | Method for estimating the gas values for user operations.
> There are also several DEBUG gRPC endpoints, but they are not described due to being used only for testing purposes.
## Status/roadmap
- Entrypoint versions
- [x] v0.6.0
- [ ] v0.7.0
- ETH RPC API endpoints
- eth Namespace
- [x] eth_chainId
- [x] eth_supportedEntryPoints
- [x] eth_sendUserOperation
- [x] eth_estimateUserOperationGas
- [x] eth_getUserOperationReceipt
- [x] eth_getUserOperationByHash
- debug Namespace
- [x] debug_bundler_clearState
- [x] debug_bundler_dumpMempool
- [x] debug_bundler_sendBundleNow
- [x] debug_bundler_setBundlingMode
- [x] debug_bundler_setReputation
- [x] debug_bundler_dumpReputation
- [x] debug_bundler_addUserOps
- UoPool
- Add
- [x] Sanity checks
- [x] Simulation validation
- [x] Get sorted
- [x] Remove
- [x] Chain id
- [x] Supported entry points
- [x] Estimate user operation gas
- [x] Memory mempool
- [x] Database mempool
- [x] P2P
- [ ] Alternative mempools with custom sanity checks and simulation validation
- [ ] Support different versions (smart contracts) of the entry point
- Bundler Core
- [x] Wallet
- [ ] Signature aggregation
- Bundling
- [x] Based on max priority fee per gas
- [ ] Custom logic
- Submitting bundles
- [x] ETH execution client - public transaction pool
- [x] Flashbots integration
- [ ] Conditional RPC endpoint
- [ ] Networks (tested)
- [x] Mainnet
- [x] Goerli
- [x] Sepolia
- [x] Polygon
- [x] Polygon Mumbai
- [x] Arbitrum
- [x] Optimism
- [x] Base
- [x] Linea
- [x] Avalanche
- [x] Blast
- [x] Binance Smart Chain
- [ ] Mode
Additional enhancements:
- Smart contract wallets tests
- [x] [Trampoline](https://github.com/eth-infinitism/trampoline)
- [x] [Candide Wallet](https://github.com/candidelabs/candide-mobile-app)
- Libraries
- [x] [userop.js](https://github.com/stackup-wallet/userop.js)
- [ ] Reth (integration or reusing components)
- [ ] Documentation
## Resources
[ERC-4337: Account Abstraction Using Alt Mempool](https://eips.ethereum.org/EIPS/eip-4337)
[ERC-4337 website](https://www.erc4337.io/)
[ERC-4337 Twitter](https://twitter.com/erc4337)
[GitHub ETH Infinitism](https://github.com/eth-infinitism)
[Bundler spec](https://github.com/eth-infinitism/bundler-spec)
[Bundler spec tests](https://github.com/eth-infinitism/bundler-spec-tests)
[Bundler test executor](https://github.com/eth-infinitism/bundler-test-executor)
[Bundler spec tests results](https://www.erc4337.io/bundlers)
[Ethereum Protocol Fellowship - The Third Cohort (project description)](https://github.com/eth-protocol-fellows/cohort-three/blob/master/projects/4337-bundler-rust.md)
Sign in with Wallet
Connect another wallet