Skip to main content

forge_script/
lib.rs

1//! # foundry-script
2//!
3//! Smart contract scripting.
4
5#![recursion_limit = "256"]
6#![cfg_attr(not(test), warn(unused_crate_dependencies))]
7#![cfg_attr(docsrs, feature(doc_cfg))]
8
9#[macro_use]
10extern crate foundry_common;
11
12#[macro_use]
13extern crate tracing;
14
15use crate::{broadcast::BundledState, runner::ScriptRunner, simulate::PreSimulationState};
16use alloy_eips::BlockId;
17use alloy_json_abi::{Function, JsonAbi};
18use alloy_network::{Network, TransactionBuilder};
19use alloy_primitives::{
20    Address, B256, Bytes, Log, U256, hex,
21    map::{AddressHashMap, HashMap},
22};
23use alloy_signer::Signer;
24use build::PreprocessedState;
25use clap::{Parser, ValueHint, builder::RangedU64ValueParser};
26use dialoguer::Confirm;
27use evm2::{EvmFeatures, interpreter::InstrStop};
28use eyre::{ContextCompat, Result, WrapErr};
29use forge_script_sequence::{AdditionalContract, NestedValue};
30use forge_verify::{RetryArgs, VerifierArgs};
31use foundry_cli::{
32    opts::{BuildOpts, EvmArgs, GlobalArgs, TempoOpts, TracingArgs},
33    utils::LoadConfig,
34};
35use foundry_common::{
36    ContractsByArtifact, FoundryTransactionBuilder, SELECTOR_LEN,
37    abi::{encode_function_args, get_func},
38    compile::ContractSizeLimits,
39    provider::ProviderBuilder,
40    shell,
41    tempo::configurable_account::{detect_configurable_account, linked_account},
42};
43use foundry_compilers::{ArtifactId, artifacts::output_selection::ContractOutputSelection};
44use foundry_config::{
45    Config, Eip1559FeeEstimatePreset, FoundryHardfork, figment,
46    figment::{
47        Metadata, Profile, Provider,
48        value::{Dict, Map},
49    },
50};
51use foundry_debugger::ensure_dump_dir;
52use foundry_evm::{
53    backend::Backend,
54    core::{
55        Breakpoints,
56        evm::{
57            EthEvmNetwork, EvmEnvFor, EvmFactoryFor, FoundryEvmNetwork, SpecFor, TempoEvmNetwork,
58            TransactionRequestFor,
59        },
60    },
61    executors::ExecutorBuilder,
62    hardforks::ExecutionSpec,
63    inspectors::{
64        CheatsConfig,
65        cheatcodes::{BroadcastableTransactions, Wallets},
66    },
67    opts::{EvmOpts, ExecutionSpecContext, ForkContext, resolve_execution_spec},
68    traces::{InternalTraceMode, TraceRequirements, Traces},
69};
70use foundry_evm_networks::{NetworkConfigs, NetworkVariant};
71use foundry_wallets::{MultiWalletOpts, utils::maybe_get_keystore_path, wallet_multi::MultiWallet};
72use serde::Serialize;
73use std::path::PathBuf;
74use tempo_alloy::TempoNetwork;
75
76#[cfg(feature = "base")]
77use foundry_evm::core::evm::BaseEvmNetwork;
78
79#[cfg(feature = "monad")]
80use foundry_evm::core::evm::MonadEvmNetwork;
81
82#[cfg(feature = "optimism")]
83use foundry_evm::core::evm::OpEvmNetwork;
84
85mod broadcast;
86mod build;
87mod execute;
88mod library_deployments;
89mod multi_sequence;
90mod owner_approvals;
91mod progress;
92mod providers;
93mod receipts;
94mod recovery;
95mod runner;
96mod sequence;
97mod session;
98mod simulate;
99mod transaction;
100mod verify;
101mod wallet_session;
102
103pub use wallet_session::ScriptWalletSessionArgs;
104
105// Loads project's figment and merges the build cli arguments into it
106foundry_config::merge_impl_figment_convert!(ScriptArgs, build, evm);
107
108const DEFAULT_CONFIRMATIONS: u64 = 1;
109
110/// Shared preparation stops before execution-family-specific on-chain simulation.
111enum PreparedScript<FEN: FoundryEvmNetwork> {
112    Resume(Box<BundledState<FEN>>),
113    Simulate(Box<PreSimulationState<FEN>>),
114}
115
116/// CLI arguments for `forge script`.
117#[derive(Clone, Debug, Default, Parser)]
118pub struct ScriptArgs {
119    // Include global options for users of this struct.
120    #[command(flatten)]
121    pub global: GlobalArgs,
122
123    /// The contract you want to run. Either the file path or contract name.
124    ///
125    /// If multiple contracts exist in the same file you must specify the target contract with
126    /// --target-contract.
127    #[arg(value_hint = ValueHint::FilePath)]
128    pub path: String,
129
130    /// Arguments to pass to the script function.
131    pub args: Vec<String>,
132
133    /// The name of the contract you want to run.
134    #[arg(long, visible_alias = "tc", value_name = "CONTRACT_NAME")]
135    pub target_contract: Option<String>,
136
137    /// The signature of the function you want to call in the contract, or raw calldata.
138    #[arg(long, short, default_value = "run")]
139    pub sig: String,
140
141    /// Max priority fee per gas for EIP1559 transactions.
142    #[arg(
143        long,
144        env = "ETH_PRIORITY_GAS_PRICE",
145        value_parser = foundry_cli::utils::parse_ether_value,
146        value_name = "PRICE"
147    )]
148    pub priority_gas_price: Option<U256>,
149
150    /// Use legacy transactions instead of EIP1559 ones.
151    ///
152    /// This is auto-enabled for common networks without EIP1559.
153    #[arg(long)]
154    pub legacy: bool,
155
156    /// How to estimate EIP-1559 fees: `low`, `market` (default), or `aggressive`.
157    ///
158    /// The preset sets the priority-fee percentile and the `maxFeePerGas` buffer
159    /// (`low`: `base_fee * 1.5`, others: `* 2`); `low`'s tighter buffer is more
160    /// likely to stall if the base fee rises. `--with-gas-price` and
161    /// `--priority-gas-price` override only `maxFeePerGas` and
162    /// `maxPriorityFeePerGas` respectively. Ignored for `--legacy`.
163    #[arg(long = "estimate", value_name = "PRESET")]
164    pub eip1559_fee_estimate: Option<Eip1559FeeEstimatePreset>,
165
166    /// Broadcasts the transactions.
167    #[arg(long)]
168    pub broadcast: bool,
169
170    /// Batch all broadcast transactions into a single Tempo batch transaction.
171    ///
172    /// When enabled, all vm.broadcast() calls are collected and sent as a single
173    /// atomic type 0x76 transaction instead of individual transactions.
174    /// This provides atomicity (all-or-nothing execution) and gas savings.
175    #[arg(long)]
176    pub batch: bool,
177
178    /// Tempo transaction options.
179    #[command(flatten)]
180    pub tempo: TempoOpts,
181
182    /// Create a temporary Tempo wallet session, run this script with it, then revoke it.
183    #[command(flatten)]
184    pub wallet_session: ScriptWalletSessionArgs,
185
186    /// Skips on-chain simulation.
187    #[arg(long)]
188    pub skip_simulation: bool,
189
190    /// Relative percentage to multiply gas estimates by.
191    #[arg(long, short, default_value = "130")]
192    pub gas_estimate_multiplier: u64,
193
194    /// Override the sender's initial nonce for script execution and transaction generation.
195    #[arg(
196        long,
197        value_name = "NONCE",
198        value_parser = RangedU64ValueParser::<u64>::new().range(..u64::MAX),
199    )]
200    pub sender_nonce: Option<u64>,
201
202    /// Send via `eth_sendTransaction` using the `--sender` argument as sender.
203    #[arg(
204        long,
205        conflicts_with_all = &["private_key", "private_keys", "ledger", "trezor", "aws", "gcp", "turnkey", "browser"],
206    )]
207    pub unlocked: bool,
208
209    /// Resumes submitting transactions that failed or timed-out previously.
210    ///
211    /// It DOES NOT simulate the script again and it expects nonces to have remained the same.
212    ///
213    /// Example: If transaction N has a nonce of 22, then the account should have a nonce of 22,
214    /// otherwise it fails.
215    #[arg(long)]
216    pub resume: bool,
217
218    /// Selects the interrupted delegated submission attempt to resolve.
219    #[arg(long, requires = "resume")]
220    pub resume_attempt: Option<B256>,
221
222    /// Records a transaction hash discovered for an interrupted delegated submission.
223    #[arg(
224        long,
225        requires_all = ["resume", "resume_attempt"],
226        conflicts_with = "resume_retry"
227    )]
228    pub resume_tx_hash: Option<B256>,
229
230    /// Retries an interrupted delegated submission proven not to have been submitted.
231    #[arg(
232        long,
233        requires_all = ["resume", "resume_attempt"],
234        conflicts_with = "resume_tx_hash"
235    )]
236    pub resume_retry: bool,
237
238    /// An owner's approval of a Tempo configurable account transaction that awaits its owners.
239    ///
240    /// When the local owner keys of a configurable account sender do not reach its threshold,
241    /// `--broadcast` saves its transactions unsigned and prints the digest of each. Owners sign
242    /// the digests with `cast wallet sign --no-hash <DIGEST>` or with a passkey, and `--resume`
243    /// sends the transactions once their approvals reach the threshold. Repeat for each approval,
244    /// in any order. Takes a hex signature, a JSON signature, or a browser WebAuthn assertion, as
245    /// `cast wallet assemble` does; a value naming a file is read from it.
246    #[arg(
247        long = "tempo.owner-signature",
248        value_name = "SIGNATURE",
249        requires = "resume",
250        conflicts_with = "batch"
251    )]
252    pub tempo_owner_signatures: Vec<String>,
253
254    /// Archives an unfinished previous broadcast of this script and broadcasts it anew.
255    ///
256    /// Without this flag, `--broadcast` refuses to replace a previous broadcast whose operations
257    /// have not all mined or reverted. Finish that broadcast with `--resume` instead.
258    #[arg(long, requires = "broadcast", conflicts_with = "resume")]
259    pub start_fresh: bool,
260
261    /// If present, --resume or --verify will be assumed to be a multi chain deployment.
262    #[arg(long)]
263    pub multi: bool,
264
265    /// Open the script in the debugger.
266    ///
267    /// Takes precedence over broadcast.
268    #[arg(long)]
269    pub debug: bool,
270
271    /// Writes a SolDB trace and source bundle to a directory.
272    ///
273    /// Read the bundle with SolDB tools, for example:
274    /// `soldb profile --trace-file <PATH>/trace.json --contracts <PATH>/contracts.json`.
275    #[arg(
276        long,
277        requires = "debug",
278        value_hint = ValueHint::DirPath,
279        value_name = "PATH"
280    )]
281    pub dump: Option<PathBuf>,
282
283    /// Makes sure a transaction is sent,
284    /// only after its previous one has been confirmed and succeeded.
285    ///
286    /// Transactions are prepared during local script execution, before broadcasting. This flag
287    /// does not re-run the script or update transaction destinations and calldata derived from
288    /// simulated return values.
289    ///
290    /// State changes or front-running can make those values stale, even with this flag.
291    #[arg(long)]
292    pub slow: bool,
293
294    /// The number of confirmations to wait for after broadcasting.
295    #[arg(
296        long,
297        default_value_t = DEFAULT_CONFIRMATIONS,
298        value_parser = RangedU64ValueParser::<u64>::new().range(1..),
299    )]
300    pub confirmations: u64,
301
302    /// Skips script confirmation prompts, including no-code targets and oversized contracts.
303    #[arg(long)]
304    pub non_interactive: bool,
305
306    /// Disables the contract size limit during script execution.
307    #[arg(long)]
308    pub disable_code_size_limit: bool,
309
310    #[command(flatten)]
311    pub tracing: TracingArgs,
312
313    /// The Etherscan (or equivalent) API key
314    #[arg(long, env = "ETHERSCAN_API_KEY", value_name = "KEY")]
315    pub etherscan_api_key: Option<String>,
316
317    /// Verifies all the contracts found in the receipts of a script, if any.
318    #[arg(long, requires = "broadcast")]
319    pub verify: bool,
320
321    /// Opt-in verification of contracts deployed by external factories using explorer source.
322    #[arg(long, requires = "verify", conflicts_with_all = ["skip_simulation", "offline"])]
323    pub verify_external: bool,
324
325    /// Gas price for legacy transactions, or max fee per gas for EIP1559 transactions, either
326    /// specified in wei, or as a string with a unit type.
327    ///
328    /// Examples: 1ether, 10gwei, 0.01ether
329    #[arg(
330        long,
331        env = "ETH_GAS_PRICE",
332        value_parser = foundry_cli::utils::parse_ether_value,
333        value_name = "PRICE",
334    )]
335    pub with_gas_price: Option<U256>,
336
337    /// Timeout to use for broadcasting transactions.
338    #[arg(long, env = "ETH_TIMEOUT")]
339    pub timeout: Option<u64>,
340
341    #[command(flatten)]
342    pub build: BuildOpts,
343
344    #[command(flatten)]
345    pub wallets: MultiWalletOpts,
346
347    #[command(flatten)]
348    pub evm: EvmArgs,
349
350    #[command(flatten)]
351    pub verifier: VerifierArgs,
352
353    #[command(flatten)]
354    pub retry: RetryArgs,
355}
356
357impl ScriptArgs {
358    fn has_tempo_session(&self) -> Result<bool> {
359        Ok(self.tempo.session_id()?.is_some())
360    }
361
362    /// Resolves evm_opts (including network inference from fork) using the loaded config.
363    async fn resolved_evm_opts(
364        &self,
365        mut config: Config,
366        mut evm_opts: EvmOpts,
367    ) -> Result<(Config, EvmOpts)> {
368        if self.tempo.is_tempo() || self.has_tempo_session()? {
369            if evm_opts.networks.has_network_selection() {
370                let network = evm_opts.networks.execution_network();
371                eyre::ensure!(
372                    network.is_tempo(),
373                    "Tempo transaction options conflict with configured network `{}`",
374                    evm_opts.networks.execution_profile_name()
375                );
376            }
377            // If Tempo tx options or a session are set, select the Tempo network.
378            evm_opts.networks = NetworkConfigs::with_tempo();
379        }
380        // Discover endpoint source identity and exact hardfork even when execution network is
381        // explicit. Without an explicit selection this also infers the execution network.
382        evm_opts.infer_network_from_fork().await?;
383        config.networks = evm_opts.networks;
384
385        Ok((config, evm_opts))
386    }
387
388    async fn preprocess<FEN: FoundryEvmNetwork>(
389        self,
390        mut config: Config,
391        mut evm_opts: EvmOpts,
392        executor_builder: ExecutorBuilder<FEN>,
393    ) -> Result<PreprocessedState<FEN>> {
394        let args = self;
395        let mut tempo = args.tempo.clone();
396
397        let session_sender = if args.resume {
398            None
399        } else {
400            // Initial scripts may only reveal multi-chain transactions during execution. Use the
401            // session root as the script sender here and validate chain scope during broadcast.
402            tempo.session_sender_for_multi_wallet(&args.wallets, args.evm.sender)?
403        };
404
405        // Resume reconciles durable submissions before loading interactive signers.
406        let (script_wallets, browser_wallet) = if args.resume {
407            (Wallets::new(MultiWallet::default(), args.evm.sender), None)
408        } else {
409            (
410                Wallets::new(args.wallets.get_multi_wallet().await?, args.evm.sender),
411                args.wallets.browser_signer::<FEN::Network>().await?,
412            )
413        };
414
415        if let Some(sender) = session_sender {
416            evm_opts.sender = sender;
417        } else if !args.resume
418            && args.evm.sender.is_none()
419            && let Some(sender) = args.maybe_load_private_key()?
420        {
421            evm_opts.sender = sender;
422        } else if !args.resume && args.evm.sender.is_none() {
423            // If no sender was explicitly set via --sender, auto-detect it from available signers:
424            // use the sole signer's address if there's exactly one, or fall back to the browser
425            // wallet address if present.
426            let mut addresses = script_wallets.addresses();
427            if addresses.is_empty() && browser_wallet.is_none() {
428                // A keystore without an `address` field, such as one written by `cast wallet`,
429                // must be unlocked to find its address.
430                addresses = script_wallets.signers().map_err(|err| {
431                    eyre::eyre!("{err}").wrap_err(
432                        "failed to unlock the wallet to find the script sender; pass `--sender`, \
433                         or a keystore password file with `--password-file` or `ETH_PASSWORD`",
434                    )
435                })?;
436            }
437            if addresses.len() == 1 {
438                evm_opts.sender = addresses[0];
439            } else if let Some(signer) = browser_wallet.as_ref().map(|b| b.address()) {
440                evm_opts.sender = signer
441            }
442        }
443
444        // An explicit configurable account is the sender of a bare `vm.startBroadcast()`, as
445        // `--sender` would make it; its owner keys must not broadcast in its place.
446        if let Some(account) = args.tempo.configurable_account
447            && !args.resume
448        {
449            if let Some(sender) = args.evm.sender {
450                eyre::ensure!(
451                    sender == account,
452                    "--sender {sender} conflicts with --tempo.configurable-account {account}"
453                );
454            }
455            evm_opts.sender = account;
456            script_wallets.inner.lock().provided_sender = Some(account);
457        } else if !args.resume
458            && !args.batch
459            && args.evm.sender.is_none()
460            && !args.tempo.eoa
461            && let Some((account, owner)) = args.linked_account_sender(&config, &evm_opts).await?
462        {
463            // `vm.startBroadcast()` without an address broadcasts from the provided sender, and
464            // `vm.sign` without a signer signs with its owner key.
465            evm_opts.sender = account;
466            let mut wallets = script_wallets.inner.lock();
467            wallets.provided_sender = Some(account);
468            wallets.sender_owner = Some(owner);
469        }
470
471        tempo.resolve_expires();
472        config.tracing = args.tracing.resolve(&config.tracing, evm_opts.verbosity);
473        // `--json` keeps stdout for the result, so logs are captured into it.
474        if shell::is_json() {
475            config.live_logs = false;
476        }
477        if args.debug {
478            if !config.extra_output.contains(&ContractOutputSelection::StorageLayout) {
479                config.extra_output.push(ContractOutputSelection::StorageLayout);
480            }
481            // Full build infos keep the sources the compiler saw, which dynamic test linking
482            // rewrites in scripts.
483            if let Err(error) = config.enable_debug_build_info() {
484                let _ = sh_warn!(
485                    "the debugger may show source files that differ from the compiled ones: {error:#}"
486                );
487            }
488        }
489
490        let script_config = ScriptConfig::new(
491            config,
492            evm_opts,
493            executor_builder,
494            args.batch,
495            tempo,
496            args.sender_nonce,
497        )
498        .await?;
499        Ok(PreprocessedState { args, script_config, script_wallets, browser_wallet })
500    }
501
502    /// Executes the script
503    #[allow(clippy::large_stack_frames)]
504    pub async fn run_script(self) -> Result<()> {
505        trace!(target: "script", "executing script command");
506
507        if self.tempo.sponsor_url.is_some() {
508            eyre::bail!(
509                "--sponsor-url is not supported by forge script; use --tempo.sponsor with \
510                 --tempo.sponsor-signer or --tempo.sponsor-sig"
511            );
512        }
513        eyre::ensure!(
514            self.tempo.configurable_access_key.is_none(),
515            "--tempo.configurable-access-key is not supported by forge script; use cast send"
516        );
517
518        if let Some(dir) = &self.dump {
519            ensure_dump_dir(dir)?;
520        }
521
522        if self.wallet_session.enabled {
523            return self.run_wallet_session_wrapper();
524        }
525
526        let (mut config, evm_opts) = self.load_config_and_evm_opts()?;
527        self.install_missing_dependencies(&mut config)?;
528        let (config, evm_opts) = self.resolved_evm_opts(config, evm_opts).await?;
529
530        let is_tempo = evm_opts.networks.is_tempo();
531
532        if self.batch && !is_tempo {
533            eyre::bail!("--batch mode is only supported on Tempo networks");
534        }
535
536        if self.unlocked && self.has_tempo_session()? {
537            eyre::bail!("--tempo.session/TEMPO_SESSION_ID cannot be combined with --unlocked");
538        }
539
540        // Box each branch's future to keep its large async state off `run_script`'s future;
541        // otherwise `run_command` trips `clippy::large_stack_frames` by a small margin.
542        match evm_opts.networks.execution_network() {
543            NetworkVariant::Tempo => {
544                let batch = self.batch;
545                Box::pin(async move {
546                    let bundled = match self
547                        .prepare_bundled::<TempoEvmNetwork>(
548                            config,
549                            evm_opts,
550                            ExecutorBuilder::<TempoEvmNetwork>::new(),
551                        )
552                        .await?
553                    {
554                        Some(bundled) => bundled,
555                        None => return Ok(()),
556                    };
557                    // batch mode owns its own pending recovery inside broadcast_batch(); running
558                    // the generic wait_for_pending() first would race with that and could
559                    // double-process an already-confirmed batch hash.
560                    let bundled = if batch { bundled } else { bundled.wait_for_pending().await? };
561                    let broadcasted = if batch {
562                        bundled.broadcast_batch().await?
563                    } else {
564                        bundled.broadcast().await?
565                    };
566                    // Transactions saved for their owners are deployed and verified on resume.
567                    if owner_approvals::awaits_approvals(&broadcasted.sequence) {
568                        return Ok(());
569                    }
570                    broadcasted.print_deployed_contracts()?;
571                    if broadcasted.args.verify {
572                        broadcasted.verify().await?;
573                    }
574                    Ok(())
575                })
576                .await
577            }
578            #[cfg(feature = "base")]
579            NetworkVariant::Base => {
580                Box::pin(self.run_generic_script::<BaseEvmNetwork>(
581                    config,
582                    evm_opts,
583                    ExecutorBuilder::<BaseEvmNetwork>::new(),
584                ))
585                .await
586            }
587            #[cfg(feature = "monad")]
588            NetworkVariant::Monad => {
589                Box::pin(async move {
590                    let Some(prepared) = self
591                        .prepare_script(config, evm_opts, ExecutorBuilder::<MonadEvmNetwork>::new())
592                        .await?
593                    else {
594                        return Ok(());
595                    };
596                    let bundled = match prepared {
597                        PreparedScript::Resume(bundled) => *bundled,
598                        PreparedScript::Simulate(state) => {
599                            state.fill_monad_metadata().await?.bundle().await?
600                        }
601                    };
602                    let Some(bundled) = Self::finish_bundle(bundled).await? else { return Ok(()) };
603                    Self::broadcast_bundle(bundled).await
604                })
605                .await
606            }
607            #[cfg(feature = "optimism")]
608            NetworkVariant::Optimism => {
609                Box::pin(self.run_generic_script::<OpEvmNetwork>(
610                    config,
611                    evm_opts,
612                    ExecutorBuilder::<OpEvmNetwork>::new(),
613                ))
614                .await
615            }
616            NetworkVariant::Ethereum => {
617                Box::pin(self.run_generic_script::<EthEvmNetwork>(
618                    config,
619                    evm_opts,
620                    ExecutorBuilder::<EthEvmNetwork>::new(),
621                ))
622                .await
623            }
624        }
625    }
626
627    /// Prepares the bundled state (compile, simulate, bundle) and returns it
628    /// for broadcasting, or returns `None` if there's nothing to broadcast
629    /// (e.g., debug mode, no transactions, missing RPCs).
630    #[allow(clippy::large_stack_frames)]
631    async fn prepare_bundled<FEN: FoundryEvmNetwork>(
632        self,
633        config: Config,
634        evm_opts: EvmOpts,
635        executor_builder: ExecutorBuilder<FEN>,
636    ) -> Result<Option<BundledState<FEN>>> {
637        let Some(prepared) = self.prepare_script(config, evm_opts, executor_builder).await? else {
638            return Ok(None);
639        };
640        let bundled = match prepared {
641            PreparedScript::Resume(bundled) => *bundled,
642            PreparedScript::Simulate(state) => {
643                state.fill_ordinary_metadata().await?.bundle().await?
644            }
645        };
646        Self::finish_bundle(bundled).await
647    }
648
649    /// Compiles and executes the local script, leaving on-chain simulation to its concrete owner.
650    #[allow(clippy::large_stack_frames)]
651    async fn prepare_script<FEN: FoundryEvmNetwork>(
652        self,
653        config: Config,
654        evm_opts: EvmOpts,
655        executor_builder: ExecutorBuilder<FEN>,
656    ) -> Result<Option<PreparedScript<FEN>>> {
657        let state = self.preprocess::<FEN>(config, evm_opts, executor_builder).await?;
658        let create2_deployer = state.script_config.evm_opts.create2_deployer;
659        let compiled = state.compile()?;
660
661        // Move from `CompiledState` to `BundledState` either by resuming or executing and
662        // simulating script.
663        let prepared = if compiled.args.resume {
664            PreparedScript::Resume(Box::new(compiled.resume().await?))
665        } else {
666            // Drive state machine to point at which we have everything needed for simulation.
667            let pre_simulation = compiled
668                .link()
669                .await?
670                .prepare_execution()
671                .await?
672                .execute()
673                .await?
674                .prepare_simulation()
675                .await?
676                .optimize_library_deployments()
677                .await?;
678
679            if pre_simulation.args.debug {
680                return match pre_simulation.args.dump.clone() {
681                    Some(path) => pre_simulation.dump_debugger(&path).map(|_| None),
682                    None => pre_simulation.run_debugger().map(|_| None),
683                };
684            }
685
686            if shell::is_json() {
687                pre_simulation.show_json().await?;
688            } else {
689                pre_simulation.show_traces().await?;
690            }
691
692            // Ensure that we have transactions to simulate/broadcast, otherwise exit early to avoid
693            // hard error.
694            if pre_simulation
695                .execution_result
696                .transactions
697                .as_ref()
698                .is_none_or(|txs| txs.is_empty())
699            {
700                if pre_simulation.args.broadcast {
701                    sh_warn!("No transactions to broadcast.")?;
702                }
703
704                return Ok(None);
705            }
706
707            // Check if there are any missing RPCs and exit early to avoid hard error.
708            if pre_simulation.execution_artifacts.rpc_data.missing_rpc {
709                if !shell::is_json() {
710                    sh_println!("\nIf you wish to simulate on-chain transactions pass a RPC URL.")?;
711                }
712
713                return Ok(None);
714            }
715
716            let size_limits = pre_simulation.args.contract_size_limits::<FEN>(
717                &pre_simulation.script_config.config,
718                &pre_simulation.script_config.evm_opts,
719                pre_simulation.script_config.hardfork,
720            );
721            pre_simulation.args.check_contract_sizes(
722                size_limits,
723                &pre_simulation.execution_result,
724                &pre_simulation.build_data.known_contracts,
725                create2_deployer,
726            )?;
727
728            PreparedScript::Simulate(Box::new(pre_simulation))
729        };
730        Ok(Some(prepared))
731    }
732
733    /// Performs the shared post-simulation output and verification preflight checks.
734    async fn finish_bundle<FEN: FoundryEvmNetwork>(
735        bundled: BundledState<FEN>,
736    ) -> Result<Option<BundledState<FEN>>> {
737        // Exit early in case user didn't provide any broadcast/verify related flags.
738        if !bundled.args.should_broadcast() {
739            if bundled.sequence.sequences().iter().any(|sequence| {
740                sequence
741                    .transactions
742                    .iter()
743                    .any(|tx| tx.tx().from() == Some(Config::DEFAULT_SENDER))
744            }) {
745                sh_warn!(
746                    "Simulated with Foundry's default sender, so addresses and nonces may not match your deployer. Set your own --sender."
747                )?;
748            }
749            if !shell::is_json() {
750                if shell::verbosity() >= 4 {
751                    sh_println!("\n=== Transactions that will be broadcast ===\n")?;
752                    bundled.sequence.show_transactions()?;
753                }
754
755                sh_println!(
756                    "\nSIMULATION COMPLETE. To broadcast these transactions, add --broadcast and wallet configuration(s) to the previous command. See forge script --help for more."
757                )?;
758            }
759            return Ok(None);
760        }
761
762        // Exit early if something is wrong with verification options.
763        if bundled.args.verify {
764            bundled.verify_preflight_check().await?;
765        }
766
767        Ok(Some(bundled))
768    }
769
770    async fn run_generic_script<FEN: FoundryEvmNetwork>(
771        self,
772        config: Config,
773        evm_opts: EvmOpts,
774        executor_builder: ExecutorBuilder<FEN>,
775    ) -> Result<()> {
776        let bundled = match self.prepare_bundled::<FEN>(config, evm_opts, executor_builder).await? {
777            Some(bundled) => bundled,
778            None => return Ok(()),
779        };
780
781        // Wait for pending txes and broadcast others.
782        Self::broadcast_bundle(bundled).await
783    }
784
785    async fn broadcast_bundle<FEN: FoundryEvmNetwork>(bundled: BundledState<FEN>) -> Result<()> {
786        let broadcasted = bundled.wait_for_pending().await?.broadcast().await?;
787        broadcasted.print_deployed_contracts()?;
788
789        if broadcasted.args.verify {
790            broadcasted.verify().await?;
791        }
792
793        Ok(())
794    }
795
796    /// Returns the Tempo configurable account linked to the keystore of the detected sender, and
797    /// its owner key. The account becomes the script sender when the RPC is a Tempo chain where
798    /// T14 is active.
799    async fn linked_account_sender(
800        &self,
801        config: &Config,
802        evm_opts: &EvmOpts,
803    ) -> Result<Option<(Address, Address)>> {
804        let Some(fork_url) = evm_opts.fork_url.as_deref() else { return Ok(None) };
805        if !evm_opts.networks.is_tempo() {
806            return Ok(None);
807        }
808        let paths = match (&self.wallets.keystore_paths, &self.wallets.keystore_account_names) {
809            (Some(paths), _) => paths.iter().map(PathBuf::from).collect(),
810            (None, Some(names)) => {
811                let mut paths = Vec::with_capacity(names.len());
812                for name in names {
813                    paths.extend(maybe_get_keystore_path(None, Some(name))?);
814                }
815                paths
816            }
817            (None, None) => Vec::new(),
818        };
819        for path in paths {
820            if let Some((account, owner)) = linked_account(&path)?
821                && owner == evm_opts.sender
822            {
823                let provider =
824                    ProviderBuilder::<TempoNetwork>::from_config_with_url(config, fork_url)?
825                        .build()?;
826                // Before T14 the linked account does not exist yet, and the key sends as before.
827                let config = detect_configurable_account(
828                    &provider,
829                    account,
830                    &[owner],
831                    None,
832                    false,
833                    BlockId::latest(),
834                )
835                .await
836                .wrap_err_with(|| {
837                    format!(
838                        "could not check the configurable account {account} linked to the \
839                             keystore; pass --sender {owner} or --eoa to send from the key"
840                    )
841                })?;
842                return Ok(config.map(|_| (account, owner)));
843            }
844        }
845        Ok(None)
846    }
847
848    /// In case the user has loaded *only* one private-key or a single remote signer (e.g.,
849    /// Turnkey), we can assume that they're using it as the `--sender`.
850    fn maybe_load_private_key(&self) -> Result<Option<Address>> {
851        if let Some(turnkey_address) = self.wallets.turnkey_address() {
852            return Ok(Some(turnkey_address));
853        }
854
855        let maybe_sender = self
856            .wallets
857            .private_keys()?
858            .filter(|pks| pks.len() == 1)
859            .map(|pks| pks.first().unwrap().address());
860        Ok(maybe_sender)
861    }
862
863    /// Returns the Function and calldata based on the signature
864    ///
865    /// If the `sig` is a valid human-readable function we find the corresponding function in the
866    /// `abi` If the `sig` is valid hex, we assume it's calldata and try to find the
867    /// corresponding function by matching the selector, first 4 bytes in the calldata.
868    ///
869    /// Note: We assume that the `sig` is already stripped of its prefix, See [`ScriptArgs`]
870    fn get_method_and_calldata(&self, abi: &JsonAbi) -> Result<(Function, Bytes)> {
871        // Hex shorter than a selector cannot be calldata, so it is treated as a function name.
872        if let Ok(decoded) = hex::decode(&self.sig)
873            && let Some(selector) = decoded.get(..SELECTOR_LEN)
874        {
875            let func =
876                abi.functions().find(|func| selector == &func.selector()[..]).ok_or_else(|| {
877                    eyre::eyre!(
878                        "Function selector `{}` not found in the ABI",
879                        hex::encode(selector)
880                    )
881                })?;
882            return Ok((func.clone(), decoded.into()));
883        }
884
885        let func = if self.sig.contains('(') {
886            let func = get_func(&self.sig)?;
887            abi.functions()
888                .find(|&abi_func| abi_func.selector() == func.selector())
889                .wrap_err(format!("Function `{}` is not implemented in your script.", self.sig))?
890        } else {
891            let matching_functions =
892                abi.functions().filter(|func| func.name == self.sig).collect::<Vec<_>>();
893            match matching_functions.len() {
894                0 => {
895                    eyre::bail!("Function `{}` not found in the ABI", self.sig);
896                }
897                1 => matching_functions[0],
898                2.. => {
899                    eyre::bail!(
900                        "Multiple functions with the same name `{}` found in the ABI",
901                        self.sig
902                    );
903                }
904            }
905        };
906        let data = encode_function_args(func, &self.args)?;
907
908        Ok((func.clone(), data.into()))
909    }
910
911    /// Checks if the transaction is a deployment with a size above the active EVM specification's
912    /// contract size limit or the specified `code_size_limit`.
913    ///
914    /// If `self.broadcast` is enabled, it asks confirmation of the user. Otherwise, it just warns
915    /// the user.
916    fn check_contract_sizes<N: Network>(
917        &self,
918        size_limits: ContractSizeLimits,
919        result: &ScriptResult<N>,
920        known_contracts: &ContractsByArtifact,
921        create2_deployer: Address,
922    ) -> Result<()> {
923        // If disable-code-size-limit flag is enabled then skip the size check
924        if self.disable_code_size_limit {
925            return Ok(());
926        }
927
928        // (name, &init, &deployed)[]
929        let mut bytecodes: Vec<(String, &[u8], &[u8])> = vec![];
930
931        // From artifacts
932        for (artifact, contract) in known_contracts.iter() {
933            let Some(bytecode) = contract.bytecode() else { continue };
934            let Some(deployed_bytecode) = contract.deployed_bytecode() else { continue };
935            bytecodes.push((artifact.name.clone(), bytecode, deployed_bytecode));
936        }
937
938        // From traces
939        let create_nodes = result.traces.iter().flat_map(|(_, traces)| {
940            traces.nodes().iter().filter(|node| node.trace.kind.is_any_create())
941        });
942        let mut unknown_c = 0usize;
943        for node in create_nodes {
944            let init_code = &node.trace.data;
945            let deployed_code = &node.trace.output;
946            if !bytecodes.iter().any(|(_, b, _)| *b == init_code.as_ref()) {
947                bytecodes.push((format!("Unknown{unknown_c}"), init_code, deployed_code));
948                unknown_c += 1;
949            }
950        }
951
952        let mut prompt_user = false;
953        let max_size = size_limits.runtime;
954
955        for (data, to) in result.transactions.iter().flat_map(|txes| {
956            txes.iter().filter_map(|tx| {
957                tx.transaction
958                    .input()
959                    .filter(|data| data.len() > max_size)
960                    .map(|data| (data, tx.transaction.to()))
961            })
962        }) {
963            let mut offset = 0;
964
965            // Find if it's a CREATE or CREATE2. Otherwise, skip transaction.
966            if let Some(to) = to {
967                if to == create2_deployer {
968                    // Size of the salt prefix.
969                    offset = 32;
970                } else {
971                    continue;
972                }
973            }
974
975            // Find artifact with a deployment code same as the data.
976            if let Some((name, _, deployed_code)) =
977                bytecodes.iter().find(|(_, init_code, _)| *init_code == &data[offset..])
978            {
979                let deployment_size = deployed_code.len();
980
981                if deployment_size > max_size {
982                    prompt_user = self.should_broadcast();
983                    sh_err!(
984                        "`{name}` is above the contract size limit ({deployment_size} > {max_size})."
985                    )?;
986                }
987            }
988        }
989
990        // Only prompt if we're broadcasting and we've not disabled interactivity.
991        if prompt_user && !self.non_interactive {
992            if !dialoguer::console::Term::stderr().is_term() {
993                eyre::bail!(
994                    "contract above the code size limit requires confirmation; pass --non-interactive to continue without confirmation"
995                );
996            }
997            if !Confirm::new().with_prompt("Do you wish to continue?".to_string()).interact()? {
998                eyre::bail!("User canceled the script.");
999            }
1000        }
1001
1002        Ok(())
1003    }
1004
1005    fn contract_size_limits<FEN: FoundryEvmNetwork>(
1006        &self,
1007        config: &Config,
1008        evm_opts: &EvmOpts,
1009        hardfork: Option<FoundryHardfork>,
1010    ) -> ContractSizeLimits {
1011        self.evm
1012            .env
1013            .code_size_limit
1014            .or(evm_opts.env.code_size_limit)
1015            .or(config.code_size_limit)
1016            .map(ContractSizeLimits::with_runtime_limit)
1017            .or_else(|| {
1018                evm_opts
1019                    .networks
1020                    .contract_size_limits()
1021                    .map(|limits| ContractSizeLimits::new(limits.runtime, limits.initcode))
1022            })
1023            .unwrap_or_else(|| {
1024                let spec_id = hardfork
1025                    .and_then(SpecFor::<FEN>::from_foundry_hardfork)
1026                    .unwrap_or_else(|| config.evm_spec_id());
1027                ContractSizeLimits::for_spec_id(spec_id.into())
1028            })
1029    }
1030
1031    /// We only broadcast transactions if --broadcast, --resume, or --verify was passed.
1032    const fn should_broadcast(&self) -> bool {
1033        self.broadcast || self.resume || self.verify
1034    }
1035}
1036
1037impl Provider for ScriptArgs {
1038    fn metadata(&self) -> Metadata {
1039        Metadata::named("Script Args Provider")
1040    }
1041
1042    fn data(&self) -> Result<Map<Profile, Dict>, figment::Error> {
1043        let mut dict = Dict::default();
1044
1045        if let Some(etherscan_api_key) =
1046            self.etherscan_api_key.as_ref().filter(|s| !s.trim().is_empty())
1047        {
1048            dict.insert(
1049                "etherscan_api_key".to_string(),
1050                figment::value::Value::from(etherscan_api_key.clone()),
1051            );
1052        }
1053
1054        if let Some(timeout) = self.timeout {
1055            dict.insert("transaction_timeout".to_string(), timeout.into());
1056        }
1057
1058        if let Some(preset) = self.eip1559_fee_estimate {
1059            dict.insert(
1060                "eip1559_fee_estimate".to_string(),
1061                figment::value::Value::from(preset.to_string()),
1062            );
1063        }
1064
1065        Ok(Map::from([(Config::selected_profile(), dict)]))
1066    }
1067}
1068
1069#[derive(Serialize, Clone)]
1070#[serde(bound = "")]
1071pub struct ScriptResult<N: Network> {
1072    pub success: bool,
1073    #[serde(rename = "raw_logs")]
1074    pub logs: Vec<Log>,
1075    pub traces: Traces,
1076    pub gas_used: u64,
1077    pub labeled_addresses: AddressHashMap<String>,
1078    #[serde(skip)]
1079    pub debug_bytecodes: AddressHashMap<Bytes>,
1080    #[serde(skip)]
1081    pub transactions: Option<BroadcastableTransactions<N>>,
1082    pub returned: Bytes,
1083    #[serde(skip)]
1084    pub exit_reason: Option<InstrStop>,
1085    pub address: Option<Address>,
1086    #[serde(skip)]
1087    pub breakpoints: Breakpoints,
1088}
1089
1090impl<N: Network> Default for ScriptResult<N> {
1091    fn default() -> Self {
1092        Self {
1093            success: Default::default(),
1094            logs: Default::default(),
1095            traces: Default::default(),
1096            gas_used: Default::default(),
1097            labeled_addresses: Default::default(),
1098            debug_bytecodes: Default::default(),
1099            transactions: Default::default(),
1100            returned: Default::default(),
1101            exit_reason: Default::default(),
1102            address: Default::default(),
1103            breakpoints: Default::default(),
1104        }
1105    }
1106}
1107
1108impl<N: Network> ScriptResult<N> {
1109    pub fn get_created_contracts(
1110        &self,
1111        known_contracts: &ContractsByArtifact,
1112    ) -> Vec<AdditionalContract> {
1113        self.traces
1114            .iter()
1115            .flat_map(|(_, traces)| {
1116                let nodes = traces.nodes();
1117                nodes.iter().filter_map(|node| {
1118                    if !node.trace.kind.is_any_create() || !node.trace.success {
1119                        return None;
1120                    }
1121
1122                    let mut creator_code_addresses = Vec::new();
1123                    let mut parent = node.parent;
1124                    while let Some(parent_idx) = parent {
1125                        let ancestor = &nodes[parent_idx];
1126                        if !ancestor.trace.success {
1127                            return None;
1128                        }
1129                        if !ancestor.trace.kind.is_any_create()
1130                            && !creator_code_addresses.contains(&ancestor.trace.address)
1131                        {
1132                            creator_code_addresses.push(ancestor.trace.address);
1133                        }
1134                        parent = ancestor.parent;
1135                    }
1136
1137                    let init_code = node.trace.data.clone();
1138                    let artifact = known_contracts.find_by_creation_code_prefix(init_code.as_ref());
1139                    let contract_name = artifact
1140                        .or_else(|| known_contracts.find_by_creation_code(init_code.as_ref()))
1141                        .map(|(id, _)| id.name.clone());
1142                    let exact_artifact_match = artifact.is_some_and(|(id, _)| {
1143                        !id.source.extension().is_some_and(|ext| ext == "vy")
1144                    });
1145                    Some(AdditionalContract {
1146                        call_kind: node.trace.kind,
1147                        address: node.trace.address,
1148                        contract_name,
1149                        exact_artifact_match,
1150                        init_code,
1151                        creator_code_addresses,
1152                        label: None,
1153                    })
1154                })
1155            })
1156            .collect()
1157    }
1158}
1159
1160#[derive(Serialize)]
1161#[serde(bound = "")]
1162struct JsonResult<'a, N: Network> {
1163    logs: Vec<String>,
1164    returns: &'a HashMap<String, NestedValue>,
1165    #[serde(flatten)]
1166    result: &'a ScriptResult<N>,
1167}
1168
1169#[derive(Clone, Debug)]
1170pub struct ScriptConfig<FEN: FoundryEvmNetwork> {
1171    pub config: Config,
1172    pub evm_opts: EvmOpts,
1173    /// Executor construction selected by concrete network dispatch.
1174    pub executor_builder: ExecutorBuilder<FEN>,
1175    /// Exact network hardfork selected for script execution.
1176    pub hardfork: Option<FoundryHardfork>,
1177    /// Source chain used for trace decoding and external identifiers.
1178    pub source_chain_id: Option<u64>,
1179    pub sender_nonce: u64,
1180    sender_nonce_override: Option<u64>,
1181    /// Pristine backend shared by preflight and cloned for each execution.
1182    backend: Backend<FEN>,
1183    /// Whether to batch all broadcast transactions into a single Tempo batch transaction.
1184    pub batch: bool,
1185    /// Tempo transaction options applied to broadcast transactions.
1186    pub tempo: TempoOpts,
1187}
1188
1189impl<FEN: FoundryEvmNetwork> ScriptConfig<FEN> {
1190    pub(crate) async fn new(
1191        mut config: Config,
1192        mut evm_opts: EvmOpts,
1193        executor_builder: ExecutorBuilder<FEN>,
1194        batch: bool,
1195        tempo: TempoOpts,
1196        sender_nonce_override: Option<u64>,
1197    ) -> Result<Self> {
1198        // Linking and execution share the backend created here, before any preflight reads.
1199        prepare_script_source(&mut config, &mut evm_opts, None).await?;
1200        let backend = Backend::spawn_source(
1201            evm_opts.get_fork(&config, evm_opts.env.chain_id.unwrap_or_default(), None),
1202            evm_opts.local_evm_env::<FEN>(),
1203        )?;
1204        let sender_nonce = if let Some(sender_nonce) = sender_nonce_override {
1205            sender_nonce
1206        } else if evm_opts.fork_url.is_some() {
1207            backend.transaction_count(evm_opts.sender).await?
1208        } else {
1209            // dapptools compatibility
1210            1
1211        };
1212
1213        Ok(Self {
1214            config,
1215            evm_opts,
1216            executor_builder,
1217            hardfork: None,
1218            source_chain_id: None,
1219            sender_nonce,
1220            sender_nonce_override,
1221            backend,
1222            batch,
1223            tempo,
1224        })
1225    }
1226
1227    pub async fn update_sender(&mut self, sender: Address) -> Result<()> {
1228        self.sender_nonce = if let Some(sender_nonce) = self.sender_nonce_override {
1229            sender_nonce
1230        } else if self.evm_opts.fork_url.is_some() {
1231            self.backend.transaction_count(sender).await?
1232        } else {
1233            // dapptools compatibility
1234            1
1235        };
1236        self.evm_opts.sender = sender;
1237        Ok(())
1238    }
1239
1240    async fn select_rpc(&mut self, fork_url: String) -> Result<()> {
1241        self.evm_opts.set_fork_url(fork_url);
1242        self.select_backend().await
1243    }
1244
1245    async fn select_backend(&mut self) -> Result<()> {
1246        if self.evm_opts.fork_url.is_none() {
1247            if self.backend.fork().is_some() {
1248                self.backend.replace_fork(None, self.evm_opts.local_evm_env::<FEN>())?;
1249            }
1250            return Ok(());
1251        }
1252        if !self.prepare_requested_source().await? {
1253            return Ok(());
1254        }
1255        self.backend.replace_fork(
1256            self.evm_opts.get_fork(
1257                &self.config,
1258                self.evm_opts.env.chain_id.unwrap_or_default(),
1259                None,
1260            ),
1261            self.evm_opts.local_evm_env::<FEN>(),
1262        )
1263    }
1264
1265    /// Prepares the requested RPC source. Returns `false` if the backend already serves it.
1266    async fn prepare_requested_source(&mut self) -> Result<bool> {
1267        if let Some(fork) = self.backend.fork() {
1268            if fork.matches_request(&self.evm_opts) {
1269                return Ok(false);
1270            }
1271            self.evm_opts.invalidate_fork_endpoint_if_source_changed(&fork);
1272        }
1273        let active_networks = self.config.networks;
1274        prepare_script_source(&mut self.config, &mut self.evm_opts, Some(active_networks)).await?;
1275        Ok(true)
1276    }
1277
1278    /// Resolves the execution spec for `fork_url` without a backend for that RPC.
1279    ///
1280    /// Trace decoders only need the source chain and hardfork, so they do not open a fork cache.
1281    async fn resolve_rpc_execution_spec(&mut self, fork_url: String) -> Result<()> {
1282        self.evm_opts.set_fork_url(fork_url);
1283        if !self.prepare_requested_source().await? {
1284            self.resolve_execution_env().await?;
1285            return Ok(());
1286        }
1287        let (mut evm_env, _, fork_context) = self.evm_opts.env_with_fork_context::<FEN>().await?;
1288        self.apply_execution_spec(&mut evm_env, fork_context);
1289        Ok(())
1290    }
1291
1292    pub(crate) async fn update_tempo_session_sender(
1293        &mut self,
1294        wallets: &MultiWalletOpts,
1295        expected_sender: Option<Address>,
1296    ) -> Result<()> {
1297        if let Some(sender) =
1298            self.tempo.session_sender_for_multi_wallet(wallets, expected_sender)?
1299        {
1300            self.update_sender(sender).await?;
1301        }
1302        Ok(())
1303    }
1304
1305    async fn get_runner_with_cheatcodes(
1306        &mut self,
1307        known_contracts: ContractsByArtifact,
1308        script_wallets: Wallets,
1309        debug: bool,
1310        target: ArtifactId,
1311        restricted: bool,
1312    ) -> Result<ScriptRunner<FEN>> {
1313        let mut runner = self
1314            ._get_runner(Some((known_contracts, script_wallets, target)), debug, restricted)
1315            .await?;
1316
1317        // Script execution is synthetic. Keep the Tempo transaction context, but do not charge
1318        // protocol fees for deploying or calling the local script contract.
1319        if self.evm_opts.networks.is_tempo() {
1320            runner.executor.evm_env_mut().set_feature(EvmFeatures::FEE_CHARGE, false);
1321        }
1322
1323        Ok(runner)
1324    }
1325
1326    async fn _get_runner(
1327        &mut self,
1328        cheats_data: Option<(ContractsByArtifact, Wallets, ArtifactId)>,
1329        debug: bool,
1330        restricted: bool,
1331    ) -> Result<ScriptRunner<FEN>> {
1332        trace!("preparing script runner");
1333        let (evm_env, mut tx) = self.resolve_execution_env().await?;
1334        let db = self.backend.clone();
1335
1336        // We need to enable tracing to decode contract names: local or external.
1337        let mut builder = self
1338            .executor_builder
1339            .clone()
1340            .inspectors(|stack| {
1341                stack
1342                    .logs(self.config.live_logs)
1343                    .trace_requirements(script_trace_requirements(&self.config, debug))
1344                    .create2_deployer(self.evm_opts.create2_deployer)
1345                    .fork_prefetch(self.evm_opts.fork_prefetch)
1346            })
1347            .gas_limit(self.evm_opts.gas_limit())
1348            .legacy_assertions(self.config.legacy_assertions);
1349
1350        if let Some((known_contracts, script_wallets, target)) = cheats_data {
1351            builder = builder.inspectors(|stack| {
1352                let mut cheats_config = CheatsConfig::new(
1353                    &self.config,
1354                    self.evm_opts.clone(),
1355                    Some(known_contracts),
1356                    Some(target),
1357                    self.batch,
1358                );
1359                if restricted {
1360                    cheats_config.blocked_cheatcodes =
1361                        library_deployments::rerun_unsafe_cheatcode_selectors();
1362                }
1363                stack
1364                    .cheatcodes(cheats_config.into())
1365                    .wallets(script_wallets)
1366                    .enable_isolation(self.evm_opts.isolate)
1367            });
1368        }
1369
1370        // Propagate fee token to the transaction environment so that internal EVM calls
1371        // (e.g. script deployment, setUp) use the correct fee token for Tempo networks.
1372        if let Some(fee_token) = self.tempo.fee_token {
1373            tx.set_fee_token(fee_token);
1374            // A fee token makes calls Tempo AA transactions, which are priced with EIP-1559 fees.
1375            tx.set_max_fee_per_gas(0);
1376            tx.set_max_priority_fee_per_gas(0);
1377        }
1378
1379        let mut runner = ScriptRunner::new(
1380            builder.build(evm_env, tx, db, self.evm_opts.networks),
1381            self.evm_opts.clone(),
1382        )
1383        .with_debug_bytecodes(debug);
1384
1385        if self.sender_nonce_override.is_some() {
1386            runner.executor.set_nonce(self.evm_opts.sender, self.sender_nonce)?;
1387        }
1388
1389        Ok(runner)
1390    }
1391
1392    /// Builds the execution environment and spec from the selected backend.
1393    async fn resolve_execution_env(
1394        &mut self,
1395    ) -> Result<(EvmEnvFor<FEN>, TransactionRequestFor<FEN>)> {
1396        let (mut evm_env, tx) = self.backend.env(&self.evm_opts).await?;
1397        let fork_context = self.backend.fork().map(|fork| fork.context());
1398        self.apply_execution_spec(&mut evm_env, fork_context);
1399        Ok((evm_env, tx))
1400    }
1401
1402    /// Records the source chain and resolves the execution spec for `fork_context`.
1403    fn apply_execution_spec(
1404        &mut self,
1405        evm_env: &mut EvmEnvFor<FEN>,
1406        fork_context: Option<ForkContext>,
1407    ) {
1408        let fork_chain_id = fork_context.map(|context| context.source_chain_id);
1409        let fork_hardfork = fork_context.and_then(|context| context.hardfork);
1410        self.source_chain_id = fork_chain_id;
1411        self.hardfork = resolve_execution_spec::<EvmFactoryFor<FEN>>(
1412            self.config.evm_version,
1413            self.config.hardfork,
1414            evm_env,
1415            ExecutionSpecContext::local_or_script(fork_chain_id, fork_hardfork),
1416            None,
1417        );
1418    }
1419}
1420
1421async fn prepare_script_source(
1422    config: &mut Config,
1423    evm_opts: &mut EvmOpts,
1424    active_networks: Option<NetworkConfigs>,
1425) -> Result<()> {
1426    if evm_opts.fork_url.is_none() {
1427        return Ok(());
1428    }
1429    if evm_opts.fork_endpoint.is_none() {
1430        evm_opts.infer_network_from_fork().await?;
1431    }
1432    if let Some(active_networks) = active_networks
1433        && !active_networks.supports_fork_source(&evm_opts.networks)
1434    {
1435        eyre::bail!(
1436            "fork network `{}` is incompatible with the active EVM",
1437            evm_opts.networks.execution_network()
1438        );
1439    }
1440    config.networks = evm_opts.networks;
1441    if let Some(identity) = evm_opts.fork_endpoint.clone() {
1442        let network_is_inferred = evm_opts.fork_network_is_inferred;
1443        evm_opts.expect_fork_endpoint(identity, network_is_inferred);
1444    }
1445    Ok(())
1446}
1447
1448const fn script_trace_requirements(config: &Config, debug: bool) -> TraceRequirements {
1449    TraceRequirements::none()
1450        .with_calls(true)
1451        .with_debug_recording(debug)
1452        .with_verbosity(config.tracing.verbosity)
1453        .with_decode_internal(if config.tracing.decode_internal {
1454            InternalTraceMode::Full
1455        } else {
1456            InternalTraceMode::None
1457        })
1458}
1459
1460#[cfg(test)]
1461mod tests {
1462    use super::*;
1463    use alloy_chains::NamedChain;
1464    use alloy_network::Ethereum;
1465    use alloy_primitives::address;
1466    use alloy_provider::Provider as _;
1467    use alloy_rpc_types::TransactionRequest;
1468    use alloy_signer::SignerSync as _;
1469    use anvil::{NodeConfig, spawn};
1470    use foundry_cli::opts::TEMPO_SESSION_ID_ENV;
1471    use foundry_common::tempo::{
1472        GeneratedSessionKey, SessionAuthorizationRequest, SessionEntry, TEMPO_HOME_ENV,
1473        upsert_session_entry,
1474    };
1475    use foundry_config::UnresolvedEnvVarError;
1476    use foundry_evm::traces::{
1477        CallKind, CallTrace, CallTraceArena, CallTraceNode, SparsedTraceArena, TraceKind,
1478    };
1479    use semver::Version;
1480    use std::{fs, num::NonZeroU64, sync::LazyLock};
1481    use tempfile::tempdir;
1482    use tokio::sync::{Mutex, MutexGuard};
1483
1484    const SESSION_PRIVATE_KEY: &str =
1485        "0x59c6995e998f97a5a004497e5da3b5d2b2b66a87f064d39c44da0b6d6e4f8ff0";
1486    const SESSION_ROOT_PRIVATE_KEY: &str =
1487        "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
1488    const SESSION_ID_HEX: &str =
1489        "0x1111111111111111111111111111111111111111111111111111111111111111";
1490    const SESSION_ROOT_ADDRESS: &str = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266";
1491    static TEMPO_HOME_LOCK: LazyLock<Mutex<()>> = LazyLock::new(|| Mutex::new(()));
1492
1493    fn assert_missing_orphaned_block(error: &eyre::Report) {
1494        let message = format!("{error:#}").to_ascii_lowercase();
1495        assert!(
1496            message.contains("failed to get block hash")
1497                || message.contains("not found")
1498                || message.contains("unknown block"),
1499            "unexpected orphaned block lookup error: {error:#}"
1500        );
1501    }
1502
1503    #[tokio::test(flavor = "multi_thread")]
1504    async fn script_fork_context_is_re_resolved_for_a_new_rpc() {
1505        let (api_a, handle_a) = spawn(NodeConfig::test()).await;
1506        let (api_b, handle_b) = spawn(NodeConfig::test()).await;
1507        api_a.anvil_mine(Some(U256::ONE), None).await.unwrap();
1508        api_b.anvil_mine(Some(U256::from(3)), None).await.unwrap();
1509
1510        let evm_opts = EvmOpts {
1511            fork_url: Some(handle_a.http_endpoint()),
1512            sender: handle_a.dev_accounts().next().unwrap(),
1513            ..Default::default()
1514        };
1515        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1516            Config::default(),
1517            evm_opts,
1518            ExecutorBuilder::<EthEvmNetwork>::new(),
1519            false,
1520            TempoOpts::default(),
1521            None,
1522        )
1523        .await
1524        .unwrap();
1525        let first = config.backend.fork().unwrap();
1526        assert_eq!(first.number(), 1);
1527        assert_eq!(config.evm_opts.fork_block_number, None);
1528        assert!(first.matches_request(&config.evm_opts));
1529
1530        config._get_runner(None, false, false).await.unwrap();
1531
1532        config.select_rpc(handle_b.http_endpoint()).await.unwrap();
1533        let second = config.backend.fork().unwrap();
1534
1535        assert_eq!(second.number(), 3);
1536        assert_eq!(config.evm_opts.fork_block_number, None);
1537        assert!(second.matches_request(&config.evm_opts));
1538        assert_ne!(first, second);
1539    }
1540
1541    #[cfg(feature = "monad")]
1542    #[tokio::test(flavor = "multi_thread")]
1543    async fn script_explicit_network_is_preserved_for_a_new_rpc() {
1544        let (api_a, handle_a) = spawn(NodeConfig::test_monad()).await;
1545        let (api_b, handle_b) = spawn(NodeConfig::test_monad()).await;
1546        api_a.anvil_mine(Some(U256::ONE), None).await.unwrap();
1547        api_b.anvil_mine(Some(U256::from(3)), None).await.unwrap();
1548
1549        let evm_opts = EvmOpts {
1550            fork_url: Some(handle_a.http_endpoint()),
1551            sender: handle_a.dev_accounts().next().unwrap(),
1552            networks: NetworkConfigs::with_ethereum(),
1553            ..Default::default()
1554        };
1555        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1556            Config::default(),
1557            evm_opts,
1558            ExecutorBuilder::<EthEvmNetwork>::new(),
1559            false,
1560            TempoOpts::default(),
1561            None,
1562        )
1563        .await
1564        .unwrap();
1565        assert_eq!(config.evm_opts.networks, NetworkConfigs::with_ethereum());
1566
1567        config.select_rpc(handle_b.http_endpoint()).await.unwrap();
1568        let second = config.backend.fork().unwrap();
1569
1570        assert_eq!(second.number(), 3);
1571        assert_eq!(second.context().network_profile, NetworkConfigs::with_monad());
1572        assert_eq!(config.evm_opts.networks, NetworkConfigs::with_ethereum());
1573    }
1574
1575    #[tokio::test(flavor = "multi_thread")]
1576    async fn script_explicit_fork_block_is_preserved_for_a_new_rpc() {
1577        let (api_a, handle_a) = spawn(NodeConfig::test()).await;
1578        let (api_b, handle_b) = spawn(NodeConfig::test()).await;
1579        api_a.anvil_mine(Some(U256::from(2)), None).await.unwrap();
1580        api_b.anvil_mine(Some(U256::from(4)), None).await.unwrap();
1581
1582        let evm_opts = EvmOpts {
1583            fork_url: Some(handle_a.http_endpoint()),
1584            fork_block_number: Some(1),
1585            sender: handle_a.dev_accounts().next().unwrap(),
1586            ..Default::default()
1587        };
1588        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1589            Config::default(),
1590            evm_opts,
1591            ExecutorBuilder::<EthEvmNetwork>::new(),
1592            false,
1593            TempoOpts::default(),
1594            None,
1595        )
1596        .await
1597        .unwrap();
1598        config._get_runner(None, false, false).await.unwrap();
1599
1600        config.select_rpc(handle_b.http_endpoint()).await.unwrap();
1601        let context = config.backend.fork().unwrap();
1602
1603        assert_eq!(context.number(), 1);
1604        assert_eq!(config.evm_opts.fork_block_number, Some(1));
1605        assert!(context.matches_request(&config.evm_opts));
1606    }
1607
1608    #[tokio::test(flavor = "multi_thread")]
1609    async fn script_explicit_fork_block_can_equal_previous_latest() {
1610        let (api_a, handle_a) = spawn(NodeConfig::test()).await;
1611        let (api_b, handle_b) = spawn(NodeConfig::test()).await;
1612        api_a.anvil_mine(Some(U256::ONE), None).await.unwrap();
1613        api_b.anvil_mine(Some(U256::ONE), None).await.unwrap();
1614
1615        let evm_opts = EvmOpts {
1616            fork_url: Some(handle_a.http_endpoint()),
1617            sender: handle_a.dev_accounts().next().unwrap(),
1618            ..Default::default()
1619        };
1620        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1621            Config::default(),
1622            evm_opts,
1623            ExecutorBuilder::<EthEvmNetwork>::new(),
1624            false,
1625            TempoOpts::default(),
1626            None,
1627        )
1628        .await
1629        .unwrap();
1630        let latest = config.backend.fork().unwrap();
1631        assert_eq!(config.evm_opts.fork_block_number, None);
1632        config._get_runner(None, false, false).await.unwrap();
1633
1634        config.select_rpc(handle_b.http_endpoint()).await.unwrap();
1635        config.evm_opts.fork_block_number = Some(1);
1636        config.select_backend().await.unwrap();
1637        let explicit = config.backend.fork().unwrap();
1638
1639        assert_eq!(explicit.number(), 1);
1640        assert_eq!(config.evm_opts.fork_block_number, Some(1));
1641        assert!(explicit.matches_request(&config.evm_opts));
1642        assert_ne!(latest, explicit);
1643
1644        config._get_runner(None, false, false).await.unwrap();
1645    }
1646
1647    #[tokio::test(flavor = "multi_thread")]
1648    async fn script_fork_cache_distinguishes_same_height_contexts() {
1649        let (api_a, handle_a) = spawn(NodeConfig::test()).await;
1650        let (api_b, handle_b) = spawn(NodeConfig::test()).await;
1651        let state_address = address!("0000000000000000000000000000000000001337");
1652        let balance_a = U256::ONE;
1653        let balance_b = U256::from(2);
1654        api_a.anvil_set_balance(state_address, balance_a).await.unwrap();
1655        api_b.anvil_set_balance(state_address, balance_b).await.unwrap();
1656        let original_prevrandao = B256::with_last_byte(0x42);
1657        api_a.anvil_set_next_block_prevrandao(original_prevrandao).await.unwrap();
1658        api_a.anvil_mine(Some(U256::ONE), None).await.unwrap();
1659        api_b.anvil_mine(Some(U256::ONE), None).await.unwrap();
1660        let url_a = handle_a.http_endpoint();
1661        let url_b = handle_b.http_endpoint();
1662        let sender = handle_a.dev_accounts().next().unwrap();
1663
1664        let evm_opts = EvmOpts { fork_url: Some(url_a.clone()), sender, ..Default::default() };
1665        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1666            Config::default(),
1667            evm_opts,
1668            ExecutorBuilder::<EthEvmNetwork>::new(),
1669            false,
1670            TempoOpts::default(),
1671            None,
1672        )
1673        .await
1674        .unwrap();
1675        let mut runner_a = config._get_runner(None, false, false).await.unwrap();
1676        assert_eq!(runner_a.executor.get_balance(state_address).unwrap(), balance_a);
1677        let first_a = config.backend.fork().unwrap();
1678        let cache_a = runner_a.executor.backend().active_fork_info().unwrap().id.clone();
1679        runner_a.executor.set_balance(state_address, U256::from(3)).unwrap();
1680
1681        config.select_rpc(url_b.clone()).await.unwrap();
1682        let runner_b = config._get_runner(None, false, false).await.unwrap();
1683        assert_eq!(runner_b.executor.get_balance(state_address).unwrap(), balance_b);
1684        let context_b = config.backend.fork().unwrap().clone();
1685        assert_eq!(context_b.number(), 1);
1686
1687        config.select_rpc(url_a.clone()).await.unwrap();
1688        let reused_a = config._get_runner(None, false, false).await.unwrap();
1689        assert_eq!(reused_a.executor.get_balance(state_address).unwrap(), balance_a);
1690        // A reused fork shares the creating fork's RPC cache under a suffixed ID.
1691        let reused_id = &reused_a.executor.backend().active_fork_info().unwrap().id;
1692        assert!(
1693            reused_id.0 == cache_a.0 || reused_id.0.starts_with(&format!("{}-", cache_a.0)),
1694            "{reused_id:?} does not reuse {cache_a:?}"
1695        );
1696        config.select_rpc(url_b.clone()).await.unwrap();
1697
1698        let provider_a = handle_a.http_provider();
1699        provider_a
1700            .raw_request::<_, ()>("anvil_reorg".into(), (1_u64, Vec::<serde_json::Value>::new()))
1701            .await
1702            .unwrap();
1703        let replacement = provider_a.get_block_by_number(1.into()).await.unwrap().unwrap();
1704        assert_eq!(replacement.header.number, first_a.number());
1705        assert_ne!(replacement.header.hash, first_a.hash());
1706        assert_ne!(replacement.header.mix_hash, Some(original_prevrandao));
1707
1708        config.select_rpc(url_a.clone()).await.unwrap();
1709        let second_a = config.backend.fork().unwrap();
1710        assert_eq!(second_a.number(), first_a.number());
1711        assert_eq!(second_a.hash(), replacement.header.hash);
1712        assert_ne!(second_a.hash(), first_a.hash());
1713
1714        let runner = config._get_runner(None, false, false).await.unwrap();
1715        assert_eq!(runner.executor.get_balance(state_address).unwrap(), balance_a);
1716        assert_eq!(
1717            runner.executor.evm_env().block.prevrandao,
1718            U256::from_be_bytes(replacement.header.mix_hash.unwrap().0)
1719        );
1720    }
1721
1722    #[tokio::test(flavor = "multi_thread")]
1723    async fn script_same_endpoint_keeps_backend_block() {
1724        let (api, handle) = spawn(NodeConfig::test()).await;
1725        api.anvil_mine(Some(U256::ONE), None).await.unwrap();
1726        let url = handle.http_endpoint();
1727        let evm_opts = EvmOpts {
1728            fork_url: Some(url.clone()),
1729            sender: handle.dev_accounts().next().unwrap(),
1730            ..Default::default()
1731        };
1732        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1733            Config::default(),
1734            evm_opts,
1735            ExecutorBuilder::<EthEvmNetwork>::new(),
1736            false,
1737            TempoOpts::default(),
1738            None,
1739        )
1740        .await
1741        .unwrap();
1742        let resolved = config.backend.fork().unwrap();
1743        config._get_runner(None, false, false).await.unwrap();
1744
1745        api.anvil_mine(Some(U256::ONE), None).await.unwrap();
1746        config.select_rpc(url.clone()).await.unwrap();
1747        let runner = config._get_runner(None, false, false).await.unwrap();
1748
1749        assert_eq!(config.backend.fork().as_ref(), Some(&resolved));
1750        assert_eq!(runner.executor.evm_env().block.number, U256::ONE);
1751        assert_eq!(config.evm_opts.fork_block_number, None);
1752    }
1753
1754    #[tokio::test(flavor = "multi_thread")]
1755    async fn script_fork_changed_headers_replace_cached_backend() {
1756        let (api, handle) = spawn(NodeConfig::test()).await;
1757        api.anvil_mine(Some(U256::ONE), None).await.unwrap();
1758        let url = handle.http_endpoint();
1759        let evm_opts = EvmOpts {
1760            fork_url: Some(url.clone()),
1761            sender: handle.dev_accounts().next().unwrap(),
1762            ..Default::default()
1763        };
1764        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1765            Config::default(),
1766            evm_opts,
1767            ExecutorBuilder::<EthEvmNetwork>::new(),
1768            false,
1769            TempoOpts::default(),
1770            None,
1771        )
1772        .await
1773        .unwrap();
1774        config._get_runner(None, false, false).await.unwrap();
1775        let without_headers = config.backend.fork().unwrap().clone();
1776
1777        config.evm_opts.fork_headers = Some(vec!["x-foundry-test: resolved-fork".to_string()]);
1778        config.select_backend().await.unwrap();
1779        let with_headers = config.backend.fork().unwrap();
1780        config._get_runner(None, false, false).await.unwrap();
1781
1782        assert_ne!(without_headers, with_headers);
1783        assert!(with_headers.matches_request(&config.evm_opts));
1784    }
1785
1786    async fn assert_same_url_fork_auth_change_re_resolves(
1787        configure_initial: impl FnOnce(&mut EvmOpts),
1788        configure_changed: impl FnOnce(&mut EvmOpts),
1789    ) {
1790        let (api, handle) = spawn(NodeConfig::test()).await;
1791        let mut evm_opts = EvmOpts {
1792            fork_url: Some(handle.http_endpoint()),
1793            fork_block_number: Some(0),
1794            networks: NetworkConfigs::with_ethereum(),
1795            ..Default::default()
1796        };
1797        evm_opts.env.chain_id = Some(42);
1798        configure_initial(&mut evm_opts);
1799
1800        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1801            Config::default(),
1802            evm_opts,
1803            ExecutorBuilder::<EthEvmNetwork>::new(),
1804            false,
1805            TempoOpts::default(),
1806            None,
1807        )
1808        .await
1809        .unwrap();
1810        config._get_runner(None, false, false).await.unwrap();
1811        let first = config.backend.fork().unwrap().clone();
1812        let first_instance = first.context().instance_id.unwrap();
1813
1814        api.anvil_reset(None).await.unwrap();
1815        assert_ne!(api.instance_id(), first_instance);
1816        configure_changed(&mut config.evm_opts);
1817
1818        config.select_backend().await.unwrap();
1819        let second = config.backend.fork().unwrap();
1820        assert_ne!(second.context().instance_id, Some(first_instance));
1821        assert_ne!(second, first);
1822        assert_eq!(config.evm_opts.fork_block_number, Some(0));
1823        assert_eq!(config.evm_opts.networks, NetworkConfigs::with_ethereum());
1824        assert_eq!(config.evm_opts.env.chain_id, Some(42));
1825
1826        config._get_runner(None, false, false).await.unwrap();
1827    }
1828
1829    #[tokio::test(flavor = "multi_thread")]
1830    async fn script_same_url_rpc_headers_change_adopts_new_fork_identity() {
1831        assert_same_url_fork_auth_change_re_resolves(
1832            |evm_opts| evm_opts.rpc_headers = Some(vec!["x-fork-source: first".to_string()]),
1833            |evm_opts| evm_opts.rpc_headers = Some(vec!["x-fork-source: second".to_string()]),
1834        )
1835        .await;
1836    }
1837
1838    #[tokio::test(flavor = "multi_thread")]
1839    async fn script_same_url_jwt_change_adopts_new_fork_identity() {
1840        const FIRST_JWT: &str = "5c43996d0d150a81f06ae452fce38120d97a4156650aec7487b3384bfe32edae";
1841        const SECOND_JWT: &str = "cabee703106087906e50f3e75a6ddbab60809f980511d1d1548d449d52220795";
1842
1843        assert_same_url_fork_auth_change_re_resolves(
1844            |evm_opts| evm_opts.rpc_jwt = Some(FIRST_JWT.to_string()),
1845            |evm_opts| evm_opts.rpc_jwt = Some(SECOND_JWT.to_string()),
1846        )
1847        .await;
1848    }
1849
1850    #[tokio::test(flavor = "multi_thread")]
1851    async fn script_runner_env_preserves_prepared_fork_after_reorg() {
1852        let (api, handle) = spawn(NodeConfig::test()).await;
1853        let prevrandao = B256::with_last_byte(0x42);
1854        api.anvil_set_next_block_prevrandao(prevrandao).await.unwrap();
1855        api.anvil_mine(Some(U256::ONE), None).await.unwrap();
1856
1857        let evm_opts = EvmOpts {
1858            fork_url: Some(handle.http_endpoint()),
1859            sender: handle.dev_accounts().next().unwrap(),
1860            ..Default::default()
1861        };
1862        let mut config = ScriptConfig::<EthEvmNetwork>::new(
1863            Config::default(),
1864            evm_opts,
1865            ExecutorBuilder::<EthEvmNetwork>::new(),
1866            false,
1867            TempoOpts::default(),
1868            None,
1869        )
1870        .await
1871        .unwrap();
1872        assert!(
1873            config
1874                .backend
1875                .can_use_create2_deployer(config.evm_opts.create2_deployer)
1876                .await
1877                .unwrap()
1878        );
1879        config._get_runner(None, false, false).await.unwrap();
1880
1881        let provider = handle.http_provider();
1882        let pinned = config.backend.fork().unwrap();
1883        provider
1884            .raw_request::<_, ()>("anvil_reorg".into(), (1_u64, Vec::<serde_json::Value>::new()))
1885            .await
1886            .unwrap();
1887        let replacement = provider.get_block_by_number(1.into()).await.unwrap().unwrap();
1888        assert_ne!(replacement.header.hash, pinned.hash());
1889        assert_ne!(replacement.header.mix_hash, Some(prevrandao));
1890
1891        // Reusing the prepared environment must not adopt the replacement block header.
1892        config.select_rpc(handle.http_endpoint()).await.unwrap();
1893        match config._get_runner(None, false, false).await {
1894            Ok(runner) => {
1895                assert_eq!(
1896                    runner.executor.evm_env().block.prevrandao,
1897                    U256::from_be_bytes(prevrandao.0)
1898                );
1899            }
1900            Err(error) => assert_missing_orphaned_block(&error),
1901        }
1902        assert_eq!(config.backend.fork().as_ref(), Some(&pinned));
1903    }
1904
1905    #[test]
1906    fn script_trace_requirements_honor_tracing_verbosity() {
1907        let mut config = Config::default();
1908        config.tracing.verbosity = 5;
1909
1910        let tracing = script_trace_requirements(&config, false).into_config().unwrap();
1911        assert!(tracing.record_state_diff);
1912    }
1913
1914    #[test]
1915    fn created_contracts_include_successful_creator_code_ancestry() {
1916        let root = Address::repeat_byte(0x11);
1917        let implementation = Address::repeat_byte(0x22);
1918        let helper = Address::repeat_byte(0x33);
1919        let created = Address::repeat_byte(0x44);
1920        let init_code = Bytes::from_static(&[0x60, 0x00]);
1921        let mut arena = CallTraceArena::default();
1922        arena.nodes_mut()[0].trace =
1923            CallTrace { success: true, address: root, kind: CallKind::Call, ..Default::default() };
1924        arena.nodes_mut().extend([
1925            CallTraceNode {
1926                parent: Some(0),
1927                idx: 1,
1928                trace: CallTrace {
1929                    success: true,
1930                    address: implementation,
1931                    kind: CallKind::DelegateCall,
1932                    ..Default::default()
1933                },
1934                ..Default::default()
1935            },
1936            CallTraceNode {
1937                parent: Some(1),
1938                idx: 2,
1939                trace: CallTrace {
1940                    success: true,
1941                    address: helper,
1942                    kind: CallKind::Call,
1943                    ..Default::default()
1944                },
1945                ..Default::default()
1946            },
1947            CallTraceNode {
1948                parent: Some(2),
1949                idx: 3,
1950                trace: CallTrace {
1951                    success: true,
1952                    address: created,
1953                    kind: CallKind::Create2,
1954                    data: init_code.clone(),
1955                    ..Default::default()
1956                },
1957                ..Default::default()
1958            },
1959        ]);
1960        let result = ScriptResult::<Ethereum> {
1961            traces: vec![(
1962                TraceKind::Execution,
1963                SparsedTraceArena {
1964                    arena,
1965                    ignored: Default::default(),
1966                    diagnostics: Default::default(),
1967                    debug_steps: None,
1968                },
1969            )],
1970            ..Default::default()
1971        };
1972
1973        let contracts = result.get_created_contracts(&ContractsByArtifact::default());
1974        assert_eq!(contracts.len(), 1);
1975        assert_eq!(contracts[0].address, created);
1976        assert_eq!(contracts[0].init_code, init_code);
1977        assert_eq!(contracts[0].creator_code_addresses, [helper, implementation, root]);
1978    }
1979
1980    #[test]
1981    fn created_contracts_exclude_creations_rolled_back_by_an_ancestor() {
1982        let mut arena = CallTraceArena::default();
1983        arena.nodes_mut()[0].trace = CallTrace { success: true, ..Default::default() };
1984        arena.nodes_mut().extend([
1985            CallTraceNode {
1986                parent: Some(0),
1987                idx: 1,
1988                trace: CallTrace { success: false, kind: CallKind::Call, ..Default::default() },
1989                ..Default::default()
1990            },
1991            CallTraceNode {
1992                parent: Some(1),
1993                idx: 2,
1994                trace: CallTrace {
1995                    success: true,
1996                    kind: CallKind::Create,
1997                    data: Bytes::from_static(&[0x60, 0x00]),
1998                    ..Default::default()
1999                },
2000                ..Default::default()
2001            },
2002        ]);
2003        let result = ScriptResult::<Ethereum> {
2004            traces: vec![(
2005                TraceKind::Execution,
2006                SparsedTraceArena {
2007                    arena,
2008                    ignored: Default::default(),
2009                    diagnostics: Default::default(),
2010                    debug_steps: None,
2011                },
2012            )],
2013            ..Default::default()
2014        };
2015
2016        assert!(result.get_created_contracts(&ContractsByArtifact::default()).is_empty());
2017    }
2018
2019    fn active_session_entry(
2020        session_id: B256,
2021        root_account: Address,
2022        chain_id: u64,
2023    ) -> SessionEntry {
2024        let foundry_wallets::WalletSigner::Local(root) =
2025            foundry_wallets::utils::create_private_key_signer(SESSION_ROOT_PRIVATE_KEY).unwrap()
2026        else {
2027            unreachable!("a raw private key always creates a local signer")
2028        };
2029        assert_eq!(root.address(), root_account);
2030        let key = GeneratedSessionKey::from_private_key(SESSION_PRIVATE_KEY).unwrap();
2031        let prepared = SessionAuthorizationRequest {
2032            session_id,
2033            root_account,
2034            chain_id,
2035            key_address: key.address(),
2036            expiry: NonZeroU64::new(u64::MAX).unwrap(),
2037            scope: vec![tempo_primitives::transaction::CallScope {
2038                target: Address::repeat_byte(0xaa),
2039                selector_rules: vec![],
2040            }],
2041            spend_limits: vec![],
2042        }
2043        .prepare(0)
2044        .unwrap();
2045        let signature = root.sign_hash_sync(&prepared.authorization.signature_hash()).unwrap();
2046        let authorization = prepared
2047            .authorization
2048            .clone()
2049            .into_signed(tempo_primitives::transaction::PrimitiveSignature::Secp256k1(signature));
2050        prepared.into_active_entry(key, &authorization).unwrap()
2051    }
2052
2053    struct TempoHomeGuard {
2054        _guard: MutexGuard<'static, ()>,
2055    }
2056
2057    impl TempoHomeGuard {
2058        async fn set(path: &std::path::Path) -> Self {
2059            let guard = TEMPO_HOME_LOCK.lock().await;
2060            // SAFETY: test-only environment override for Tempo local state.
2061            unsafe {
2062                std::env::remove_var(TEMPO_SESSION_ID_ENV);
2063                std::env::set_var(TEMPO_HOME_ENV, path);
2064            }
2065            Self { _guard: guard }
2066        }
2067    }
2068
2069    impl Drop for TempoHomeGuard {
2070        fn drop(&mut self) {
2071            // SAFETY: restore process environment after the critical section.
2072            unsafe {
2073                std::env::remove_var(TEMPO_HOME_ENV);
2074                std::env::remove_var(TEMPO_SESSION_ID_ENV);
2075            }
2076        }
2077    }
2078
2079    fn session_root() -> Address {
2080        SESSION_ROOT_ADDRESS.parse().unwrap()
2081    }
2082
2083    #[test]
2084    fn can_parse_sig() {
2085        let sig = "0x522bb704000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfFFb92266";
2086        let args = ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--sig", sig]);
2087        assert_eq!(args.sig, sig);
2088    }
2089
2090    #[test]
2091    fn short_hex_sig_is_resolved_as_function_name() {
2092        let abi = JsonAbi::parse(["function fade()", "function run()"]).unwrap();
2093        let method = |sig: &str| {
2094            ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--sig", sig])
2095                .get_method_and_calldata(&abi)
2096        };
2097
2098        let fade = abi.function("fade").unwrap()[0].clone();
2099        let (func, calldata) = method("fade").unwrap();
2100        assert_eq!(func, fade);
2101        assert_eq!(calldata, Bytes::from(fade.selector()));
2102
2103        for sig in ["", "0x12"] {
2104            assert_eq!(
2105                method(sig).unwrap_err().to_string(),
2106                format!("Function `{sig}` not found in the ABI")
2107            );
2108        }
2109
2110        // Hex with a full selector is still raw calldata.
2111        let run = abi.function("run").unwrap()[0].clone();
2112        let (func, calldata) = method(&hex::encode(run.selector())).unwrap();
2113        assert_eq!(func, run);
2114        assert_eq!(calldata, Bytes::from(run.selector()));
2115    }
2116
2117    #[test]
2118    fn parses_confirmations() {
2119        let args = ScriptArgs::parse_from(["foundry-cli", "Contract.sol"]);
2120        assert_eq!(args.confirmations, DEFAULT_CONFIRMATIONS);
2121
2122        let args = ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--confirmations", "6"]);
2123        assert_eq!(args.confirmations, 6);
2124
2125        let err =
2126            ScriptArgs::try_parse_from(["foundry-cli", "Contract.sol", "--confirmations", "0"])
2127                .unwrap_err();
2128        assert_eq!(err.kind(), clap::error::ErrorKind::ValueValidation);
2129    }
2130
2131    #[test]
2132    fn verify_external_requires_verify() {
2133        let err = ScriptArgs::try_parse_from(["foundry-cli", "Contract.sol", "--verify-external"])
2134            .unwrap_err();
2135        assert_eq!(err.kind(), clap::error::ErrorKind::MissingRequiredArgument);
2136
2137        let args = ScriptArgs::try_parse_from([
2138            "foundry-cli",
2139            "Contract.sol",
2140            "--broadcast",
2141            "--verify",
2142            "--verify-external",
2143        ])
2144        .unwrap();
2145        assert!(args.verify_external);
2146    }
2147
2148    #[test]
2149    fn verify_external_requires_simulation_and_online_mode() {
2150        for conflicting_arg in ["--skip-simulation", "--offline"] {
2151            let err = ScriptArgs::try_parse_from([
2152                "foundry-cli",
2153                "Contract.sol",
2154                "--broadcast",
2155                "--verify",
2156                "--verify-external",
2157                conflicting_arg,
2158            ])
2159            .unwrap_err();
2160            assert_eq!(err.kind(), clap::error::ErrorKind::ArgumentConflict);
2161        }
2162    }
2163
2164    #[test]
2165    fn rejects_max_sender_nonce() {
2166        let max_valid_nonce = (u64::MAX - 1).to_string();
2167        let args = ScriptArgs::try_parse_from([
2168            "foundry-cli",
2169            "Contract.sol",
2170            "--sender-nonce",
2171            &max_valid_nonce,
2172        ])
2173        .unwrap();
2174        assert_eq!(args.sender_nonce, Some(u64::MAX - 1));
2175
2176        let max_nonce = u64::MAX.to_string();
2177        let err = ScriptArgs::try_parse_from([
2178            "foundry-cli",
2179            "Contract.sol",
2180            "--sender-nonce",
2181            &max_nonce,
2182        ])
2183        .unwrap_err();
2184        assert_eq!(err.kind(), clap::error::ErrorKind::ValueValidation);
2185    }
2186
2187    #[tokio::test(flavor = "multi_thread")]
2188    async fn update_sender_fork_does_not_read_nonce_from_replacement_block() {
2189        let (_api, handle) = spawn(NodeConfig::test()).await;
2190        let accounts = handle.dev_wallets().collect::<Vec<_>>();
2191        let original_sender = accounts[0].address();
2192        let replacement_sender = accounts[1].address();
2193        let provider = handle.http_provider();
2194        let tx = TransactionRequest::default()
2195            .from(replacement_sender)
2196            .to(original_sender)
2197            .value(U256::ONE);
2198        provider.send_transaction(tx.into()).await.unwrap().get_receipt().await.unwrap();
2199
2200        let evm_opts = EvmOpts {
2201            fork_url: Some(handle.http_endpoint()),
2202            sender: original_sender,
2203            ..Default::default()
2204        };
2205        let mut config = ScriptConfig::<EthEvmNetwork>::new(
2206            Config::default(),
2207            evm_opts,
2208            ExecutorBuilder::<EthEvmNetwork>::new(),
2209            false,
2210            TempoOpts::default(),
2211            None,
2212        )
2213        .await
2214        .unwrap();
2215        let resolved = config.backend.fork().unwrap();
2216        assert_eq!(config.evm_opts.fork_block_number, None);
2217        assert_eq!(config.sender_nonce, 0);
2218
2219        provider
2220            .raw_request::<_, ()>("anvil_reorg".into(), (1_u64, Vec::<serde_json::Value>::new()))
2221            .await
2222            .unwrap();
2223        assert_eq!(provider.get_transaction_count(replacement_sender).number(1).await.unwrap(), 0);
2224
2225        match config.update_sender(replacement_sender).await {
2226            Ok(()) => assert_eq!(config.sender_nonce, 1),
2227            Err(error) => assert_missing_orphaned_block(&error),
2228        }
2229        assert_eq!(config.backend.fork().as_ref(), Some(&resolved));
2230    }
2231
2232    #[tokio::test(flavor = "multi_thread")]
2233    async fn sender_nonce_override_does_not_refresh_fork() {
2234        let (_api, handle) = spawn(NodeConfig::test()).await;
2235        let sender = handle.dev_accounts().next().unwrap();
2236        let evm_opts =
2237            EvmOpts { fork_url: Some(handle.http_endpoint()), sender, ..Default::default() };
2238        let mut config = ScriptConfig::<EthEvmNetwork>::new(
2239            Config::default(),
2240            evm_opts,
2241            ExecutorBuilder::<EthEvmNetwork>::new(),
2242            false,
2243            TempoOpts::default(),
2244            Some(7),
2245        )
2246        .await
2247        .unwrap();
2248
2249        config.evm_opts.set_fork_url("http://127.0.0.1:1".to_string());
2250        config.update_sender(Address::with_last_byte(0x42)).await.unwrap();
2251        assert_eq!(config.sender_nonce, 7);
2252    }
2253
2254    #[tokio::test(flavor = "multi_thread")]
2255    #[cfg(feature = "monad")]
2256    async fn script_runner_preserves_nested_fork_source_chain() {
2257        let (_origin_api, origin_handle) = spawn(
2258            NodeConfig::test_monad()
2259                .with_chain_id(Some(NamedChain::MonadTestnet as u64))
2260                .with_hardfork(Some(foundry_evm::hardforks::MonadHardfork::MonadNine.into())),
2261        )
2262        .await;
2263        let (_fork_api, fork_handle) = spawn(
2264            NodeConfig::test_monad()
2265                .with_chain_id(Some(NamedChain::Mainnet as u64))
2266                .with_no_storage_caching(true)
2267                .with_eth_rpc_url(Some(origin_handle.http_endpoint()))
2268                .with_fork_block_number(Some(0u64)),
2269        )
2270        .await;
2271        let mut evm_opts =
2272            EvmOpts { fork_url: Some(fork_handle.http_endpoint()), ..Default::default() };
2273        evm_opts.infer_network_from_fork().await.unwrap();
2274        let config = Config { networks: evm_opts.networks, ..Default::default() };
2275        let mut script = ScriptConfig::<MonadEvmNetwork>::new(
2276            config,
2277            evm_opts,
2278            ExecutorBuilder::<MonadEvmNetwork>::new(),
2279            false,
2280            TempoOpts::default(),
2281            None,
2282        )
2283        .await
2284        .unwrap();
2285
2286        let _runner = script._get_runner(None, false, false).await.unwrap();
2287
2288        assert_eq!(script.source_chain_id, Some(NamedChain::MonadTestnet as u64));
2289        assert_eq!(
2290            script.hardfork,
2291            Some(FoundryHardfork::Monad(foundry_evm::hardforks::MonadHardfork::MonadNine))
2292        );
2293    }
2294
2295    #[tokio::test(flavor = "multi_thread")]
2296    async fn tempo_runner_fee_charge_matches_execution_context() {
2297        let (_api, handle) = spawn(NodeConfig::test_tempo()).await;
2298        let networks = NetworkConfigs::with_tempo();
2299        let evm_opts = EvmOpts {
2300            fork_url: Some(handle.http_endpoint()),
2301            sender: handle.dev_accounts().next().unwrap(),
2302            networks,
2303            ..Default::default()
2304        };
2305        let config = Config { networks, ..Default::default() };
2306        let mut script = ScriptConfig::<TempoEvmNetwork>::new(
2307            config,
2308            evm_opts,
2309            ExecutorBuilder::<TempoEvmNetwork>::new(),
2310            false,
2311            TempoOpts::default(),
2312            None,
2313        )
2314        .await
2315        .unwrap();
2316
2317        let rpc_runner = script._get_runner(None, false, false).await.unwrap();
2318        assert!(rpc_runner.executor.evm_env().version.feature(EvmFeatures::FEE_CHARGE));
2319
2320        let target = ArtifactId {
2321            path: PathBuf::from("Script.json"),
2322            name: "Script".to_string(),
2323            source: PathBuf::from("Script.sol"),
2324            version: Version::new(0, 8, 30),
2325            build_id: String::new(),
2326            profile: "default".to_string(),
2327        };
2328        let synthetic_runner = script
2329            .get_runner_with_cheatcodes(
2330                ContractsByArtifact::default(),
2331                Wallets::new(Default::default(), None),
2332                false,
2333                target,
2334                false,
2335            )
2336            .await
2337            .unwrap();
2338        assert!(!synthetic_runner.executor.evm_env().version.feature(EvmFeatures::FEE_CHARGE));
2339    }
2340
2341    #[test]
2342    fn can_parse_shared_tempo_opts() {
2343        let args = ScriptArgs::parse_from([
2344            "foundry-cli",
2345            "Contract.sol",
2346            "--tempo.fee-token",
2347            "1",
2348            "--tempo.expires",
2349            "10",
2350        ]);
2351
2352        assert_eq!(
2353            args.tempo.fee_token,
2354            Some(address!("0x20C0000000000000000000000000000000000001"))
2355        );
2356        assert_eq!(args.tempo.expires, Some(10));
2357    }
2358
2359    #[test]
2360    fn can_parse_sponsor_tempo_opts() {
2361        let args = ScriptArgs::parse_from([
2362            "foundry-cli",
2363            "Contract.sol",
2364            "--tempo.sponsor",
2365            SESSION_ROOT_ADDRESS,
2366            "--tempo.sponsor-signer",
2367            "env://TEMPO_SPONSOR_PK",
2368        ]);
2369
2370        assert_eq!(args.tempo.sponsor, Some(session_root()));
2371        assert_eq!(args.tempo.sponsor_signer.as_deref(), Some("env://TEMPO_SPONSOR_PK"));
2372    }
2373
2374    #[test]
2375    fn can_parse_full_tempo_opts() {
2376        let args =
2377            ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--tempo.nonce-key", "1"]);
2378
2379        assert_eq!(args.tempo.nonce_key, Some(U256::ONE));
2380    }
2381
2382    #[test]
2383    fn can_parse_tempo_session_opt() {
2384        let args = ScriptArgs::parse_from([
2385            "foundry-cli",
2386            "Contract.sol",
2387            "--tempo.session",
2388            SESSION_ID_HEX,
2389        ]);
2390
2391        assert_eq!(args.tempo.session, Some(B256::repeat_byte(0x11)),);
2392    }
2393
2394    #[tokio::test(flavor = "multi_thread")]
2395    async fn tempo_session_sets_script_sender_to_root_account() {
2396        let temp = tempdir().unwrap();
2397        let session_id = B256::repeat_byte(0x22);
2398        let root = session_root();
2399        let chain_id = foundry_common::DEV_CHAIN_ID;
2400
2401        let _guard = TempoHomeGuard::set(temp.path()).await;
2402        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2403
2404        let args = ScriptArgs::parse_from([
2405            "foundry-cli",
2406            "Contract.sol",
2407            "--tempo.session",
2408            &format!("{session_id:?}"),
2409        ]);
2410        let evm_opts = EvmOpts {
2411            networks: NetworkConfigs::with_tempo(),
2412            env: foundry_evm::opts::Env { chain_id: Some(chain_id), ..Default::default() },
2413            ..Default::default()
2414        };
2415
2416        let state = args
2417            .preprocess::<TempoEvmNetwork>(
2418                Config::default(),
2419                evm_opts,
2420                ExecutorBuilder::<TempoEvmNetwork>::new(),
2421            )
2422            .await
2423            .unwrap();
2424        assert_eq!(state.script_config.evm_opts.sender, root);
2425    }
2426
2427    #[tokio::test(flavor = "multi_thread")]
2428    async fn tempo_session_resume_multi_defers_session_sender_until_reexecution() {
2429        let temp = tempdir().unwrap();
2430        let session_id = B256::repeat_byte(0x55);
2431        let root = session_root();
2432        let chain_id = 4217;
2433
2434        let _guard = TempoHomeGuard::set(temp.path()).await;
2435        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2436
2437        let args = ScriptArgs::parse_from([
2438            "foundry-cli",
2439            "Contract.sol",
2440            "--resume",
2441            "--multi",
2442            "--tempo.session",
2443            &format!("{session_id:?}"),
2444        ]);
2445        let evm_opts = EvmOpts { networks: NetworkConfigs::with_tempo(), ..Default::default() };
2446
2447        let state = args
2448            .preprocess::<TempoEvmNetwork>(
2449                Config::default(),
2450                evm_opts,
2451                ExecutorBuilder::<TempoEvmNetwork>::new(),
2452            )
2453            .await
2454            .unwrap();
2455        assert_ne!(state.script_config.evm_opts.sender, root);
2456    }
2457
2458    #[tokio::test(flavor = "multi_thread")]
2459    async fn tempo_session_resume_defers_session_sender_until_reexecution() {
2460        let temp = tempdir().unwrap();
2461        let session_id = B256::repeat_byte(0x77);
2462        let root = session_root();
2463        let chain_id = 4217;
2464
2465        let _guard = TempoHomeGuard::set(temp.path()).await;
2466        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2467
2468        let args = ScriptArgs::parse_from([
2469            "foundry-cli",
2470            "Contract.sol",
2471            "--resume",
2472            "--tempo.session",
2473            &format!("{session_id:?}"),
2474        ]);
2475        let evm_opts = EvmOpts { networks: NetworkConfigs::with_tempo(), ..Default::default() };
2476
2477        let state = args
2478            .preprocess::<TempoEvmNetwork>(
2479                Config::default(),
2480                evm_opts,
2481                ExecutorBuilder::<TempoEvmNetwork>::new(),
2482            )
2483            .await
2484            .unwrap();
2485        assert_ne!(state.script_config.evm_opts.sender, root);
2486    }
2487
2488    #[tokio::test(flavor = "multi_thread")]
2489    async fn tempo_session_non_resume_multi_sets_sender_without_chain_validation() {
2490        let temp = tempdir().unwrap();
2491        let session_id = B256::repeat_byte(0x66);
2492        let root = session_root();
2493        let chain_id = 4217;
2494
2495        let _guard = TempoHomeGuard::set(temp.path()).await;
2496        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2497
2498        let args = ScriptArgs::parse_from([
2499            "foundry-cli",
2500            "Contract.sol",
2501            "--multi",
2502            "--tempo.session",
2503            &format!("{session_id:?}"),
2504        ]);
2505        let evm_opts = EvmOpts { networks: NetworkConfigs::with_tempo(), ..Default::default() };
2506
2507        let state = args
2508            .preprocess::<TempoEvmNetwork>(
2509                Config::default(),
2510                evm_opts,
2511                ExecutorBuilder::<TempoEvmNetwork>::new(),
2512            )
2513            .await
2514            .unwrap();
2515        assert_eq!(state.script_config.evm_opts.sender, root);
2516    }
2517
2518    #[tokio::test(flavor = "multi_thread")]
2519    async fn tempo_session_initial_broadcast_sets_sender_without_chain_validation() {
2520        let temp = tempdir().unwrap();
2521        let session_id = B256::repeat_byte(0x88);
2522        let root = session_root();
2523        let chain_id = 4217;
2524
2525        let _guard = TempoHomeGuard::set(temp.path()).await;
2526        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2527
2528        let args = ScriptArgs::parse_from([
2529            "foundry-cli",
2530            "Contract.sol",
2531            "--broadcast",
2532            "--tempo.session",
2533            &format!("{session_id:?}"),
2534        ]);
2535        let evm_opts = EvmOpts { networks: NetworkConfigs::with_tempo(), ..Default::default() };
2536
2537        let state = args
2538            .preprocess::<TempoEvmNetwork>(
2539                Config::default(),
2540                evm_opts,
2541                ExecutorBuilder::<TempoEvmNetwork>::new(),
2542            )
2543            .await
2544            .unwrap();
2545        assert_eq!(state.script_config.evm_opts.sender, root);
2546    }
2547
2548    #[tokio::test]
2549    async fn tempo_options_preserve_explicit_script_network() {
2550        let temp = tempdir().unwrap();
2551        let _guard = TempoHomeGuard::set(temp.path()).await;
2552        for options in [
2553            vec!["--tempo.fee-token", "0x20c0000000000000000000000000000000000000"],
2554            vec![
2555                "--tempo.session",
2556                "0x4444444444444444444444444444444444444444444444444444444444444444",
2557            ],
2558        ] {
2559            let args =
2560                ScriptArgs::parse_from(["foundry-cli", "Contract.sol"].into_iter().chain(options));
2561            for (networks, name) in [
2562                (NetworkConfigs::with_ethereum(), "ethereum"),
2563                (NetworkConfigs::with_celo(), "celo"),
2564                #[cfg(feature = "base")]
2565                (NetworkConfigs::with_base(), "base"),
2566            ] {
2567                let evm_opts = EvmOpts { networks, ..Default::default() };
2568                let err = args.resolved_evm_opts(Config::default(), evm_opts).await.unwrap_err();
2569                assert_eq!(
2570                    err.to_string(),
2571                    format!("Tempo transaction options conflict with configured network `{name}`")
2572                );
2573            }
2574        }
2575    }
2576
2577    #[tokio::test]
2578    async fn tempo_session_env_selects_tempo_network() {
2579        let temp = tempdir().unwrap();
2580        let _guard = TempoHomeGuard::set(temp.path()).await;
2581        let session_id = B256::repeat_byte(0x44);
2582        // SAFETY: serialized by TempoHomeGuard.
2583        unsafe { std::env::set_var(TEMPO_SESSION_ID_ENV, format!("{session_id:?}")) };
2584
2585        let args = ScriptArgs::parse_from(["foundry-cli", "Contract.sol"]);
2586        let (config, evm_opts) = args.load_config_and_evm_opts().unwrap();
2587        let (_, evm_opts) = args.resolved_evm_opts(config, evm_opts).await.unwrap();
2588
2589        assert!(evm_opts.networks.is_tempo());
2590    }
2591
2592    #[tokio::test]
2593    async fn tempo_session_rejects_explicit_script_wallet_signer() {
2594        let temp = tempdir().unwrap();
2595        let session_id = B256::repeat_byte(0x33);
2596        let root = session_root();
2597        let chain_id = foundry_common::DEV_CHAIN_ID;
2598
2599        let _guard = TempoHomeGuard::set(temp.path()).await;
2600        upsert_session_entry(active_session_entry(session_id, root, chain_id)).unwrap();
2601
2602        let args = ScriptArgs::parse_from([
2603            "foundry-cli",
2604            "Contract.sol",
2605            "--tempo.session",
2606            &format!("{session_id:?}"),
2607            "--private-key",
2608            SESSION_PRIVATE_KEY,
2609        ]);
2610        let evm_opts = EvmOpts {
2611            networks: NetworkConfigs::with_tempo(),
2612            env: foundry_evm::opts::Env { chain_id: Some(chain_id), ..Default::default() },
2613            ..Default::default()
2614        };
2615
2616        let err = match args
2617            .preprocess::<TempoEvmNetwork>(
2618                Config::default(),
2619                evm_opts,
2620                ExecutorBuilder::<TempoEvmNetwork>::new(),
2621            )
2622            .await
2623        {
2624            Ok(_) => panic!("expected --tempo.session with --private-key to fail"),
2625            Err(err) => err,
2626        };
2627        assert!(err.to_string().contains("explicit wallet signer"), "{err}");
2628    }
2629
2630    #[test]
2631    fn can_parse_unlocked() {
2632        let args = ScriptArgs::parse_from([
2633            "foundry-cli",
2634            "Contract.sol",
2635            "--sender",
2636            "0x4e59b44847b379578588920ca78fbf26c0b4956c",
2637            "--unlocked",
2638        ]);
2639        assert!(args.unlocked);
2640
2641        let key = U256::ZERO;
2642        let args = ScriptArgs::try_parse_from([
2643            "foundry-cli",
2644            "Contract.sol",
2645            "--sender",
2646            "0x4e59b44847b379578588920ca78fbf26c0b4956c",
2647            "--unlocked",
2648            "--private-key",
2649            &key.to_string(),
2650        ]);
2651        assert!(args.is_err());
2652    }
2653
2654    #[test]
2655    fn can_merge_script_config() {
2656        let args = ScriptArgs::parse_from([
2657            "foundry-cli",
2658            "Contract.sol",
2659            "--etherscan-api-key",
2660            "goerli",
2661        ]);
2662        let config = args.load_config().unwrap();
2663        assert_eq!(config.etherscan_api_key, Some("goerli".to_string()));
2664    }
2665
2666    #[test]
2667    fn can_disable_code_size_limit() {
2668        let args =
2669            ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--disable-code-size-limit"]);
2670        assert!(args.disable_code_size_limit);
2671
2672        let result = ScriptResult::<Ethereum>::default();
2673        let contracts = ContractsByArtifact::default();
2674        let create = Address::ZERO;
2675        assert!(
2676            args.check_contract_sizes(ContractSizeLimits::default(), &result, &contracts, create)
2677                .is_ok()
2678        );
2679    }
2680
2681    #[test]
2682    fn can_parse_verifier_url() {
2683        let args = ScriptArgs::parse_from([
2684            "foundry-cli",
2685            "script",
2686            "script/Test.s.sol:TestScript",
2687            "--fork-url",
2688            "http://localhost:8545",
2689            "--verifier-url",
2690            "http://localhost:3000/api/verify",
2691            "--etherscan-api-key",
2692            "blacksmith",
2693            "--broadcast",
2694            "--verify",
2695            "-vvvvv",
2696        ]);
2697        assert_eq!(
2698            args.verifier.verifier_url,
2699            Some("http://localhost:3000/api/verify".to_string())
2700        );
2701    }
2702
2703    #[test]
2704    fn can_extract_code_size_limit() {
2705        let args = ScriptArgs::parse_from([
2706            "foundry-cli",
2707            "script",
2708            "script/Test.s.sol:TestScript",
2709            "--fork-url",
2710            "http://localhost:8545",
2711            "--broadcast",
2712            "--code-size-limit",
2713            "50000",
2714        ]);
2715        assert_eq!(args.evm.env.code_size_limit, Some(50000));
2716    }
2717
2718    /// `--code-size-limit` on the CLI should be used by `check_contract_sizes`, not silently
2719    /// ignored in favour of the foundry.toml value (which defaults to None → EIP-170's 24576).
2720    #[test]
2721    fn cli_code_size_limit_is_honoured_by_check() {
2722        let args = ScriptArgs::parse_from([
2723            "foundry-cli",
2724            "script",
2725            "script/Test.s.sol:TestScript",
2726            "--code-size-limit",
2727            "2147483647",
2728        ]);
2729        // The CLI flag must land in evm_opts so that the size_limits computation in run() picks
2730        // it up via `.evm_opts.env.code_size_limit.or(config.code_size_limit)`.
2731        assert_eq!(args.evm.env.code_size_limit, Some(2147483647));
2732    }
2733
2734    #[test]
2735    #[cfg(feature = "monad")]
2736    fn contract_size_limits_use_resolved_monad_network() {
2737        let args =
2738            ScriptArgs::parse_from(["foundry-cli", "script", "script/Test.s.sol:TestScript"]);
2739        let evm_opts = EvmOpts { networks: NetworkConfigs::with_monad(), ..Default::default() };
2740
2741        let limits =
2742            args.contract_size_limits::<MonadEvmNetwork>(&Config::default(), &evm_opts, None);
2743
2744        assert!(limits.runtime > ContractSizeLimits::default().runtime);
2745        assert!(limits.initcode > ContractSizeLimits::default().initcode);
2746    }
2747
2748    #[test]
2749    #[cfg(feature = "monad")]
2750    fn contract_size_limits_prefer_cli_then_config_over_network() {
2751        let args = ScriptArgs::parse_from([
2752            "foundry-cli",
2753            "script",
2754            "script/Test.s.sol:TestScript",
2755            "--code-size-limit",
2756            "64",
2757        ]);
2758        let mut config = Config { code_size_limit: Some(128), ..Default::default() };
2759        let evm_opts = EvmOpts { networks: NetworkConfigs::with_monad(), ..Default::default() };
2760        assert_eq!(
2761            args.contract_size_limits::<MonadEvmNetwork>(&config, &evm_opts, None),
2762            ContractSizeLimits::with_runtime_limit(64)
2763        );
2764
2765        let args =
2766            ScriptArgs::parse_from(["foundry-cli", "script", "script/Test.s.sol:TestScript"]);
2767        config.code_size_limit = Some(128);
2768        assert_eq!(
2769            args.contract_size_limits::<MonadEvmNetwork>(&config, &evm_opts, None),
2770            ContractSizeLimits::with_runtime_limit(128)
2771        );
2772    }
2773
2774    #[test]
2775    fn can_extract_script_etherscan_key() {
2776        let temp = tempdir().unwrap();
2777        let root = temp.path();
2778
2779        let config = r#"
2780                [profile.default]
2781                etherscan_api_key = "amoy"
2782
2783                [etherscan]
2784                amoy = { key = "https://etherscan-amoy.com/" }
2785            "#;
2786
2787        let toml_file = root.join(Config::FILE_NAME);
2788        fs::write(toml_file, config).unwrap();
2789        let args = ScriptArgs::parse_from([
2790            "foundry-cli",
2791            "Contract.sol",
2792            "--etherscan-api-key",
2793            "amoy",
2794            "--root",
2795            root.as_os_str().to_str().unwrap(),
2796        ]);
2797
2798        let config = args.load_config().unwrap();
2799        let amoy = config.get_etherscan_api_key(Some(NamedChain::PolygonAmoy.into()));
2800        assert_eq!(amoy, Some("https://etherscan-amoy.com/".to_string()));
2801    }
2802
2803    #[test]
2804    fn can_extract_script_rpc_alias() {
2805        let temp = tempdir().unwrap();
2806        let root = temp.path();
2807
2808        let config = r#"
2809                [profile.default]
2810
2811                [rpc_endpoints]
2812                polygonAmoy = "https://polygon-amoy.g.alchemy.com/v2/${_CAN_EXTRACT_RPC_ALIAS}"
2813            "#;
2814
2815        let toml_file = root.join(Config::FILE_NAME);
2816        fs::write(toml_file, config).unwrap();
2817        let args = ScriptArgs::parse_from([
2818            "foundry-cli",
2819            "DeployV1",
2820            "--rpc-url",
2821            "polygonAmoy",
2822            "--root",
2823            root.as_os_str().to_str().unwrap(),
2824        ]);
2825
2826        let err = args.load_config_and_evm_opts().unwrap_err();
2827
2828        assert!(err.downcast::<UnresolvedEnvVarError>().is_ok());
2829
2830        unsafe {
2831            std::env::set_var("_CAN_EXTRACT_RPC_ALIAS", "123456");
2832        }
2833        let (config, evm_opts) = args.load_config_and_evm_opts().unwrap();
2834        assert_eq!(config.eth_rpc_url, Some("polygonAmoy".to_string()));
2835        assert_eq!(
2836            evm_opts.fork_url,
2837            Some("https://polygon-amoy.g.alchemy.com/v2/123456".to_string())
2838        );
2839    }
2840
2841    #[test]
2842    fn can_extract_script_rpc_and_etherscan_alias() {
2843        let temp = tempdir().unwrap();
2844        let root = temp.path();
2845
2846        let config = r#"
2847            [profile.default]
2848
2849            [rpc_endpoints]
2850            amoy = "https://polygon-amoy.g.alchemy.com/v2/${_EXTRACT_RPC_ALIAS}"
2851
2852            [etherscan]
2853            amoy = { key = "${_ETHERSCAN_API_KEY}", chain = 80002, url = "https://amoy.polygonscan.com/" }
2854        "#;
2855
2856        let toml_file = root.join(Config::FILE_NAME);
2857        fs::write(toml_file, config).unwrap();
2858        let args = ScriptArgs::parse_from([
2859            "foundry-cli",
2860            "DeployV1",
2861            "--rpc-url",
2862            "amoy",
2863            "--etherscan-api-key",
2864            "amoy",
2865            "--root",
2866            root.as_os_str().to_str().unwrap(),
2867        ]);
2868        let err = args.load_config_and_evm_opts().unwrap_err();
2869
2870        assert!(err.downcast::<UnresolvedEnvVarError>().is_ok());
2871
2872        unsafe {
2873            std::env::set_var("_EXTRACT_RPC_ALIAS", "123456");
2874        }
2875        unsafe {
2876            std::env::set_var("_ETHERSCAN_API_KEY", "etherscan_api_key");
2877        }
2878        let (config, evm_opts) = args.load_config_and_evm_opts().unwrap();
2879        assert_eq!(config.eth_rpc_url, Some("amoy".to_string()));
2880        assert_eq!(
2881            evm_opts.fork_url,
2882            Some("https://polygon-amoy.g.alchemy.com/v2/123456".to_string())
2883        );
2884        let etherscan = config.get_etherscan_api_key(Some(80002u64.into()));
2885        assert_eq!(etherscan, Some("etherscan_api_key".to_string()));
2886        let etherscan = config.get_etherscan_api_key(None);
2887        assert_eq!(etherscan, Some("etherscan_api_key".to_string()));
2888    }
2889
2890    #[test]
2891    fn can_extract_script_rpc_and_sole_etherscan_alias() {
2892        let temp = tempdir().unwrap();
2893        let root = temp.path();
2894
2895        let config = r#"
2896                [profile.default]
2897
2898               [rpc_endpoints]
2899                amoy = "https://polygon-amoy.g.alchemy.com/v2/${_SOLE_EXTRACT_RPC_ALIAS}"
2900
2901                [etherscan]
2902                amoy = { key = "${_SOLE_ETHERSCAN_API_KEY}" }
2903            "#;
2904
2905        let toml_file = root.join(Config::FILE_NAME);
2906        fs::write(toml_file, config).unwrap();
2907        let args = ScriptArgs::parse_from([
2908            "foundry-cli",
2909            "DeployV1",
2910            "--rpc-url",
2911            "amoy",
2912            "--root",
2913            root.as_os_str().to_str().unwrap(),
2914        ]);
2915        let err = args.load_config_and_evm_opts().unwrap_err();
2916
2917        assert!(err.downcast::<UnresolvedEnvVarError>().is_ok());
2918
2919        unsafe {
2920            std::env::set_var("_SOLE_EXTRACT_RPC_ALIAS", "123456");
2921        }
2922        unsafe {
2923            std::env::set_var("_SOLE_ETHERSCAN_API_KEY", "etherscan_api_key");
2924        }
2925        let (config, evm_opts) = args.load_config_and_evm_opts().unwrap();
2926        assert_eq!(
2927            evm_opts.fork_url,
2928            Some("https://polygon-amoy.g.alchemy.com/v2/123456".to_string())
2929        );
2930        let etherscan = config.get_etherscan_api_key(Some(80002u64.into()));
2931        assert_eq!(etherscan, Some("etherscan_api_key".to_string()));
2932        let etherscan = config.get_etherscan_api_key(None);
2933        assert_eq!(etherscan, Some("etherscan_api_key".to_string()));
2934    }
2935
2936    // <https://github.com/foundry-rs/foundry/issues/5923>
2937    #[test]
2938    fn test_5923() {
2939        let args =
2940            ScriptArgs::parse_from(["foundry-cli", "DeployV1", "--priority-gas-price", "100"]);
2941        assert!(args.priority_gas_price.is_some());
2942    }
2943
2944    #[test]
2945    fn test_eip1559_fee_estimate() {
2946        // Defaults to unset (config provides `market`).
2947        let args = ScriptArgs::parse_from(["foundry-cli", "DeployV1"]);
2948        assert!(args.eip1559_fee_estimate.is_none());
2949
2950        let args = ScriptArgs::parse_from(["foundry-cli", "DeployV1", "--estimate", "aggressive"]);
2951        assert_eq!(args.eip1559_fee_estimate, Some(Eip1559FeeEstimatePreset::Aggressive));
2952    }
2953
2954    // <https://github.com/foundry-rs/foundry/issues/5910>
2955    #[test]
2956    fn test_5910() {
2957        let args = ScriptArgs::parse_from([
2958            "foundry-cli",
2959            "--broadcast",
2960            "--with-gas-price",
2961            "0",
2962            "SolveTutorial",
2963        ]);
2964        assert!(args.with_gas_price.unwrap().is_zero());
2965    }
2966
2967    #[test]
2968    fn test_priority_gas_price_cannot_exceed_gas_price() {
2969        let args = ScriptArgs::parse_from([
2970            "foundry-cli",
2971            "--broadcast",
2972            "--with-gas-price",
2973            "100",
2974            "--priority-gas-price",
2975            "200",
2976            "Script",
2977        ]);
2978        // priority (200) > max_fee (100) — broadcast should reject this at runtime
2979        assert!(args.priority_gas_price.unwrap() > args.with_gas_price.unwrap());
2980    }
2981
2982    #[tokio::test(flavor = "multi_thread")]
2983    async fn explicit_sender_takes_precedence_over_sole_private_key() {
2984        let temp = tempdir().unwrap();
2985        let _guard = TempoHomeGuard::set(temp.path()).await;
2986
2987        let private_key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
2988        let key_address = address!("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
2989        let sender = address!("0x70997970C51812dc3A010C7d01b50e0d17dc79C8");
2990
2991        let args = ScriptArgs::parse_from([
2992            "foundry-cli",
2993            "Contract.sol",
2994            "--private-key",
2995            private_key,
2996            "--sender",
2997            &sender.to_string(),
2998        ]);
2999        let state = args
3000            .preprocess::<EthEvmNetwork>(
3001                Config::default(),
3002                EvmOpts { sender, ..Default::default() },
3003                ExecutorBuilder::<EthEvmNetwork>::new(),
3004            )
3005            .await
3006            .unwrap();
3007        assert_eq!(state.script_config.evm_opts.sender, sender);
3008
3009        let args =
3010            ScriptArgs::parse_from(["foundry-cli", "Contract.sol", "--private-key", private_key]);
3011        let state = args
3012            .preprocess::<EthEvmNetwork>(
3013                Config::default(),
3014                EvmOpts::default(),
3015                ExecutorBuilder::<EthEvmNetwork>::new(),
3016            )
3017            .await
3018            .unwrap();
3019        assert_eq!(state.script_config.evm_opts.sender, key_address);
3020    }
3021}