Skip to content

Commit 68cdc75

Browse files
dylanlottdylanlott
authored
docs: update README with Flashbots architecture changes (#164)
# docs: update README with Flashbots architecture changes Update the README diagrams to reflect Flashbots changes. Closes [ENG-1299](https://linear.app/initiates/issue/ENG-1299/update-documentation-to-reflect-flashbots-changes)
1 parent 4d6aee1 commit 68cdc75

File tree

1 file changed

+112
-127
lines changed

1 file changed

+112
-127
lines changed

‎README.md‎

Lines changed: 112 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ The Builder simulates bundles and transactions against the latest chain state to
44

55
Bundles are treated as Flashbots-style bundles, meaning that the Builder should respect transaction ordering, bundle atomicity, and the specified revertability.
66

7-
---
7+
--------------------------------------------------------------------------------
88

99
## 🚀 System Design
1010

@@ -13,104 +13,120 @@ 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.
17-
6. **Metrics** - records block and tx data over time.
16+
4. **FlashbotsSubmit** - handles preparing and submitting the simulated block to a private Flashbots relay.
17+
5. **Metrics** - records block and tx data over time.
1818

1919
```mermaid
2020
%%{ init : { "theme" : "dark" } }%%
2121
flowchart TD
22-
%% ────────────── INITIALIZATION ──────────────
23-
A0(["Start main"]) --> A1[Init tracing & logging]
24-
A1 --> A2_BuilderConfig[Load BuilderConfig from env]
25-
26-
%% ────────────── CORE TASK SPAWNS ──────────────
27-
subgraph Tasks_Spawned["Spawned Actors"]
28-
EnvTaskActor["🔢 Env Task"] ==block_env==> CacheSystem
29-
CacheSystem["🪏 Cache System"]
30-
MetricsTaskActor["📏 Metrics Task"]
31-
SubmitTaskActor["📡 Submit Task "]
32-
SimulatorTaskActor["💾 Simulator Task"]
33-
Quincey["🖊️ Quincey"]
34-
35-
SubmitTaskActor -.block hash.-> Quincey
36-
Quincey -.block signature.-> SubmitTaskActor
37-
end
38-
39-
%% ────────────── CONNECTIONS & DATA FLOW ──────────────
40-
A2_BuilderConfig -.host_provider.-> MetricsTaskActor
41-
A2_BuilderConfig -.host_provider.->SubmitTaskActor
42-
A2_BuilderConfig -.ru_provider.-> SimulatorTaskActor
43-
A2_BuilderConfig -.ru_provider.-> EnvTaskActor
44-
45-
A3["📥 Transactions &
46-
📦 Bundles"] --> CacheSystem
47-
48-
EnvTaskActor ==block_env==> SimulatorTaskActor
49-
CacheSystem ==sim_cache ==> SimulatorTaskActor
50-
SubmitTaskActor ==tx receipt==> MetricsTaskActor
51-
SimulatorTaskActor ==built block==> SubmitTaskActor
52-
53-
SubmitTaskActor ==>|"signet block (blob tx)"| C1["⛓️ Ethereum L1"]
22+
%% Initialization
23+
Start(["Start"]) --> Init["Init tracing & logging"]
24+
Init --> Config["Load BuilderConfig from env"]
25+
26+
Inbound["📥 Transactions &
27+
📦 Bundles"] --> Cache["🪏 Cache Task"]
28+
Quincey["🖊️ Quincey (Signer)"]
29+
30+
%% Block building loop
31+
subgraph BuilderLoop["Block Building Loop"]
32+
Env["🔢 Env Task"]
33+
Cache["🪏 Cache Task"]
34+
Simulator["💾 Simulator Task"]
35+
Metrics["📏 Metrics Task"]
36+
FlashbotsSubmit["📥 Flashbots Submit Task"]
37+
end
38+
39+
%% Signing
40+
FlashbotsSubmit --hash--> Quincey
41+
Quincey -- signature --> FlashbotsSubmit
42+
43+
%% Config wiring
44+
Config -.rollup rpc.-> Env
45+
Config -.host rpc.-> Env
46+
Config -.host rpc.-> Simulator
47+
Config -.rollup rpc.-> Simulator
48+
Config -.host rpc.-> Metrics
49+
Config -.host rpc.-> FlashbotsSubmit
50+
51+
%% Core flow
52+
Env ==block env==> Simulator
53+
Cache ==sim cache==> Simulator
54+
Simulator ==built block==> FlashbotsSubmit
55+
56+
%% Network submission
57+
FlashbotsSubmit ==>|"tx bundle"| FlashbotsRelay["🛡️ Flashbots Relay"]
58+
FlashbotsRelay ==> Ethereum
59+
60+
%% Metrics
61+
FlashbotsSubmit ==rollup block tx hash==> Metrics
5462
```
5563

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

5868
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.
5969

60-
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.
70+
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.
71+
72+
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.
73+
74+
### ✨ Submit Task
75+
76+
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.
6177

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.
78+
If a Flashbots endpoint has _not_ been configured, the Builder uses the [builder helper contract] and to craft a rollup block transaction and submits that to the default mempool. This mode of operation 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.
6379

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

66-
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.
82+
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.
6783

68-
---
84+
--------------------------------------------------------------------------------
6985

7086
## ⚙️ Configuration
7187

7288
The Builder is configured via environment variables. The following values are supported for configuration.
7389

74-
| Key | Required | Description |
75-
| ----------------------------- | -------- | ---------------------------------------------------------------------- |
76-
| `HOST_CHAIN_ID` | Yes | Host-chain ID (e.g. `3151908`) |
77-
| `RU_CHAIN_ID` | Yes | Rollup-chain ID (e.g. `14174`) |
78-
| `HOST_RPC_URL` | Yes | RPC endpoint for the host chain |
79-
| `ROLLUP_RPC_URL` | Yes | RPC endpoint for the rollup chain |
80-
| `TX_POOL_URL` | Yes | Transaction pool URL (must end with `/`) |
81-
| `TX_BROADCAST_URLS` | No | Additional endpoints for blob txs (comma-separated, slash required) |
82-
| `FLASHBOTS_ENDPOINT` | No | Flashbots API to submit blocks to. |
83-
| `ZENITH_ADDRESS` | Yes | Zenith contract address |
84-
| `BUILDER_HELPER_ADDRESS` | Yes | Builder helper contract address |
85-
| `QUINCEY_URL` | Yes | Remote sequencer signing endpoint |
86-
| `BUILDER_PORT` | Yes | HTTP port for the Builder (default: `8080`) |
87-
| `SEQUENCER_KEY` | Yes | AWS KMS key ID _or_ local private key for sequencer signing |
88-
| `BUILDER_KEY` | Yes | AWS KMS key ID _or_ local private key for builder signing |
89-
| `BUILDER_REWARDS_ADDRESS` | Yes | Address receiving builder rewards |
90-
| `ROLLUP_BLOCK_GAS_LIMIT` | No | Override for block gas limit |
91-
| `CONCURRENCY_LIMIT` | No | Max concurrent tasks the simulator uses |
92-
| `OAUTH_CLIENT_ID` | Yes | Oauth client ID for the builder |
93-
| `OAUTH_CLIENT_SECRET` | Yes | Oauth client secret for the builder |
94-
| `OAUTH_AUTHENTICATE_URL` | Yes | Oauth authenticate URL for the builder for performing OAuth logins |
95-
| `OAUTH_TOKEN_URL` | Yes | Oauth token URL for the builder to get an Oauth2 access token |
96-
| `AUTH_TOKEN_REFRESH_INTERVAL` | Yes | The OAuth token refresh interval in seconds. |
97-
| `CHAIN_NAME` | No | The chain name ("pecorino", or the corresponding name) |
98-
| `SLOT_OFFSET` | No | Slot timing offset in seconds. Required if `CHAIN_NAME` is not present |
99-
| `SLOT_DURATION` | No | Slot duration in seconds. Required if `CHAIN_NAME` is not present |
100-
| `START_TIMESTAMP` | No | UNIX timestamp for slot 0. Required if `CHAIN_NAME` is not present |
101-
102-
---
90+
Key | Required | Description
91+
----------------------------- | -------- | ----------------------------------------------------------------------------------------
92+
`HOST_CHAIN_ID` | Yes | Host-chain ID (e.g. `3151908`)
93+
`RU_CHAIN_ID` | Yes | Rollup-chain ID (e.g. `14174`)
94+
`HOST_RPC_URL` | Yes | RPC endpoint for the host chain
95+
`ROLLUP_RPC_URL` | Yes | RPC endpoint for the rollup chain
96+
`TX_POOL_URL` | Yes | Transaction pool URL (must end with `/`)
97+
`TX_BROADCAST_URLS` | No | Additional endpoints for blob txs (comma-separated, slash required)
98+
`FLASHBOTS_ENDPOINT` | No | Flashbots API to submit blocks to. Defaults to the BuilderHelper submit task if not set.
99+
`ZENITH_ADDRESS` | Yes | Zenith contract address
100+
`BUILDER_HELPER_ADDRESS` | Yes | Builder helper contract address
101+
`QUINCEY_URL` | Yes | Remote sequencer signing endpoint
102+
`BUILDER_PORT` | Yes | HTTP port for the Builder (default: `8080`)
103+
`SEQUENCER_KEY` | Yes | AWS KMS key ID _or_ local private key for sequencer signing
104+
`BUILDER_KEY` | Yes | AWS KMS key ID _or_ local private key for builder signing
105+
`BUILDER_REWARDS_ADDRESS` | Yes | Address receiving builder rewards
106+
`ROLLUP_BLOCK_GAS_LIMIT` | No | Override for block gas limit
107+
`CONCURRENCY_LIMIT` | No | Max concurrent tasks the simulator uses
108+
`OAUTH_CLIENT_ID` | Yes | Oauth client ID for the builder
109+
`OAUTH_CLIENT_SECRET` | Yes | Oauth client secret for the builder
110+
`OAUTH_AUTHENTICATE_URL` | Yes | Oauth authenticate URL for the builder for performing OAuth logins
111+
`OAUTH_TOKEN_URL` | Yes | Oauth token URL for the builder to get an Oauth2 access token
112+
`AUTH_TOKEN_REFRESH_INTERVAL` | Yes | The OAuth token refresh interval in seconds.
113+
`CHAIN_NAME` | No | The chain name ("pecorino", or the corresponding name)
114+
`SLOT_OFFSET` | No | Slot timing offset in seconds. Required if `CHAIN_NAME` is not present
115+
`SLOT_DURATION` | No | Slot duration in seconds. Required if `CHAIN_NAME` is not present
116+
`START_TIMESTAMP` | No | UNIX timestamp for slot 0\. Required if `CHAIN_NAME` is not present
117+
118+
--------------------------------------------------------------------------------
103119

104120
## 💻 Recommended Specs
105121

106-
| Key | Minimum | Recommended |
107-
| ------------------ | ------------------ | ----------------- |
108-
| CPU | 0.1 vCPU | 0.5 vCPU |
109-
| Memory | 256MB | 512MB |
122+
Key | Minimum | Recommended
123+
------ | -------- | -----------
124+
CPU | 0.1 vCPU | 0.5 vCPU
125+
Memory | 256MB | 512MB
110126

111127
**Note: Builder prefers clock speed over core count, recommended 2.8Ghz+**
112128

113-
---
129+
--------------------------------------------------------------------------------
114130

115131
## 💾 EVM Behavior
116132

@@ -127,57 +143,18 @@ prevrandao: Some(B256::random()),
127143

128144
Blob gas values `excess_blob_gas` and `blob_gasprice` are also set to 0 for all Signet blocks.
129145

130-
### 🔢 Disabled Opcodes
146+
### 🔢 Disabled Opcodes
131147

132-
`BLOBHASH` - EIP-4844 is not supported on Signet.
133-
`BLOBBASEFEE` - EIP4844 is not supported.
148+
`BLOBHASH` - EIP-4844 is not supported on Signet. `BLOBBASEFEE` - EIP4844 is not supported.
134149

135150
## ⛽ Transaction Submission
136151

137-
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.
152+
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.
138153

139-
If it fails, it will retry up to 3 times with a 12.5% bump on each retry.
154+
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
@@ -186,22 +163,30 @@ Run the order submitter with `cargo run --bin order-submitter`
186163
- **AWS CLI**
187164
- A private key or AWS KMS key for signing transactions
188165

189-
---
166+
--------------------------------------------------------------------------------
190167

191168
## ✅ Testing
192169

193170
1. Build the Docker image:
194-
```bash
195-
docker build -t builder:latest .
196-
```
171+
172+
```bash
173+
docker build -t builder:latest .
174+
```
175+
197176
2. Push to your container registry:
198-
```bash
199-
docker push <registry>/builder:latest
200-
```
177+
178+
```bash
179+
docker push <registry>/builder:latest
180+
```
181+
201182
3. Update your deployment manifests with the new image.
183+
202184
4. Verify expected behavior in your target network.
203-
- This should typically include sending a test transaction and verifying it is simulated and built into a block.
204-
185+
186+
- This should typically include sending a test transaction and verifying it is simulated and built into a block.
187+
205188
## 🪪 License
206189

207190
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
191+
192+
[builder helper contract]: https://github.com/init4tech/helper-contracts/blob/main/src/BuilderHelper.sol

0 commit comments

Comments
 (0)