alchemyplatform · 0xfourzerofour · Sep 20, 2023 · Sep 20, 2023 · Sep 20, 2023
@@ -56,6 +56,24 @@ cargo run --bin deploy_dev_contracts
 cargo run node
 ```
 
-### Contributing:
+### Documentation
 
-* Commit messages must follow [conventional commits style](https://www.conventionalcommits.org/en/v1.0.0/).
+- [configuration](docs/config.md)
+- [transactions](docs/transactions.md)
+- [contributing](docs/CONTRIBUTING.md)
+- [architecture](docs/architecture.md)
+
+### Goals
+
+- Implement P2P mempool
+- Implement persistant mempool
+- Keep our spec test fork in like with origin 
+- Deploy public docker image
+- Cross platform compilation
+
+### Resources
+
+- [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337)
+
+### Communication:
+- [Telegram](https://t.me/+F_xS9IVOdJZmZjQx)
@@ -81,16 +81,6 @@ pub struct BuilderArgs {
     )]
     max_bundle_size: u64,
 
-    /// Interval at which the builder polls an Eth node for new blocks and
-    /// mined transactions.
-    #[arg(
-        long = "builder.eth_poll_interval_millis",
-        name = "builder.eth_poll_interval_millis",
-        env = "BUILDER_ETH_POLL_INTERVAL_MILLIS",
-        default_value = "250"
-    )]
-    pub eth_poll_interval_millis: u64,
-
     /// If present, the url of the ETH provider that will be used to send
     /// transactions. Defaults to the value of `node_http`.
     #[arg(
@@ -204,7 +194,7 @@ impl BuilderArgs {
             bundle_priority_fee_overhead_percent: common.bundle_priority_fee_overhead_percent,
             priority_fee_mode,
             use_conditional_send_transaction: self.use_conditional_send_transaction,
-            eth_poll_interval: Duration::from_millis(self.eth_poll_interval_millis),
+            eth_poll_interval: Duration::from_millis(common.eth_poll_interval_millis),
             sim_settings: common.try_into()?,
             mempool_configs,
             max_blocks_to_wait_for_mine: self.max_blocks_to_wait_for_mine,

@@ -191,6 +191,16 @@ pub struct CommonArgs {
     )]
     priority_fee_mode_value: u64,
 
+    /// Interval at which the builder polls an Eth node for new blocks and
+    /// mined transactions.
+    #[arg(
+        long = "eth_poll_interval_millis",
+        name = "eth_poll_interval_millis",
+        env = "ETH_POLL_INTERVAL_MILLIS",
+        default_value = "100"
+    )]
+    pub eth_poll_interval_millis: u64,
+
     #[arg(
         long = "aws_region",
         name = "aws_region",

@@ -57,16 +57,6 @@ pub struct PoolArgs {
     )]
     pub min_replacement_fee_increase_percentage: u64,
 
-    /// ETH Node HTTP polling interval in milliseconds
-    /// (only used if node_http is set)
-    #[arg(
-        long = "pool.http_poll_interval_millis",
-        name = "pool.http_poll_interval_millis",
-        env = "POOL_HTTP_POLL_INTERVAL_MILLIS",
-        default_value = "100"
-    )]
-    pub http_poll_interval_millis: u64,
-
     #[arg(
         long = "pool.blocklist_path",
         name = "pool.blocklist_path",
@@ -146,7 +136,7 @@ impl PoolArgs {
                 .node_http
                 .clone()
                 .context("pool requires node_http arg")?,
-            http_poll_interval: Duration::from_millis(self.http_poll_interval_millis),
+            http_poll_interval: Duration::from_millis(common.eth_poll_interval_millis),
             pool_configs,
             remote_address,
         })

@@ -0,0 +1,93 @@
+## Contributing to Rundler
+
+Thanks for your interest in improving Rundler!
+
+There are multiple opportunities to contribute at any level. It doesn't matter if you are just getting started with Rust or are an expert, we can use your help.
+
+**No contribution is too small and all contributions are valued.**
+
+This document will help you get started. **Do not let the document intimidate you**.
+It should be considered as a guide to help you navigate the process.
+
+The [Telegram][dev-tg] is available for any concerns you may have that are not covered in this guide.
+
+If you contribute to this project, your contributions will be made to the project under both Apache 2.0 and the MIT license.
+
+### Ways to contribute
+
+There are fundamentally three ways an individual can contribute:
+
+1. **By opening an issue:** For example, if you believe that you have uncovered a bug
+   in Rundler, creating a new issue in the issue tracker is the way to report it.
+2. **By adding context:** Providing additional context to existing issues,
+   such as screenshots and code snippets to help resolve issues.
+3. **By resolving issues:** Typically this is done in the form of either
+   demonstrating that the issue reported is not a problem after all, or more often,
+   by opening a pull request that fixes the underlying problem, in a concrete and
+   reviewable manner.
+
+**Anybody can participate in any stage of contribution**. We urge you to participate in the discussion around bugs and participate in reviewing PRs.
+
+### Submitting a bug report
+
+When filing a new bug report in the issue tracker, you will be presented with a basic form to fill out.
+
+If you believe that you have uncovered a bug, please fill out the form to the best of your ability. Do not worry if you cannot answer every detail, just fill in what you can. Contributors will ask follow-up questions if something is unclear.
+
+The most important pieces of information we need in a bug report are:
+
+-   The Rundler version you are on (and that it is up to date)
+-   The platform you are on (Windows, macOS, an M1 Mac or Linux)
+-   Code snippets if this is happening in relation to testing or building code
+-   Concrete steps to reproduce the bug
+
+In order to rule out the possibility of the bug being in your project, the code snippets should be as minimal as possible. It is better if you can reproduce the bug with a small snippet as opposed to an entire project!
+
+### Submitting a feature request
+
+When adding a feature request in the issue tracker, you will be presented with a basic form to fill out.
+
+Please include as detailed of an explanation as possible of the feature you would like, adding additional context if necessary.
+
+If you have examples of other tools that have the feature you are requesting, please include them as well.
+
+### Resolving an issue
+
+Pull requests are the way concrete changes are made to the code, documentation, and dependencies of Rundler.
+
+Even tiny pull requests, like fixing wording, are greatly appreciated. Before making a large change, it is usually a good idea to first open an issue describing the change to solicit feedback and guidance. This will increase the likelihood of the PR getting merged.
+
+Please also make sure that the following commands pass if you have changed the code:
+
+```sh
+cargo check --all
+cargo test --all --all-features
+cargo +nightly fmt -- --check
+cargo +nightly clippy --all --all-features -- -D warnings
+```
+
+#### Adding tests
+
+If the change being proposed alters code, it is either adding new functionality to Rundler, or fixing existing, broken functionality.
+In both of these cases, the pull request should include one or more tests to ensure that Rundler does not regress in the future.
+
+Types of tests include:
+
+-   **Unit tests**: Functions which have very specific tasks should be unit tested.
+-   **Integration tests**: For general purpose, far reaching functionality,
+    integration tests should be added. The best way to add a new integration test is to look at existing ones and follow the style.
+
+Tests that use forking must contain "fork" in their name.
+
+#### Commits
+
+It is a recommended best practice to keep your changes as logically grouped as possible within individual commits. There is no limit to the number of commits any single pull request may have, and many contributors find it easier to review changes that are split across multiple commits.
+That said, if you have a number of commits that are "checkpoints" and don't represent a single logical change, please squash those together.
+
+We follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification to make sure that all of our commits are formatted well and are in proporly tailored to the change that the commit is making.
+
+#### Opening the pull request
+
+From within GitHub, opening a new pull request will present you with a template that should be filled out. Please try your best at filling out the details, but feel free to skip parts if you're not sure what to put.
+
+[dev-tg]: https://t.me/+F_xS9IVOdJZmZjQx
@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you would like to report a vulnerability, please open a github issue and tag it with the `security` label.
@@ -0,0 +1,13 @@
+## TODO
+
+*example configuration*
+
+```
+{
+  "0x0000000000000000000000000000000000000000000000000000000000000000": {
+    "description": "USDC paymaster allowlist - base goerli",
+    "chainIds": ["0x2105"],
+    "allowlist": []
+  }
+}
+```
@@ -0,0 +1,62 @@
+# Rundler Architecture
+
+there are 3 main process that are execute when running the rundler application and they are `rpc`, `builder` and `op_pool`.
+
+## RPC
+
+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.
+
+## Builder
+
+The builder module is used to propose, send and track transactions that need to be bundled together and pushed onto the chain. 
+
+### Bundle Proposer
+
+The bundle proposer is is most important part of Rundler as it performs numerous operations to check whether transactions and valid based on the [EIP4337 spec](https://eips.ethereum.org/EIPS/eip-4337), estimate gas and see if the next bundle
+has enough room for it to be included or wait until a new bundle is proposed. 
+
+### Bundle Sender 
+
+After the bundle proposal runs, the bundle sender logic will handle the process of propagating a transction on chain and checking on the status to see if it is included in a block. This process also handles the gas increases if the transaction
+has any issues being included.
+
+### Sender
+
+The sender is a lower level module that is used by the bundle sender to forward the bundled user operations to a node url or to a relay server (eg. Flashbots) if the chain is supported, after the transactions have been sent out to be landed on chain, there are a
+couple process that track the status of the operations and perform updates to the gas price if the transaction has not landed within a few blocks.
+
+### Signer
+
+The signer component is used to sign transactions before they are sent to be propogated 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 imediate revertion 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 propogated 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 incuded 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
+
+![distributed](images/multiimage.png)  
+
+## Single Image architecture
+
+![singleimage](images/multiprocess.png)  
+
+[parity]: https://www.parity.io/
+[jsonrpsee]: https://github.com/paritytech/jsonrpsee