cast/cmd/
run.rs

1use crate::{
2    revm::primitives::EnvWithHandlerCfg, utils::apply_chain_and_block_specific_env_changes,
3};
4use alloy_consensus::Transaction;
5use alloy_network::{AnyNetwork, TransactionResponse};
6use alloy_primitives::U256;
7use alloy_provider::Provider;
8use alloy_rpc_types::BlockTransactions;
9use clap::Parser;
10use eyre::{Result, WrapErr};
11use foundry_cli::{
12    opts::{EtherscanOpts, RpcOpts},
13    utils::{handle_traces, init_progress, TraceResult},
14};
15use foundry_common::{is_known_system_sender, shell, SYSTEM_TRANSACTION_TYPE};
16use foundry_compilers::artifacts::EvmVersion;
17use foundry_config::{
18    figment::{
19        self,
20        value::{Dict, Map},
21        Figment, Metadata, Profile,
22    },
23    Config,
24};
25use foundry_evm::{
26    executors::{EvmError, TracingExecutor},
27    opts::EvmOpts,
28    traces::{InternalTraceMode, TraceMode},
29    utils::configure_tx_env,
30};
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.cfg.disable_block_gas_limit = self.disable_block_gas_limit;
153        env.block.number = U256::from(tx_block_number);
154
155        if let Some(block) = &block {
156            env.block.timestamp = U256::from(block.header.timestamp);
157            env.block.coinbase = block.header.beneficiary;
158            env.block.difficulty = block.header.difficulty;
159            env.block.prevrandao = Some(block.header.mix_hash.unwrap_or_default());
160            env.block.basefee = U256::from(block.header.base_fee_per_gas.unwrap_or_default());
161            env.block.gas_limit = U256::from(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>(&mut env, 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 =
191            EnvWithHandlerCfg::new_with_spec_id(Box::new(env.clone()), executor.spec_id());
192
193        // Set the state to the moment right before the transaction
194        if !self.quick {
195            if !shell::is_json() {
196                sh_println!("Executing previous transactions from the block.")?;
197            }
198
199            if let Some(block) = block {
200                let pb = init_progress(block.transactions.len() as u64, "tx");
201                pb.set_position(0);
202
203                let BlockTransactions::Full(ref txs) = block.transactions else {
204                    return Err(eyre::eyre!("Could not get block txs"))
205                };
206
207                for (index, tx) in txs.iter().enumerate() {
208                    // System transactions such as on L2s don't contain any pricing info so
209                    // we skip them otherwise this would cause
210                    // reverts
211                    if is_known_system_sender(tx.from()) ||
212                        tx.transaction_type() == Some(SYSTEM_TRANSACTION_TYPE)
213                    {
214                        pb.set_position((index + 1) as u64);
215                        continue;
216                    }
217                    if tx.tx_hash() == tx_hash {
218                        break;
219                    }
220
221                    configure_tx_env(&mut env, &tx.inner);
222
223                    if let Some(to) = Transaction::to(tx) {
224                        trace!(tx=?tx.tx_hash(),?to, "executing previous call transaction");
225                        executor.transact_with_env(env.clone()).wrap_err_with(|| {
226                            format!(
227                                "Failed to execute transaction: {:?} in block {}",
228                                tx.tx_hash(),
229                                env.block.number
230                            )
231                        })?;
232                    } else {
233                        trace!(tx=?tx.tx_hash(), "executing previous create transaction");
234                        if let Err(error) = executor.deploy_with_env(env.clone(), None) {
235                            match error {
236                                // Reverted transactions should be skipped
237                                EvmError::Execution(_) => (),
238                                error => {
239                                    return Err(error).wrap_err_with(|| {
240                                        format!(
241                                            "Failed to deploy transaction: {:?} in block {}",
242                                            tx.tx_hash(),
243                                            env.block.number
244                                        )
245                                    })
246                                }
247                            }
248                        }
249                    }
250
251                    pb.set_position((index + 1) as u64);
252                }
253            }
254        }
255
256        // Execute our transaction
257        let result = {
258            executor.set_trace_printer(self.trace_printer);
259
260            configure_tx_env(&mut env, &tx.inner);
261
262            if let Some(to) = Transaction::to(&tx) {
263                trace!(tx=?tx.tx_hash(), to=?to, "executing call transaction");
264                TraceResult::try_from(executor.transact_with_env(env))?
265            } else {
266                trace!(tx=?tx.tx_hash(), "executing create transaction");
267                TraceResult::try_from(executor.deploy_with_env(env, None))?
268            }
269        };
270
271        handle_traces(
272            result,
273            &config,
274            chain,
275            self.label,
276            self.with_local_artifacts,
277            self.debug,
278            self.decode_internal,
279        )
280        .await?;
281
282        Ok(())
283    }
284}
285
286impl figment::Provider for RunArgs {
287    fn metadata(&self) -> Metadata {
288        Metadata::named("RunArgs")
289    }
290
291    fn data(&self) -> Result<Map<Profile, Dict>, figment::Error> {
292        let mut map = Map::new();
293
294        if self.odyssey {
295            map.insert("odyssey".into(), self.odyssey.into());
296        }
297
298        if let Some(api_key) = &self.etherscan.key {
299            map.insert("etherscan_api_key".into(), api_key.as_str().into());
300        }
301
302        if let Some(evm_version) = self.evm_version {
303            map.insert("evm_version".into(), figment::value::Value::serialize(evm_version)?);
304        }
305
306        Ok(Map::from([(Config::selected_profile(), map)]))
307    }
308}