# Proposal: Transeptor, an ERC-4337 Open Source Bundler, designed with a strong emphasis on performance

The following document proposes a standalone [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) Bundler node. This proposal document outlines our approach, methodology, roadmap for the project, and the expected outcomes and deliverables. We have carefully considered the motivation behind ERC-4337 and its priorities and have tailored our proposal to meet those requirements.

## Abstract

One of the crucial components of the ERC-4337 is bundlers, which are the infrastructure of Account Abstraction. The ERC-4337 Bundler ecosystem needs bundler diversity and the ability to allow any actor to participate effortlessly in the bundling process. The more bundlers nodes participating in the Bundler network, the more decentralized and censorship-resistant the account abstraction layer can be.

This proposal outlines the development of an open-source Bundler for ERC-4337. Bundler nodes that participate in the bundling of UserOperation need access to a diverse set of Bundler implementations. Having multiple Bundler options helps to increase the security, stability, and overall health of the account abstraction layer by reducing the risk of a single point of failure.

Contributors: [V00D00-child](https://github.com/V00D00-child)
Project road Map: [see details below](#Project-StatusRoadmap-)

**Socials**

- [GitHub](https://github.com/transeptorlabs/transeptor-bundler)
- [Twitter](https://twitter.com/transeptorlabs)
- [Telegram](https://t.me/+eUGda3KIND4zMjRh)

## Objectives

This proposal aims to develop and deploy a functional ERC-4337 bundler node to promote the adoption of Account Abstraction by making it easier for anyone to participate in the Bundler network. Specifically, the goals of this project include:

1. Developing an open-source ERC-4337 standalone Bundler written in [Typescript](https://www.typescriptlang.org/) distributed using a Docker image.
2. Provide clear and comprehensive installation and debugging documentation for the Bundler software.
3. Ensure the Bundler software should fully comply with ERC-4337 and fulfill the core responsibilities:
- Receiving, verifying, and simulating user operations from smart contract wallets via the alternative public mempool.
- Manage the reputation of different entities - accounts, factories, paymasters, and signature aggregators.
- Maintaining alternative public mempool of user operations over a P2P network with other bundlers.
- Bundle multiple user operations into regular Ethereum transactions and submit them to Flashbot service for execution. Transactions are sent to Flashbot service instead of directly inserted into the public tx pool to avoid front-running.
6. Testing the Bundler in real-world scenarios to ensure their functionality, reliability, and security.
7. Encouraging community involvement and collaboration by fostering an open-source development process that enables other developers to contribute to the project, customize the technology, and extend its capabilities.

To measure the success of this project, we will use the following metrics:

1. **Adoption rate**: Track the number of downloads of the Bundler Docker image.
2. **Feedback**: The quality and quantity of feedback from actors using the Bundler software, focusing on key usability, functionality, and documentation areas.
3. **Community involvement**: Track the level of community involvement and collaboration in the development process, including the number of contributions from external developers.
4. **Security**: The absence of critical vulnerabilities in the Bundler.

By achieving these objectives and measuring success through these metrics, we aim to significantly impact the Ethereum ecosystem and help drive its continued growth and adoption.

## Outcomes
Developing and deploying an ERC-4337 bundler will significantly benefit the greater Ethereum ecosystem.

Also, we will encourage community involvement and collaboration in the development process by providing an open-source bundler. Driving community will enable other developers to contribute to the project, customize the technology, and extend its capabilities, leading to a more vibrant and innovative ecosystem.

## High-level overview - ERC-4337

See our documentation [here](https://transeptorlabs.io/docs/learn/erc4337-overview).

### What is ERC-4337
ERC-4337 is a higher-layer infrastructure for Ethereum to allow account abstraction. This will allows user to use a smart contract account to handle all network interactions. ERC-4337 introduces a new transaction called a UserOperation. Users will send signed UserOperations to a network of nodes called a Bundlers. Bundlers, will relay these transactions to Entrypoint smart contract to execute the UserOperations. ERC-4337 also introduces paymaster smart contracts to allow transaction sponsorship. Paymaster User can allow paymaster. With paymaster users have gasless transactions or pay gas fees with ERC-20 tokens.

### UserOperation

Users create a UserOperation for actions they want their account to perform.

| Field | Type | Description |
| --- | --- | --- |
| sender | address | The account making the operation |
| nonce | uint256 | Anti-replay parameter; also used as the salt for first-time account creation |
| initCode | bytes | The initCode of the account (needed if and only if the account is not yet on-chain and needs to be created) |
| callData | bytes | The data to pass to the sender during the main execution call |
| callGasLimit | uint256 | The amount of gas to allocate the main execution call |
| verificationGasLimit | uint256 | The amount of gas to allocate for the verification step |
| preVerificationGas | uint256 | The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata |
| maxFeePerGas | uint256 | Maximum fee per gas (similar to https://eips.ethereum.org/EIPS/eip-1559 max_fee_per_gas) |
| paymasterAndData | bytes | Address of paymaster sponsoring the transaction, followed by extra data to send to the paymaster (empty for self-sponsored transaction) |
| signature | bytes | Data passed into the account along with the nonce during the verification step |

### How does ERC-4337 work

There are five main components to ERC-4337: a `UserOperation`, `Bundler`, `EntryPoint Contract`, `Wallet(Account)`, and `Paymaster Contract`.

1. **Wallet(Account)**
- Wallet contract - a contract representing a user smart contract account
- Wallet Deployer - a contract(singleton) that creates a wallet contract
- Wallet software - UX client app used to sign and send the UserOperation to the Bundler node.
2. **UserOperation** - Users create a UserOperation for actions they want their account to perform. Users will send signed UserOperations to a network of nodes called a Bundlers.
- Like a transaction, it contains `sender`, `to`, `calldata`, `maxFeePerGas`, `maxPriorityFee`, `signature`, and `nonce`.
- Unlike a transaction, it contains several other fields.
3. **EntryPoint** - A smart contract that executes bundles of UserOperations as a standard transaction.
4. **Bundler** - A Bundler is a special type of node that works alongside Ethereum execution clients. It acts as a relayer, processing UserOperations. It performs simulations to ensure that the UserOperations are valid. Enforces storage access rules and opcode banning. Checks things like verifying signatures and handling gas fees. It then take valid UserOperations and package them together into a bundled transaction. Bundlers, will send this bundled transactions to Entrypoint smart contract for execution. It is important to note that not all block-builders on the network need to be bundlers. If a Bundler doesn't want to be a block-builder, it can use an API like [Flashbots](https://docs.flashbots.net/flashbots-auction/searchers/quick-start). Flashbots will allow the transaction to bypass the transaction mempool.
5. **Paymaster** - This contract can pay for transactions instead of the wallet itself. Wallet contracts can choose Paymaster to sponsor or pay transactions themselves.

## Bundler High-level Architecture
Transeptor provides two Node.js runtime configurations to suit your needs. You can run it using the Docker configuration for a container architecture. Or, you can use the cluster configuration for a standalone machine architecture.

### Clusters architecture
1. Dapps allow users to send user operations from ERC-4337 compatible wallets to a ERC-4337 Bundler.
2. The Bundler node will broadcast received user operations and retrieves other user operations by connection to other bundlers' in the p2p network.
3. The Bundler node connects to an ETH client(execution client) to retrieve information about Ethereum accounts (balances, stake/deposit info, etc.). It will also use the ETH client to simulate user operation using debug_traceCall for full validation.
4. The Bundler node will retrieve user operations from the mempool, create bundle transactions.
5. The bundle transactions will be sent on-chain using Flashbots service, or eth_sendRawTransactionConditional to protect the bundle transaction from front-running and allow block builders to propose to the Ethereum network.


### Docker Container architecture
1. Dapps allow users to send user operations from ERC-4337 compatible wallets to a ERC-4337 Bundler.
2. The Bundler node will broadcast received user operations and retrieves other user operations by connection to other bundlers' in the p2p network.
3. The Bundler node connects to an ETH client(execution client) to retrieve information about Ethereum accounts (balances, stake/deposit info, etc.). It will also use the ETH client to simulate user operation using debug_traceCall for full validation.
4. The Bundler node will retrieve user operations from the mempool, create bundle transactions.
5. The bundle transactions will be sent on-chain using Flashbots service, or eth_sendRawTransactionConditional to protect the bundle transaction from front-running and allow block builders to propose to the Ethereum network.


### Bundling Modes
Transeptor offers a wide range of bundling modes to fit your needs.

1. **Mempool support**: Determines the visibility of the UserOperations.
2. **EVM network**: The networks that the Bundler supports.
3. **Block building strategy**: The strategy the Bundler uses to send bundled UseOperations.
4. **Front-running protection**: Does the strategy to send bundles to protect the UseOperations from front-running

| Mode | Mempool support | EVM Networks | Block building strategy | Front-running protection |
| --- | --- | --- | --- | --- |
| **base | Private mempool of UserOperation | All EVM clients | Uses eth_sendRawTransaction RPC | no |
| **searcher | *p2p public mempool or private mempool | Ethereum and Goerli | Uses [Flashbots](https://docs.flashbots.net/flashbots-auction/searchers/quick-start) to send bundled UserOperations to block builders | yes |
| **conditional | *p2p public mempool or private mempool | EVM clients that support conditional transactions | Uses [eth_sendRawTransactionConditional](https://notes.ethereum.org/@yoav/SkaX2lS9j) RPC | yes |

*You can run with p2p enabled excluding private mode. Base mode should not run in production since it does not protect bundled transaction from front-running.

**active development

### Specification

See our documentation [here](https://transeptorlabs.io/bundler)

## Project Status/Roadmap :rocket:
This roadmap provides a comprehensive view of the project's timeline.

### Stage 1

**Deliverables**: A finalized project roadmap, a comprehensive analysis of existing ERC-4337 implementations, and a fully formed project team.

**Status**:

- [x] Finalized roadmap
- [x] Established team(in progress)
- [x] Proposal peer review
- [x] Contributing guidelines
- [x] Socials
- [x] Telegram(The best way to find an issue to work on): [https://t.me/+eUGda3KIND4zMjRh](https://t.me/+eUGda3KIND4zMjRh)
- [x] Twitter: [https://twitter.com/transeptorlabs](https://twitter.com/transeptorlabs)

### Stage 2

**Deliverables**: A fully functional and tested ERC-4337 Bundler.

**Status**:

- [x] **JsonrpcHttpServer modules**
- [x] start server
- [x] stop server
- [x] Run preflight checks before starting up server
- [x] Register eth method handler
- [x] Register debug method handler
- [x] Configure logging
- [x] param validation with correct rpc error codes
- [x] **Config modules**
- [x] Read .env variables
- [x] Read mnemonic txt for signer wallet
- [x] Handle cli input arguments
- [x] Init signer wallet using mnemonic
- [x] Configure rpc provider
- [x] Bundler modes
- [ ] **Provider Service**
- [x] Get provider from global Blockchain RPC provider Module
- [x] Handle all rpc calls(debug/tracer) to eth clients
- [ ] Handle rpc calls to [flashbot provider](https://docs.flashbots.net/flashbots-auction/searchers/quick-start) to send bundle transactions
- [ ] **Health check endpoint**
- [x] **eth RPC API**
- [x] eth_chainId
- [x] eth_supportedEntryPoints
- [x] eth_sendUserOperation
- [x] eth_estimateUserOperationGas
- [x] eth_getUserOperationReceipt
- [x] eth_getUserOperationByHash
- [x] **debug RPC API**
- [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] **web3 RPC API**
- [x] web3_clientVersion
- [x] **Validation module**
- [x] User operation simulations
- [x] validate UserOperation
- [x] **MempoolManager module**
- [x] Implementation of an in-memory non-priority queue. To avoid race conditions the enqueuing requests will behave in a [synchronous](https://www.npmjs.com/package/async-mutex) manner
- [x] Count mempool length
- [x] Add userOperation into the mempool
- [x] Check if there are already too many entries in mempool for a sender
- [x] Find item by key(useropHash)
- [x] Find item by sender/nonce
- [x] Replace existng userops if new gas is higher
- [x] Remove userOperation from the mempool by userOpHash or userOp
- [x] Clear in-memory state of mempool(debugging only)
- [x] Dump mempool content(debugging only)
- [x] Internal Memory mempool, default configuration
- [x] getAllPending userops in mempool
- [x] getNextPending userops in mempool based on bundle size
- [x] sender entryCount
- [x] **BundlerManager module**
- [x] Automatically attempt(every `xmins`) to send a bundle
- [x] manually send bundle
- [ ] **BundlerProcessor module**
- [x] collect UserOps from mempool into a bundle
- [ ] send bundle with Flashbot
- [x] send bundle eth_sendRawTransactionConditional
- [x] send bundle eth_sendRawTransaction
- [ ] handle bundle transaction fails
- [ ] bundle transaction conformation manager
- [x] update mempool after transaction
- [x] drop failed userOperations from mempool
- [x] second Validation before bundleing userop
- [x] **Event module**
- [x] listen and handle events on the entrypoint contract
- [x] **ReputationManager module**
- [ ] **p2p module** (public modes only) [spec](https://github.com/eth-infinitism/bundler-spec/blob/main/p2p-specs/p2p-interface.md)
- [ ] **Bundler mode support**
- [x] base
- [ ] searcher
- [x] conditional
- [X] **CI/CD**
- [x] Docker image `v0.1.0` - see [here](https://hub.docker.com/r/transeptorlabs/bundler)
- [X] Github action workflow to build and deploy Docker image to image repo
- [x] Github action workflow to automate MR builds
- [x] Require passing test
- [x] Require passing lint
- [x] Require passing build bundler
- [x] **Pass ERC-4337 bundler compatibility tests** - [bundler-spec-tests](https://github.com/eth-infinitism/bundler-spec-tests)
- [x] Entrypoint v6 support
- [X] Entrypoint v7 support
- [ ] **Additional enhancements:**
- [X] Set up real-time metrics(system performance) with InfluxDB database, and Grafana.
- [ ] Set up real-time metrics(bundler specfic) with database Prometheus, and Grafana.data.
- [ ] Support WebSocket transport
- [ ] refactor code/clean up and unit testing

### Stage 3

**Deliverables**: Comprehensive documentation and tutorials.

**Status**:

- [ ] Documentation site built on [Docusaurus](https://docusaurus.io/) ([https://transeptorlabs.io/docs/intro](https://transeptorlabs.io/docs/intro))
- [x] Installation documentation
- [ ] Set up bundler walkthrough documentation
- [ ] Set up bundler walkthrough documentation with metrics enabled
- [ ] Refesh Bundler Architecture docs

## Resources

### ERC 4337

- [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337)
- [Bundlerimplementation Golang](https://docs.stackup.sh/docs/packages/bundler/install)
- [Bundler implementation(Typescript)](https://github.com/eth-infinitism/bundler)
- [Bundler compatibility test spec](https://github.com/eth-infinitism/bundler-spec-tests)
- [High-level architecture(Rust)](https://hackmd.io/@Vid201/aa-bundler-rust)
- [Bundler infrastructure](https://www.stackup.sh/)

### Ethereum Architecture

- [https://ethereum.org/en/developers/docs/evm/](https://ethereum.org/en/developers/docs/evm/)
- [https://ethereum.org/en/developers/docs/nodes-and-clients/](https://ethereum.org/en/developers/docs/nodes-and-clients/)
- [https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/)

### JSON-RPC

- [JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/)
- [Infura- Ethereum RPCs, Methods and Calls](https://blog.infura.io/post/ethereum-rpcs-methods)
- [Explained - Remote Procedure Calls (RPC)](https://www.youtube.com/watch?v=QmhTjsOOrlw&t=854s)
- [Issues in RPC & How They're Resolved](https://www.youtube.com/watch?v=jH3RezOHROU)