Skip to content

Commit a312e38

Browse files
committed
docs: update README with Flashbots architecture changes
1 parent f2ca599 commit a312e38

File tree

1 file changed

+20
-43
lines changed

1 file changed

+20
-43
lines changed

README.md

Lines changed: 20 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ The Builder orchestrates a series of asynchronous actors that work together to b
1313
1. **Env** - watches the latest host and rollup blocks to monitor gas rates and block updates.
1414
2. **Cache** - polls bundle and transaction caches and adds them to the cache.
1515
3. **Simulator** - simulates transactions and bundles against rollup state and block environment to build them into a cohesive block.
16-
5. **Submit** - creates a blob transaction from the built block and sends it to Ethereum L1.
16+
5. **Submit** - creates a blob transaction from the built block and sends it to the configured submit task.
17+
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.
18+
2. Builder Helper - builds a transaction call with the builder helper contract and submits that as a transaction.
1719
6. **Metrics** - records block and tx data over time.
1820

1921
```mermaid
@@ -30,6 +32,7 @@ flowchart TD
3032
MetricsTaskActor["📏 Metrics Task"]
3133
SubmitTaskActor["📡 Submit Task "]
3234
SimulatorTaskActor["💾 Simulator Task"]
35+
Submitter["📤 Submitter"]
3336
Quincey["🖊️ Quincey"]
3437
3538
SubmitTaskActor -.block hash.-> Quincey
@@ -39,6 +42,7 @@ flowchart TD
3942
%% ────────────── CONNECTIONS & DATA FLOW ──────────────
4043
A2_BuilderConfig -.host_provider.-> MetricsTaskActor
4144
A2_BuilderConfig -.host_provider.->SubmitTaskActor
45+
A2_BuilderConfig -.host_provider.-> SimulatorTaskActor
4246
A2_BuilderConfig -.ru_provider.-> SimulatorTaskActor
4347
A2_BuilderConfig -.ru_provider.-> EnvTaskActor
4448
@@ -47,21 +51,32 @@ flowchart TD
4751
4852
EnvTaskActor ==block_env==> SimulatorTaskActor
4953
CacheSystem ==sim_cache ==> SimulatorTaskActor
54+
5055
SubmitTaskActor ==tx receipt==> MetricsTaskActor
5156
SimulatorTaskActor ==built block==> SubmitTaskActor
5257
53-
SubmitTaskActor ==>|"signet block (blob tx)"| C1["⛓️ Ethereum L1"]
58+
SubmitTaskActor ==signet_block==> Submitter
59+
Submitter ==>|"signet block"| C2["⚡🤖 Flashbots"]
60+
Submitter ==>|"signet block"| C1["⛓️ Ethereum L1"]
5461
```
5562

56-
The block building loop waits until a new block has been received, and then kicks off the next attempt.
63+
### Simulation Task
64+
65+
The block building loop waits until a new block environment has been received, and then kicks off the next attempt.
5766

5867
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.
5968

6069
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.
6170

62-
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.
71+
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.
72+
73+
### Submit Task
74+
75+
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.
76+
77+
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.
6378

64-
If no transactions in the cache are valid and the resulting block is empty, the submit task will ignore it.
79+
If the block received from simulation is empty, the submit task will ignore it.
6580

6681
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.
6782

@@ -140,44 +155,6 @@ If it fails, it will retry up to 3 times with a 12.5% bump on each retry.
140155

141156
The previous header's basefee is tracked through the build loop and used for gas estimation purposes in the Submit Task.
142157

143-
---
144-
145-
## 📤 Transaction Sender
146-
147-
A binary (`bin/submit_transaction.rs`) for continously sending very small transactions for testing block construction.
148-
149-
The following values are available for configuring the transaction sender:
150-
151-
| Key | Required | Description |
152-
| ------------------- | -------- | --------------------------------------------- |
153-
| `RPC_URL` | Yes | RPC endpoint used for sending the transaction |
154-
| `RECIPIENT_ADDRESS` | Yes | Address to which the transaction is sent |
155-
| `SLEEP_TIME` | Yes | Optional delay (in ms) between transactions |
156-
| `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing |
157-
| `SIGNER_KEY` | Yes | Signing key used to sign the transaction |
158-
159-
The transaction submitter is located at `bin/submit_transaction.rs`.
160-
161-
Run the transaction submitter with `cargo run --bin transaction-submitter`
162-
163-
---
164-
165-
## 📤 Order Submitter
166-
167-
A binary (`bin/submit_order.rs`) for continuously sending small example orders for testing block construction with fills.
168-
169-
The following values need to be configured:
170-
171-
| Key | Required | Description |
172-
| ----------------- | -------- | -------------------------------------------------------------- |
173-
| `RPC_URL` | Yes | RPC endpoint used for sending the transaction |
174-
| `SEND_TO_ROLLUP` | Yes | Whether to make a rollup order (RU-RU) or host order (RU-HOST) |
175-
| `SLEEP_TIME` | Yes | Optional delay (in ms) between transactions |
176-
| `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing |
177-
| `SIGNER_KEY` | Yes | Signing key used to sign the transaction |
178-
179-
Run the order submitter with `cargo run --bin order-submitter`
180-
181158
## 🛠️ Development
182159

183160
### Requirements

0 commit comments

Comments
 (0)