Skip to content

Extend Wasm execution tracing to host calls, storage, objects, and contract calls#121

Merged
bbyalcinkaya merged 17 commits into
masterfrom
trace-soroban-vm
Jul 8, 2026
Merged

Extend Wasm execution tracing to host calls, storage, objects, and contract calls#121
bbyalcinkaya merged 17 commits into
masterfrom
trace-soroban-vm

Conversation

@bbyalcinkaya

Copy link
Copy Markdown
Member

This PR extends the existing instruction-level execution tracing (tracing.md) to cover the higher-level events: host function calls, storage reads/writes, host object allocation, and the start and end of every contract call, including a snapshot of the callee's storage before it runs.

Added traces

  • Host calls (traceHostCall): every host function invocation logs its module/function name and the current locals. hostCall was changed from Instr to HelperInstr so it's no longer picked up by the generic per-instruction tracer, and is logged once via this dedicated hook instead.
  • Storage (trace-putContractData/trace-delContractData): logs the contract, storage type (instance, persistent, or temporary), and key/value for every storage write and delete.
  • Host objects (trace-addObject): logs the ScVal value and the index a new host object is about to be created.
  • Contract calls (trace-callContract / trace-endWasm / trace-endWasm-error) — new in this PR:
    • trace-callContract logs the start of every contract call: caller, callee, function name, arguments (List of ScVal), call depth, and the callee's full storage (instance + persistent/temporary, each tagged with its durability) as it stands before the call runs.
    • trace-endWasm / trace-endWasm-error log the end of every contract call: success/failure, call depth, and the resolved return value or Error.
    • Both cover the outermost invocation (e.g. via callTx) as well as every nested call/try_call sub-call, since all contract calls funnel through callContract/#endWasm regardless of how they were initiated.

Design notes

  • trace-callContract/trace-endWasm/trace-endWasm-error duplicate the state transition of their corresponding base rules in soroban.md/switch.md (rather than appending #resetAlreadyTraced and requeuing).
  • The now-redundant <logging> cell was removed; its only use (logging callContract invocations) is superseded by trace-callContract.
  • Added doc comments to callContract/callContractAux/mkCall in soroban.md explaining the three-command call-setup handoff, since tracing now duplicates part of it.

Testing

Added three tracing-specific tests to src/tests/integration/test_integration.py that run .wast fixtures with tracing and assert on the resulting JSON records:

  • test_tracing_call_contract_and_end_wasm — checks callContract/endWasm are each logged once per call, depths agree between a call's start/end and increase for the nested call, and args/result resolve correctly (call_add.wast).
  • test_tracing_end_wasm_error — checks a panicking call's endWasm is logged as a failure with the trap's Error, and that tracing continues correctly afterward (increment_panic.wast).
  • test_tracing_call_contract_storage — checks each callContract's storage snapshot reflects the previous call's writes, and that the individual trace-putContractData/trace-delContractData writes are logged in order (put, del, put) with the right contract, durability, and args (storage.wast).

@bbyalcinkaya bbyalcinkaya force-pushed the trace-soroban-vm branch 2 times, most recently from edb171c to 721ab6c Compare July 3, 2026 13:48
@bbyalcinkaya bbyalcinkaya marked this pull request as ready for review July 3, 2026 19:43
@RaoulSchaffranek

Copy link
Copy Markdown
Member

LGTM. Let's just make sure that the JSON format for host interactions is properly documented, an example trace would be highly beneficial.

@bbyalcinkaya bbyalcinkaya merged commit 089b3aa into master Jul 8, 2026
5 of 6 checks passed
@bbyalcinkaya bbyalcinkaya deleted the trace-soroban-vm branch July 8, 2026 12:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants