Merge pull request #126 from ralexstokes/setup-md-book

add `mdbook` for project

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/book.yml

@@ -0,0 +1,121 @@
+# cribbed from: https://github.com/paradigmxyz/reth/blob/21db2936e617d1018c0bfa5690d8f035dee2843f/.github/workflows/book.yml
+name: book
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # test:
+  #   runs-on: ubuntu-latest
+  #   name: test
+
+  #   steps:
+  #     - uses: actions/checkout@v3
+
+  #     - name: Install mdbook
+  #       run: |
+  #         mkdir mdbook
+  #         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+  #         echo `pwd`/mdbook >> $GITHUB_PATH
+
+  #     - name: Install mdbook-template
+  #       run: |
+  #         mkdir mdbook-template
+  #         curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+  #         echo `pwd`/mdbook-template >> $GITHUB_PATH
+
+  #     - name: Run tests
+  #       run: mdbook test
+
+  # lint:
+  #   runs-on: ubuntu-20.04
+  #   name: lint
+
+  #   steps:
+  #     - uses: actions/checkout@v3
+
+  #     - name: Install mdbook-linkcheck
+  #       run: |
+  #         mkdir mdbook-linkcheck
+  #         curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
+  #         unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
+  #         chmod +x `pwd`/mdbook-linkcheck/mdbook-linkcheck
+  #         echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH
+
+  #     - name: Run linkcheck
+  #       run: mdbook-linkcheck --standalone
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Build docs
+        run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc --all --no-deps
+
+      - name: Move docs to book folder
+        run: |
+          mv target/doc target/book/docs
+
+      - name: Archive artifact
+        shell: sh
+        run: |
+          chmod -c -R +rX "target/book" |
+          while read line; do
+             echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+          tar \
+            --dereference --hard-dereference \
+            --directory "target/book" \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+
+  deploy:
+    # Only deploy if a push to main
+    if: github.ref_name == 'main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: [build]
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

book.toml

@@ -0,0 +1,12 @@
+[book]
+authors = ["mev-rs contributors"]
+language = "en"
+multilingual = false
+src = "book"
+title = "mev-rs"
+
+[output.html]
+git-repository-url = "https://github.com/ralexstokes/mev-rs"
+
+[build]
+build-dir = "target/book"

book/SUMMARY.md

@@ -0,0 +1,4 @@
+# Summary
+
+- [intro](./introduction.md)
+- [mev-build-rs](./mev-build-rs.md)

book/introduction.md

@@ -0,0 +1,3 @@
+# `mev-rs`
+
+a platform for exploring mev research and development

book/mev-build-rs.md

