Feat-11 : Add `limit` param to stop opcode trace capture after N steps by sagarkhandagre998 · Pull Request #10173 · besu-eth/besu

sagarkhandagre998 · 2026-04-03T05:01:08Z

PR description

Add limit param to stop opcode trace capture after N steps

Part of aligning Besu's debug RPC endpoints with the execution-apis spec.

What changed:

OpCodeTracerConfigBuilder — new limit(int) config option (0 = unlimited, default)
TransactionTraceParams — new optional limit JSON param wired into traceOptions()
DebugOperationTracer — dedicated stepCount field drives the limit check; backfill of gasRemainingPostExecution on the last captured frame is preserved even after the limit is hit
DebugOperationTracerTest — two new unit tests covering frame count cap and backfill correctness

Behaviour:

When limit is absent or 0 — no change to existing behaviour
When limit=N — exactly N StructLog entries are recorded; EVM execution continues to completion per spec

Two bugs fixed over the naive implementation:

Used traceFrames.size() as step counter — replaced with a dedicated stepCount field that is explicit and reset correctly per transaction
The last captured frame never got its gasRemainingPostExecution backfilled — moved the early-return guard in tracePostExecution to after the backfill block so it always runs

Fixed Issue(s)

Refs #10115

Thanks for sending a pull request! Have you done the following?

Checked out our contribution guidelines?
Considered documentation and added the doc-change-required label to this PR if updates are required.
Considered the changelog and included an update if required.
For database changes (e.g. KeyValueSegmentIdentifier) considered compatibility and performed forwards and backwards compatibility tests

Locally, you can run these tests to catch failures early:

spotless: ./gradlew spotlessApply
unit tests: ./gradlew build
acceptance tests: ./gradlew acceptanceTest
integration tests: ./gradlew integrationTest
reference tests: ./gradlew ethereum:referenceTests:referenceTests
hive tests: Engine or other RPCs modified?

sagarkhandagre998 · 2026-04-04T04:11:08Z

@macfarla Kindly take a look at once.

parthdagia05 · 2026-04-10T12:38:20Z

This PR doesn't seem to handle negative limit values if someone passes limit = -1, then stepCount >= limit would be true from step 0 , so no frames would be captured. Better to reject negative values .

Also, limit = 0 is treated as "unlimited" based on the options.limit() > 0 check, but there's no test confirming that behavior. Should add one.

@sagarkhandagre998

sagarkhandagre998 · 2026-04-11T13:27:57Z

This PR doesn't seem to handle negative limit values if someone passes limit = -1, then stepCount >= limit would be true from step 0 , so no frames would be captured. Better to reject negative values .

Also, limit = 0 is treated as "unlimited" based on the options.limit() > 0 check, but there's no test confirming that behavior. Should add one.

@sagarkhandagre998

@parthdagia05 Good Catch! will fix.

macfarla · 2026-04-21T08:55:28Z

@sagarkhandagre998 taking a look, however there is a compile error. please ensure you have built locally and run relevant tests before requesting a review. This will massively speed up the feedback loop.

What went wrong:
Execution failed for task ':ethereum:core:compileJava'.

