feat(full trace): Add full trace hook framework by JimmyShi22 · Pull Request #103 · okx/xlayer-reth

JimmyShi22 · 2026-01-20T09:07:21Z

This pull request introduces two new crates, xlayer-engine-api and xlayer-full-trace, to the codebase and wires them into the workspace. These crates provide a modular middleware system for the Engine API and comprehensive tracing capabilities for both Engine API and RPC transaction calls. The changes include new builder and middleware traits for the Engine API, as well as tools for tracing blockchain state changes and transaction submissions.

The most important changes are:

Engine API Middleware System:

Added the new crate xlayer-engine-api, which provides a builder pattern (XLayerEngineApiBuilder) and a core middleware trait (XLayerEngineApiMiddleware) for composing middleware with the Optimism Engine API. This enables extensible customization of Engine API behavior. [1] [2] [3] [4] [5]

Full Trace and Tracing Infrastructure:

Introduced the xlayer-full-trace crate, which supplies tracing functionality for both Engine API calls and RPC transaction submissions. This includes event hooks for tracing state changes and transaction events, as well as example usage and documentation. [1] [2] [3] [4]

Blockchain and RPC Tracing Implementations:

Added a blockchain tracer (blockchain_tracer.rs) that listens for canonical state changes (commits and reorgs) and triggers event handlers for block and transaction commits.
Implemented an RPC tracer middleware (rpc_tracer.rs) which intercepts transaction submission RPC calls (eth_sendRawTransaction, eth_sendTransaction) and invokes tracing logic before delegating to the underlying service.
Implemented an Engine API tracer middleware (engine_api_tracer.rs) which intercepts Engine API calls (new_payload_v2/v3/v4, fork_choice_updated_v1/v2/v3) and invokes tracing logic before delegating to the underlying OpEngineApi service.

Dependency and Workspace Updates:

Registered the new crates in the workspace and added their dependencies to Cargo.toml, including additional Reth and Alloy libraries to support the new functionality. [1] [2] [3]

These changes lay the groundwork for modular middleware and tracing extensibility in the XLayer node.

bin/node/src/main.rs

crates/engine-api/src/middleware.rs

bin/node/src/main.rs

crates/engine-api/src/builder.rs

Vui-Chee · 2026-01-21T04:14:10Z

crates/full-trace/src/rpc_tracer.rs

