Skip to content

Commit 579a2cb

Browse files
dylanlottdylanlott
committed
add mermaid diagram and readme polish
1 parent a19ff73 commit 579a2cb

File tree

1 file changed

+104
-66
lines changed

1 file changed

+104
-66
lines changed

‎README.md

Lines changed: 104 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,118 @@
1-
# builder
2-
3-
Our sample signet builder implementation.
4-
5-
## Development
6-
7-
This crate contains an example block builder in the Signet ecosystem.
1+
# The Signet Block Builder
2+
3+
The Builder is responsible for transactions through the Signet rollup, from ingestion and simulation to block construction and submission to Ethereum L1.
4+
5+
---
6+
7+
## 🚀 System Design
8+
9+
The Builder orchestrates a series of asynchronous actors that work together to:
10+
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.
16+
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
31+
32+
%% ────────────── CONNECTIONS & DATA FLOW ──────────────
33+
A2_BuilderConfig --> A4_Providers["Connect Providers"]
34+
35+
A4_Providers -.host_provider.-> MetricsTaskActor
36+
A4_Providers -.host_provider.->SubmitTaskActor
37+
A4_Providers -.ru_provider.-> SimulatorTaskActor
38+
39+
EnvTaskActor ==block_env==> SimulatorTaskActor
40+
CacheSystem ==sim_cache ==> SimulatorTaskActor
41+
SubmitTaskActor ==tx receipt==> MetricsTaskActor
42+
SimulatorTaskActor ==built block==> SubmitTaskActor
43+
44+
SubmitTaskActor ==>|"signet block (blob tx)"| C1["Ethereum L1"]
45+
```
846

9-
### Requirements
47+
---
1048

11-
- Rust 1.85
12-
- AWS CLI
13-
- A private key or AWS KMS key for signing transactions
49+
## ⚙️ Configuration
1450

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-
```
51+
The Builder is configured via environment variables. The following values are supported for configuration.
5152

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

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`.
74+
---
5575

56-
It requires a key to sign the transactions and a funded wallet.
76+
## 📤 Transaction Sender
5777

58-
### Environment Variables
78+
A binary (`bin/submit-transaction.rs`) for continously sending very small transactions for testing block construction.
5979

60-
The `transaction-sender` also has a set of configurable environment variables listed below.
80+
The following values are available for configuring the transaction sender:
6181

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=""
68-
```
82+
| Key | Required | Description |
83+
| ------------------- | -------- | ------------------------------------------------ |
84+
| `RPC_URL` | Yes | RPC endpoint used for sending the transaction |
85+
| `RECIPIENT_ADDRESS` | Yes | Address to which the transaction is sent |
86+
| `SLEEP_TIME` | No | Optional delay (in seconds) between transactions |
87+
| `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing |
88+
| `SIGNER_KEY` | Yes | Signing key used to sign the transaction |
6989

70-
## Testing
90+
---
7191

72-
### F
92+
## 🛠️ Development
7393

74-
In order to test the `builder`, one must build and deploy an image in the target network with a provisioned key.
94+
### Requirements
7595

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
96+
- **Rust** ≥ 1.85
97+
- **AWS CLI**
98+
- A private key or AWS KMS key for signing transactions
8099

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

0 commit comments

Comments
 (0)