Skip to content

Commit e2a542e

Browse files
dylanlottdylanlott
committed
add mermaid diagram and readme polish
1 parent 6ac265c commit e2a542e

File tree

1 file changed

+106
-62
lines changed

1 file changed

+106
-62
lines changed

‎README.md

Lines changed: 106 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,124 @@
1-
# builder
1+
# The Signet Block Builder
22

3-
Our sample signet builder implementation.
3+
The Builder is responsible for transactions through the Signet rollup, from ingestion and simulation to block construction and submission to Ethereum L1.
44

5-
## Development
5+
---
66

7-
This crate contains an example block builder in the Signet ecosystem.
7+
## 🚀 System Design
88

9-
### Requirements
9+
The Builder orchestrates a series of asynchronous actors that work together to:
1010

11-
- Rust 1.85
12-
- AWS CLI
13-
- A private key or AWS KMS key for signing transactions
11+
1. **Env** - watches the latest host and rollup blocks to monitor gas rates and block updates.
12+
2. **Cache** - polls bundle and transaction caches and adds them to the cache.
13+
3. **Simulator** - simulates transactions against rollup state and block environment to build them into a cohesive block.
14+
5. **Submit** - builds a blob transaction of the built block and sends it to Ethereum L1.
15+
6. **Metrics** - records block and tx data.
1416

