Added replay-based support for tracing dry runs by awelc · Pull Request #27749 · MystenLabs/sui

awelc · 2026-08-19T00:53:41Z

Description

This PR adds tracing support for sui client ptb --dry-run via an additional --trace flag. It produces artifacts similar to those created by the replay tool, most importantly the artifacts needed for trace debugging.

The traced dry-run executes locally, similarly to how the replay tool executes historical transactions, but instead of a historical transaction being replayed, it's a transaction dry-ran on a full-node.

The results of full-node dry-run remain the source of truth and are reported to the user. Traced dry-run uses state fetched via GraphQL and its result may diverge from the full-node execution results. This is mitigated by comparing transaction effects between local execution and full-node execution and reporting potential discrepancies

Test plan

New unit tests have been added. All tests must pass. Also tested manually

vercel · 2026-08-19T00:53:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sui-docs	Ready	Preview	Aug 20, 2026 8:15pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
multisig-toolkit	Ignored	Preview	Aug 20, 2026 8:15pm
sui-kiosk	Ignored	Preview	Aug 20, 2026 8:15pm

tzakian

Overall liking it and much nicer than the checkpoint-pinned one!

Left some comments, but please ping on Slack with any questions or when you want me to take another pass.

tzakian · 2026-08-19T20:35:03Z

    }
+
+    /// Return the latest checkpoint sequence number indexed by the configured GraphQL endpoint.
+    pub fn latest_checkpoint_sequence_number(&self) -> Result<u64, Error> {


It seems like this generally exposes an async interface, so I'm wondering if this should be async and the call and/or somewhere else should block on the async call rather than here?

Good point. It's not super elegant and, indirectly, also makes scheduling trace execution in ptb.rs a bit awkward as well. Re-worked a few things to be more idiomatic with how all this should work with tokio

tzakian · 2026-08-19T20:50:05Z

+            );
+            ensure!(
+                !program_metadata.dev_inspect_set,
+                "--trace cannot be combined with --dev-inspect."


but..should it? what if anything prevents being able to use it with dev-inspect?

Another artifact of this being a "child" of another implementation... In this on we can indeed trace dev-inspect as well!

tzakian · 2026-08-19T20:51:21Z

+            ensure!(
+                !program_metadata.tx_digest_set,
+                "--trace cannot be combined with --tx-digest."
+            );
+            ensure!(
+                !program_metadata.serialize_unsigned_set && !program_metadata.serialize_signed_set,
+                "--trace cannot be combined with transaction serialization."
+            );


for these "--trace cannot be combined with X" type of error messages, would it be better to just say "--trace can only be combined with XYZ" instead -- that way when we add another flag or the like we don't need to worry about adding that here as well.

tzakian · 2026-08-19T20:59:38Z

    pub tx_digest_set: bool,
    pub dry_run_set: bool,
+    /// Whether best-effort local tracing was requested for the fullnode dry-run.
+    pub trace_set: bool,


IMo no need for the comment.

tzakian · 2026-08-19T21:01:08Z

            .try_remove_artifact()?;
    }
-    Ok(())
+    Ok(effects == expected_effects)


nit: I'd lift this up into an let tx_forked = ; and have the check on line 302 use that as well.

tzakian · 2026-08-19T21:11:29Z

+};
+
+// Keep this in sync with `DEV_INSPECT_GAS_COIN_VALUE` in `sui-core/src/authority.rs`.
+const SIMULATION_GAS_COIN_VALUE: u64 = 1_000_000_000_000_000_000;


..we should just use that const then? It's public and we have access to sui-core in this crate.

I did not want to pull the entire sui-core dependency to the replay tool's crate, but thinking about it more, the tool is largely used as part of Sui CLI anyway where this dependency is already pulled, and having the extra heft for the replay tool's dev builds should be OK. Changed!

tzakian · 2026-08-19T21:14:54Z

