feat: enable DAP-backed transaction script debugging

CHANGELOG.md

@@ -35,6 +35,8 @@
 
 ### Enhancements
 
+* Added DAP-backed transaction script debugging support with `--start-debug-adapter` flag on the `exec` CLI command, `execute_program_with_dap` client method, and offline bootstrap mode for node-less execution ([#1959](https://github.com/0xMiden/miden-client/pull/1959)).
+
 * Made `GrpcNoteTransportClient` connection lazy, deferring it to the first RPC call instead of connecting eagerly at client initialization ([#1970](https://github.com/0xMiden/miden-client/pull/1970)).
 * Updated the `GrpcClient` to fetch the RPC limits from the node ([#1724](https://github.com/0xMiden/miden-client/pull/1724)) ([#1737](https://github.com/0xMiden/miden-client/pull/1737), [#1809](https://github.com/0xMiden/miden-client/pull/1809)).
 * Added typed error parsing for node RPC endpoints, enabling programmatic error handling instead of string parsing ([#1734](https://github.com/0xMiden/miden-client/pull/1734)).

Cargo.toml

@@ -55,6 +55,9 @@ miden-node-validator             = { version = "0.14" }
 miden-note-transport-proto-build = { default-features = false, version = "0.2" }
 miden-remote-prover-client       = { default-features = false, features = ["tx-prover"], version = "0.14" }
 
+# Miden debug dependency
+miden-debug = { default-features = false, features = ["dap", "std"], version = "0.6" }
+
 # External dependencies
 anyhow      = { default-features = false, version = "1.0" }
 async-trait = { version = "0.1" }

bin/miden-cli/Cargo.toml

@@ -16,10 +16,16 @@ version.workspace      = true
 name = "miden-client"
 path = "src/main.rs"
 
+[features]
+dap     = ["dep:miden-debug", "miden-client/dap"]
+default = ["dap"]
+testing = ["miden-client/testing"]
+
 [dependencies]
 # Workspace dependencies
 miden-client              = { features = ["tonic"], workspace = true }
 miden-client-sqlite-store = { workspace = true }
+miden-debug               = { optional = true, workspace = true }
 
 # External dependencies
 clap               = { features = ["derive"], version = "4.5" }

bin/miden-cli/src/commands/exec.rs

@@ -1,8 +1,13 @@
 use std::collections::BTreeMap;
+use std::fs;
+#[cfg(feature = "dap")]
+use std::net::SocketAddr;
 use std::path::PathBuf;
 
 use clap::Parser;
+use miden_client::account::AccountId;
 use miden_client::keystore::Keystore;
+use miden_client::transaction::{ForeignAccount, TransactionScript};
 use miden_client::vm::AdviceInputs;
 use miden_client::{Client, Felt, Word};
 use serde::{Deserialize, Deserializer, Serialize, de};
@@ -47,6 +52,12 @@ pub struct ExecCmd {
     /// Print the output stack grouped into words
     #[arg(long, default_value_t = false)]
     hex_words: bool,
+
+    /// Start a DAP debug adapter server on the given address (e.g. "127.0.0.1:4711")
+    /// and wait for a DAP client to connect before executing.
+    #[cfg(feature = "dap")]
+    #[arg(long = "start-debug-adapter")]
+    start_debug_adapter: Option<SocketAddr>,
 }
 
 impl ExecCmd {
@@ -62,7 +73,7 @@ impl ExecCmd {
             ));
         }
 
-        let program = std::fs::read_to_string(script_path)?;
+        let program = fs::read_to_string(script_path)?;
 
         let account_id =
             get_input_acc_id_by_prefix_or_default(&client, self.account_id.clone()).await?;
@@ -77,7 +88,7 @@ impl ExecCmd {
                     ));
                 }
 
-                let input_data = std::fs::read_to_string(input_file)?;
+                let input_data = fs::read_to_string(input_file)?;
                 deserialize_tx_inputs(&input_data)?
             },
             None => vec![],
@@ -87,19 +98,13 @@ impl ExecCmd {
 
         let tx_script = client.code_builder().compile_tx_script(&program)?;
 
-        let result = client
-            .execute_program(account_id, tx_script, advice_inputs, BTreeMap::new())
-            .await;
+        let output_stack =
+            self.execute_program(&mut client, account_id, tx_script, advice_inputs).await?;
 
-        match result {
-            Ok(output_stack) => {
-                println!("Program executed successfully");
-                println!("Output stack:");
-                self.print_stack(output_stack);
-                Ok(())
-            },
-            Err(err) => Err(CliError::Exec(err.into(), "error executing the program".to_string())),
-        }
+        println!("Program executed successfully");
+        println!("Output stack:");
+        self.print_stack(output_stack);
+        Ok(())
     }
 
     /// Print the output stack in a human-readable format
@@ -130,6 +135,53 @@ impl ExecCmd {
             }
         }
     }
+
+    async fn execute_program<AUTH: Keystore + Sync + 'static>(
+        &self,
+        client: &mut Client<AUTH>,
+        account_id: AccountId,
+        tx_script: TransactionScript,
+        advice_inputs: AdviceInputs,
+    ) -> Result<[Felt; 16], CliError> {
+        let foreign_accounts = BTreeMap::<AccountId, ForeignAccount>::new();
+
+        #[cfg(feature = "dap")]
+        if let Some(addr) = self.start_debug_adapter.as_ref() {
+            let config = miden_debug::DapConfig::new(addr.to_string());
+            let config_handle = config.clone();
+            miden_debug::DapConfig::set_global(config);
+
+            let script_path = PathBuf::from(&self.script_path);
+            loop {
+                let program = fs::read_to_string(&script_path)?;
+                let tx_script = client.code_builder().compile_tx_script(&program)?;
+
+                let result = client
+                    .execute_program_with_dap(
+                        account_id,
+                        tx_script,
+                        advice_inputs.clone(),
+                        foreign_accounts.clone(),
+                    )
+                    .await;
+
+                if config_handle.restart_requested() {
+                    config_handle.reset_restart();
+                    println!("Recompiling from source and restarting debug session...");
+                    continue;
+                }
+
+                return result.map_err(|err| {
+                    CliError::Exec(err.into(), "error executing the program".to_string())
+                });
+            }
+        }
+
+        client
+            .execute_program(account_id, tx_script, advice_inputs, foreign_accounts)
+            .await
+            .map_err(|err| CliError::Exec(err.into(), "error executing the program".to_string()))
+    }
 }
 
 // INPUT FILE PROCESSING

