wip: update readme

Author: dylanlott

README.md

@@ -1,49 +1,71 @@
 # The Signet Block Builder
 
-The Builder is responsible for transactions through the Signet rollup, from ingestion and simulation to block construction and submission to Ethereum L1.
+The Builder simulates bundles and transactions against the latest chain state to create valid Signet rollup blocks and submits them to the configured host chain as an [EIP-4844 transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md).
+
+Bundles are treated as Flashbots-style bundles, meaning that the Builder should respect transaction ordering, bundle atomicity, and the specified revertability.
 
 ---
 
 ## 🚀 System Design
 
-The Builder orchestrates a series of asynchronous actors that work together to:
+The Builder orchestrates a series of asynchronous actors that work together to build blocks for every assigned slot.
 
 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 against rollup state and block environment to build them into a cohesive block.
-5. **Submit** - builds a blob transaction of the built block and sends it to Ethereum L1.
-6. **Metrics** - records block and tx data.
+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 Ethereum L1.
+6. **Metrics** - records block and tx data over time.
 
 ```mermaid
+%%{ init : { "theme" : "dark" } }%%
 flowchart TD
     %% ────────────── INITIALIZATION ──────────────
     A0(["Start main"]) --> A1[Init tracing & logging]
     A1 --> A2_BuilderConfig[Load BuilderConfig from env]
     
     %% ────────────── CORE TASK SPAWNS ──────────────
     subgraph Tasks_Spawned["Spawned Actors"]
-        EnvTaskActor["Env Task"] ==block_env==> CacheSystem
-        CacheSystem["Cache System"]
-        MetricsTaskActor["Metrics Task"]
-        SubmitTaskActor["Submit Task"]
-        SimulatorTaskActor["Simulator Task"]
+        EnvTaskActor["🔢 Env Task"] ==block_env==> CacheSystem
+        CacheSystem["🪏 Cache System"]
+        MetricsTaskActor["📏 Metrics Task"]
+        SubmitTaskActor["📡 Submit Task "]
+        SimulatorTaskActor["💾 Simulator Task"]
+        Quincey["🖊️ Quincey"]
+
+        SubmitTaskActor -.block hash.-> Quincey
+        Quincey -.block signature.-> SubmitTaskActor
     end
 
     %% ────────────── CONNECTIONS & DATA FLOW ──────────────
-    A2_BuilderConfig --> A4_Providers["Connect Providers"]
+    A2_BuilderConfig -.host_provider.-> MetricsTaskActor
+    A2_BuilderConfig -.host_provider.->SubmitTaskActor
+    A2_BuilderConfig -.ru_provider.-> SimulatorTaskActor
+    A2_BuilderConfig -.host_provider.-> EnvTaskActor
+    A2_BuilderConfig -.ru_provider.-> EnvTaskActor
 
-    A4_Providers -.host_provider.-> MetricsTaskActor
-    A4_Providers -.host_provider.->SubmitTaskActor
-    A4_Providers -.ru_provider.-> SimulatorTaskActor
+    A3["📥 Transactions &
+    📦 Bundles"] --> CacheSystem
 
     EnvTaskActor ==block_env==> SimulatorTaskActor
     CacheSystem ==sim_cache ==> SimulatorTaskActor
     SubmitTaskActor ==tx receipt==> MetricsTaskActor
     SimulatorTaskActor ==built block==> SubmitTaskActor
 
-    SubmitTaskActor ==>|"signet block (blob tx)"| C1["Ethereum L1"]
+    SubmitTaskActor ==>|"signet block (blob tx)"| C1["⛓️ Ethereum L1"]
 ```
 
+The block building loop waits until a new block has been received, and then kicks off the next attempt. 
+
+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.
+
+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. 
+
+When the deadline is reached, the simulator is stopped, and all open simulation threads and cancelled. The block is then bundled with the block environment and the previous host header that it was simulated against, and passes all three along to the submit task. 
+
+If no transactions in the cache are valid and the resulting block is empty, the submit task will ignore it. 
+
+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. 
+
 ---
 
 ## ⚙️ Configuration
@@ -73,6 +95,36 @@ The Builder is configured via environment variables. The following values are su
 
 ---
 
+## 💾 EVM Behavior
+
+### 🗿 Inherited Header Values
+
+`PREVRANDAO` is set to a random byte string for each block.
+
+```rust
+// `src/tasks/env.rs`
+prevrandao: Some(B256::random()),
+```
+
+`TIMESTAMP` - Block timestamps are set to the same value as the current Ethereum block.
+
+Blob gas values `excess_blob_gas` and `blob_gasprice` are also set to 0 for all Signet blocks.
+
+### 🔢 Disabled Opcodes 
+
+`BLOBHASH` - EIP-4844 is not supported on Signet.
+`BLOBBASEFEE` - EIP4844 is not supported.
+
+## ⛽ Transaction Submission
+
+When a completed, non-empty Signet block is received by the Submit task, it prepares the block data into a blob transaction and submits it to the network. 
+
+If it fails, it will retry up to 3 times with a 12.5% bump on each retry. 
+
+The previous header's basefee is tracked through the build loop and used for gas estimation purposes in the Submit Task.
+
+---
+
 ## 📤 Transaction Sender
 
 A binary (`bin/submit-transaction.rs`) for continously sending very small transactions for testing block construction.
@@ -87,6 +139,10 @@ The following values are available for configuring the transaction sender:
 | `SIGNER_CHAIN_ID`   | Yes      | Chain ID used for signing                        |
 | `SIGNER_KEY`        | Yes      | Signing key used to sign the transaction         |
 
+The transaction submitter is located at `bin/submit_transaction.rs`.
+
+Run the transaction submitter with `cargo run --bin transaction-submitter`
+
 ---
 
 ## 🛠️ Development

src/test_utils.rs

@@ -45,6 +45,7 @@ pub fn setup_test_config() -> Result<BuilderConfig> {
             1740681556, // pecorino start timestamp as sane default
             0, 1,
         ),
+        block_confirmation_buffer: todo!(),
     };
     Ok(config)
 }