feat: add support for testing_ rpc namespace and testing_buildBlockV1 by 0xKarl98 · Pull Request #20094 · paradigmxyz/reth

0xKarl98 · 2025-12-03T12:51:14Z

This closes issue #20069 , summerized as below :

Implemented the testing_buildBlockV1 RPC namespace (testing-only, default disabled) per spec:
- Added TestingApi and TestingBuildBlockRequest (camelCase, payloadAttributes+transactions+extraData) in rpc-ap
- Implemented server-side handler and builder: TestingBlockBuilder trait and EthTestingBlockBuilder execute only the provided raw signed transactions (order preserved), reject blob tx without sidecars, apply payloadAttributes/extraData, and return ExecutionPayloadEnvelopeV4 without touching the canonical chain.
- Wired conditional registration: hidden CLI flags --http.testing / --ws.testing add testing to module selection, and in Ethereum node we construct EthTestingBlockBuilder and merge TestingApi only when the testing module is explicitly requested. Security note added to API docs
- Expose a hidden --testing.max-concurrent flag (default 1), and wire testing RPC instantiation to use a semaphore + spawn_blocking so heavy block builds don’t block the async runtime and have bounded concurrency

References :
testing_buildBlockV1.md ethereum/execution-apis#710

cc @mattsse

0xKarl98 · 2025-12-04T04:48:25Z

@mattsse Should we support testing blob/sidecar transactions here ?

mattsse

this looks pretty good already

left some suggestions

mattsse · 2025-12-04T09:18:12Z

crates/node/core/src/args/rpc_server.rs

these args we can exclude, we can make it so that --http.api also accepts testing

Yeah we can exclude that and make it more simple

mattsse · 2025-12-04T09:19:01Z

crates/rpc/rpc-api/src/testing.rs

+/// Request payload for `testing_buildBlockV1`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TestingBuildBlockRequest {


let's name this V1

Suggested change

