Tweak

Cargo.toml

@@ -22,6 +22,7 @@ members = [
     "crates/forge/",
     "crates/macros/",
     "crates/test-utils/",
+    "crates/tweak/"
 ]
 resolver = "2"
 
@@ -153,6 +154,7 @@ foundry-evm-fuzz = { path = "crates/evm/fuzz" }
 foundry-evm-traces = { path = "crates/evm/traces" }
 foundry-macros = { path = "crates/macros" }
 foundry-test-utils = { path = "crates/test-utils" }
+foundry-tweak = { path = "crates/tweak" }
 foundry-wallets = { path = "crates/wallets" }
 foundry-linking = { path = "crates/linking" }
 

README.md

@@ -4,6 +4,8 @@
 
 ![Github Actions][gha-badge] [![Telegram Chat][tg-badge]][tg-url] [![Telegram Support][tg-support-badge]][tg-support-url]
 
+### Foundry tweak is available to tweak the code of on-chain contracts, please see [TWEAK.md](./TWEAK.md)!
+
 [gha-badge]: https://img.shields.io/github/actions/workflow/status/foundry-rs/foundry/test.yml?branch=master
 [tg-badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&style=flat-square&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Ffoundry_rs
 [tg-url]: https://t.me/foundry_rs

TWEAK.md

@@ -0,0 +1,72 @@
+# Foundry with on-chain contract Tweak!
+
+**Tweak** allows users/developers to alter the code of an on-chain contract with the on-chain state untouched.
+Almost any modification is allowed, as long as the storage layout is preserved.
+
+With **Tweak**, you can:
+- Add `console.log()` in any on-chain contracts with source code available on Etherscan.
+- Change the logic of an on-chain contract (e.g., fixing bugs, conduct what-if analysis, etc.)
+
+Tweaking on-chain contracts are especially useful when:
+- inspecting the execution on-chain transactions;
+- investigating the logic of a complex contract (e.g., UniswapV3) on chain;
+- debug the interaction with on-chain contracts which produce unexpected revert errors.
+
+Here's the demo!
+[![asciicast](https://asciinema.org/a/650466.svg)](https://asciinema.org/a/650466)
+
+## Installation
+
+This project is a fork of foundry.
+The easiest way to install is to compile this project and replace the foundry toolchain originally on your machine.
+
+```
+cargo build
+```
+
+The executables are available in `target/debug` folder. 
+All the tools that you are familiar in foundry are still there.
+
+What is enhanced is the `cast` and `forge` command.
+
+## Usage 1: Clone a verified contract code from Etherscan
+
+```
+forge clone <address> <path>
+```
+
+`forge clone` is a new feature that downloads the source code of a verified contract at `<address>` from Etherscan (or other block explorers supported by foundry) and save as a foundry project in the specified `<path>`.
+
+The cloned project is fully compilable foundry project, guaranteed to generate exactly the same bytecode as the on-chain contract.
+
+## Usage 2: Tweak one on-chain contract and replay a historical transaction invoking it
+
+```
+cd path/to/cloned/contract/project
+forge replay <transaction_hash>
+```
+
+If the current working directory is a foundry project created by `forge clone`, then the command `forge replay` is available to replay a historical transaction with the on-chain contract's code tweaked by the current project.
+Note that the cloned project "knows" which contract address it should tweak.
+
+You may want to modify the code of the cloned contract (e.g., add `console.log`s) before running `forge replay`.
+
+## Usage 3: Tweak multiple on-chain contracts and replay a historical transaction invoking them
+
+```
+cast run --tweak <path/to/cloned/project1> --tweak <path/to/cloned/project2> <transaction_hash>
+```
+
+`cast run` is also enhanced by allowing specified cloned projects to tweak the code of multiple on-chain contracts. 
+Note that each cloned project "knows" which contract address it should tweak.
+
+## Disclaimer
+
+The **Tweak** feature is still under active development as part of the __EtherDebug__ project, whose ultimate goal is improve the overall development and debugging experience of EVM-compatibla smart contracts.
+
+The functionality is not stable yet and may suffer from breaking change in the future.
+Any contribution (bug reports, PRs, documentation, etc.) is welcome and greatly appreciated.
+
+## Acknowledgement
+
+Contributed by @Troublor and @ZhangZhuoSJTU with passion.

crates/cast/Cargo.toml

@@ -32,6 +32,7 @@ foundry-compilers.workspace = true
 foundry-config.workspace = true
 foundry-evm.workspace = true
 foundry-wallets.workspace = true
+foundry-tweak.workspace = true
 
 alloy-chains.workspace = true
 alloy-consensus = { workspace = true, features = ["serde", "kzg"] }

crates/cast/bin/cmd/run.rs

@@ -1,7 +1,9 @@
+use std::path::PathBuf;
+
 use alloy_primitives::U256;
 use alloy_provider::Provider;
 use alloy_rpc_types::BlockTransactions;
-use cast::{revm::primitives::EnvWithHandlerCfg, traces::TraceKind};
+use cast::{decode::decode_console_logs, revm::primitives::EnvWithHandlerCfg, traces::TraceKind};
 use clap::Parser;
 use eyre::{Result, WrapErr};
 use foundry_cli::{
@@ -16,6 +18,7 @@ use foundry_evm::{
     opts::EvmOpts,
     utils::configure_tx_env,
 };
+use foundry_tweak::tweak_backend;
 
 /// CLI arguments for `cast run`.
 #[derive(Clone, Debug, Parser)]
@@ -32,6 +35,7 @@ pub struct RunArgs {
     trace_printer: bool,
 
     /// Executes the transaction only with the state from the previous block.
+    /// Note that this also include transactions that are used for tweaking code.
     ///
     /// May result in different results than the live execution!
     #[arg(long, short)]
@@ -71,6 +75,13 @@ pub struct RunArgs {
     /// See also, https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second
     #[arg(long, value_name = "NO_RATE_LIMITS", visible_alias = "no-rpc-rate-limit")]
     pub no_rate_limit: bool,
+
+    /// One `forge clone`d project that will be used to tweak the code of the corresponding
+    /// on-chain contract.
+    ///
+    /// This option can be used multiple times to tweak multiple contracts.
+    #[arg(long, value_name = "CLONED_PROJECT")]
+    pub tweak: Vec<PathBuf>,
 }
 
 impl RunArgs {
@@ -80,8 +91,8 @@ impl RunArgs {
     ///
     /// Note: This executes the transaction(s) as is: Cheatcodes are disabled
     pub async fn run(self) -> Result<()> {
-        let figment =
-            Config::figment_with_root(find_project_root_path(None).unwrap()).merge(self.rpc);
+        let figment = Config::figment_with_root(find_project_root_path(None).unwrap())
+            .merge(self.rpc.clone());
         let evm_opts = figment.extract::<EvmOpts>()?;
         let mut config = Config::try_from(figment)?.sanitized();
 
@@ -143,6 +154,24 @@ impl RunArgs {
         }
 
         let mut executor = TracingExecutor::new(env.clone(), fork, evm_version, self.debug);
+        if !self.tweak.is_empty() {
+            // If user specified tweak projects, we need to tweak the code of the contracts
+            let mut cloned_projects: Vec<foundry_tweak::ClonedProject> = vec![];
+            for path in self.tweak.iter() {
+                let path = dunce::canonicalize(path)
+                    .map_err(|e| eyre::eyre!("failed to load tweak project: {:?}", e))?;
+                let project =
+                    foundry_tweak::ClonedProject::load_with_root(&path).wrap_err_with(|| {
+                        format!("failed to load tweak project from path: {:?}", &path)
+                    })?;
+                cloned_projects.push(project);
+            }
+            let tweak_map =
+                foundry_tweak::build_tweak_data(&cloned_projects, &self.rpc, self.quick).await?;
+            tweak_backend(executor.backend_mut(), &tweak_map)?;
+        }
+        println!("Executing transaction: {:?}", tx.hash);
+
         let mut env =
             EnvWithHandlerCfg::new_with_spec_id(Box::new(env.clone()), executor.spec_id());
 
@@ -158,6 +187,10 @@ impl RunArgs {
                     return Err(eyre::eyre!("Could not get block txs"))
                 };
 
+                let txs = txs.into_iter().take_while(|tx| tx.hash != tx_hash).collect::<Vec<_>>();
+                let pb = init_progress(txs.len() as u64, "tx");
+                pb.set_position(0);
+
                 for (index, tx) in txs.into_iter().enumerate() {
                     // System transactions such as on L2s don't contain any pricing info so
                     // we skip them otherwise this would cause
@@ -206,22 +239,44 @@ impl RunArgs {
         }
 
         // Execute our transaction
-        let result = {
-            executor.set_trace_printer(self.trace_printer);
-
+        let (result, console_logs) = {
             configure_tx_env(&mut env, &tx);
 
             if let Some(to) = tx.to {
                 trace!(tx=?tx.hash, to=?to, "executing call transaction");
-                TraceResult::from_raw(executor.transact_with_env(env)?, TraceKind::Execution)
+                let result = executor.transact_with_env(env)?;
+                let logs = decode_console_logs(&result.logs);
+                (TraceResult::from_raw(result, TraceKind::Execution), logs)
             } else {
                 trace!(tx=?tx.hash, "executing create transaction");
-                TraceResult::try_from(executor.deploy_with_env(env, None))?
+                let deploy_result = executor.deploy_with_env(env, None);
+                match deploy_result {
+                    Ok(res) => {
+                        let logs = decode_console_logs(&res.logs);
+                        (TraceResult::from(res), logs)
+                    }
+                    Err(ref err) => {
+                        let logs = match &err {
+                            EvmError::Execution(e) => decode_console_logs(&e.logs),
+                            _ => vec![],
+                        };
+                        (TraceResult::try_from(deploy_result)?, logs)
+                    }
+                }
             }
         };
 
         handle_traces(result, &config, chain, self.label, self.debug).await?;
 
+        // print logs if any
+        if !console_logs.is_empty() {
+            println!("Logs:");
+            for log in console_logs {
+                println!("  {log}");
+            }
+            println!();
+        }
+
         Ok(())
     }
 }

crates/evm/evm/src/executors/mod.rs

@@ -136,6 +136,11 @@ impl Executor {
         &self.env.env
     }
 
+    /// Returns a reference to the EVM environment with the handler configuration.
+    pub fn env_with_handler_cfg(&self) -> &EnvWithHandlerCfg {
+        &self.env
+    }
+
     /// Returns a mutable reference to the EVM environment.
     pub fn env_mut(&mut self) -> &mut Env {
         &mut self.env.env

crates/forge/Cargo.toml

@@ -33,6 +33,7 @@ foundry-config.workspace = true
 foundry-evm.workspace = true
 foundry-wallets.workspace = true
 foundry-linking.workspace = true
+foundry-tweak.workspace = true
 
 ethers-contract-abigen = { workspace = true, features = ["providers"] }
 

crates/forge/bin/cmd/debug.rs

@@ -29,6 +29,20 @@ pub struct DebugArgs {
     #[arg(long, short, default_value = "run()", value_name = "SIGNATURE")]
     pub sig: String,
 
+    /// One `forge clone`d project that will be used to tweak the code of the corresponding
+    /// on-chain contract.
+    ///
+    /// This option can be used multiple times to tweak multiple contracts.
+    #[arg(long, value_name = "CLONED_PROJECT")]
+    pub tweak: Vec<PathBuf>,
+
+    /// When tweaking the contract, use the quick mode where we replay the creation transaction
+    /// only with the state from the previous block.
+    ///
+    /// May result in different results than the live execution!
+    #[arg(long, requires = "tweak")]
+    pub tweak_quick: bool,
+
     /// Open the script in the debugger.
     #[arg(long)]
     pub debug: bool,
@@ -50,8 +64,10 @@ impl DebugArgs {
             gas_estimate_multiplier: 130,
             opts: self.opts,
             evm_opts: self.evm_opts,
-            debug: true,
+            debug: self.debug,
             retry: RETRY_VERIFY_ON_CREATE,
+            tweak: self.tweak,
+            tweak_quick: self.tweak_quick,
             ..Default::default()
         };
         script.run_script().await

crates/forge/bin/cmd/mod.rs

@@ -57,6 +57,7 @@ pub mod inspect;
 pub mod install;
 pub mod remappings;
 pub mod remove;
+pub mod replay;
 pub mod selectors;
 pub mod snapshot;
 pub mod soldeer;