Timeboost Bundle Format #296

akonring · 2025-03-26T08:46:31Z

This PR is an implementation of the Bundle-centric approach for Timeboost transactions and roughly follows the design proposal (see Design Proposal for detailed description).

tl;dr:

No need to "shoe-horn" bundles and encrypted transactions into Ethereum transaction format.
While the spec addendum describes a union type (priority bundles, encrypted non-priority tx, regular non-priority tx), this PR (and design proposal) instead introduces non-priority bundles.
Priority bundle submission should closely mirror centralized timeboost; the idea being that a PLC should be able to use the same approach to submit a priority bundle to the new decentralized timeboost.

Content

This PR refactors timeboost phases to handle the new format for (regular) Bundle and modified PriorityBundle. Most of the underlying logic remains unchanged.

Other points

This PR touches almost all parts of the Timeboost stack and thus will not be easy to maintain.
Final confirmation is needed for this design to be merged. In any case, modifying the new design to conform to the union type (described above) is a trivial addition to this PR.

twittner

Thanks for putting so much effort into getting the bundle format details right!

Cargo.toml

timeboost-sequencer/Cargo.toml

timeboost-types/Cargo.toml

twittner · 2025-03-30T19:24:59Z

timeboost-types/src/bundle.rs

+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+pub struct Bundle {


Perhaps this should be named RegularBundle and BundleVariant can become Bundle?

timeboost-types/src/bundle.rs

timeboost-types/src/seqno.rs

timeboost-types/src/bundle.rs

twittner · 2025-03-30T19:35:51Z

timeboost-types/src/bundle.rs

+    ) -> arbitrary::Result<PriorityBundle<Signed>> {
+        let bundle = Bundle::arbitrary(u)?;
+        let auction = Address::default();
+        let seqno = SeqNo::from(u.int_in_range(1..=u64::MAX)?);


If the sequence number space is that large, chances are that there will always be gaps in tests.

Addendum: do we hit any tricky behavior when we hit u64::MAX in anything? It's overwhelmingly unlikely that we'll hit this, of course, but just a thought. Not sure if we do any math anywhere.

If the sequence number space is that large, chances are that there will always be gaps in tests.

Fixed: 24ec63e.
But there will be gaps, regardless. We should fix test/validation - currently no priority bundles make it through the inclusion phase. But consider this out-of-scope for this PR.

Addendum: do we hit any tricky behavior when we hit u64::MAX in anything? It's overwhelmingly unlikely that we'll hit this, of course, but just a thought. Not sure if we do any math anywhere.

iiuc it is the responsibility of the PLC to ensure correct bundle format (incl. correct seqno). We could do saturating/checked add in places like:

timeboost/timeboost-sequencer/src/include.rs

Line 172 in 24ec63e

.any(|(x, y)| *x + 1 != *y)

Think Rust does silent overflows by default in release-mode which also seems ok.

timeboost-sequencer/src/lib.rs

timeboost-sequencer/src/queue.rs

jparr721

Some comments

jparr721 · 2025-04-01T01:24:50Z

timeboost-sequencer/src/decrypt.rs

        let data = dec
-            .get(i + ptxs.len())
+            .get(i + priority_bundles.len())


Since we're touching this, it might be nice to get a comment here. Not sure what this offset is doing with i + len. Mind throwing something here to make drive-by edits easier?

added a comment to the function to make it easier to parse.

jparr721 · 2025-04-01T01:25:14Z

timeboost-sequencer/src/include.rs

@@ -21,7 +24,7 @@ pub struct Includer {
    /// Consensus delayed inbox index.
    index: DelayedInboxIndex,
    /// Cache of transaction hashes for the previous 8 rounds.
-    cache: BTreeMap<RoundNumber, HashSet<Hash>>,
+    cache: BTreeMap<RoundNumber, HashSet<[u8; 32]>>,


This is just a 256-bit keccak hash.

jparr721 · 2025-04-01T01:27:25Z

timeboost-sequencer/src/queue.rs

+            match b {
+                BundleVariant::Regular(b) => inner.regular.push_back((now, b)),
+                BundleVariant::Priority(b) =>
+                // TODO: Check auction contract address on bundle


In case this happens when you're not here when we tackle this, can we get a bit more detail on this? I will make it a ticket as well. Basically, what are we checking? We can either document here, or can you please add a ticket in asana so I know what to do?

I'll remove it from here since the TODO is already present in Bundle::validate.
The check in centralized timeboost: https://github.com/OffchainLabs/nitro/blob/1e16dc408d24a7784f19acd1e76a71daac528a22/execution/gethexec/express_lane_service.go#L414.
Applying Occam's razor it seems like an extra check in case of multiple auctions on the same chain.

jparr721 · 2025-04-01T01:28:54Z

timeboost-sequencer/src/sort.rs

+            .map(|p| (p.bundle(), true))
+            .chain(regular.iter().map(|r| (r, false)))


How come we aren't just using the Priority types here instead?

jparr721 · 2025-04-01T01:29:28Z

timeboost-sequencer/src/sort.rs

                            Err(err) => {
                                warn!(%err, "failed to decode transaction")
                            }
                        }
                    }
                }
                Err(err) => {
-                    warn!(?err, "failed to ssz-decode priority bundle")
+                    warn!(?err, "failed to ssz-decode bundle")


What happens when this dies? Do we throw everything away? If it's a serious issue, perhaps it could be an error? Who is at fault when such a circumstance happens? The sender? Sailfish?

Not sure what you mean by die. If ssz_decode results in an error then there is not much to do. The bundle will simply be ignored but hopefully all honest nodes will come to the same conclusion. imo warn is an appropriate verbosity level and we can always adjust this.

jparr721 · 2025-04-01T01:31:46Z

timeboost-types/src/bundle.rs

+        self.epoch
+    }
+
+    pub fn data(&self) -> &Bytes {


Do we need trivial getters instead of just making the fields public?

jparr721 · 2025-04-01T01:32:58Z

timeboost-types/src/bundle.rs

+        &self.bundle
+    }
+
+    pub fn auction(&self) -> Address {


Nit for later, Address and cliquenet::Address are sometimes head-spinning if they crop up in the same file. Is this Address here an ethereum address? Perhaps we can rename? Doon't do it here, just want thoughts.

sure. rename sounds good.

jparr721 · 2025-04-01T01:33:47Z

timeboost-types/src/bundle.rs

+        Ok(())
+    }
+
+    pub fn sender(&self) -> Result<Address, ValidationError> {


Can we get a doc comment here? It's not super clear why this is a failible operation.

jparr721 · 2025-04-01T01:34:52Z

timeboost-types/src/bundle.rs

+    ) -> arbitrary::Result<PriorityBundle<Signed>> {
+        let bundle = Bundle::arbitrary(u)?;
+        let auction = Address::default();
+        let seqno = SeqNo::from(u.int_in_range(1..=u64::MAX)?);


Addendum: do we hit any tricky behavior when we hit u64::MAX in anything? It's overwhelmingly unlikely that we'll hit this, of course, but just a thought. Not sure if we do any math anywhere.

jparr721 · 2025-04-01T01:36:03Z

timeboost/api/endpoints.toml

+[route.submit-priority]
+PATH = ["/submit-priority"]
 METHOD = "POST"
-DOC = "Submit transaction to Timeboost"
+DOC = "Submit priority bundle to Timeboost"
+
+[route.submit-regular]


Is this correct? Would a user ever submit a priority bundle to the node? Doesn't the user just submit a transaction and only the PLC has priority tx? How do we not spoof this?

How do you envision a PLC submitting priority bundles if not through an API endpoint? The bundle will eventually be authenticated (PLC signature will be checked) before being queued.

timeboost-types/src/bundle.rs

twittner · 2025-04-01T17:06:09Z

timeboost-types/Cargo.toml

@@ -5,6 +5,9 @@ version.workspace = true
 edition.workspace = true
 rust-version.workspace = true

+[features]
+default = ["arbitrary"]


Rather than making this test-related feature a default I think the relevant code sections should be feature-gated.

Thanks. That is indeed better. Fixed in e855b6f.

twittner

👍

akonring force-pushed the ak/bundle-format branch from c903423 to 68ae028 Compare March 26, 2025 09:01

akonring marked this pull request as ready for review March 26, 2025 10:03

akonring mentioned this pull request Mar 26, 2025

Timeboost Bundle Format #293

Closed

akonring added the timeboost label Mar 26, 2025

akonring changed the title ~~Bundle Format~~ Timeboost Bundle Format Mar 26, 2025

akonring mentioned this pull request Mar 28, 2025

Exercise Sailfish with Extensive Load #297

Closed

akonring force-pushed the ak/bundle-format branch from 41ade11 to 4a5829a Compare March 29, 2025 14:32

akonring added 12 commits March 29, 2025 15:45

tests for timeboost bundle verification

48a8abf

add endpoints for bundle

fcf0080

add bundle post request for HTTP API

ea90602

bundle-centric timeboost

ba0238d

fix lint

9fe1079

log signer from failed priority bundle

d0200ab

fix unnecessary async

f714576

add derive for alloy-rlp

3511980

defaults for load gen; add arbitrary for bundles

b384d72

fix lint, script and bundle size for load_gen

b0c21b6

avoid sampling eip4844 blob transactions

bb027de

fix tests

eaf180a

akonring force-pushed the ak/bundle-format branch from 4a5829a to eaf180a Compare March 29, 2025 15:44

twittner reviewed Mar 30, 2025

View reviewed changes

akonring added 5 commits March 31, 2025 09:25

Merge branch 'main' into ak/bundle-format

f401e14

fix alloy dependencies

20a5014

fix remaining dependencies

75a5a7a

ensure type state without generics, renaming, etc.

bd005e9

fix seqno in arbitrary

24ec63e

jparr721 reviewed Apr 1, 2025

View reviewed changes

akonring added 3 commits April 1, 2025 12:47

add comment for assembling inclusion list

6247456

Merge branch 'main' into ak/bundle-format

6b7b46c

adjust comments

9e2d8b4

twittner reviewed Apr 1, 2025

View reviewed changes

timeboost-types/src/bundle.rs Outdated Show resolved Hide resolved

timeboost-types/src/bundle.rs Show resolved Hide resolved

timeboost-types/src/bundle.rs Show resolved Hide resolved

impl Arbitrary for bundle

2222d55

twittner reviewed Apr 1, 2025

View reviewed changes

timeboost-types/src/bundle.rs Show resolved Hide resolved

timeboost-types/src/bundle.rs Show resolved Hide resolved

add arbitrary as default feature

04ab3f9

twittner reviewed Apr 1, 2025

View reviewed changes

use feature gate instead of defaults

e855b6f

twittner approved these changes Apr 1, 2025

View reviewed changes

akonring merged commit ae818c5 into main Apr 1, 2025
6 checks passed

akonring deleted the ak/bundle-format branch April 1, 2025 18:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Timeboost Bundle Format #296

Timeboost Bundle Format #296

akonring commented Mar 26, 2025 •

edited

Loading

twittner left a comment

twittner Mar 30, 2025

twittner Mar 30, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025 •

edited

Loading

jparr721 left a comment

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

jparr721 Apr 1, 2025

jparr721 Apr 1, 2025

akonring Apr 1, 2025

twittner Apr 1, 2025

akonring Apr 1, 2025

twittner left a comment

		.map(\|p\| (p.bundle(), true))
		.chain(regular.iter().map(\|r\| (r, false)))

Timeboost Bundle Format #296

Timeboost Bundle Format #296

Conversation

akonring commented Mar 26, 2025 • edited Loading

tl;dr:

Content

Other points

twittner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akonring Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

jparr721 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

twittner left a comment

Choose a reason for hiding this comment

akonring commented Mar 26, 2025 •

edited

Loading

akonring Apr 1, 2025 •

edited

Loading