silius-rs/silius

ERC-4337 (Account Abstraction) - modular and efficient bundler implementation in Rust.

Silius

Silius - ERC-4337 (Account Abstraction) bundler implementation in Rust.

For more information: https://hackmd.io/@Vid201/aa-bundler-rust

This project is still under active development.

Getting started

Native

Prerequisites:

Rust version: 1.78.0

1. libclang-dev, pkg-config and libssl-dev on Debian/Ubuntu.
2. Ethereum execution client JSON-RPC API with enabled debug_traceCall. For production, you can use Geth or Erigon. For testing, we are using Geth dev mode (tested with v1.12.0); so you need to install Geth for running tests.
3. solc >=0.8.12.
4. cargo-sort and cargo-udeps.

Set up third-party dependencies (ERC-4337 smart contracts and bundler tests):

make fetch-thirdparty
make setup-thirdparty

Create wallet for bundler:

cargo run --release -- create-wallet --output-path ${HOME}/.silius --chain-id 5

Run bundler (with user operation pool and JSON-RPC API):

cargo run --release -- node --eth-client-address http://127.0.0.1:8545 --mnemonic-file ${HOME}/.silius/0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --beneficiary 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --entry-points 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 --http --ws

Run only bundling component:

cargo run --release -- bundler --eth-client-address ws://127.0.0.1:8546 --mnemonic-file ${HOME}/.silius/0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --beneficiary 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --entry-points 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789

Run only user operation pool:

cargo run --release -- uopool --eth-client-address ws://127.0.0.1:8546 --entry-points 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789

Run only JSON-RPC API:

cargo run --release -- rpc --http --ws

Docker

docker run --net=host -v ./bundler-spec-tests/keys/0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266:/data/silius/0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 -v ./.local/db:/data/silius/db ghcr.io/silius-rs/silius:latest node --eth-client-address http://127.0.0.1:8545 --datadir data/silius --mnemonic-file data/silius/0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --beneficiary 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --entry-points 0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789 --http --http.addr 0.0.0.0 --http.port 3000 --http.api eth,debug,web3 --ws --ws.addr 0.0.0.0 --ws.port 3001 --ws.api eth,debug,web3 --eth-client-proxy-address http://127.0.0.1:8545

Supported networks

Silius was tested on the following networks, and some public endpoints are available for testing. If you have problems with any endpoint below, you are welcome to fire an issue.

Chain	Supported Status	Public RPC URL
Ethereum	✔️	https://rpc.silius.xyz/api/v1/chain/ethereum-mainnet
Ethereum Goerli	✔️	https://rpc.silius.xyz/api/v1/chain/ethereum-goerli
Ethereum Sepolia	✔️	https://rpc.silius.xyz/api/v1/chain/ethereum-sepolia
Ethereum Holesky	✔️	https://rpc.silius.xyz/api/v1/chain/ethereum-holesky
Polygon	✔️	https://rpc.silius.xyz/api/v1/chain/polygon-mainnet
Polygon Mumbai	✔️	https://rpc.silius.xyz/api/v1/chain/polygon-mumbai
Linea	✔️	https://rpc.silius.xyz/api/v1/chain/linea-mainnet
Linea Goerli	✔️	https://rpc.silius.xyz/api/v1/chain/linea-goerli
Optimism	✔️	https://rpc.silius.xyz/api/v1/chain/optimism-mainnet
Optimism Sepolia	✔️	https://rpc.silius.xyz/api/v1/chain/optimism-sepolia
Arbitrum	✔️	https://rpc.silius.xyz/api/v1/chain/arbitrum-mainnet
Arbitrum Sepolia	✔️	https://rpc.silius.xyz/api/v1/chain/arbitrum-sepolia
BSC	✔️	https://rpc.silius.xyz/api/v1/chain/bsc-mainnet
BSC Testnet	✔️	https://rpc.silius.xyz/api/v1/chain/bsc-testnet
Base	✔️	https://rpc.silius.xyz/api/v1/chain/base-mainnet
Base Sepolia	✔️	https://rpc.silius.xyz/api/v1/chain/base-sepolia
Avalanche	✔️	https://rpc.silius.xyz/api/v1/chain/avalanche-mainnet
Avalanche Fuji	✔️	https://rpc.silius.xyz/api/v1/chain/avalanche-fuji
Blast	✔️	https://rpc.silius.xyz/api/v1/chain/blast-mainnet
Blast Sepolia	✔️	https://rpc.silius.xyz/api/v1/chain/blast-sepolia

Bundler's account: 0x0a4E15d25E97e747bD568979A3B7dbEb95970Eb3

You can also try the Silius on any other EVM network, but you may encounter some problems (e.g., gas calculating differences on L2s) - please use it at our own risk! You are always welcome to open up a new issue when you meet any problem. ⚠️

Supported entry point

The address of the entry point smart contract is the same on all EVM networks.