+/// For a request without gas payment, the fullnode executes with a deterministic synthetic gas
+/// coin while returning the original payment-free transaction data. Insert the same coin locally
+/// and require the resulting digest to match the effects; any other mismatch is rejected.
+fn reconstruct_fullnode_transaction(


why not have this call ensure_supported_transation? That way if this function passes than you're gtg as far as checks?

Makes sense. The way it's structured is a historical artifact from the "base" PR where it made more sense, but really does not make sense here. Fixed!

tzakian · 2026-08-19T21:16:47Z

+    })
+}
+
+fn clear_generated_artifacts(path: &Path) -> Result<()> {


Can/should this live on the artifact manager?

Makes sense! Moved!

…ruction

tzakian · 2026-08-20T19:19:51Z

    }
 }
+
+#[cfg(test)]


not entirely sure if we need these tests, but I guess it doesn't hurt to have them 🤷🏻

I'd say let's keep them as they indeed do no harm :-)

tzakian · 2026-08-20T19:21:09Z

-use sui_types::{effects::TransactionEffects, gas::GasUsageReport};
+use sui_types::{base_types::ObjectID, effects::TransactionEffects, gas::GasUsageReport};
+
+pub(crate) const BCODE_DIR: &str = "bytecode";


Ok, you moved it so it's fair game to comment on it! 🥳

Maybe rename this to a bit nicer name (looking at you BYTECODE_DIR 👀)

tzakian · 2026-08-20T19:23:41Z

 serde.workspace = true
 similar.workspace = true
 sui-config.workspace = true
+sui-core.workspace = true


oh, wow, I thought we already pulled this for replay-2 in but I was wrong!

My bad, I think in that case, revert back to what you had for the const for the dev inspect gas and remove this dep as not having a dep on sui-core is actually quite nice 🙇🏻

awelc requested a review from tzakian August 19, 2026 00:53

awelc self-assigned this Aug 19, 2026

awelc temporarily deployed to sui-typescript-aws-kms-test-env August 19, 2026 00:53 — with GitHub Actions Inactive

awelc mentioned this pull request Aug 19, 2026

Added support for tracing (local) dry-runs #27592

Closed

awelc temporarily deployed to sui-typescript-aws-kms-test-env August 19, 2026 01:00 — with GitHub Actions Inactive

Added replay-based support for tracing dry runs

20d2df6

vercel Bot deployed to Preview – sui-docs August 19, 2026 01:03 View deployment

awelc force-pushed the aw/replay-dry-run-support-add branch from 2662a7d to 20d2df6 Compare August 19, 2026 01:03

awelc temporarily deployed to sui-typescript-aws-kms-test-env August 19, 2026 01:03 — with GitHub Actions Inactive

vercel Bot deployed to Preview – sui-docs August 19, 2026 01:06 View deployment

tzakian reviewed Aug 19, 2026

View reviewed changes

awelc added 7 commits August 19, 2026 16:29

Moved generated artifact cleanup to ArtifactManager

0153b60

Reused the core simulation gas coin value

203cd01

Moved validation of transaction replay support to transaction reconst…

3b9fd54

…ruction

Reused the transaction effects comparison

4ecdc11

Removed the redundant trace flag comment

d4c404c

Reworked sync and async execution for dry-run tracing

52121ce

Added supprt for locally tracing dev-inspect

35ec8f6

awelc temporarily deployed to sui-typescript-aws-kms-test-env August 20, 2026 17:49 — with GitHub Actions Inactive

awelc requested a review from tzakian August 20, 2026 17:49

vercel Bot deployed to Preview – sui-docs August 20, 2026 17:52 View deployment

tzakian reviewed Aug 20, 2026

View reviewed changes

awelc added 2 commits August 20, 2026 12:43

Renamed the replay bytecode directory constant

85b9c8f

Removed sui-core from replay dependencies

e7fdc9e

awelc temporarily deployed to sui-typescript-aws-kms-test-env August 20, 2026 20:09 — with GitHub Actions Inactive

awelc requested a review from tzakian August 20, 2026 20:09

vercel Bot deployed to Preview – sui-docs August 20, 2026 20:12 View deployment

awelc requested a review from a team August 21, 2026 23:14

Uh oh!

Conversation

awelc commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Test plan

Uh oh!

vercel Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tzakian 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

awelc commented Aug 19, 2026 •

edited

Loading

vercel Bot commented Aug 19, 2026 •

edited

Loading