Compilation failed; see the compiler output below.
/Users/sallymacfarlane/workspace/b2/ethereum/core/src/main/java/org/hyperledger/besu/ethereum/vm/DebugOperationTracer.java:68: error: cannot find symbol
if (!(traceOpcode = traceOpcode(currentOperation))) {
^
symbol: method traceOpcode(Operation)
location: class DebugOperationTracer
1 error

sagarkhandagre998 · 2026-04-21T11:16:11Z

@sagarkhandagre998 taking a look, however there is a compile error. please ensure you have built locally and run relevant tests before requesting a review. This will massively speed up the feedback loop.
* What went wrong:
  Execution failed for task ':ethereum:core:compileJava'.
Compilation failed; see the compiler output below.
/Users/sallymacfarlane/workspace/b2/ethereum/core/src/main/java/org/hyperledger/besu/ethereum/vm/DebugOperationTracer.java:68: error: cannot find symbol
if (!(traceOpcode = traceOpcode(currentOperation))) {
^
symbol: method traceOpcode(Operation)
location: class DebugOperationTracer
1 error

Really sorry for that @macfarla ,I had built that locally and tested but had resolved the conflict from github web and something wrong happend . I will fix it to the correct changes .

sagarkhandagre998 · 2026-04-21T11:49:17Z

@macfarla

traceOpcode() was a private method in DebugOperationTracer itself before upstream commit b2cbdeae01 (Stream debug_traceBlock responses directly to avoid OOM on large blocks). That commit introduced AbstractDebugOperationTracer and moved the logic there — renaming it to shouldTraceOpcode() (private to the base class) and having the base class own tracePreExecution.

thats why you got the compilation error , I will fix that .

macfarla

couple of comments. I'm not sure about modifying the traceOpcode boolean, there may be a cleaner way

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

…emainingPostExecution Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

…ostExecution backfill Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

Verifies that limit(0) captures all EVM steps without capping, per the spec contract that 0 means unlimited. Without this test a regression flipping the guard from to would pass all other limit tests undetected. Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

…s positive. Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

Introduce a dedicated limitReached flag in DebugOperationTracer for step-limit handling. Stop mutating traceOpcode for limit enforcement; keep it only for opcode-filter semantics. Preserve existing behavior: no new frames after limit, while backfill path still runs correctly. Improve readability and reduce surprise/maintenance risk called out in review. Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

sagarkhandagre998 · 2026-04-30T06:19:31Z

@macfarla please take a look.

macfarla

looking pretty good, can you add a changelog entry and we can run final checks

macfarla · 2026-05-01T01:07:10Z

  @Override
  protected void capturePreExecutionState(final MessageFrame frame) {
+    if (options.limit() > 0 && stepCount >= options.limit()) {
+      limitReached = true;


yep this is better

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

sagarkhandagre998 · 2026-05-04T03:39:07Z

@macfarla We can run the final checks .

besu-eth#10173) * feat(debug): add limit param to stop trace capture after N steps Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com> --------- Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com> Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com> Signed-off-by: abhay-dev2901 <abhaytp1998@gmail.com>

sagarkhandagre998 mentioned this pull request Apr 3, 2026

debug RPC endpoints standardization #10115

Closed

sagarkhandagre998 force-pushed the issue-10115-11 branch 2 times, most recently from 83f9f4d to e8a899b Compare April 11, 2026 13:42

macfarla assigned sagarkhandagre998 Apr 21, 2026

macfarla marked this pull request as draft April 21, 2026 08:55

sagarkhandagre998 force-pushed the issue-10115-11 branch from 8e93982 to 812abc4 Compare April 21, 2026 12:12

sagarkhandagre998 marked this pull request as ready for review April 21, 2026 12:26

macfarla mentioned this pull request Apr 21, 2026

DebugOperationTracer #10115 - 10 : storage snapshot timing #10176

Merged

10 tasks

macfarla assigned macfarla and unassigned sagarkhandagre998 Apr 27, 2026

macfarla reviewed Apr 28, 2026

View reviewed changes

macfarla assigned sagarkhandagre998 and unassigned macfarla Apr 28, 2026

sagarkhandagre998 force-pushed the issue-10115-11 branch from f8f91d4 to 91d3bca Compare April 30, 2026 04:49

sagarkhandagre998 added 9 commits April 30, 2026 11:46

feat(debug): add limit param to stop trace capture after N steps

2a4a342

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

fix(debug): use dedicated stepCount for limit and fix last-frame gasR…

b384d7a

…emainingPostExecution Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

test(debug): add unit tests for limit frame capture and gasRemainingP…

cd3e31f

…ostExecution backfill Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

reject negative values at builder layer and rpc boundary

9b540f9

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

apply sptoless

a2c16b0

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

changing validation to deserialization layer

af9eccb

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

Updated assertion in DebugOperationTracerTest to avoid assuming gas i…

7b73cb8

…s positive. Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

sagarkhandagre998 force-pushed the issue-10115-11 branch from 9b7afe8 to b82efa1 Compare April 30, 2026 06:17

sagarkhandagre998 requested a review from macfarla April 30, 2026 06:17

macfarla reviewed May 1, 2026

View reviewed changes

adding changlog

96843cb

Signed-off-by: Sagar Khandagre <sagar.khandagre998@gmail.com>

sagarkhandagre998 force-pushed the issue-10115-11 branch from fc3a249 to 96843cb Compare May 1, 2026 04:05

sagarkhandagre998 requested a review from macfarla May 4, 2026 03:38

macfarla assigned macfarla and unassigned sagarkhandagre998 May 5, 2026

Merge branch 'main' into issue-10115-11

c9d045e

macfarla approved these changes May 5, 2026

View reviewed changes

macfarla merged commit a95327a into besu-eth:main May 5, 2026
34 checks passed

macfarla mentioned this pull request May 5, 2026

feat(debug): add enableReturnData param and returnData field #10172

Merged

10 tasks

Conversation

sagarkhandagre998 commented Apr 3, 2026 • edited by macfarla Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR description

Fixed Issue(s)

Thanks for sending a pull request! Have you done the following?

Locally, you can run these tests to catch failures early:

Uh oh!

sagarkhandagre998 commented Apr 4, 2026

Uh oh!

parthdagia05 commented Apr 10, 2026

Uh oh!

sagarkhandagre998 commented Apr 11, 2026

Uh oh!

macfarla commented Apr 21, 2026

Uh oh!

sagarkhandagre998 commented Apr 21, 2026

Uh oh!

sagarkhandagre998 commented Apr 21, 2026

Uh oh!

macfarla left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sagarkhandagre998 commented Apr 30, 2026

Uh oh!

macfarla left a comment

Choose a reason for hiding this comment

Uh oh!

macfarla May 1, 2026

Choose a reason for hiding this comment

Uh oh!

sagarkhandagre998 commented May 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sagarkhandagre998 commented Apr 3, 2026 •

edited by macfarla

Loading