Address	Version	Commit	Audited
0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789	0.6.0	9b5f2e4	April 2023

Paymasters and account factories

You can find a list of many paymasters and account factories here.

Examples

To get started, check the examples here. More examples will be added in the future.

Contributing

Thank you for showing interest in contributing to the project!

There is a contributing guide to help get you started.

There are some additional prerequisites for testing:

1. geth

Before making a PR, make sure to run the following commands:

make format
make lint
make test

Official bundler spec tests developed by the eth-infinitism team are also included in the repo's CI pipeline (commit: 08cbbfcb9e37b84c0ef9e546975f88fa638cac61). You can find more information on how to run tests here. Make sure your contribution doesn't break the tests!

Contact

The best place for the discussion is the dedicated Telegram group.

Authors

• Vid Kersic: GitHub, Twitter
• WillQ: GitHub, Twitter

Projects using Silius

• Luban the Paymaster: A Cross-chain Tx Sponsorship Protocol.
• Ethers UserOp: An ether-rs middleware to craft UserOperations.

Licenses

This project is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

Donations

Silius is an open-source project and a public good. If you want to help the project, you can send donations of any size via:

• Ethereum address: 0x7cB801446AC4f5EA8f7333EFc58ab787eB611558

Acknowledgements

• Bundler - eth-infinitism
• Akula
• ethers-rs
• Reth
• Lighthouse
• Alloy

silius's Issues

Add docker support

DB user operation pool

Use mdbx.

RPC eth_getUserOperationReceipt

P2P mempool of user operations

Bundlers will form P2P network to exchange user operations (similar to P2P tx pool in the normal Ethereum network).

There will be official spec test released by eth-infinitism that the bundler MUST pass.

Unify binary executbles into one

Currently we have 4 executables bundle-rpc, bundler-uopool, bundler, create-wallet.

We could create a big binary executable like aa-bundler and put the 4 above into subcommand

Integration into Rust execution client

eth_estimateUserOperationGas

Abstract sanity check and simulation rules

Alternative mempools (that is not canonical mempool) can use only subset of all sanity check and simulation rules, e.g., only forbidden opcodes. They can also introduce new custom rules that are specific to them.

We should have a way modular way of enabling/turning on certain rules and add way to write custom rules and include them in the verification/validation workflow.

When bundler will received user operation, it will have to match to which alt mempool the user operation should be passed.

Send bundles (txs) to Flashbots

Sending bundles (txs) to the public mempool can result in front-running, which leads to loss for bundlers.

Updating reputation when UserOperation is valid

There are some undone todo in codes:

https://github.com/Vid201/aa-bundler/blob/ba51bad1dd76d17bbc60b9ddd1a5617f9b9dea59/src/uopool/services/uopool.rs#L120-L121

Improve error handling

Improve error handling and make it consistent throughout the codebase

In-memory user operation pool

Received user operations are persisted in memory untill they are included in the bundle.

Add docker build and push to containers registry to GitHub CI

Push automatically on each PR to main branch.

https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

RPC eth_getUserOperationByHash

Provide a debug api flag for bundler api

I want to continue the question #43 (comment) here.

Currently, our debug API is config with a compiling flag #[cfg(debug_assertions)] which means the debug api would be there only when we build with cargo build. If we want to build with release version cargo build --release with compiler optimization, there are no debug apis.

I suggest we using the method like geth does providing a flag like --api debug to enable debug api instead of put it as a compilation flag. In that way, we could use release version to run tests especially for https://bundler-test-results.eip4337.com/. (BTW, @Vid201 very great job on it.) I want to see whether we could beat stackup-bundler on performance.

@Vid201 What do you think?

Throw UserOperationExecution in eth_estimateUserOperationGas

@zsluedem I merged the PR for removing JsonRpcError and created this ticket for throwing this error when execution is reverted (and fixing the test).

Would you mind taking this one?

Bundler mnemonic and private key

Problem

Currently, the bundler binary accepts a mnemonic folder or mnemonic file for the bundler's account. This can be confusing and should always be the same.

Proposed solution

1. Implement standalone binary for creating new mnemonic and saving it to file.
2. Change the bundler to always accept the mnemonic file.

Listen to new blocks and remove user operations from mempool

Reth could probably be used for that, look at: https://fiber.chainbound.io/blog/reth-p2p/

The approach above is not very stable at the moment. We should listen for new blocks over websockets (connected with Ethereum execution client).

Setup bundler spec test in ci

Remove user operation from mempool (gRPC endpoint)

Introduce github action cache to improve ci

Currently the ci is running so slow. It took about 17 mins to complete the ci.

We could accelerate it by introducing the github cache which could save a lot of time on network downloading.

Some guides:

1. https://github.com/actions/cache
2. https://github.com/marketplace/actions/rust-cache
3. https://github.com/marketplace/actions/yarn-install-cache

