chore(docs): new docs format

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 [email protected].
 
-- [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 [email protected].
 
-- 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)
+- [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.

docs/SECURITY.md → 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.
+If you would like to report a vulnerability, please contact security@alchemy.com

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.

crates/pool/proto/README.md

@@ -1 +1,3 @@
-# TODO
+Protocol buffer definitions for the pool module.
+
+Refer to [proto.md](../../../docs/proto.md) for best practices.

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]

docs/architecture.md → 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,33 +56,35 @@ 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
 
 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
+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.

docs/architecture/pool.md

@@ -0,0 +1,17 @@
+# Pool Task
+
+## Simulation
+
+### Tracer
+
+## Reputation
+
+## Chain Tracking
+
+## Mempool Sharding
+
+## Allowlist/Blocklist
+
+## Alternative Mempools (in preview)
+
+## P2P