You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> This library is early alpha software under active and rapid development. Breaking changes are expected, APIs may shift, and stability is not guaranteed. No official support is provided at this stage; however, early adopters are encouraged to open issues for bugs, feedback, or feature requests. Your input will help shape the roadmap.
1
+
# rblib — A Modular Rust SDK for Ethereum Block Building
> This library is **alpha software** under active development. Breaking changes are expected, APIs are not yet stable, and no official support is provided. Early adopters are encouraged to open issues for bugs and feedback to help shape the project's direction.
8
+
9
+
10
+
11
+
12
+
**rblib** is a high-performance, modular Rust SDK for constructing Ethereum-compatible block builders. Built on top of the [Reth](https://github.com/paradigmxyz/reth) execution engine, it provides robust, platform-agnostic primitives and declarative workflows designed for both L1 and L2 applications.
9
13
10
-
**rblib** is a Rust SDK for building Ethereum-compatible block builders using the [Reth](https://github.com/paradigmxyz/reth) execution engine. It provides two independent, platform-agnostic APIs:
14
+
-----
11
15
12
-
-**Payload API** — Flexible primitives for constructing and inspecting block payloads.
13
-
-**Pipelines API** — Declarative workflows for block building, suitable for both L1 and L2 scenarios.
16
+
## Core Philosophy
14
17
15
-
Out-of-the-box support is provided for both `Ethereum` and `Optimism` platforms via the `Platform` trait.
18
+
`rblib`is designed for sophisticated engineering teams who require granular control and composability in their block-building logic. Our philosophy centers on three key principles:
16
19
17
-
---
20
+
***Modularity:** Core components are decoupled. Use the low-level Payload API for fine-grained control, or compose high-level Pipelines for declarative workflows.
21
+
***Performance:** By leveraging Reth and a zero-copy design for payload state, `rblib` is built for high-throughput, latency-sensitive environments.
22
+
***Extensibility:** A clean `Platform` trait abstraction allows for seamless extension to support custom EVM-based chains (L2s, app-chains) without forking the core logic.
18
23
19
-
## Payload Building API
24
+
-----
20
25
21
-
Located in `src/payload`, this API offers a composable interface for building block payloads through a series of checkpoints. It can be used standalone, without the pipeline system.
26
+
## Key Features
22
27
23
-
### Checkpoints
28
+
***Composable Payload API:** A flexible, low-level API for constructing and inspecting block payloads via immutable `Checkpoint` transformations.
29
+
***Declarative Pipelines API:** A high-level, composable system for defining block-building workflows (e.g., ordering, revert protection) as reusable `Step`s.
30
+
***Platform-Agnostic Design:** Out-of-the-box support for `Ethereum` and `Optimism`, with a clear interface for adding new platforms.
31
+
***Integrated Testing Framework:** A rich test suite with utilities for multi-platform testing, local Reth nodes, and isolated component tests.
24
32
25
-
A `Checkpoint<P>` is an atomic unit of payload mutation—think of it as a state transformation (e.g., applying a transaction or bundle). Checkpoints are cheap to copy, discard, and fork, making it easy to explore alternative payload constructions.
33
+
-----
26
34
27
-
Each checkpoint:
35
+
## Getting Started
36
+
37
+
Add `rblib` to your project's dependencies:
38
+
39
+
```bash
40
+
cargo add rblib
41
+
```
28
42
29
-
- Tracks its entire history back to the block’s initial state.
30
-
- Implements `DatabaseRef`, acting as a chain state provider rooted at the parent block plus all mutations in its history.
43
+
-----
31
44
32
-
Common algorithms for building and inspecting checkpoints are available in `src/payload/ext/checkpoint.rs`.
45
+
## Core Concepts
33
46
34
-
#### Example: Building and Forking Payloads
47
+
`rblib` is split into two primary APIs that can be used independently or together.
48
+
49
+
### 1\. The Payload API
50
+
51
+
Located in `rblib::payload` (see `src/payload`), this API provides the foundational primitives for block construction. It enables exploring many different payload variations efficiently.
52
+
53
+
#### Checkpoints
54
+
55
+
A `Checkpoint<P>` is an immutable snapshot of a payload's state after a mutation (e.g., applying a transaction or bundle). Checkpoints are cheap to clone and fork, making it trivial to explore alternative block constructions from a common state. Each checkpoint retains the history of its parent, allowing it to act as a `DatabaseRef` for the chain state at that specific point. Common algorithms for inspecting checkpoints are available in `src/payload/ext/checkpoint.rs`.
56
+
57
+
**Example: Building and Forking a Payload**
35
58
36
59
```rust
37
60
userblib::{*, test_utils::*};
38
61
39
62
letctx=BlockContext::<Ethereum>::mocked();
40
63
64
+
// Create a linear history
41
65
letcheckpoint1=ctx.apply(tx1)?;
42
66
letcheckpoint2=checkpoint1.apply(tx2)?;
43
67
44
-
// Fork the state to explore alternatives
68
+
// Fork from an earlier state to explore an alternative
A `Span<P>`represents a linear sequence of checkpoints—useful for analyzing or manipulating parts of a payload.
80
+
A `Span<P>`is a view over a linear sequence of checkpoints, useful for analyzing or manipulating a specific portion of a payload's history.
58
81
59
82
```rust
60
83
userblib::payload::*;
61
84
62
-
letall_history=checkpoint.history();
63
-
letall_gas=all_history.gas_used();
85
+
letfull_history=checkpoint.history();
86
+
lettotal_gas=full_history.gas_used();
64
87
65
-
letsub_span=all_history.skip(2).take(4);
88
+
// Analyze a sub-section of the payload
89
+
letsub_span=full_history.skip(2).take(4);
66
90
letsub_gas=sub_span.gas_used();
67
91
```
68
92
69
-
### Platform Agnostic
70
-
71
-
The Payload API works with any type implementing the `Platform` trait.
93
+
### 2\. The Pipelines API
72
94
73
-
---
95
+
Located in `rblib::pipelines` (see `src/pipelines/`), this API uses the Payload API to create declarative, reusable block-building workflows. It is particularly powerful for L2s, where standardized logic can be composed and customized.
74
96
75
-
## Pipelines API
97
+
Pipelines are built from **Steps** (`src/pipelines/step.rs`) and control-flow components (`src/pipelines/mod.rs`). A rich library of common, reusable steps is provided in `src/pipelines/steps/`.
76
98
77
-
Located in `src/pipelines/`, this API builds on the Payload API to provide a declarative, composable workflow for block building. It’s especially useful for L2 builders, where common logic can be reused and customized.
99
+
**Example: A Minimal Builder Pipeline**
78
100
79
-
### Example: Minimal Builder Pipeline
101
+
This example defines a pipeline that loops over a set of ordering and protection steps before finalizing the block.
80
102
81
103
```rust
82
104
userblib::*;
83
105
84
106
fnmain() {
107
+
// Define a reusable pipeline workflow
85
108
letpipeline=Pipeline::<Ethereum>::default()
86
109
.with_epilogue(BuilderEpilogue)
87
110
.with_pipeline(
@@ -94,6 +117,7 @@ fn main() {
94
117
),
95
118
);
96
119
120
+
// Integrate with a Reth node
97
121
Cli::parse_args()
98
122
.run(|builder, _|asyncmove {
99
123
lethandle=builder
@@ -111,65 +135,51 @@ fn main() {
111
135
}
112
136
```
113
137
114
-
### Pipeline Pattern
138
+
-----
115
139
116
-
-**Steps** (`src/pipelines/step.rs`): Each `Step<P>` implements methods like `step()`, `before_job()`, and `after_job()`. Common steps include transaction ordering, revert protection, and more.
117
-
-**Pipelines** (`src/pipelines/mod.rs`): Compose steps and control-flow components using a builder pattern (`.with_step()`, `.with_prologue()`, `.with_epilogue()`).
118
-
-**Common Steps Library** (`src/pipelines/steps/`): A collection of well-tested reusable payload building steps commonly used in most block builders.
140
+
## Platform Abstraction
119
141
120
-
---
142
+
Chain-specific logic (e.g., transaction types, block validation rules) is abstracted via the `Platform` trait (`src/platform/mod.rs`). This allows the core building logic to remain generic while providing concrete implementations for `Ethereum` and `Optimism`.
121
143
122
-
## Platform Abstraction Layer
144
+
To support a custom chain, implement the `Platform` trait. See `examples/custom-platform.rs` for a practical example.
123
145
124
-
Chain-specific logic is separated via the `Platform` trait (`src/platform/mod.rs`). You can customize platforms for different EVMs, block structures, or transaction types. See `examples/custom-platform.rs` for extending Optimism with custom bundles.
146
+
-----
125
147
126
-
Default implementations for `Ethereum`and `Optimism` are included.
148
+
## Examples and Integration
127
149
128
-
---
150
+
`Pipeline::into_service()` is the primary entry point for converting a pipeline into a Reth-compatible `PayloadServiceBuilder`. For complete integration examples, see the `examples/` directory and the reference builder implementation in `bin/flashblocks/src/main.rs`.
129
151
130
-
## Testing Infrastructure
152
+
-----
131
153
154
+
## Development & Testing
155
+
156
+
The project includes a comprehensive testing infrastructure to ensure reliability.
157
+
158
+
***Run all tests:**
159
+
```bash
160
+
cargo test
161
+
```
162
+
***Run a specific test with verbose logging:**
163
+
```bash
164
+
TEST_TRACE=on cargo test smoke::all_transactions_included_ethereum
165
+
```
132
166
- **Multi-Platform Testing**: Use `#[rblib_test(Ethereum, Optimism, YourCustomPlatform)]` to run tests across platforms.
133
167
- **Local Test Nodes**: `LocalNode<P, C>` (`src/test_utils/node.rs`) provides full Reth nodes for integration testing.
- **Funded Accounts**: Use `FundedAccounts::by_address()` or `.with_random_funded_signer()`fortest transactions.
136
170
- **Mocks**: Mocking utilities are available for types like `BlockContext` and `PayloadAttributes`.
137
171
138
-
---
139
-
140
-
## Development Commands
141
-
142
-
Run all tests:
143
-
144
-
```bash
145
-
cargo test
146
-
```
147
-
148
-
Debug a specific test with logs:
149
-
150
-
```bash
151
-
TEST_TRACE=on cargo test smoke::all_transactions_included_ethereum
152
-
```
153
-
154
-
---
155
-
156
-
## Integration with Reth
157
-
158
-
-`Pipeline::into_service()` converts pipelines to `PayloadServiceBuilder`.
159
-
- Platform-specific `build_payload()` methods use Reth’s native builders.
160
-
161
-
See `examples/` and `bin/flashblocks/src/main.rs` for integration examples.
162
172
163
-
---
173
+
-----
164
174
165
175
## Contributing
166
176
167
-
Contributions, issues, and feature requests are welcome. Please see the codebase and examples for guidance on extending platforms, steps, or pipelines.
177
+
Contributionsare welcome. Please feel free to open an issue to discuss a bug, feature request, or design question. Pull requests should be focused and include relevant tests.
168
178
169
-
## License
179
+
## License
170
180
171
-
The code in this project is free software under the [MIT License](/LICENSE).
181
+
This project is licensed under the [MIT License](/LICENSE).
0 commit comments