Read chain id from eth provider

User Operations simulations

This issue tracks work on simulation of user operations. Everything is explained here: https://eips.ethereum.org/EIPS/eip-4337#simulation

JS Tracer is needed to perform simulation.

Enable validating tests.

Currently the validating test is not enable because https://github.com/Vid201/aa-bundler/blob/398d24623db5021906c556de9daede998af5f051/tests/validate_tests.rs#L192-L195 isn't implemented.
We need to enable the test after the validation is completed #47.

User Operation sanity checks

This issue tracks work related to sanity checks of user operations. All sanity checks are described here: https://eips.ethereum.org/EIPS/eip-4337#client-behavior-upon-receiving-a-useroperation

Create crate primitives

First step to modular repo, create primitives crate

Implement tracer logic

The UserOperation simulation needs Geth debug_traceCall js tracer to collect custom evm operations.
And we need to implement this tracer logic for the simulations.

Here are some other implementations for reference:

1. https://github.com/eth-infinitism/bundler/blob/f5af738e7f95f53b8954d98e777b2c76c6ea9b1f/packages/bundler/src/GethTracer.ts#L18-L37
2. https://github.com/stackup-wallet/stackup-bundler/blob/main/pkg/tracer/types.go#L48-L54

Goal

1. implement Rust serde types for custom json output (Done in https://github.com/Vid201/aa-bundler/blob/feat/uopool/src/contracts/tracer.rs)
2. implement TracerTest.js

Github action

Set up github flow to run test, lint, etc

Add license

Add unwrap check to lint

https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used

Add tests for validation result to entrypoint.rs

Currently, there are only tests for parsing json rpc error.

It would be good to have some tests for parsing the data into validation result also.

Connection to the EntryPoint smart contract

Problem

Bundler must be able to conect to the EntryPoint smart contract and make calls.

Proposed solution

Use ethers-rs.

Bundler Configuration

1. Network level configuration (config file src/res/chainspec, mainnet, goerli, local) with neccessary values: supported entry points ...
2. Bundler level configuration (probably as params): bundler beneficiary ...

Add new RPC methods

eth-infinitism/bundler@c36bbc4#diff-521ed211628d3920a69fd17d254f8f29b6c93af1a63df613fc1a7c9b7f8ea8fd

Add local version geth to the GitHub CI, update tests

Some tests will rely on local geth node, would be useful to have this in github action

Modular ideas: split bundler, mempool and rpc into 3 crates.

Currently, we got everything in the aa-bundler crate.

Maybe we could separate these bundler, mempool and rpc into 3 crates and publish it for other rust developers to depend on.

Generally I am talking to change Cargo.toml into

[workspace]
members = [
    "bundler",
    "mempool",
    "rpc",
]

@Vid201 It is more like a discussion now and I am curious how you think about it.

Shortcoming:
A lot of code changes.

Bundling - sending bundles to local Ethereum node

In the first version, constructed bundles will be sent to public mempool of Ethereum node.

Paymaster

Bundling - core logic

Implement all necessay steps as defined here.

User operation pack and hash

Compute hash of user operation (which is ID), used in user operation pool (#7)

Add bundler mode in bundler

Add bundler mode in bundler for testing

Integration tests idea

Problem

We need a local Ethereum network tool like Hardhat tests. They should provide enough gRPCJSON endpoint and correct EVM execution. The bundler could be able to integrate with the local test network.

Proposed solution

I suggest we used the anvil tool. It is written in Rust and it is light enough for tests.

@Vid201 Please let me know if you have some other options to choose.

Goal

1. Introduce anvil tool into the repo.
2. Setup the test environment for abstract contracts .
3. Integrate with the anvil node with bundler.(This could be another issue.)

The goal here is to achieve 1 and 2.

Implement reputation scoring and throttling/banning for global entities

Details in https://github.com/eth-infinitism/account-abstraction/blob/develop/eip/EIPS/eip-4337.md#reputation-scoring-and-throttlingbanning-for-global-entities

And example in https://github.com/eth-infinitism/bundler/blob/main/packages/bundler/src/modules/ReputationManager.ts

Fix Rust cache in github ci

Rust cache stopped working for some reason.

Implementation of JSON RPC endpoint eth_sendUserOperation

Implement all the necessary steps as defined here.

Repeat debug calls to geth if they fail

debug_traceCall sometimes returns empty response - in that case, request should be repeated after some timeout.

eth_supportedEntryPoints

Remove user operations in the pool when clients create a block with the user operartions

This is a leftover in #68 .

The user operations should be removed when they are included in the blocks.

The request is in which component the bundler should keep an eye on it the bundler or the memory pool
@Vid201 Do you have any preference on this?

Example of bundler with single entry point running in single process

As discussed some time ago, showcase a minimal example of bundler with single entry point running in one process.

Add contribution guidelines