feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Himess · 2026-01-10T21:44:55Z

Summary

Introduces UnifiedReceiptBuilder - a wrapper that handles both deposit and non-deposit transaction receipts seamlessly, eliminating the try-catch pattern required by OpReceiptBuilder.

Changes

Added receipt_builder.rs with UnifiedReceiptBuilder<C> struct
Single build() method handles both tx types internally
Simplified state_builder.rs - removed ~40 lines of manual deposit handling
Removed unused alloy-op-evm dependency

Closes #309

…eipt handling Add a new UnifiedReceiptBuilder that handles both deposit and non-deposit transactions seamlessly without requiring error handling at the call site. The builder wraps OpRethReceiptBuilder and automatically handles the deposit receipt case internally, eliminating the need for callers to implement the try-catch pattern typically required when using build_receipt followed by build_deposit_receipt. Changes: - Add receipt_builder module with UnifiedReceiptBuilder - Update PendingStateBuilder to use UnifiedReceiptBuilder - Simplify execute_with_evm method by removing manual deposit handling - Remove receipt_builder parameter from PendingStateBuilder::new() Closes base#309

cb-heimdall · 2026-01-10T21:44:59Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

Removed wrapper around OpRethReceiptBuilder and implemented direct receipt building logic. This fixes type mismatches between OpTxEnvelope and OpTransactionSigned that prevented compilation. - Use direct OpTxType matching instead of build_receipt/build_deposit_receipt pattern - Accept ExecutionResult<E::HaltReason> for proper generic type handling - Remove unused alloy-op-evm dependency

refcell · 2026-01-11T21:39:18Z

crates/client/flashblocks/src/state_builder.rs

+                    input,
+                    &mut self.l1_block_info,
+                )
+                .unwrap()


Can we properly bubble up an error here instead of using .unwrap()? We should have fixed this previously but if we're modifying this, let's cleanup past issues.

refcell · 2026-01-11T21:41:42Z

crates/client/flashblocks/src/state_builder.rs

+                        self.cumulative_gas_used,
+                        self.pending_block.timestamp,
+                    )
+                    .map_err(|_| ExecutionError::DepositAccountLoad)?;


Let's implement From<ReceiptBuildError> for ExecutionError. This should let us remove the .map_err here and just use the ? operator.

So this would just become:

let receipt = self .receipt_builder .build( &mut self.evm, &transaction, result, &state, self.cumulative_gas_used, self.pending_block.timestamp, )?;

refcell · 2026-01-11T21:43:12Z

crates/client/flashblocks/src/receipt_builder.rs

+        evm: &mut E,
+        transaction: &Recovered<OpTxEnvelope>,
+        result: ExecutionResult<E::HaltReason>,
+        _state: &EvmState,


Can we remove this argument if it's unused?

crates/client/flashblocks/src/receipt_builder.rs

refcell

A few changes + nits

- Add From<ReceiptBuildError> for ExecutionError and StateProcessorError - Remove unused _state parameter from build() - Replace .unwrap() with proper error handling - Add comprehensive tests for receipt building logic

- Add EVM-based tests that directly test build() method - Test legacy receipt building - Test deposit receipt building - Test Canyon hardfork activation (deposit_receipt_version) - Test failed transaction receipt

Himess · 2026-01-12T10:53:16Z

@refcell Ready to review

refcell · 2026-01-12T14:54:45Z

crates/client/flashblocks/src/error.rs

+impl From<crate::ReceiptBuildError> for ExecutionError {
+    fn from(_: crate::ReceiptBuildError) -> Self {
+        Self::DepositAccountLoad
+    }
+}
+


Shouldn't this be the ExecutionError::RpcReceiptBuild() error variant rather than the ExecutionError::DepositAccountLoad unless I'm not understanding something?

refcell · 2026-01-12T14:56:11Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_legacy_receipt_type() {
+        let tx = create_legacy_tx();
+        assert_eq!(tx.tx_type(), OpTxType::Legacy);
+    }
+
+    #[test]
+    fn test_deposit_receipt_type() {
+        let tx = create_deposit_tx();
+        assert_eq!(tx.tx_type(), OpTxType::Deposit);
+    }


rm

Suggested change

#[test]

fn test_legacy_receipt_type() {

let tx = create_legacy_tx();

assert_eq!(tx.tx_type(), OpTxType::Legacy);

}

#[test]

fn test_deposit_receipt_type() {

let tx = create_deposit_tx();

assert_eq!(tx.tx_type(), OpTxType::Deposit);

}

