diff --git a/docs/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from docs/CONTRIBUTING.md rename to CONTRIBUTING.md diff --git a/README.md b/README.md index 71419fd2e..2620d8e73 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,118 @@ # Rundler -## Development +[![gh_ci_badge]][gh_ci_link] +[![tg_badge]][tg_link] -### Build & Test +[gh_ci_badge]: https://github.com/OMGWINNING/rundler/workflows/ci/badge.svg +[gh_ci_link]: https://github.com/OMGWINNING/rundler/actions/workflows/ci.yml +[tg_badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Frundler +[tg_link]: https://t.me/rundler -Prerequisites: +**High-performance, modular implementation of an ERC-4337 bundler** -* [Rust & Cargo](https://rustup.rs/) - * Nightly rust required for `rustfmt`: -``` -rustup toolchain add nightly -``` -* [Cocogitto](https://github.com/cocogitto/cocogitto) - * `cargo install --locked cocogitto` -* [Docker](https://docs.docker.com/engine/install/) +[TODO] cover art -Run tests: -``` -git clone https://github.com/OMGWINNING/rundler -cd rundler -cargo test --all -``` +[Run](#running) | [Developer Docs](./docs) + +🚧 *Under active development, see [status](#status) below.* + +## What's a Rundler? + +**Rundler** (**R**ust B**undler**) is an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) bundler implementation written in Rust. Rundler is designed to achieve high-performance and high-reliability in cloud deployments via its modular architecture. + +Built, maintained, and used by [Alchemy](https://www.alchemy.com/) to push the limits of user experience on EVM chains via [Account Abstraction](https://www.alchemy.com/blog/account-abstraction). + +## Goals + +Rundler is meant to power the ERC-4337 ecosystem with an implementation that users can rely on to scale to their needs while maintaining high reliability. As ERC-4337 is a nascent technology, Rundler strives to be on the bleeding edge of feature support and the team will be contributing to push the protocol forward. + +Our goals with Rundler: + +1. **ERC-4337 Specification Compliance**: Rundler strives to implement the full ERC-4337 specification and to maintain support as the specification is changed and new onchain components are released. This includes new Entry Point contract support, support for the upcoming P2P mempool specification, and support for alt-mempools. +2. **High Performance and Reliability**: Rundler strives to power the most demanding workloads in cloud environments. Rust was chosen for its high performance and memory safety. Rundler's modular architecture lets providers choose to run the stateless components (RPC, builder) in a fully horizontally scalable manner connecting to the stateful components (mempool, p2p, event cache) via the network. Rundler's bundle builder is designed to be able to support the full gas throughput of the network its building for. +3. **Extendability/Chain Support**: ERC-4337 is designed to support any EVM chain. However, different EVM supporting networks have different rules around how they support things like gas usage, gas fees, precompiles, etc. Rundler is designed to be extendable and easily adapted to support any EVM chain. +4. **Modularity**: Rundler is written in a modular manner, allowing its components to be run as a single integrated binary, or as a distributed system. Rundler also strives for its individual crates to be used to support future ERC-4337 tooling. + +## Status + +Rundler is under active development. It is used in Alchemy's cloud to power its account abstraction APIs. However, it is rapidly being upgraded, features are being added, interfaces will have breaking changes, and the ERC-4337 spec is evolving from onchain learnings. + +The documentation is also very work in progress, and we are working to improve it. Please [reach out](#help) with any questions. -### Run locally: +**Use in production at your own risk.** -Running locally requires access to an Ethereum RPC node on the network the Rundler is running on. For testing it is recommended to run a local development node. +### ERC-4337 Support -Steps to run `Geth` in dev mode locally: +Rundler currently supports the [v0.6 release](https://github.com/eth-infinitism/account-abstraction/tree/v0.6.0) of Entry Point contract. -1. `cd test` -2. `docker compose up` (use `-d`) to run in background. +### Chain Support -Steps to run `Rundler` locally: +Rundler currently supports and has been tested on the following networks and their testnets: -1. Copy the default .env file. By default, this will be pointing at the local `Geth` node. +* Ethereum +* Optimism +* Base +* Arbitrum One +* Polygon POS + +## Developers + +### Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). + +### Running + +The easiest way to run Rundler is via a docker container. There is currently no pre-built image. See our [docker documentation](docs/docker.md) for further instructions. + +### Developing + +For detailed instructions see [developing](docs/developing.md). + +Prerequisites: +* [Rust](https://rustup.rs/) 1.71.0 or higher. +* [Docker](https://docs.docker.com/engine/install/) (for spec testing) +* [PDM](https://pdm.fming.dev/latest/) (for spec testing) + +Clone the repository and checkout submodules: ``` -cp test/.env.default .env +git clone https://github.com/OMGWINNING/rundler +cd rundler +git submodule update --init --recursive ``` -2. (Optional) Fund and deploy contracts. Contracts are deployed from the [account-abstraction](https://github.com/eth-infinitism/account-abstraction) repo. This does the following: - * Creates an account for the bundler to use. - * Deploys the `EntryPoint`. - * Deploys a `SimpleAccountFactory`. - * Deploys a `VerifyingPaymaster`. - * Deploys a `SimpleAccount`. - * Funds each of the accounts. +Run unit tests: ``` -cargo run --bin deploy_dev_contracts +make test-unit ``` -3. (Optional) Modify the `BUNDLER_PRIVATE_KEY` field if using a different account than was funded in #2. - -4. Start the Rundler +Run ERC-4337 spec tests: ``` -cargo run node +cd test/spec-tests/bundler-spec-tests && pdm install && pdm run update-deps +make test-spec-integrated ``` -### Documentation +### Help + +If you have questions regarding the Rundler codebase, please first look through our [documentation](./docs/). + +With further questions: + +* Github discussions +* [Telegram][tg_link] +* [Github issues](https://github.com/OMGWINNING/rundler/issues/new/choose) + +If you have questions regarding Alchemy's APIs or service, kindly refrain from discussion here. Please join the [Discord](https://discord.com/invite/alchemyplatform) or reach out to support@alchemy.com. -- [configuration](docs/config.md) -- [transactions](docs/transactions.md) -- [contributing](docs/CONTRIBUTING.md) -- [architecture](docs/architecture.md) +### Security -### Goals +For security concerns do not file a public ticket, please reach out to security@alchemy.com. -- Implement P2P mempool -- Implement persistent mempool -- Keep our spec test fork in like with origin -- Deploy public docker image -- Cross platform compilation +See [SECURITY.md](SECURITY.md) for details. -### Resources +## Acknowledgements -- [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) +We stand on the shoulders of the following teams: -### Communication: -- [Telegram](https://t.me/+F_xS9IVOdJZmZjQx) \ No newline at end of file +- [ERC-4337 team](https://github.com/eth-infinitism/account-abstraction): The ERC-4337 team has pioneered the standard, and has answered countless questions during our development. They also developed the bundler reference implementation and spec tests that were invaluable during our development process. We are excited to continue to work with this team to push ERC-4337 ahead. +- [Reth](https://github.com/paradigmxyz/reth): Shoutout to the Reth team, from which we've taken inspiration for many of our practices in this repo (including this README). They are pushing the Ethereum Rust ecosystem forward in an open way. We thank the Reth team for their continued contributions. diff --git a/docs/SECURITY.md b/SECURITY.md similarity index 61% rename from docs/SECURITY.md rename to SECURITY.md index b52c7e1f1..5ce0981a8 100644 --- a/docs/SECURITY.md +++ b/SECURITY.md @@ -8,4 +8,4 @@ ## Reporting a Vulnerability -If you would like to report a vulnerability, please open a github issue and tag it with the `security` label. \ No newline at end of file +If you would like to report a vulnerability, please contact security@alchemy.com diff --git a/crates/builder/proto/README.md b/crates/builder/proto/README.md index c2ed9d54f..a46ffd6da 100644 --- a/crates/builder/proto/README.md +++ b/crates/builder/proto/README.md @@ -1,18 +1,3 @@ -# TODO +Protocol buffer definitions for the builder module. -# Protocol Buffer Definitions - -This directory stores the schema definitions used by Rundler and the supporting gRPC services of it's internal components. - -## Building - -Rundler builds on [Tonic](https://github.com/hyperium/tonic) to power lightning quick gRPC interfaces between internal components. To re-compile changes to the protocol buffers: - -1. Make sure `protoc` is installed locally. On Macs one can run `brew install protobuf`. Otherwise see the official [protobuf docs](https://grpc.io/docs/protoc-installation/) for installation instructions. -2. Run `cargo build` to recompile the protocol buffers as part of the overall binary build. This is configured in `build.rs` in the `generate_protos` function. Adding schemas in new files will require a change to `build.rs`. - -## Protocol Buffer to Memory Representation Translation - -## Style Guide - -Rundler largely relies on the canonical (protobuf style guide)[https://protobuf.dev/programming-guides/style/]. There are a few minor differences captured in `buf.yaml` to support Tonic best practices. Rundler use (buf)[https://buf.build/] to lint the `.proto` files. To use `buf` run `buf lint protos/.`. To install `buf` on Macs, run `brew install bufbuild/buf/buf`. +Refer to [proto.md](../../../docs/proto.md) for best practices. diff --git a/crates/pool/proto/README.md b/crates/pool/proto/README.md index f87f5c14c..b97ae2e57 100644 --- a/crates/pool/proto/README.md +++ b/crates/pool/proto/README.md @@ -1 +1,3 @@ -# TODO \ No newline at end of file +Protocol buffer definitions for the pool module. + +Refer to [proto.md](../../../docs/proto.md) for best practices. diff --git a/docs/alt-mempools.md b/docs/alt-mempools.md deleted file mode 100644 index 83d23a5ad..000000000 --- a/docs/alt-mempools.md +++ /dev/null @@ -1,13 +0,0 @@ -## TODO - -*example configuration* - -``` -{ - "0x0000000000000000000000000000000000000000000000000000000000000000": { - "description": "USDC paymaster allowlist - base goerli", - "chainIds": ["0x2105"], - "allowlist": [] - } -} -``` \ No newline at end of file diff --git a/docs/architecture/architecture.md b/docs/architecture/architecture.md new file mode 100644 index 000000000..591098565 --- /dev/null +++ b/docs/architecture/architecture.md @@ -0,0 +1,33 @@ +# Rundler Architecture + +Rundler consists of 3 main "tasks" that work in tandem to implement the ERC-4337 bundler specification. + +- [**RPC**](./rpc.md): The `RPC` task implements the defined [ERC-4337 RPC methods](https://eips.ethereum.org/EIPS/eip-4337#rpc-methods-eth-namespace) under both the `eth_` and `debug_` namespaces. It also implements Rundler specific methods under the `rundler_` namespace and a health check endpoint. + +- [**Pool**](./pool.md): The `Pool` task implements a User Operation (UO) mempool. The mempool validates and simulates User Operations per the rules in the spec. It maintains the UOs in memory until they are mined onchain. The pool handles chain reorgs up to a defined depth using a cache of mined UOs. + +- [**Builder**](./builder.md): The `Builder` task is responsible for constructing bundles of User Operations, submitting them as transactions, and monitoring the status of those transactions. + +## Task Communication + +The tasks communicate with each other via message passing mechanisms. The `Pool` and `Builder` each run a "server" component responsible for receiving, acting upon, and responding to messages. + +**RPC -> Pool**: The `RPC` module submits UOs to the `Pool` during the `eth_sendUserOperation` RPC method. Future RPC method implementations may use this communication path to retrieve UO status. + +**RPC -> Builder**: This communication path is only used when the `debug_` namespace is enabled. It is used to set the builder's bundling mode (to `manual` in tests) and trigger bundle submission (in `manual` mode). + +**Builder <-> Pool**: The `Builder` and the `Pool` coordinate to create bundles that contain valid, unmined, and profitable user operations. The `Builder` subscribes to a stream up of updates from the pool and is notified after each new block is processed. The builder then queries the pool for its most valuable UOs, re-simulates them and builds bundles. Any operations that fail 2nd simulation are communicated back to the `Pool` for removal. + +## Communication Modes + +Both the `Builder` and the `Pool` tasks can be configured to run a gRPC server capable of receiving and responding to messages from the network. Thus, Rundler can be configured to run in a distributed mode where its tasks run in separate processes. + +The `Builder` and `RPC` modules can be configured to communicate to other tasks via in-memory message passing (if running in the same process) or via gRPC (if running in separate processes). + +## Architecture Diagrams + +### Integrated Mode +[TODO] + +### Distributed +[TODO] diff --git a/docs/architecture.md b/docs/architecture/builder.md similarity index 54% rename from docs/architecture.md rename to docs/architecture/builder.md index 833585e82..46d3915a6 100644 --- a/docs/architecture.md +++ b/docs/architecture/builder.md @@ -1,12 +1,38 @@ -# Rundler Architecture +# Builder Task -there are 3 main process that are execute when running the rundler application and they are `rpc`, `builder` and `op_pool`. +## Bundle Proposer -## RPC +### Required Fees -The rpc module is used to expose a JSONRPC http api, much like a normal Ethereum node. To see the available requests, please refer to the [EIP4337 spec](https://eips.ethereum.org/EIPS/eip-4337) and find the RPC methods section. -To generate the JSONRPC api, we make use of [Parity's][parity] [jsonrpsee library][jsonrpsee] and its useful macro definitions. +### Gas Limit +### 2nd Simulation and Rejection + +## Transaction Signers + +- **Local**: +- [**KMS**](#kms-with-key-leasing): + +### KMS with Key Leasing + +## Transaction Senders + +- **Raw**: + +- **Conditional**: + +- **Flashbots**: + +- **Bloxroute**: + +## Transaction Lifecycle + +## N-Senders + + + +WIP UNDER THIS +--- ## Builder The builder module is used to propose, send and track transactions that need to be bundled together and pushed onto the chain. @@ -30,7 +56,7 @@ couple process that track the status of the operations and perform updates to th The signer component is used to sign transactions before they are sent to be propagated on chain. The signing process can either be done by a key that is local to the server instance or an AWS KMS key. When using the KMS option, there also needs to be a configured redis cache to perform locking. The locking is required as if there are multiple instances of the builder modules running, we want to -make sure that none there are two of the services are using the same key with the same nonce. This can lead to an immediate revertion of the bundle if the nonce is not correct when sending the bundle to be +make sure that none there are two of the services are using the same key with the same nonce. This can lead to an immediate reversion of the bundle if the nonce is not correct when sending the bundle to be processed on chain. ### Server @@ -38,25 +64,27 @@ processed on chain. The server component is a little bit more complex than the `sender` and the `signer` modules as there is a context of local or distributed options. The local server will work by passing messages between threads and listening to updates from the `pool`. If the server is running in the distributed mode, messaging is done via gRPC which can be local to the machine or across multiple machines. -## Op Pool - -The pool components purpose is to manage the mempool operations. Once a user operation is sent to the RPC server, the pool will add the operation to its mempool to be proposed via the builder and then to be propagated on chain. The Pool should be the -module that lets the bulder know when a new user operation has been added to the mempool so that it can then be proposed to be included in a new bundle. - -### Mempool - -Within the `op_pool` process, the state of the mempool is updated and controlled by the `mempool` module which provides basic crud operations for the underlying pool and keeps track of address reputation to make sure there is a reduced risk of -malicious activity when interacting with Rundler. - -## TODO make better diagrams -## Distributed architecture +# TODO -![distributed](images/multiimage.png) +## Bundle Transaction Submission -## Single Image architecture +There are three types of senders that we have implemented to propagate bundles on to the chain. -![singleimage](images/multiprocess.png) +- `RawTransactionSender` + - This sender will send the bundle as an `eth_sendRawTransaction`, so each of the transactions will need to be signed + before sending the bundle to the node url provided. +- `ConditionalTransactionSender` + - This sender will send the bundle as an `eth_sendRawTransactionConditional`, so each of the transactions will need to + be signed before sending the bundle to the node url provided. +- `FlashbotsTransactionSender` + - This sender will send the bundle as an `eth_sendBundle`, so each of the transactions will need to be signed before + sending the bundle to the flashbots protect relay url. This allows the transaction to be protected from frontrunning attacks, however + it is only available on `mainnet`, `goerli` and `sepolia`. +- `BloxrouteTransactionSender` + - [TODO] -[parity]: https://www.parity.io/ -[jsonrpsee]: https://github.com/paritytech/jsonrpsee \ No newline at end of file +When a bundle is submitted, we wait 2 blocks to see if the transaction has been mined. If the transaction has not +been mined within `BUILDER_MAX_BLOCKS_TO_WAIT_FOR_MINE` blocks, we increase the gas fees `BUILDER_REPLACEMENT_FEE_PERCENT_INCREASE` +percent. We repeat this process until the transaction either lands on chain or we increase the fee over `BUILDER_REPLACEMENT_FEE_PERCENT_INCREASE` +times and in that case the transaction will be set as stalled in the `StalledAtMaxFeeIncreases` status. diff --git a/docs/architecture/pool.md b/docs/architecture/pool.md new file mode 100644 index 000000000..b7abe4f80 --- /dev/null +++ b/docs/architecture/pool.md @@ -0,0 +1,17 @@ +# Pool Task + +## Simulation + +### Tracer + +## Reputation + +## Chain Tracking + +## Mempool Sharding + +## Allowlist/Blocklist + +## Alternative Mempools (in preview) + +## P2P diff --git a/docs/architecture/rpc.md b/docs/architecture/rpc.md new file mode 100644 index 000000000..9e4869565 --- /dev/null +++ b/docs/architecture/rpc.md @@ -0,0 +1,54 @@ +# RPC Task + +## Supported Methods + +### `eth_` Namespace + +| Method | Supported | +| ------ | :-----------: | +| `eth_chainId` | ✅ | +| `eth_supportedEntryPoints` | ✅ | +| `eth_estimateUserOperationGas` | ✅ | +| `eth_sendUserOperation` | ✅ | +| `eth_getUserOperationByHash` | ✅ | +| `eth_getUserOperationReceipt` | ✅ | + +### `debug_` Namespace + +| Method | Supported | +| ------ | :-----------: | +| `debug_clearState` | ✅ | +| `debug_dumpMempool` | ✅ | +| `debug_sendBundleNow` | ✅ | +| `debug_setBundlingMode` | ✅ | +| `debug_setReputation` | ✅ | +| `debug_dumpReputation` | ✅ | + +### `rundler_` Namespace + +| Method | Supported | +| ------ | :-----------: | +| `rundler_maxPriorityFeePerGas` | ✅ | + +### Health Check + +| Route | Supported | +| ------ | :-----------: | +| `/health` | ✅ | + + +## Gas Estimation + +To serve `eth_estimateUserOperationGas` Rundler attempts to estimate gas as accurately as possible, while always erroring to over-estimation. + +### `preVerificationGas` Estimation + +#### Static + +#### Dynamic + +### `verificationGasLimit` Estimation + +### `callGasLimit` Estimation + +## Fee Estimation diff --git a/docs/config.md b/docs/cli.md similarity index 88% rename from docs/config.md rename to docs/cli.md index dd04ed5ff..835f847aa 100644 --- a/docs/config.md +++ b/docs/cli.md @@ -1,4 +1,4 @@ -# RUNDLER CLI +# Rundler CLI The Rundler Command Line Interface (CLI) offers a versatile and configurable User Operation Bundler, equipped with a wide array of options and subcommands tailored to your needs. @@ -11,7 +11,7 @@ The Rundler Command Line Interface (CLI) offers a versatile and configurable Use The `pool` and `builder` servers will also start a gRPC endpoint to allow other processes to interact with each service -## General Options +## Common Options These options are common to all subcommands and can be used globally: @@ -54,6 +54,8 @@ These options are common to all subcommands and can be used globally: - env: *MEMPOOL_CONFIG_PATH* - [config example](alt-mempools.md) +### Mempool Configuration + ## Metrics Options Options for the metrics server: @@ -95,9 +97,9 @@ List of command line options for configuring the RPC API. - `--rpc.builder_url`: Builder URL for RPC (default: `http://localhost:50052`) - env: *RPC_BUILDER_URL* -## OP Pool Options +## Pool Options -List of command line options for configuring the OP Pool. +List of command line options for configuring the Pool. - `--pool.port`: Port to listen on for gRPC requests (default: `50051`) - env: *POOL_PORT* @@ -120,7 +122,9 @@ List of command line options for configuring the OP Pool. - `--pool.chain_history_size`: Size of the chain history - env: *POOL_CHAIN_HISTORY_SIZE* -## Builder CLI Options +### Allowlist/Blocklist + +## Builder Options List of command line options for configuring the Builder. @@ -155,38 +159,13 @@ List of command line options for configuring the Builder. - `--builder.max_fee_increases`: Maximum number of fee increases to attempt (Seven increases of 10% is roughly 2x the initial fees) (default: `7`) - env: *BUILDER_MAX_FEE_INCREASES* -## Key management +### Key management Private keys for the bundler can be provided in a few ways. You can set the `--builder.private_key` flag or the `BUILDER_PRIVATE_KEY` environment variable -within your local or deployed environment. Alternateley, you can provide the application with one or more AWS KMS ids using the `--builder.aws_kms_key_ids` flag or `AWS_KMS_KEY_IDS` environment +within your local or deployed environment. Alternatively, you can provide the application with one or more AWS KMS ids using the `--builder.aws_kms_key_ids` flag or `AWS_KMS_KEY_IDS` environment variable. Rundler will download the key/s so long as you have `kms:DescribeKey` & `kms:Decrypt` IAM access to the KMS resource. -When using KMS keys, a redis url must be provided to the bundler which will take care of key locking to make sure keys are not accessed at the same time from concurrent processes - -## Example configuration files - -### Pool allowlist path - -``` -export POOL_ALLOWLIST_PATH=blocklist.json -``` - -``` -[ - "0x0000000000000000000000000000000000000000000000000000000000000000" -] -``` -### Pool blocklist path - -``` -export POOL_BLOCKLIST_PATH=blocklist.json -``` - -``` -[ - "0x0000000000000000000000000000000000000000000000000000000000000000" -] -``` +When using KMS keys, a Redis URL must be provided to Rundler which will take care of key leasing to make sure keys are not accessed at the same time from concurrent processes. ## Example Usage @@ -194,10 +173,11 @@ Here are some example commands to use the CLI: ```sh # Run the Node subcommand with custom options -$ ./app --entry_points 0x0000000000000000000000000000000000000000 --chain_id 1337 --max_verification_gas 10000000 node +$ ./rundler node --entry_points 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 --chain_id 1337 --max_verification_gas 10000000 -# Run the Rpc subcommand with custom options and enable JSON logging. The builder and pool will need to be running before this starts. -$ ./app --node_http http://localhost:8545 --log.json rpc +# Run the RPC subcommand with custom options and enable JSON logging. The builder and pool will need to be running before this starts. +$ ./rundler rpc --node_http http://localhost:8545 --log.json # Run the Pool subcommand with custom options and specify a mempool config file -$ ./app --max_simulate_handle_ops_gas=15000000 --mempool_config_path=mempool.json --node_http http://localhost:8545 --chain_id=8453 pool \ No newline at end of file +$ ./rundler pool --max_simulate_handle_ops_gas 15000000 --mempool_config_path mempool.json --node_http http://localhost:8545 --chain_id 8453 +``` \ No newline at end of file diff --git a/docs/developing.md b/docs/developing.md new file mode 100644 index 000000000..f4cb7f5b3 --- /dev/null +++ b/docs/developing.md @@ -0,0 +1,20 @@ +# Developing + +## Setup + +## Build & Test + +## Running Locally + +## Dev Tools + +Fund and deploy contracts. Contracts are deployed from the [account-abstraction](https://github.com/eth-infinitism/account-abstraction) repo. This does the following: + * Creates an account for the bundler to use. + * Deploys the `EntryPoint`. + * Deploys a `SimpleAccountFactory`. + * Deploys a `VerifyingPaymaster`. + * Deploys a `SimpleAccount`. + * Funds each of the accounts. +``` +cargo run --bin deploy_dev_contracts +``` diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 000000000..837946c8d --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,5 @@ +# Docker + +## Build + +## Run diff --git a/docs/images/multiimage.png b/docs/images/multiimage.png deleted file mode 100644 index 847c5b11b..000000000 Binary files a/docs/images/multiimage.png and /dev/null differ diff --git a/docs/images/multiprocess.png b/docs/images/multiprocess.png deleted file mode 100644 index eb40626c9..000000000 Binary files a/docs/images/multiprocess.png and /dev/null differ diff --git a/docs/proto.md b/docs/proto.md new file mode 100644 index 000000000..3dd3c1a9f --- /dev/null +++ b/docs/proto.md @@ -0,0 +1,16 @@ +# Rundler Protocol Buffers + +Rundler utilizes gRPC for communication between modules while running in distributed mode. Refer to this document for best practices when utilizing protocol buffers in gRPC. + +## Building + +Rundler builds on [Tonic](https://github.com/hyperium/tonic) to power lightning quick gRPC interfaces between internal components. To re-compile changes to the protocol buffers: + +1. Make sure `protoc` is installed locally. On Macs one can run `brew install protobuf`. Otherwise see the official [protobuf docs](https://grpc.io/docs/protoc-installation/) for installation instructions. +2. Run `cargo build` to recompile the protocol buffers as part of the overall binary build. This is configured in `build.rs` in the `generate_protos` function. Adding schemas in new files will require a change to `build.rs`. + +## Protocol Buffer to Memory Representation Translation + +## Style Guide + +Rundler largely relies on the canonical (protobuf style guide)[https://protobuf.dev/programming-guides/style/]. There are a few minor differences captured in `buf.yaml` to support Tonic best practices. Rundler use (buf)[https://buf.build/] to lint the `.proto` files. To use `buf` run `buf lint protos/.`. To install `buf` on Macs, run `brew install bufbuild/buf/buf`. diff --git a/docs/transactions.md b/docs/transactions.md deleted file mode 100644 index 2ae19b231..000000000 --- a/docs/transactions.md +++ /dev/null @@ -1,19 +0,0 @@ -## Bundle Transaction Submission - -There are three types of senders that we have implemented to propagate bundles on to the chain. - -- `RawTransactionSender` - - This sender will send the bundle as an `eth_sendRawTransaction`, so each of the transactions will need to be signed - before sending the bundle to the node url provided. -- `ConditionalTransactionSender` - - This sender will send the bundle as an `eth_sendRawTransactionConditional`, so each of the transactions will need to - be signed before sending the bundle to the node url provided. -- `FlashbotsTransactionSender` - - This sender will send the bundle as an `eth_sendBundle`, so each of the transactions will need to be signed before - sending the bundle to the flashbots protect relay url. This allows the transaction to be protected from frontrunning attacks, however - it is only available on `mainnet`, `goerli` and `sepolia`. - -When a bundle is submitted, we wait 2 blocks to see if the transaction has been mined. If the transaction has not -been mined within `BUILDER_MAX_BLOCKS_TO_WAIT_FOR_MINE` blocks, we increase the gas fees `BUILDER_REPLACEMENT_FEE_PERCENT_INCREASE` -percent. We repeat this process until the transaction either lands on chain or we increase the fee over `BUILDER_REPLACEMENT_FEE_PERCENT_INCREASE` -times and in that case the transaction will be set as stalled in the `StalledAtMaxFeeIncreases` status.