pub struct TestingBuildBlockRequest {

pub struct TestingBuildBlockRequestV1 {

crates/rpc/rpc-builder/src/config.rs

mattsse · 2025-12-04T09:21:33Z

crates/rpc/rpc-builder/src/lib.rs

these changes we can all undo because we can instantiate this on demand specifically for eth

similar to flashbots api:

reth/crates/ethereum/node/src/node.rs

Lines 307 to 310 in a62b46a

container.modules.merge_if_module_configured(

RethRpcModule::Flashbots,

validation_api.into_rpc(),

)?;

mattsse · 2025-12-04T09:24:01Z

crates/rpc/rpc/src/testing.rs

+    async fn build_block(
+        &self,
+        request: TestingBuildBlockRequest,
+    ) -> RpcResult<ExecutionPayloadEnvelopeV4> {


this entire fn logic we need to spawn as blocking, ideally also add a semaphor for this so we can limit how many requests we allow at the same time

In terms of the semaphor , which number do you think is appropriate by default ?

I just set the concurrent number to at least 1 and can be overriten if value provided

I think let's go with just 1 by default for now

mattsse

cool, a few more nits

would be great to get a simple e2e test for this that calls this, see ethereum/node/tests/it for reference

paging @klkvr for suggestions re generics

mattsse · 2025-12-06T08:12:44Z

crates/ethereum/node/src/node.rs

+                let testing_requested = {
+                    let cfg = container.modules.module_config();
+                    cfg.contains_http(&RethRpcModule::Other("testing".to_string())) ||
+                        cfg.contains_ws(&RethRpcModule::Other("testing".to_string())) ||
+                        cfg.contains_ipc(&RethRpcModule::Other("testing".to_string()))


I believe this is just merge_if_configured

yeah should use merge_if_module_configured instead

mattsse · 2025-12-06T08:13:20Z

crates/ethereum/node/src/node.rs

+                if testing_requested {
+                    let evm_config: EthEvmConfig<ChainSpec> =
+                        EthEvmConfig::new(testing_chain.clone());
+                    let builder = EthTestingBlockBuilder::new(
+                        testing_provider,
+                        evm_config,
+                        EthereumBuilderConfig::new(),
+                    );
+                    let testing_api = TestingApi::new(builder, testing_max_concurrent).into_rpc();


imo we can always instantiate this and just call merge_if_configured

mattsse · 2025-12-06T08:14:35Z

crates/node/core/src/args/rpc_server.rs

+    /// Max concurrent `testing_buildBlockV1` requests (hidden, defaults to 1).
+    #[arg(long = "testing.max-concurrent", default_value_t = 1usize, hide = true)]
+    pub testing_max_concurrent: usize,


we can make some default assumptions here and dont really need this as a setting imo

Ahh alright let's go by default

mattsse · 2025-12-06T08:16:01Z

crates/rpc/rpc/src/testing.rs

+pub trait TestingBlockBuilder: Send + Sync + std::fmt::Debug + 'static {
+    /// Build a block according to the testing API request.
+    async fn build_block(
+        &self,
+        request: TestingBuildBlockRequestV1,
+    ) -> RpcResult<ExecutionPayloadEnvelopeV4>;
+}


I think this api could potentially be useful for other networks as well, so we can make an effort here to make this generic over the types, like N: NodePrimitives perhaps, or at least the actual TestingApi

mattsse · 2025-12-06T08:17:14Z

crates/ethereum/node/src/node.rs

+            ChainSpec = ChainSpec,
            Primitives = EthPrimitives,
            Payload: EngineTypes<ExecutionData = ExecutionData>,
        >,
        Evm: ConfigureEvm<NextBlockEnvCtx = NextBlockEnvAttributes>,
    >,
+    N::Provider: BlockReaderIdExt<
+            Block = EthBlock,
+            Header = <EthBlock as BlockTrait>::Header,
+            Transaction = TransactionSigned,
+            Receipt = Receipt,
+        > + StateProviderFactory
+        + ChainSpecProvider<ChainSpec = ChainSpec>
+        + Send
+        + Sync
+        + 'static,


I'd like to avoid these changes if possible, I think the entire block building logic is already sufficiently generic enough and we can make a few changes to the TestingApi to route the types accordingly

mattsse · 2025-12-06T08:17:53Z

crates/ethereum/node/src/node.rs

+                    let evm_config: EthEvmConfig<ChainSpec> =
+                        EthEvmConfig::new(testing_chain.clone());


all of these should be obtainable from the ctx type I believe

Yeah have reduced the unnessary part

mattsse · 2025-12-06T08:18:43Z

crates/rpc/rpc/src/testing.rs

+        let handle = Handle::current();
+        let join_handle =
+            tokio::task::spawn_blocking(move || handle.block_on(builder.build_block(request)));


we can give this type a Box<dyn TaskExecutor> which can also obtain from the ctx where this type is created

mattsse · 2025-12-06T08:19:30Z

crates/rpc/rpc/src/testing.rs

+    async fn build_block(
+        &self,
+        request: TestingBuildBlockRequest,
+    ) -> RpcResult<ExecutionPayloadEnvelopeV4> {


I think let's go with just 1 by default for now

0xKarl98 · 2025-12-06T11:52:33Z

cool, a few more nits

would be great to get a simple e2e test for this that calls this, see ethereum/node/tests/it for reference

paging @klkvr for suggestions re generics

Yeah before i was thinking to add it after getting feedbacks from you , now will add it

…number * upstream: (203 commits) feat(node-core): make rpc server args customizable (paradigmxyz#20312) feat: add `account_history_in_rocksdb` field to `StorageSettings` (paradigmxyz#20282) feat(engine): Add BAL stub methods to ExecutionPayload and BlockOrPayload (paradigmxyz#20311) docs: fix misleading links (paradigmxyz#20300) ci: add more sccache (paradigmxyz#20316) feat: bump alloy-evm (paradigmxyz#20314) feat: allow larger ws frames on client side (paradigmxyz#20307) docs: add architecture diagrams to ExEx documentation (paradigmxyz#20193) feat: add semaphore for blocking IO requests (paradigmxyz#20289) ci: scale down depot runners (paradigmxyz#20295) perf: fetch header directly (paradigmxyz#20294) docs(exex): fix DebugApi comment (paradigmxyz#20296) feat: add support for testing_ rpc namespace and testing_buildBlockV1 (paradigmxyz#20094) chore: update engine_getBlobs metric (paradigmxyz#20290) chore(optimism): move predeploy constant to op-alloy (paradigmxyz#20181) docs: fix stages order and add missing EraStage (paradigmxyz#20283) docs: improve map_add_ons method documentation (paradigmxyz#20248) feat: add `transaction_hash_numbers_in_rocksdb` field to `StorageSettings` (paradigmxyz#20209) docs: clarify network mode, tx gossip and NAT (paradigmxyz#20247) feat: add support for debug_getBadBlock (paradigmxyz#20177) ...

0xKarl98 requested review from Rjected, gakonst, klkvr and mattsse as code owners December 3, 2025 12:51

github-project-automation bot added this to Reth Tracker Dec 3, 2025

github-project-automation bot moved this to Backlog in Reth Tracker Dec 3, 2025

0xKarl98 marked this pull request as draft December 4, 2025 02:57

0xKarl98 marked this pull request as ready for review December 4, 2025 04:47

mattsse requested changes Dec 4, 2025

View reviewed changes

github-project-automation bot moved this from Backlog to In Progress in Reth Tracker Dec 4, 2025

0xKarl98 requested a review from mattsse December 5, 2025 03:43

mattsse requested changes Dec 6, 2025

View reviewed changes

0xKarl98 requested a review from mattsse December 6, 2025 12:00

0xKarl98 added 15 commits December 11, 2025 03:36

resolve issues

0b2a564

remove unnessary default-features

e94df09

add tests and clean up

e10c7e9

clean up

806b0bd

add comments

fa0fc35

cargo fmt

0fa0ea7

add missed config

4fc5db4

pass test --doc check

a901c1a

re-export without touch main.rs

50569ac

refactor and simplify build_block

8deb28c

remove unused helper functions

e10b073

Avoid pre-install at rpc-builder

d5b6c8c

exclude --http.api/--ws.api

0f05ce1

fix clippy

6ba66d1

make build_block blocking && set semophore to build_block

ea8f28f

0xKarl98 and others added 8 commits December 11, 2025 03:36

add comments to build_blocks related functions

2b2ed83

hardcode testing_max_concurrent

970dc63

make interface generic

786340b

make api generic

5c8c811

Inject task executor into testing API

2d2498f

obtain from ctx directly

8d77ebf

add e2e test

41bb41f

simplify

7262e4a

klkvr force-pushed the testing_buildBlockV1 branch from 6f1b5d2 to 7262e4a Compare December 11, 2025 00:40

klkvr requested a review from rakita as a code owner December 11, 2025 00:40

klkvr and others added 4 commits December 11, 2025 04:43

revert

54b9014

Merge branch 'main' into testing_buildBlockV1

3a056ca

chore: add named testing module

66f3090

chore: update test

c447c79

mattsse approved these changes Dec 11, 2025

View reviewed changes

mattsse added C-enhancement New feature or request M-changelog This change should be included in the changelog A-rpc Related to the RPC implementation labels Dec 11, 2025

mattsse added 3 commits December 11, 2025 09:43

chore: typos

82318ee

chore: typos

7aaa655

chore: typos

7196283

mattsse enabled auto-merge December 11, 2025 08:54

mattsse added this pull request to the merge queue Dec 11, 2025

Merged via the queue into paradigmxyz:main with commit e90cfed Dec 11, 2025
45 checks passed

github-project-automation bot moved this from In Progress to Done in Reth Tracker Dec 11, 2025

0xKarl98 deleted the testing_buildBlockV1 branch December 30, 2025 09:08

	pub struct TestingBuildBlockRequest {
	pub struct TestingBuildBlockRequestV1 {

	container.modules.merge_if_module_configured(
	RethRpcModule::Flashbots,
	validation_api.into_rpc(),
	)?;

		let evm_config: EthEvmConfig<ChainSpec> =
		EthEvmConfig::new(testing_chain.clone());

Conversation

0xKarl98 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

0xKarl98 commented Dec 4, 2025

Uh oh!

mattsse left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xKarl98 Dec 4, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

mattsse left a comment

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!

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!

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!

0xKarl98 commented Dec 6, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

0xKarl98 commented Dec 3, 2025 •

edited

Loading

0xKarl98 Dec 4, 2025 •

edited

Loading