bin/miden-cli/src/commands/new_account.rs

@@ -98,6 +98,14 @@ pub struct NewWalletCmd {
     /// authentication transaction.
     #[arg(long, default_value_t = false)]
     pub deploy: bool,
+    /// Seed local-only state so the wallet can be created and used for execution without a node.
+    /// Only available when built with the `testing` feature.
+    #[cfg_attr(
+        feature = "testing",
+        arg(long, default_value_t = false, conflicts_with = "deploy")
+    )]
+    #[cfg_attr(not(feature = "testing"), arg(skip = false))]
+    pub offline: bool,
 }
 
 impl NewWalletCmd {
@@ -126,6 +134,7 @@ impl NewWalletCmd {
             &package_paths,
             self.init_storage_data_path.clone(),
             self.deploy,
+            self.offline,
         )
         .await?;
 
@@ -193,6 +202,14 @@ pub struct NewAccountCmd {
     /// authentication transaction.
     #[arg(long, default_value_t = false)]
     pub deploy: bool,
+    /// Seed local-only state so the account can be created and used for execution without a node.
+    /// Only available when built with the `testing` feature.
+    #[cfg_attr(
+        feature = "testing",
+        arg(long, default_value_t = false, conflicts_with = "deploy")
+    )]
+    #[cfg_attr(not(feature = "testing"), arg(skip = false))]
+    pub offline: bool,
 }
 
 impl NewAccountCmd {
@@ -209,6 +226,7 @@ impl NewAccountCmd {
             &self.packages,
             self.init_storage_data_path.clone(),
             self.deploy,
+            self.offline,
         )
         .await?;
 
@@ -385,6 +403,7 @@ async fn create_client_account<AUTH: Keystore + Sync + 'static>(
     package_paths: &[PathBuf],
     init_storage_data_path: Option<PathBuf>,
     deploy: bool,
+    offline: bool,
 ) -> Result<Account, CliError> {
     if package_paths.is_empty() {
         return Err(CliError::InvalidArgument(format!(
@@ -455,6 +474,14 @@ async fn create_client_account<AUTH: Keystore + Sync + 'static>(
         println!("Using custom authentication component from package (no key generated).");
     }
 
+    let _ = offline;
+
+    #[cfg(feature = "testing")]
+    if offline {
+        client.prepare_offline_bootstrap().await?;
+        println!("Offline mode seeded default RPC limits and a synthetic genesis header.");
+    }
+
     client.add_account(&account, false).await?;
 
     if deploy {

crates/rust-client/Cargo.toml

@@ -24,7 +24,8 @@ ignored = ["getrandom", "prost-types", "tonic-prost"]
 crate-type = ["lib"]
 
 [features]
-default = ["std"]
+dap = ["dep:miden-debug"]
+default = ["dap", "std"]
 std = [
   "dep:tempfile",
   "dep:tokio",
@@ -41,6 +42,7 @@ tonic = []
 
 [dependencies]
 # Miden dependencies
+miden-debug                = { optional = true, workspace = true }
 miden-protocol             = { workspace = true }
 miden-remote-prover-client = { default-features = false, features = ["tx-prover"], workspace = true }
 miden-standards            = { workspace = true }