+        let inner = self.inner.clone();
+        let method_owned = method.to_string();
+
+        Either::Right(Box::pin(async move {


Box::pin performs heap allocation per call I believe. Do we need this?

sieniven · 2026-01-21T07:52:17Z

crates/full-trace/src/engine_api_tracer.rs

+    Args: Clone + Send + Sync + 'static,
+{
+    /// The inner OpEngineApi (set during build)
+    inner: Option<InnerOpEngineApi<Provider, EngineT, Pool, Validator, ChainSpec>>,


We should remove the option here to ensure that the inner engine api handler is never null.

sieniven · 2026-01-21T08:22:01Z

crates/full-trace/src/blockchain_tracer.rs

I suggest we completely rename the full-trace to a generic XLayerEngineApi handler, since this infrastructure allows us to add custom logic in the future, if required

crates/full-trace/src/engine_api_tracer.rs

* upgrade to v1.10.0 (#98) * perf(builder): use XLayerPayloadServiceBuilder to simplify main codes (#95) Co-authored-by: Vui-Chee <vuicheesiew@gmail.com> Co-authored-by: Niven <sieniven@gmail.com> * drop unused dep * chore: better rename, fix unused variable warning (#99) * Better refactor, fix unused var warn * Better rename * Remove xlayer suffix * Align cargo chef base image with latest rust toolchain version (#100) * Update builder version (#101) * feat(full trace): Add full trace hook framework (#103) * add engine api hook for full trace * rm comment * fix clippy * add send tx hook * add blockchain tracer * cargo lock * fix review issues * simplify to tracer to avoid nasty type bonanza * renamed `TracerConfig` to `Tracer` * more renames * EngineApiTracer derive clone over manual impl * handle middleware overwrite problem * reorder * drop clone * no box on middleware rpc tracer * impl `EngineApiBuilder` directly to tracer --------- Co-authored-by: Vui-Chee <vuicheesiew@gmail.com> * fix: remove engine api, and simplify monitor logic (#107) * remove unused reth-node-api (#108) * fix: resolve audit issues related to flashblocks subscription (#113) * Fix unnecessary clone * Fix incomplete documentation of subscribe addrs filter * Better desc * chore(flashblocks): update builder version to v0.2.5 (#114) * Update builder version to v0.2.5 with full link monitor updates * Fix wspub init * feat: Add Transaction Trace Monitoring Support (#115) * add trace logic * optimize * fix ut * fix ut * fix * fix * optimize code * optimize code * fix * chore: fix rust formatter (#132) * Fix fmt * Remove unused dep * Fix nested if else clippy check * Update dependencies, use reth v1.10.2 and builder v0.3.0 (#133) * fix: upgrade reth v1.10.2 version with bug fixes (#134) * Fix revm dep * Update reth version, use merge fixes version * Add audit report (#135) * add audit report * add audit report --------- Co-authored-by: chunsheng.wang <chunsheng.wang@okg.com> * feat: add flashblocks enabled RPC method (#136) * feat: add flashblocks enabled RPC method * chore: clippy * chore: add unit tests * chore: reword documentation * remove min gas rpc (#138) --------- Co-authored-by: jimmyshi <417711026@qq.com> Co-authored-by: Niven <sieniven@gmail.com> Co-authored-by: Leo <335209779@qq.com> Co-authored-by: wangchunsheng-ops <13614269216@163.com> Co-authored-by: chunsheng.wang <chunsheng.wang@okg.com> Co-authored-by: lucas <66681646+limyeechern@users.noreply.github.com>

add engine api hook for full trace

d83de76

JimmyShi22 marked this pull request as ready for review January 20, 2026 09:09

JimmyShi22 added 3 commits January 20, 2026 17:11

rm comment

5d287fc

fix clippy

d884729

add send tx hook

676e5b4

Vui-Chee reviewed Jan 20, 2026

View reviewed changes

bin/node/src/main.rs Outdated Show resolved Hide resolved

Vui-Chee reviewed Jan 20, 2026

View reviewed changes

bin/node/src/main.rs Outdated Show resolved Hide resolved

add blockchain tracer

131cc31

Vui-Chee reviewed Jan 20, 2026

View reviewed changes

crates/engine-api/src/middleware.rs Outdated Show resolved Hide resolved

cargo lock

334e568

JimmyShi22 changed the title ~~feat(engine api): Add engine api hook for full trace~~ feat(full trace): Add full trace hook framework Jan 20, 2026

fix review issues

8e3445e

Vui-Chee reviewed Jan 20, 2026

View reviewed changes

bin/node/src/main.rs Outdated Show resolved Hide resolved

Vui-Chee added 4 commits January 21, 2026 10:01

simplify to tracer to avoid nasty type bonanza

5886c91

renamed TracerConfig to Tracer

2b1876c

more renames

ccc544a

EngineApiTracer derive clone over manual impl

3f96b3f

Vui-Chee reviewed Jan 21, 2026

View reviewed changes

bin/node/src/main.rs Outdated Show resolved Hide resolved

JimmyShi22 and others added 3 commits January 21, 2026 11:20

handle middleware overwrite problem

34caf6c

reorder

a808997

drop clone

bd359e8

Vui-Chee reviewed Jan 21, 2026

View reviewed changes

Vui-Chee added 2 commits January 21, 2026 14:03

no box on middleware rpc tracer

fb83f4c

impl EngineApiBuilder directly to tracer

ee34c2a

Vui-Chee approved these changes Jan 21, 2026

View reviewed changes

JimmyShi22 merged commit f88111f into dev Jan 21, 2026

sieniven reviewed Jan 21, 2026

View reviewed changes

crates/full-trace/src/engine_api_tracer.rs Show resolved Hide resolved

sieniven mentioned this pull request Jan 21, 2026

fix: Remove engine api, add monitor handle and refactor full link monitor logic #107

Merged

Vui-Chee deleted the jimmyshi/engine-api-middleware branch January 27, 2026 10:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(full trace): Add full trace hook framework#103

feat(full trace): Add full trace hook framework#103
JimmyShi22 merged 16 commits intodevfrom
jimmyshi/engine-api-middleware

JimmyShi22 commented Jan 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Vui-Chee Jan 21, 2026

Uh oh!

sieniven Jan 21, 2026

Uh oh!

sieniven Jan 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Vui-Chee Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

sieniven Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

sieniven Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JimmyShi22 commented Jan 20, 2026 •

edited

Loading