refcell · 2026-01-12T15:03:36Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_tx_type_to_receipt_mapping() {
+        let receipt =
+            Receipt { status: Eip658Value::Eip658(true), cumulative_gas_used: 21000, logs: vec![] };
+
+        // Test all non-deposit variants
+        assert!(matches!(OpReceipt::Legacy(receipt.clone()), OpReceipt::Legacy(_)));
+        assert!(matches!(OpReceipt::Eip2930(receipt.clone()), OpReceipt::Eip2930(_)));
+        assert!(matches!(OpReceipt::Eip1559(receipt.clone()), OpReceipt::Eip1559(_)));
+        assert!(matches!(OpReceipt::Eip7702(receipt), OpReceipt::Eip7702(_)));
+    }


This is also a no-op test, rm.

Suggested change

#[test]

fn test_tx_type_to_receipt_mapping() {

let receipt =

Receipt { status: Eip658Value::Eip658(true), cumulative_gas_used: 21000, logs: vec![] };

// Test all non-deposit variants

assert!(matches!(OpReceipt::Legacy(receipt.clone()), OpReceipt::Legacy(_)));

assert!(matches!(OpReceipt::Eip2930(receipt.clone()), OpReceipt::Eip2930(_)));

assert!(matches!(OpReceipt::Eip1559(receipt.clone()), OpReceipt::Eip1559(_)));

assert!(matches!(OpReceipt::Eip7702(receipt), OpReceipt::Eip7702(_)));

}

refcell · 2026-01-12T15:07:35Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_build_legacy_receipt() {
+        let chain_spec = Arc::new(OpChainSpecBuilder::base_mainnet().build());
+        let mut db = InMemoryDB::default();
+        let mut evm = create_test_evm(chain_spec.clone(), &mut db);
+
+        let builder = UnifiedReceiptBuilder::new(chain_spec);
+        let tx = create_legacy_tx();
+        let result = create_success_result();
+
+        let receipt = builder.build(&mut evm, &tx, result, 21000, 0).expect("build should succeed");
+
+        assert!(matches!(receipt, OpReceipt::Legacy(_)));
+        if let OpReceipt::Legacy(inner) = receipt {
+            assert!(inner.status.coerce_status());
+            assert_eq!(inner.cumulative_gas_used, 21000);
+        }


refcell

Much better. A couple of nits. Will add @meyer9 as a reviewer to get another pair of eyes since this addresses a ticket he wrote.

You'll also need to resolve conflicts with trunk

meyer9

LG other than the comments @refcell left! Will let them approve once comments are addressed!

Himess marked this pull request as draft January 10, 2026 21:58

Himess added 2 commits January 11, 2026 01:01

style: apply rustfmt formatting

c6c38e4

Himess marked this pull request as ready for review January 10, 2026 22:53

refactor: add const fn to simple constructors and getters

37c5b5d

refcell reviewed Jan 11, 2026

View reviewed changes

crates/client/flashblocks/src/receipt_builder.rs Show resolved Hide resolved

refcell requested changes Jan 11, 2026

View reviewed changes

Himess added 2 commits January 12, 2026 13:31

refactor: address review feedback for UnifiedReceiptBuilder

7201b10

- Add From<ReceiptBuildError> for ExecutionError and StateProcessorError - Remove unused _state parameter from build() - Replace .unwrap() with proper error handling - Add comprehensive tests for receipt building logic

test: add build() method tests for UnifiedReceiptBuilder

85737f0

- Add EVM-based tests that directly test build() method - Test legacy receipt building - Test deposit receipt building - Test Canyon hardfork activation (deposit_receipt_version) - Test failed transaction receipt

Himess requested a review from refcell January 12, 2026 10:53

refcell reviewed Jan 12, 2026

View reviewed changes

refcell requested a review from meyer9 January 12, 2026 15:10

meyer9 reviewed Jan 12, 2026

View reviewed changes

danyalprout added this to the v0.4.0 milestone Jan 12, 2026

feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Are you sure you want to change the base?

feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Uh oh!

Conversation

Himess commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

cb-heimdall commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

refcell left a comment

Choose a reason for hiding this comment

Uh oh!

Himess commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

refcell left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

meyer9 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Himess commented Jan 10, 2026 •

edited

Loading

cb-heimdall commented Jan 10, 2026 •

edited

Loading

refcell left a comment •

edited

Loading