cleanup

Author: dylanlott

CHANGELOG.md

@@ -8,82 +8,88 @@ Bundles are treated as Flashbots-style bundles, meaning that the Builder should
 
 ## 🚀 System Design
 
-The Builder orchestrates a set of asynchronous actors that collaborate to build and submit Signet rollup blocks for every assigned slot. The core components are:
+The Builder orchestrates a series of asynchronous actors that work together to build blocks for every assigned slot.
 
-1. **Env** — watches host and rollup chain headers and maintains the block environment used for simulation.
-2. **Cache** — ingests transactions and bundles from configured sources and exposes a simulation view.
-3. **Simulator** — applies transactions and bundles against the rollup state and block environment to assemble a candidate Signet block.
-4. **Submit** — takes a successfully built block and routes it to the configured submission path (either a private MEV bundle relay or direct L1 broadcast via the builder helper).
-5. **Metrics** — records runtime metrics, submit receipts, and block statistics.
-
-Below is a high-level architecture diagram that shows both submission options: direct L1 submission (Builder Helper) and private MEV bundle submission (Flashbots relay).
+1. **Env** - watches the latest host and rollup blocks to monitor gas rates and block updates.
+2. **Cache** - polls bundle and transaction caches and adds them to the cache.
+3. **Simulator** - simulates transactions and bundles against rollup state and block environment to build them into a cohesive block.
+5. **Submit** - creates a blob transaction from the built block and sends it to the configured submit task.
+   1. Flashbots - builds a Flashbots bundle out of the Signet block which contains Signet transactions, host transactions, and host fills, and submits it to the configured Flashbots endpoint.
+   2. Builder Helper - builds a transaction call with the builder helper contract and submits that as a transaction. 
+6. **Metrics** - records block and tx data over time.
 
 ```mermaid
-%%{ init : { "theme" : "dark", "flowchart": {"curve":"basis"} } }%%
+%%{ init : { "theme" : "dark" } }%%
 flowchart TD
-    %% Initialization
-    start(["Start main"]) --> init["Init tracing & logging"]
-    init --> cfg["Load BuilderConfig from env"]
-
-    %% Spawned actors
-    subgraph Actors["Spawned Actors"]
-        Env["🔢 Env Task"]
-        Cache["🪏 Cache System"]
-        Simulator["� Simulator Task"]
-        SubmitBH["📡 Submit Task (BuilderHelper)"]
-        SubmitFB["�️ Submit Task (Flashbots)"]
-        Metrics["📏 Metrics Task"]
-        Quincey["🖊️ Quincey (Signer)"]
-    end
-
-    %% Config wiring
-    cfg -.-> Metrics
-    cfg -.-> SubmitBH
-    cfg -.-> Simulator
-    cfg -.-> Env
-    cfg -. "flashbots_endpoint" -> SubmitFB
-
-    %% Data flow
-    inbound["📥 Transactions & Bundles"] --> Cache
-    Env ==block_env==> Simulator
-    Cache ==sim_cache==> Simulator
-      Simulator["💾 Simulator Task"]
-    Simulator ==built_block==> SubmitFB
-      SubmitFB["🛡️ Submit Task (Flashbots)"]
-    SubmitBH ==tx_receipt==> Metrics
-    SubmitFB ==bundle_receipt==> Metrics
-
-    %% Signing interactions
-    SubmitBH -.block_hash.-> Quincey
-    Quincey -.block_signature.-> SubmitBH
-    SubmitFB -.bundle_hash.-> Quincey
-    Quincey -.bundle_signature.-> SubmitFB
-
-    %% External targets
-   cfg -."flashbots_endpoint".-> SubmitFB
-    SubmitFB -->|"MEV bundle"| Relay["🛡️ Flashbots Relay"]
-
-    classDef ext fill:#111,stroke:#bbb,color:#fff;
-    class L1,Relay ext
+   %% ────────────── INITIALIZATION ──────────────
+   A0(["Start main"]) --> A1[Init tracing & logging]
+   A1 --> A2_BuilderConfig[Load BuilderConfig from env]
+   
+   A4_Quincey["🖊️ Quincey"]
+   
+   A3["📥 Transactions &
+   📦 Bundles"] --> CacheTask 
+
+   %% ────────────── CORE TASK SPAWNS ──────────────
+   subgraph Tasks_Spawned["Spawned Actors"]
+      EnvTaskActor["🔢 Env Task"] ==block env==>CacheTask 
+      CacheTask["🪏 Cache Task"]
+      MetricsTaskActor["📏 Metrics Task"]
+      SubmitTaskActor["📡 Submit Task "]
+      SimulatorTaskActor["💾 Simulator Task"]
+
+      %% ────────────── Transaction Preparation ──────────────
+      subgraph TxPrep["Transaction Prep"]
+         Bumpable["⛽ Bumpable Tx"] 
+      end
+   end
+
+   %% ────────────── CONNECTIONS & DATA FLOW ──────────────
+   A2_BuilderConfig -.host rpc.-> MetricsTaskActor
+   A2_BuilderConfig -.host rpc.->SubmitTaskActor
+   A2_BuilderConfig -.host rpc.-> SimulatorTaskActor
+   A2_BuilderConfig -.host rpc.-> TxPrep
+   A2_BuilderConfig -.rollup rpc.-> SimulatorTaskActor
+   A2_BuilderConfig -.rollup rpc.-> EnvTaskActor
+
+   
+   SubmitTaskActor ==tx receipt==> MetricsTaskActor
+   SubmitTaskActor ==> TxPrep
+   
+   C2 == "tx bundle" ==> C1
+   
+   TxPrep -.block hash.-> A4_Quincey
+   A4_Quincey -.block signature.-> TxPrep
+
+   
+   EnvTaskActor ==block env==> SimulatorTaskActor
+   CacheTask ==sim cache ==> SimulatorTaskActor
+   SimulatorTaskActor ==built block==> SubmitTaskActor
+
+   TxPrep ==>|"signet block"| C1["⛓️ Ethereum L1"]
+   TxPrep ==>|"signet block"| C2["⚡🤖 Flashbots"]
+
 ```
 
 ### Simulation Task
 
