leo_lang/cli/commands/
upgrade.rs

1// Copyright (C) 2019-2025 Provable Inc.
2// This file is part of the Leo library.
3
4// The Leo library is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// The Leo library is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
16
17use super::*;
18use std::{collections::HashSet, fs};
19
20use leo_ast::NetworkName;
21use leo_package::{Package, ProgramData, fetch_program_from_network};
22
23#[cfg(not(feature = "only_testnet"))]
24use snarkvm::prelude::{CanaryV0, MainnetV0};
25use snarkvm::{
26    ledger::query::Query as SnarkVMQuery,
27    prelude::{
28        Program,
29        TestnetV0,
30        VM,
31        store::{ConsensusStore, helpers::memory::ConsensusMemory},
32    },
33};
34
35use crate::cli::{check_transaction::TransactionStatus, commands::deploy::validate_deployment_limits};
36use aleo_std::StorageMode;
37use colored::*;
38use itertools::Itertools;
39use leo_span::Symbol;
40use snarkvm::{
41    prelude::{ConsensusVersion, ProgramID, Stack, store::helpers::memory::BlockMemory},
42    synthesizer::program::StackTrait,
43};
44use std::path::PathBuf;
45
46/// Upgrades an Aleo program.
47#[derive(Parser, Debug)]
48pub struct LeoUpgrade {
49    #[clap(flatten)]
50    pub(crate) fee_options: FeeOptions,
51    #[clap(flatten)]
52    pub(crate) action: TransactionAction,
53    #[clap(flatten)]
54    pub(crate) env_override: EnvOptions,
55    #[clap(flatten)]
56    pub(crate) extra: ExtraOptions,
57    #[clap(long, help = "Skips the upgrade of any program that contains one of the given substrings.")]
58    pub(crate) skip: Vec<String>,
59    #[clap(flatten)]
60    pub(crate) build_options: BuildOptions,
61}
62
63impl Command for LeoUpgrade {
64    type Input = Package;
65    type Output = ();
66
67    fn log_span(&self) -> Span {
68        tracing::span!(tracing::Level::INFO, "Leo")
69    }
70
71    fn prelude(&self, context: Context) -> Result<Self::Input> {
72        LeoBuild {
73            env_override: self.env_override.clone(),
74            options: {
75                let mut options = self.build_options.clone();
76                options.no_cache = true;
77                options
78            },
79        }
80        .execute(context)
81    }
82
83    fn apply(self, context: Context, input: Self::Input) -> Result<Self::Output> {
84        // Get the network, accounting for overrides.
85        let network = get_network(&self.env_override.network)?;
86        // Handle each network with the appropriate parameterization.
87        match network {
88            NetworkName::TestnetV0 => handle_upgrade::<TestnetV0>(&self, context, network, input),
89            NetworkName::MainnetV0 => {
90                #[cfg(feature = "only_testnet")]
91                panic!("Mainnet chosen with only_testnet feature");
92                #[cfg(not(feature = "only_testnet"))]
93                handle_upgrade::<MainnetV0>(&self, context, network, input)
94            }
95            NetworkName::CanaryV0 => {
96                #[cfg(feature = "only_testnet")]
97                panic!("Canary chosen with only_testnet feature");
98                #[cfg(not(feature = "only_testnet"))]
99                handle_upgrade::<CanaryV0>(&self, context, network, input)
100            }
101        }
102    }
103}
104
105// A helper function to handle upgrade logic.
106fn handle_upgrade<N: Network>(
107    command: &LeoUpgrade,
108    context: Context,
109    network: NetworkName,
110    package: Package,
111) -> Result<<LeoDeploy as Command>::Output> {
112    // Get the private key and associated address, accounting for overrides.
113    let private_key = get_private_key(&command.env_override.private_key)?;
114    let address =
115        Address::try_from(&private_key).map_err(|e| CliError::custom(format!("Failed to parse address: {e}")))?;
116
117    // Get the endpoint, accounting for overrides.
118    let endpoint = get_endpoint(&command.env_override.endpoint)?;
119
120    // Get whether the network is a devnet, accounting for overrides.
121    let is_devnet = get_is_devnet(command.env_override.devnet);
122
123    // If the consensus heights are provided, use them; otherwise, use the default heights for the network.
124    let consensus_heights =
125        command.env_override.consensus_heights.clone().unwrap_or_else(|| get_consensus_heights(network, is_devnet));
126    // Validate the provided consensus heights.
127    validate_consensus_heights(&consensus_heights)
128        .map_err(|e| CliError::custom(format!("Invalid consensus heights: {e}")))?;
129    // Print the consensus heights being used.
130    let consensus_heights_string = consensus_heights.iter().format(",").to_string();
131    println!(
132        "\n📢 Using the following consensus heights: {consensus_heights_string}\n  To override, pass in `--consensus-heights` or override the environment variable `CONSENSUS_VERSION_HEIGHTS`.\n"
133    );
134
135    // Set the consensus heights in the environment.
136    #[allow(unsafe_code)]
137    unsafe {
138        // SAFETY:
139        //  - `CONSENSUS_VERSION_HEIGHTS` is only set once and is only read in `snarkvm::prelude::load_consensus_heights`.
140        //  - There are no concurrent threads running at this point in the execution.
141        // WHY:
142        //  - This is needed because there is no way to set the desired consensus heights for a particular `VM` instance
143        //    without using the environment variable `CONSENSUS_VERSION_HEIGHTS`. Which is itself read once, and stored in a `OnceLock`.
144        std::env::set_var("CONSENSUS_VERSION_HEIGHTS", consensus_heights_string);
145    }
146
147    // Get all the programs but tests.
148    let programs = package.programs.iter().filter(|program| !program.is_test).cloned();
149
150    let programs_and_bytecode: Vec<(leo_package::Program, String)> = programs
151        .into_iter()
152        .map(|program| {
153            let bytecode = match &program.data {
154                ProgramData::Bytecode(s) => s.clone(),
155                ProgramData::SourcePath { .. } => {
156                    // We need to read the bytecode from the filesystem.
157                    let aleo_name = format!("{}.aleo", program.name);
158                    let aleo_path = if package.manifest.program == aleo_name {
159                        // The main program in the package, so its .aleo file
160                        // will be in the build directory.
161                        package.build_directory().join("main.aleo")
162                    } else {
163                        // Some other dependency, so look in `imports`.
164                        package.imports_directory().join(aleo_name)
165                    };
166                    fs::read_to_string(aleo_path.clone())
167                        .map_err(|e| CliError::custom(format!("Failed to read file {}: {e}", aleo_path.display())))?
168                }
169            };
170
171            Ok((program, bytecode))
172        })
173        .collect::<Result<_>>()?;
174
175    // Parse the fee options.
176    let fee_options = parse_fee_options(&private_key, &command.fee_options, programs_and_bytecode.len())?;
177
178    let tasks: Vec<Task<N>> = programs_and_bytecode
179        .into_iter()
180        .zip(fee_options)
181        .map(|((program, bytecode), (_base_fee, priority_fee, record))| {
182            let id_str = format!("{}.aleo", program.name);
183            let id =
184                id_str.parse().map_err(|e| CliError::custom(format!("Failed to parse program ID {id_str}: {e}")))?;
185            let bytecode = bytecode.parse().map_err(|e| CliError::custom(format!("Failed to parse program: {e}")))?;
186            Ok(Task {
187                id,
188                program: bytecode,
189                edition: program.edition,
190                is_local: program.is_local,
191                priority_fee,
192                record,
193            })
194        })
195        .collect::<Result<_>>()?;
196
197    // Get the program IDs.
198    let program_ids = tasks.iter().map(|task| task.id).collect::<Vec<_>>();
199
200    // Split the tasks into local and remote dependencies.
201    let (local, remote) = tasks.into_iter().partition::<Vec<_>, _>(|task| task.is_local);
202
203    // Get the skipped programs.
204    let skipped: HashSet<ProgramID<N>> = local
205        .iter()
206        .filter_map(|task| {
207            let id_string = task.id.to_string();
208            command.skip.iter().any(|skip| id_string.contains(skip)).then_some(task.id)
209        })
210        .collect();
211
212    // Get the consensus version.
213    let consensus_version =
214        get_consensus_version(&command.extra.consensus_version, &endpoint, network, &consensus_heights, &context)?;
215
216    // Print a summary of the deployment plan.
217    print_deployment_plan(
218        &private_key,
219        &address,
220        &endpoint,
221        &network,
222        &local,
223        &skipped,
224        &remote,
225        &check_tasks_for_warnings(&endpoint, network, &local, consensus_version, command),
226        consensus_version,
227        &command.into(),
228    );
229
230    // Prompt the user to confirm the plan.
231    if !confirm("Do you want to proceed with upgrade?", command.extra.yes)? {
232        println!("❌ Upgrade aborted.");
233        return Ok(());
234    }
235
236    // Initialize an RNG.
237    let rng = &mut rand::thread_rng();
238
239    // Initialize a new VM.
240    let vm = VM::from(ConsensusStore::<N, ConsensusMemory<N>>::open(StorageMode::Production)?)?;
241
242    // Load all the programs from the network into the VM.
243    let programs_and_editions = program_ids
244        .iter()
245        .map(|id| {
246            // Load the program from the network.
247            let program = leo_package::Program::fetch(
248                Symbol::intern(&id.name().to_string()),
249                None,
250                context.home()?,
251                network,
252                &endpoint,
253                true,
254            )?;
255            let ProgramData::Bytecode(bytecode) = program.data else {
256                panic!("Expected bytecode when fetching a remote program");
257            };
258            // Parse the program bytecode.
259            let bytecode = Program::<N>::from_str(&bytecode)
260                .map_err(|e| CliError::custom(format!("Failed to parse program: {e}")))?;
261            // Return the bytecode and edition.
262            // Note: We default to edition 1 since snarkVM execute may produce spurious errors if the program does not have a constructor but uses edition 0.
263            Ok((bytecode, program.edition.unwrap_or(1)))
264        })
265        .collect::<Result<Vec<_>>>()?;
266    vm.process().write().add_programs_with_editions(&programs_and_editions)?;
267
268    // Print the programs and their editions in the VM.
269    println!("Loaded the following programs into the VM:");
270    for program_id in vm.process().read().program_ids() {
271        let edition = *vm.process().read().get_stack(program_id)?.program_edition();
272        if program_id.to_string() == "credits.aleo" {
273            println!(" - credits.aleo (default)");
274        } else {
275            println!(" - {program_id} (edition {edition})");
276        }
277    }
278    println!();
279
280    // Specify the query
281    let query = SnarkVMQuery::<N, BlockMemory<N>>::from(
282        endpoint
283            .parse::<Uri>()
284            .map_err(|e| CliError::custom(format!("Failed to parse endpoint URI '{endpoint}': {e}")))?,
285    );
286    // For each of the programs, generate a deployment transaction.
287    let mut transactions = Vec::new();
288    for Task { id, program, priority_fee, record, .. } in local {
289        // If the program is a local dependency that is not skipped, generate a deployment transaction.
290        if !skipped.contains(&id) {
291            println!("📦 Creating deployment transaction for '{}'...\n", id.to_string().bold());
292            // Generate the transaction.
293            let transaction =
294                vm.deploy(&private_key, &program, record, priority_fee.unwrap_or(0), Some(&query), rng)
295                    .map_err(|e| CliError::custom(format!("Failed to generate deployment transaction: {e}")))?;
296            // Get the deployment.
297            let deployment = transaction.deployment().expect("Expected a deployment in the transaction");
298            // Print the deployment stats.
299            print_deployment_stats(&vm, &id.to_string(), deployment, priority_fee, consensus_version)?;
300            // Validate the deployment limits.
301            validate_deployment_limits(deployment, &id, &network)?;
302            // Save the transaction.
303            transactions.push((id, transaction));
304        }
305        // Add the program to the VM.
306        vm.process().write().add_program(&program)?;
307    }
308
309    // If the `print` option is set, print the deployment transaction to the console.
310    // The transaction is printed in JSON format.
311    if command.action.print {
312        for (program_name, transaction) in transactions.iter() {
313            // Pretty-print the transaction.
314            let transaction_json = serde_json::to_string_pretty(transaction)
315                .map_err(|e| CliError::custom(format!("Failed to serialize transaction: {e}")))?;
316            println!("🖨️ Printing deployment for {program_name}\n{transaction_json}")
317        }
318    }
319
320    // If the `save` option is set, save each deployment transaction to a file in the specified directory.
321    // The file format is `program_name.deployment.json`.
322    // The directory is created if it doesn't exist.
323    if let Some(path) = &command.action.save {
324        // Create the directory if it doesn't exist.
325        std::fs::create_dir_all(path).map_err(|e| CliError::custom(format!("Failed to create directory: {e}")))?;
326        for (program_name, transaction) in transactions.iter() {
327            // Save the transaction to a file.
328            let file_path = PathBuf::from(path).join(format!("{program_name}.deployment.json"));
329            println!("💾 Saving deployment for {program_name} at {}", file_path.display());
330            let transaction_json = serde_json::to_string_pretty(transaction)
331                .map_err(|e| CliError::custom(format!("Failed to serialize transaction: {e}")))?;
332            std::fs::write(file_path, transaction_json)
333                .map_err(|e| CliError::custom(format!("Failed to write transaction to file: {e}")))?;
334        }
335    }
336
337    // If the `broadcast` option is set, broadcast each upgrade transaction to the network.
338    if command.action.broadcast {
339        for (i, (program_id, transaction)) in transactions.iter().enumerate() {
340            println!("📡 Broadcasting upgrade for {program_id}...");
341            // Get and confirm the fee with the user.
342            let fee = transaction.fee_transition().expect("Expected a fee in the transaction");
343            if !confirm_fee(&fee, &private_key, &address, &endpoint, network, &context, command.extra.yes)? {
344                println!("⏩ Upgrade skipped.");
345                continue;
346            }
347            let fee_id = fee.id().to_string();
348            let id = transaction.id().to_string();
349            let height_before = check_transaction::current_height(&endpoint, network)?;
350            // Broadcast the transaction to the network.
351            let (message, status) = handle_broadcast(
352                &format!("{endpoint}/{network}/transaction/broadcast"),
353                transaction,
354                &program_id.to_string(),
355            )?;
356
357            let fail_and_prompt = |msg| {
358                println!("❌ Failed to upgrade program {program_id}: {msg}.");
359                let count = transactions.len() - i - 1;
360                // Check if the user wants to continue with the next upgrade.
361                if count > 0 {
362                    confirm("Do you want to continue with the next upgrade?", command.extra.yes)
363                } else {
364                    Ok(false)
365                }
366            };
367
368            match status {
369                200..=299 => {
370                    let status = check_transaction::check_transaction_with_message(
371                        &id,
372                        Some(&fee_id),
373                        &endpoint,
374                        network,
375                        height_before + 1,
376                        command.extra.max_wait,
377                        command.extra.blocks_to_check,
378                    )?;
379                    if status == Some(TransactionStatus::Accepted) {
380                        println!("✅ Upgrade confirmed!");
381                    } else if fail_and_prompt("could not find the transaction on the network")? {
382                        continue;
383                    } else {
384                        return Ok(());
385                    }
386                }
387                _ => {
388                    if fail_and_prompt(&message)? {
389                        continue;
390                    } else {
391                        return Ok(());
392                    }
393                }
394            }
395        }
396    }
397
398    Ok(())
399}
400
401/// Check the tasks to warn the user about any potential issues.
402/// The following properties are checked:
403/// - If the transaction is to be broadcast:
404///     - The program exists on the network and the new program is a valid upgrade.
405///     - If the consensus version is less than V9, the program does not use V9 features.
406///     - If the consensus version is V9 or greater, the program contains a constructor.
407fn check_tasks_for_warnings<N: Network>(
408    endpoint: &str,
409    network: NetworkName,
410    tasks: &[Task<N>],
411    consensus_version: ConsensusVersion,
412    command: &LeoUpgrade,
413) -> Vec<String> {
414    let mut warnings = Vec::new();
415    for Task { id, program, is_local, .. } in tasks {
416        if !is_local || !command.action.broadcast {
417            continue;
418        }
419
420        // Check if the program exists on the network.
421        if let Ok(remote_program) = fetch_program_from_network(&id.to_string(), endpoint, network) {
422            // Parse the program.
423            let remote_program = match Program::<N>::from_str(&remote_program) {
424                Ok(program) => program,
425                Err(e) => {
426                    warnings.push(format!("Could not parse '{id}' from the network. Error: {e}",));
427                    continue;
428                }
429            };
430            // Check if the program is a valid upgrade.
431            if remote_program.contains_constructor() {
432                if let Err(e) = Stack::check_upgrade_is_valid(&remote_program, program) {
433                    warnings.push(format!(
434                        "The program '{id}' is not a valid upgrade. The upgrade will likely fail. Error: {e}",
435                    ));
436                }
437            } else if consensus_version >= ConsensusVersion::V8 {
438                warnings.push(format!("The program '{id}' can only ever be upgraded once and its contents cannot be changed. Otherwise, the upgrade will likely fail."));
439            } else {
440                warnings.push(format!("The program '{id}' does not have a constructor and is not eligible for a one-time upgrade (>= `ConsensusVersion::V8`). The upgrade will likely fail."));
441            }
442        } else {
443            warnings.push(format!("The program '{id}' does not exist on the network. The upgrade will likely fail.",));
444        }
445        // Check if the program has a valid naming scheme.
446        if consensus_version >= ConsensusVersion::V7 {
447            if let Err(e) = program.check_program_naming_structure() {
448                warnings.push(format!(
449                    "The program '{id}' has an invalid naming scheme: {e}. The deployment will likely fail."
450                ));
451            }
452        }
453        // Check if the program contains restricted keywords.
454        if let Err(e) = program.check_restricted_keywords_for_consensus_version(consensus_version) {
455            warnings.push(format!(
456                "The program '{id}' contains restricted keywords for consensus version {}: {e}. The deployment will likely fail.",
457                consensus_version as u8
458            ));
459        }
460        // Check if the program uses V9 features.
461        if consensus_version < ConsensusVersion::V9 && program.contains_v9_syntax() {
462            warnings.push(format!("The program '{id}' uses V9 features but the consensus version is less than V9. The upgrade will likely fail"));
463        }
464        // Check if the program contains a constructor.
465        if consensus_version >= ConsensusVersion::V9 && !program.contains_constructor() {
466            warnings.push(format!("The program '{id}' does not contain a constructor. The upgrade will likely fail",));
467        }
468        // Check for a consensus version mismatch.
469        if let Err(e) = check_consensus_version_mismatch(consensus_version, endpoint, network) {
470            warnings.push(format!("{e}. In some cases, the deployment may fail"));
471        }
472    }
473    warnings
474}
475
476// Convert the `LeoUpgrade` into a `LeoDeploy` command.
477impl From<&LeoUpgrade> for LeoDeploy {
478    fn from(upgrade: &LeoUpgrade) -> Self {
479        Self {
480            fee_options: upgrade.fee_options.clone(),
481            action: upgrade.action.clone(),
482            env_override: upgrade.env_override.clone(),
483            extra: upgrade.extra.clone(),
484            skip: upgrade.skip.clone(),
485            build_options: upgrade.build_options.clone(),
486        }
487    }
488}
leo_lang/cli/commands/upgrade.rs

leo_lang/cli/commands/
upgrade.rs
