cast/cmd/
run.rs

1use alloy_consensus::Transaction;
2use alloy_network::{AnyNetwork, TransactionResponse};
3use alloy_provider::Provider;
4use alloy_rpc_types::BlockTransactions;
5use clap::Parser;
6use eyre::{Result, WrapErr};
7use foundry_cli::{
8    opts::{EtherscanOpts, RpcOpts},
9    utils::{handle_traces, init_progress, TraceResult},
10};
11use foundry_common::{is_known_system_sender, shell, SYSTEM_TRANSACTION_TYPE};
12use foundry_compilers::artifacts::EvmVersion;
13use foundry_config::{
14    figment::{
15        self,
16        value::{Dict, Map},
17        Figment, Metadata, Profile,
18    },
19    Config,
20};
21use foundry_evm::{
22    executors::{EvmError, TracingExecutor},
23    opts::EvmOpts,
24    traces::{InternalTraceMode, TraceMode},
25    utils::configure_tx_env,
26    Env,
27};
28use foundry_evm_core::env::AsEnvMut;
29
30use crate::utils::apply_chain_and_block_specific_env_changes;
31
32/// CLI arguments for `cast run`.
33#[derive(Clone, Debug, Parser)]
34pub struct RunArgs {
35    /// The transaction hash.
36    tx_hash: String,
37
38    /// Opens the transaction in the debugger.
39    #[arg(long, short)]
40    debug: bool,
41
42    /// Whether to identify internal functions in traces.
43    #[arg(long)]
44    decode_internal: bool,
45
46    /// Print out opcode traces.
47    #[arg(long, short)]
48    trace_printer: bool,
49
50    /// Executes the transaction only with the state from the previous block.
51    ///
52    /// May result in different results than the live execution!
53    #[arg(long)]
54    quick: bool,
55
56    /// Label addresses in the trace.
57    ///
58    /// Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045:vitalik.eth
59    #[arg(long, short)]
60    label: Vec<String>,
61
62    #[command(flatten)]
63    etherscan: EtherscanOpts,
64
65    #[command(flatten)]
66    rpc: RpcOpts,
67
68    /// The EVM version to use.
69    ///
70    /// Overrides the version specified in the config.
71    #[arg(long)]
72    evm_version: Option<EvmVersion>,
73
74    /// Sets the number of assumed available compute units per second for this provider
75    ///
76    /// default value: 330
77    ///
78    /// See also, <https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second>
79    #[arg(long, alias = "cups", value_name = "CUPS")]
80    pub compute_units_per_second: Option<u64>,
81
82    /// Disables rate limiting for this node's provider.
83    ///
84    /// default value: false
85    ///
86    /// See also, <https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second>
87    #[arg(long, value_name = "NO_RATE_LIMITS", visible_alias = "no-rpc-rate-limit")]
88    pub no_rate_limit: bool,
89
90    /// Enables Odyssey features.
91    #[arg(long, alias = "alphanet")]
92    pub odyssey: bool,
93
94    /// Use current project artifacts for trace decoding.
95    #[arg(long, visible_alias = "la")]
96    pub with_local_artifacts: bool,
97
98    /// Disable block gas limit check.
99    #[arg(long)]
100    pub disable_block_gas_limit: bool,
101}
102
103impl RunArgs {
104    /// Executes the transaction by replaying it
105    ///
106    /// This replays the entire block the transaction was mined in unless `quick` is set to true
107    ///
108    /// Note: This executes the transaction(s) as is: Cheatcodes are disabled
109    pub async fn run(self) -> Result<()> {
110        let figment = Into::<Figment>::into(&self.rpc).merge(&self);
111        let evm_opts = figment.extract::<EvmOpts>()?;
112        let mut config = Config::from_provider(figment)?.sanitized();
113
114        let compute_units_per_second =
115            if self.no_rate_limit { Some(u64::MAX) } else { self.compute_units_per_second };
116
117        let provider = foundry_cli::utils::get_provider_builder(&config)?
118            .compute_units_per_second_opt(compute_units_per_second)
119            .build()?;
120
121        let tx_hash = self.tx_hash.parse().wrap_err("invalid tx hash")?;
122        let tx = provider
123            .get_transaction_by_hash(tx_hash)
124            .await
125            .wrap_err_with(|| format!("tx not found: {tx_hash:?}"))?
126            .ok_or_else(|| eyre::eyre!("tx not found: {:?}", tx_hash))?;
127
128        // check if the tx is a system transaction
129        if is_known_system_sender(tx.from()) ||
130            tx.transaction_type() == Some(SYSTEM_TRANSACTION_TYPE)
131        {
132            return Err(eyre::eyre!(
133                "{:?} is a system transaction.\nReplaying system transactions is currently not supported.",
134                tx.tx_hash()
135            ));
136        }
137
138        let tx_block_number =
139            tx.block_number.ok_or_else(|| eyre::eyre!("tx may still be pending: {:?}", tx_hash))?;
140
141        // fetch the block the transaction was mined in
142        let block = provider.get_block(tx_block_number.into()).full().await?;
143
144        // we need to fork off the parent block
145        config.fork_block_number = Some(tx_block_number - 1);
146
147        let create2_deployer = evm_opts.create2_deployer;
148        let (mut env, fork, chain, odyssey) =
149            TracingExecutor::get_fork_material(&config, evm_opts).await?;
150        let mut evm_version = self.evm_version;
151
152        env.evm_env.cfg_env.disable_block_gas_limit = self.disable_block_gas_limit;
153        env.evm_env.block_env.number = tx_block_number;
154
155        if let Some(block) = &block {
156            env.evm_env.block_env.timestamp = block.header.timestamp;
157            env.evm_env.block_env.beneficiary = block.header.beneficiary;
158            env.evm_env.block_env.difficulty = block.header.difficulty;
159            env.evm_env.block_env.prevrandao = Some(block.header.mix_hash.unwrap_or_default());
160            env.evm_env.block_env.basefee = block.header.base_fee_per_gas.unwrap_or_default();
161            env.evm_env.block_env.gas_limit = block.header.gas_limit;
162
163            // TODO: we need a smarter way to map the block to the corresponding evm_version for
164            // commonly used chains
165            if evm_version.is_none() {
166                // if the block has the excess_blob_gas field, we assume it's a Cancun block
167                if block.header.excess_blob_gas.is_some() {
168                    evm_version = Some(EvmVersion::Cancun);
169                }
170            }
171            apply_chain_and_block_specific_env_changes::<AnyNetwork>(env.as_env_mut(), block);
172        }
173
174        let trace_mode = TraceMode::Call
175            .with_debug(self.debug)
176            .with_decode_internal(if self.decode_internal {
177                InternalTraceMode::Full
178            } else {
179                InternalTraceMode::None
180            })
181            .with_state_changes(shell::verbosity() > 4);
182        let mut executor = TracingExecutor::new(
183            env.clone(),
184            fork,
185            evm_version,
186            trace_mode,
187            odyssey,
188            create2_deployer,
189        )?;
190        let mut env = Env::new_with_spec_id(
191            env.evm_env.cfg_env.clone(),
192            env.evm_env.block_env.clone(),
193            env.tx.clone(),
194            executor.spec_id(),
195        );
196
197        // Set the state to the moment right before the transaction
198        if !self.quick {
199            if !shell::is_json() {
200                sh_println!("Executing previous transactions from the block.")?;
201            }
202
203            if let Some(block) = block {
204                let pb = init_progress(block.transactions.len() as u64, "tx");
205                pb.set_position(0);
206
207                let BlockTransactions::Full(ref txs) = block.transactions else {
208                    return Err(eyre::eyre!("Could not get block txs"))
209                };
210
211                for (index, tx) in txs.iter().enumerate() {
212                    // System transactions such as on L2s don't contain any pricing info so
213                    // we skip them otherwise this would cause
214                    // reverts
215                    if is_known_system_sender(tx.from()) ||
216                        tx.transaction_type() == Some(SYSTEM_TRANSACTION_TYPE)
217                    {
218                        pb.set_position((index + 1) as u64);
219                        continue;
220                    }
221                    if tx.tx_hash() == tx_hash {
222                        break;
223                    }
224
225                    configure_tx_env(&mut env.as_env_mut(), &tx.inner);
226
227                    if let Some(to) = Transaction::to(tx) {
228                        trace!(tx=?tx.tx_hash(),?to, "executing previous call transaction");
229                        executor.transact_with_env(env.clone()).wrap_err_with(|| {
230                            format!(
231                                "Failed to execute transaction: {:?} in block {}",
232                                tx.tx_hash(),
233                                env.evm_env.block_env.number
234                            )
235                        })?;
236                    } else {
237                        trace!(tx=?tx.tx_hash(), "executing previous create transaction");
238                        if let Err(error) = executor.deploy_with_env(env.clone(), None) {
239                            match error {
240                                // Reverted transactions should be skipped
241                                EvmError::Execution(_) => (),
242                                error => {
243                                    return Err(error).wrap_err_with(|| {
244                                        format!(
245                                            "Failed to deploy transaction: {:?} in block {}",
246                                            tx.tx_hash(),
247                                            env.evm_env.block_env.number
248                                        )
249                                    })
250                                }
251                            }
252                        }
253                    }
254
255                    pb.set_position((index + 1) as u64);
256                }
257            }
258        }
259
260        // Execute our transaction
261        let result = {
262            executor.set_trace_printer(self.trace_printer);
263
264            configure_tx_env(&mut env.as_env_mut(), &tx.inner);
265
266            if let Some(to) = Transaction::to(&tx) {
267                trace!(tx=?tx.tx_hash(), to=?to, "executing call transaction");
268                TraceResult::try_from(executor.transact_with_env(env))?
269            } else {
270                trace!(tx=?tx.tx_hash(), "executing create transaction");
271                TraceResult::try_from(executor.deploy_with_env(env, None))?
272            }
273        };
274
275        handle_traces(
276            result,
277            &config,
278            chain,
279            self.label,
280            self.with_local_artifacts,
281            self.debug,
282            self.decode_internal,
283        )
284        .await?;
285
286        Ok(())
287    }
288}
289
290impl figment::Provider for RunArgs {
291    fn metadata(&self) -> Metadata {
292        Metadata::named("RunArgs")
293    }
294
295    fn data(&self) -> Result<Map<Profile, Dict>, figment::Error> {
296        let mut map = Map::new();
297
298        if self.odyssey {
299            map.insert("odyssey".into(), self.odyssey.into());
300        }
301
302        if let Some(api_key) = &self.etherscan.key {
303            map.insert("etherscan_api_key".into(), api_key.as_str().into());
304        }
305
306        if let Some(api_version) = &self.etherscan.api_version {
307            map.insert("etherscan_api_version".into(), api_version.to_string().into());
308        }
309
310        if let Some(evm_version) = self.evm_version {
311            map.insert("evm_version".into(), figment::value::Value::serialize(evm_version)?);
312        }
313
314        Ok(Map::from([(Config::selected_profile(), map)]))
315    }
316}