-The simulation loop waits for a new block environment from the host chain, then starts a simulation window for the current slot. The Builder takes a reference to the transaction cache and computes a deadline (default: slot end minus 1.5s buffer) to stop simulating and finalize the block.
+The block building loop waits until a new block environment has been received, and then kicks off the next attempt. 
 
-Transactions flow from the cache into the simulator. Applied transactions are kept and assembled into the candidate block; failing transactions are ignored. When the simulation deadline arrives, the simulator cancels remaining work, captures the built block and the block environment it was simulated against, and forwards them to the Submit task.
+When the Builder receives a new block, it takes a reference to the transaction cache, calculates a simulation deadline for the current slot with a buffer of 1.5 seconds, and begins constructing a block for the current slot.
 
-### Submit Task
+Transactions enter through the cache, and then they're sent to the simulator, where they're run against the latest chain state and block environment. If they're successfully applied, they're added to the block. If a transaction fails to be applied, it is simply ignored. 
 
-The Submit task will route the built block to one of two paths, depending on configuration:
+When the deadline is reached, the simulator is stopped, and all open simulation threads are cancelled. The built block is then bundled with the block environment and the previous host header that it was simulated against, and all three are passed along to the submit task. 
+
+### Submit Task
 
-- Flashbots (private MEV relay): when `FLASHBOTS_ENDPOINT` is configured, the Submit task prepares an MEV-style bundle containing the Signet block (plus any host transactions/fills as needed) and submits it to the configured relay. The builder expects a bundle hash in the response and records it in metrics.
+If Flashbots endpoint has been configured the Flashbots submit task will prepare a Flashbots bundle out of that Signet block, and then submits that bundle to the Flashbots endpoint.
 
-- Builder Helper (direct L1 broadcast): when no Flashbots endpoint is configured, the Submit task composes a builder-helper contract call and broadcasts it to the mempool as a normal transaction. This path is intended for testing and private deployments; broadcasting raw Signet block data publicly may leak sensitive information.
+If a Flashbots endpoint has _not_ been configured, the Builder will create a raw contract call and submits the transaction to the default mempool. This is only for testing on private networks and should not be used in production, since it can leak sensitive transaction data from the Signet block.
 
-If the simulated block is empty, the Submit task will drop it and continue.
+If the block received from simulation is empty, the submit task will ignore it.
 
-If the submit path requires a signature (Quincey), the submit task requests one; on an authorization failure (e.g. 403) the submit task will skip the slot and resume on the next.
+Finally, if it's non-empty, the submit task attempts to get a signature for the block, and if it fails due to a 403 error, it will skip the current slot and begin waiting for the next block. 
 
 ---