15-
### Environment
16-
17-
The following environment variables are exposed to configure the Builder:
18-
19-
```bash
20-
# Builder Configs for Pecorino Test Net
21-
HOST_CHAIN_ID="3151908"
22-
RU_CHAIN_ID="14174"
23-
24-
# Transaction Pool Configs
25-
TX_POOL_URL="http://pool.url.here/" # trailing slash is required
26-
27-
# RPC Endpoints
28-
HOST_RPC_URL="https://host-rpc.pecorino.signet.sh"
29-
RU_RPC_URL="https://rpc.pecorino.signet.sh"
30-
TX_POOL_URL=""
31-
TX_BROADCAST_URLS="" # trailing slash is required - set to none for test net configuration
32-
33-
# Contract configurations
34-
ZENITH_ADDRESS="0xbe45611502116387211D28cE493D6Fb3d192bc4E"
35-
BUILDER_HELPER_ADDRESS="0xb393416A722Fd48C3b0a9ab5fC2512Ef0c55e4CA"
36-
37-
# Misc.
38-
QUINCEY_URL="http://sequencer.pecorino.signet.sh/signBlock"
39-
BUILDER_PORT="8080"
40-
SEQUENCER_KEY=""
41-
BUILDER_KEY=""
42-
BUILDER_REWARDS_ADDRESS="BUILDER_REWARDS_ADDRESS_HERE"
43-
ROLLUP_BLOCK_GAS_LIMIT=""
44-
CONCURRENCY_LIMIT=""
45-
46-
# Pecorino Slot Timing Configurations
47-
SLOT_OFFSET="4"
48-
SLOT_DURATION="12"
49-
START_TIMESTAMP="1740681556"
50-
```
17+
```mermaid
18+
flowchart TD
19+
%% ────────────── INITIALIZATION ──────────────
20+
A0(["Start main"]) --> A1[Init tracing & logging]
21+
A1 --> A2_BuilderConfig[Load BuilderConfig from env]
22+
23+
%% ────────────── CORE TASK SPAWNS ──────────────
24+
subgraph Tasks_Spawned["Spawned Actors"]
25+
EnvTaskActor["Env Task"] ==block_env==> CacheSystem
26+
CacheSystem["Cache System"]
27+
MetricsTaskActor["Metrics Task"]
28+
SubmitTaskActor["Submit Task"]
29+
SimulatorTaskActor["Simulator Task"]
30+
end
5131
52-
## Transaction Sender
32+
%% ────────────── CONNECTIONS & DATA FLOW ──────────────
33+
A2_BuilderConfig --> A4_Providers["Connect Providers"]
5334
54-
The builder includes a `transaction-sender` for sending miniscule transactions for the purpose of testing the rollup block construction process. The `transaction-sender` is located in `bin/submit-transaction.rs`.
35+
A4_Providers -.host_provider.-> MetricsTaskActor
36+
A4_Providers -.ru_provider.-> SimulatorTaskActor
5537
56-
It requires a key to sign the transactions and a funded wallet.
38+
%% Simulator needs env + cache to craft txs
39+
EnvTaskActor ==block_env==> SimulatorTaskActor
40+
CacheSystem ==sim_cache ==> SimulatorTaskActor
5741
58-
### Environment Variables
42+
%% Submit task needs host provider
43+
A4_Providers -.host_provider.->SubmitTaskActor
5944
60-
The `transaction-sender` also has a set of configurable environment variables listed below.
45+
%% CHANNELS
46+
SubmitTaskActor == tx receipt ==> MetricsTaskActor
47+
SimulatorTaskActor == built block ==> SubmitTaskActor
6148
62-
```sh
63-
RPC_URL="" # The URL of the RPC endpoint of the node you're sending the transaction to.
64-
RECIPIENT_ADDRESS="" # The address the submitter addresses the transaction to.
65-
SLEEP_TIME="" # The time to wait before sending another transaction, in seconds.
66-
SIGNER_CHAIN_ID=""
67-
SIGNER_KEY=""
49+
%% Submission to chain
50+
SubmitTaskActor ==>|"signet block (blob tx)"| C1["Ethereum L1"]
6851
```
6952

70-
## Testing
53+
---
54+
55+
## ⚙️ Configuration
56+
57+
The Builder is configured via environment variables. The following values are supported for configuration.
58+
59+
| Key | Required | Description |
60+
| ------------------------- | -------- | ------------------------------------------------------------------- |
61+
| `HOST_CHAIN_ID` | Yes | Host-chain ID (e.g. `3151908`) |
62+
| `RU_CHAIN_ID` | Yes | Rollup-chain ID (e.g. `14174`) |
63+
| `TX_POOL_URL` | Yes | Transaction pool URL (must end with `/`) |
64+
| `HOST_RPC_URL` | Yes | RPC endpoint for the host chain |
65+
| `RU_RPC_URL` | Yes | RPC endpoint for the rollup chain |
66+
| `TX_BROADCAST_URLS` | No | Additional endpoints for blob txs (comma-separated, slash required) |
67+
| `ZENITH_ADDRESS` | Yes | Zenith contract address |
68+
| `BUILDER_HELPER_ADDRESS` | Yes | Builder helper contract address |
69+
| `QUINCEY_URL` | Yes | Remote sequencer signing endpoint |
70+
| `BUILDER_PORT` | Yes | HTTP port for the Builder (default: `8080`) |
71+
| `SEQUENCER_KEY` | Yes | AWS KMS key ID _or_ local private key for sequencer signing |
72+
| `BUILDER_KEY` | Yes | AWS KMS key ID _or_ local private key for builder signing |
73+
| `BUILDER_REWARDS_ADDRESS` | Yes | Address receiving builder rewards |
74+
| `ROLLUP_BLOCK_GAS_LIMIT` | No | Override for block gas limit |
75+
| `CONCURRENCY_LIMIT` | Yes | Max concurrent tasks the simulator uses |
76+
| `SLOT_OFFSET` | Yes | Slot timing offset in seconds |
77+
| `SLOT_DURATION` | Yes | Slot duration in seconds |
78+
| `START_TIMESTAMP` | Yes | UNIX timestamp for slot 0 |
79+
80+
---
7181

72-
### F
82+
## 📤 Transaction Sender
7383

74-
In order to test the `builder`, one must build and deploy an image in the target network with a provisioned key.
84+
A binary (`bin/submit-transaction.rs`) for continously sending very small transactions for testing block construction.
7585

76-
1. Build a docker image with your changes
77-
2. Push the image to the image repository
78-
3. Update the image in the deployment
79-
4. Assert and confirm expected behavior
86+
The following values are available for configuring the transaction sender:
87+
88+
| Key | Required | Description |
89+
| ------------------- | -------- | ------------------------------------------------ |
90+
| `RPC_URL` | Yes | RPC endpoint used for sending the transaction |
91+
| `RECIPIENT_ADDRESS` | Yes | Address to which the transaction is sent |
92+
| `SLEEP_TIME` | No | Optional delay (in seconds) between transactions |
93+
| `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing |
94+
| `SIGNER_KEY` | Yes | Signing key used to sign the transaction |
95+
96+
---
97+
98+
## 🛠️ Development
99+
100+
### Requirements
101+
102+
- **Rust** ≥ 1.85
103+
- **AWS CLI**
104+
- A private key or AWS KMS key for signing transactions
80105

106+
---
107+
108+
## ✅ Testing
109+
110+
1. Build the Docker image:
111+
```bash
112+
docker build -t builder:latest .
113+
```
114+
2. Push to your container registry:
115+
```bash
116+
docker push <registry>/builder:latest
117+
```
118+
3. Update your deployment manifests with the new image.
119+
4. Verify expected behavior in your target network.
120+
- This should typically include sending a test transaction and verifying it is simulated and built into a block.
121+
122+
## 🪪 License
123+
124+
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)