Add replay tracing and fix include for templates

Author: rory-ocl

Cargo.lock

@@ -21,3 +21,6 @@ tokio = { workspace = true, features = ["rt-multi-thread"] }
 anstyle = "1.0.10"
 clap = { version = "4.5.39", features = ["derive"] }
 env_logger = "0.11"
+
+# replay
+libloading = "0.8"

cargo-stylus/Cargo.toml

@@ -7,6 +7,9 @@ use crate::{common_args::BuildArgs, error::CargoStylusResult};
 
 #[derive(Debug, clap::Args)]
 pub struct Args {
+    #[arg(long)]
+    contract: Vec<String>,
+
     #[command(flatten)]
     build: BuildArgs,
 }
@@ -16,6 +19,14 @@ pub fn exec(args: Args) -> CargoStylusResult {
         features: args.build.features,
         ..Default::default()
     };
-    ops::build_workspace(&config)?;
+
+    if args.contract.is_empty() {
+        ops::build_workspace(&config)?;
+    } else {
+        for contract in args.contract {
+            ops::build_contract(contract, &config)?;
+        }
+    }
+
     Ok(())
 }

cargo-stylus/src/commands/build.rs

@@ -75,7 +75,7 @@ pub async fn exec(cmd: Command) -> CargoStylusResult {
         Command::GetInitcode(args) => get_initcode::exec(args),
         Command::Init(args) => init::exec(args),
         Command::New(args) => new::exec(args),
-        Command::Replay(args) => replay::exec(args),
+        Command::Replay(args) => replay::exec(args).await,
         Command::Simulate(args) => simulate::exec(args),
         Command::Trace(args) => trace::exec(args).await,
         Command::Verify(args) => verify::exec(args).await,

cargo-stylus/src/commands/mod.rs

@@ -1,11 +1,81 @@
 // Copyright 2025, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/main/licenses/COPYRIGHT.md
 
-use crate::error::CargoStylusResult;
+use std::iter;
+
+use eyre::bail;
+use stylus_tools::{
+    core::{
+        build::build_shared_library,
+        debugger::Debugger,
+        tracing::{hostios, Trace},
+    },
+    utils::color::Color,
+};
+
+use crate::{
+    common_args::{ProviderArgs, TraceArgs},
+    error::CargoStylusResult,
+};
 
 #[derive(Debug, clap::Args)]
-pub struct Args {}
+pub struct Args {
+    /// Which specific package to build during replay, if any.
+    #[arg(long)]
+    package: Option<String>,
+    /// Whether this process is the child of another.
+    ///
+    /// The parent process launches the debugger, with the same arguments plus this `--child` flag.
+    /// The child process then runs the transaction.
+    #[arg(long, hide(true))]
+    child: bool,
+
+    #[command(flatten)]
+    trace: TraceArgs,
+    #[command(flatten)]
+    provider: ProviderArgs,
+}
 
-pub fn exec(_args: Args) -> CargoStylusResult {
+pub async fn exec(args: Args) -> CargoStylusResult {
+    if args.child {
+        exec_replay_transaction(args).await?;
+    } else {
+        launch_debugger()?;
+    }
     Ok(())
 }
+
+async fn exec_replay_transaction(args: Args) -> eyre::Result<()> {
+    let provider = args.provider.build_provider().await?;
+    let trace = Trace::new(args.trace.tx, args.trace.use_native_tracer, &provider).await?;
+    let shared_library = build_shared_library(&args.trace.project, args.package, None)?;
+
+    // TODO: don't assume the contract is top-level
+    let Some(args) = trace.tx().input.input() else {
+        bail!("missing transaction input");
+    };
+    let args_len = args.len();
+
+    unsafe {
+        *hostios::FRAME.lock() = Some(trace.into_frame_reader());
+
+        type Entrypoint = unsafe extern "C" fn(usize) -> usize;
+        let lib = libloading::Library::new(shared_library)?;
+        let main: libloading::Symbol<Entrypoint> = lib.get(b"user_entrypoint")?;
+
+        match main(args_len) {
+            0 => println!("call completed successfully"),
+            1 => println!("call reverted"),
+            x => println!("call exited with unknown status code: {}", x.red()),
+        }
+    }
+    Ok(())
+}
+
+// TODO: Use "never" type when feature is stabilized rust-lang/rust#35121
+fn launch_debugger() -> eyre::Result<()> {
+    let debugger = Debugger::select()?;
+    let args = std::env::args().chain(iter::once("--child".to_string()));
+    let err = debugger.exec(args);
+    eyre::bail!("failed to exec {}: {}", debugger.program, err);
+}

cargo-stylus/src/commands/replay.rs

@@ -1,27 +1,24 @@
 // Copyright 2025, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/main/licenses/COPYRIGHT.md
 
-use alloy::primitives::TxHash;
 use stylus_tools::core::tracing::Trace;
 
-use crate::{common_args::ProviderArgs, error::CargoStylusResult};
+use crate::{
+    common_args::{ProviderArgs, TraceArgs},
+    error::CargoStylusResult,
+};
 
 #[derive(Debug, clap::Args)]
 pub struct Args {
-    /// Tx to replay.
-    #[arg(short, long)]
-    tx: TxHash,
-    /// If set, use the native tracer instead of the JavaScript one. Notice the native tracer might not be available in the node.
-    #[arg(short, long, default_value_t = false)]
-    use_native_tracer: bool,
-
+    #[command(flatten)]
+    trace: TraceArgs,
     #[command(flatten)]
     provider: ProviderArgs,
 }
 
 pub async fn exec(args: Args) -> CargoStylusResult {
     let provider = args.provider.build_provider().await?;
-    let trace = Trace::new(args.tx, args.use_native_tracer, &provider)
+    let trace = Trace::new(args.trace.tx, args.trace.use_native_tracer, &provider)
         .await
         .map_err(eyre::Error::from)?;
     println!("{}", trace.json());

cargo-stylus/src/commands/trace.rs

@@ -5,7 +5,7 @@ use std::{fs, path::PathBuf};
 
 use alloy::{
     network::EthereumWallet,
-    primitives::FixedBytes,
+    primitives::{FixedBytes, TxHash},
     providers::{Provider, ProviderBuilder, WalletProvider},
     signers::{
         local::{LocalSigner, PrivateKeySigner},
@@ -67,6 +67,19 @@ pub struct ProviderArgs {
     pub endpoint: String,
 }
 
+#[derive(Debug, clap::Args)]
+pub struct TraceArgs {
+    /// Tx to replay.
+    #[arg(short, long)]
+    pub tx: TxHash,
+    /// If set, use the native tracer instead of the JavaScript one. Notice the native tracer might not be available in the node.
+    #[arg(short, long, default_value_t = false)]
+    pub use_native_tracer: bool,
+    /// Project path.
+    #[arg(short, long, default_value = ".")]
+    pub project: PathBuf,
+}
+
 #[derive(Debug, clap::Args)]
 pub struct VerificationArgs {
     /// If specified, will not run the command in a reproducible docker container.

cargo-stylus/src/common_args.rs

@@ -10,10 +10,13 @@ license.workspace = true
 repository.workspace = true
 version.workspace = true
 
+include = ["src/templates/**"]
+
 [dependencies]
 alloy = { workspace = true, features = ["contract", "getrandom", "rpc-types", "signer-local", "sol-types"] }
 eyre.workspace = true
 hex.workspace = true
+lazy_static.workspace = true
 regex.workspace = true
 reqwest.workspace = true
 testcontainers = { workspace = true, optional = true }
@@ -44,5 +47,10 @@ wasmparser = "0.213.0"
 wasmprinter = "0.221.2"
 wat = "1.230"
 
+# replay
+function_name = "0.3"
+parking_lot = "0.12"
+sneks = "0.1"
+
 [features]
 integration-tests = ["dep:testcontainers"]

stylus-tools/Cargo.toml

@@ -19,7 +19,7 @@ use crate::{
     precompiles,
     utils::{
         bump_data_fee,
-        color::{DebugColor, GREY, LAVENDER},
+        color::{GREY, LAVENDER},
         format_data_fee,
     },
 };
@@ -81,13 +81,6 @@ pub async fn activate_contract(
         .await?
         .get_receipt()
         .await?;
-
-    info!(@grey,
-        "successfully activated contract 0x{} with tx {}",
-        hex::encode(address),
-        hex::encode(receipt.transaction_hash).debug_lavender()
-    );
-
     Ok(receipt)
 }