@@ -0,0 +1,121 @@
+# `mev-build-rs`
+
+This repository provides a basic builder which can submit blocks to [`mev-boost` relays](https://boost.flashbots.net) using the [Relay APIs](https://flashbots.github.io/relay-specs/).
+
+The builder is built as an extension to the [`reth`](https://github.com/paradigmxyz/reth) execution layer (EL) client and also requires a consensus layer (CL) client to run.
+
+The default builder simply uses `reth`'s local mempool when sourcing transactions.
+
+## Installation
+
+### Build from source
+
+The best way to run the builder right now is to build this project from source.
+
+#### Prerequisites
+
+Follow the steps [here under `Dependencies`](https://paradigmxyz.github.io/reth/installation/source.html#dependencies).
+
+#### Build `mev-rs`
+
+You can install the `mev-rs` binary, named `mev`, with the following steps:
+
+```sh
+git clone https://github.com/ralexstokes/mev-rs
+cd mev-rs
+cargo install --locked
+```
+
+> The builder has been verified as of this commit `bf3d41f026e9728233dd3e1c40e75c49b9ae00b3`. No guarantees about other states of the repository currently.
+
+The `cargo install` command should place the `mev` binary under the default `.cargo/bin` folder which is also in your `PATH` following the suggested Rust installation process.
+
+## Run the builder
+
+Once installed, we are ready to run the builder.
+
+### Syncing nodes
+
+Before we can run the builder, we need to sync a CL and EL node pair on our target network.
+
+The remainder of this document will assume we are building for the `sepolia` network.
+
+> Repository has only been tested on the **Sepolia** network and there is no guarantee the builder works on other networks.
+
+The builder requires a synced CL client like [Lighthouse](https://github.com/sigp/lighthouse/).
+You can find instructions on [how to sync a `lighthouse` node here](https://lighthouse-book.sigmaprime.io).
+
+> Repository has only been tested with **Lighthouse** and there is no guarantee other CLs will work.
+
+Doing the initial/bulk sync from the `mev` builder should be possible, but has not been tested.
+
+The recommended approach will be to run `reth` (ideally built from source at the same commit pinned in this repo) for the target network alongside the CL until the pair has reached the head of the chain.
+
+Example commands utilizing [checkpoint sync following the Lighthouse book](https://lighthouse-book.sigmaprime.io/run_a_node.html) to do this:
+
+1. Make the JWT secret (refer to the Lighthouse guide for more info).
+
+2. [recommended] Obtain a checkpoint sync URL if you wish to use this sync mode.
+
+3. Run `reth`:
+  ```sh
+  reth --chain sepolia \
+    node \
+    --http \
+    --authrpc.jwtsecret $JWT_SECRET_FILE_PATH
+  ````
+
+4. Run `lighthouse`:
+  ```sh
+  lighthouse --network sepolia \
+    bn \
+    --http \
+    --execution-endpoint http://localhost:8551 \
+    --execution-jwt $JWT_SECRET_FILE_PATH \
+    --disable-deposit-contract-sync \
+    --checkpoint-sync-url $CHECKPOINT_SYNC_PROVIDER
+  ```
+
+The pair should start syncing. Once the pair of nodes is fully synced you can stop `reth` and run the `mev` builder in its place.
+
+### Run the builder on a synced chain
+
+To run the `mev` builder, first you should make the appropriate configuration. You can make a local copy of `example.config.toml` to get started.
+
+To configure the builder, you can edit the fields under the `[builder]` key of the TOML.
+
+Fields you should change:
+
+* `execution_mnemonic`: update to a seed phrase of an ethereum wallet you control.
+  This wallet will be used to author payment transactions to the proposer and also is used as the source of funds for any subsidy value you wish to add to the block.
+  You can select a particular index (following BIP-39) by terminating the seed phrase with a `:N` and integer index `N`. Otherwise the builder will just use the first index from the key tree.
+* `subsidy_gwei`: set this value to 0 if your execution layer address has no ETH in it; otherwise, the blocks will be invalid.
+* `jwt_secret_path`: ensure this value matches the one used previously when doing the initial sync.
+
+Once the configuration looks good, you can run the builder as follows alongside `lighthouse`.
+
+> `lighthouse` has some additional configuration from above to ensure the builder always receives head updates from the chain.
+
+1. Run `mev` with config file `config.toml`:
+  ```sh
+  mev --network sepolia build config.toml
+  ```
+
+2. Run `lighthouse`:
+  ```sh
+  lighthouse --network sepolia \
+    bn \
+    --http \
+    --execution-endpoint http://localhost:8551 \
+    --execution-jwt $JWT_SECRET_FILE_PATH \
+    --disable-deposit-contract-sync \
+    --checkpoint-sync-url $CHECKPOINT_SYNC_PROVIDER
+    --always-prepare-payload
+    --suggested-fee-recipient $FEE_RECIPIENT
+  ```
+
+### Additional notes
+
+* The `--suggested-fee-recipient` for `lighthouse` is ultimately not used, but currently required to run the node. Any valid address should do and it should not affect the builder.
+* If you are seeing slow or lagging operation, you can try to adjust the preparation lookahead with the `--prepare-payload-lookahead` option on `lighthouse`.
+* The builder has been tested on an AWS EC2 instance of `t3.xlarge` variety with a `512Gb` disk.

flake.nix

@@ -0,0 +1,18 @@
+{
+  description = "flake for `mev-rs` repo";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, flake-utils, nixpkgs }:
+    flake-utils.lib.eachDefaultSystem
+      (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+        in
+        {
+          devShells.default = import ./shell.nix { inherit pkgs; };
+        });
+}

justfile

@@ -19,3 +19,8 @@ lint: fmt validate-example-config
 build:
     cargo build --all-targets --all-features --all
 run-ci: lint build test run-integration-tests
+
+build-book:
+    mdbook build
+serve-book:
+    mdbook serve --open

shell.nix

@@ -0,0 +1,5 @@
+{ pkgs ? import <nixpkgs> { } }:
+with pkgs;
+mkShell {
+  buildInputs = [ mdbook ];
+}