Upgrade an existing program that has already been deployed to the Aleo network. This command creates upgrade transactions for programs with constructors, allowing you to modify program logic while maintaining state.
Usage
Options
Fee Options
Priority fee in microcredits. Higher fees may result in faster confirmation.
Record to use for paying the priority fee
Transaction Actions
Broadcast the upgrade transaction to the network
Save the upgrade transaction to the specified directory
Print the upgrade transaction in JSON format
Environment Options
Network to deploy to (mainnet, testnet, canary)
Private key for signing (can also use PRIVATE_KEY environment variable)
Build Options
Skip upgrade of programs containing these substrings
--skip-deploy-certificate
Skip deployment certificate generation (advanced usage)
Skip confirmation prompts
Examples
Basic upgrade
Upgrade with priority fee
leo upgrade --broadcast --priority-fee 1000000
Save upgrade transaction without broadcasting
leo upgrade --save ./transactions
Skip specific programs
leo upgrade --skip "test" --skip "debug" --broadcast
Upgrade to mainnet
leo upgrade --network mainnet --broadcast
Upgrade Requirements
Constructor Required: Only programs with a constructor (marked with @noupgrade or regular constructor) can be upgraded. Programs without constructors can only be upgraded once using special migration rules.
Valid Upgrade Rules
- Constructor Must Exist: New version must have a constructor
- Mappings Cannot Change: Mapping definitions must remain identical
- Records Can Be Added: New record types can be added
- Function Signatures: Can modify logic but some constraints apply
- Edition Increments: Edition number automatically increments
Example Valid Constructor
program token.aleo {
@noupgrade
constructor() {}
// Program logic can be modified in upgrades
fn transfer(amount: u64) -> bool {
return true;
}
}
Upgrade Process
Build updated program
Leo automatically builds your project before upgrading.# Happens automatically
leo build
Verify program exists on network
The command checks that the program is already deployed.# Automatic validation
# Error if program not found on network
Validate upgrade compatibility
Checks that the upgrade follows all rules:
- Constructor requirements
- Mapping compatibility
- Naming structure
- Consensus version compatibility
Generate upgrade transaction
Creates the upgrade deployment transaction with incremented edition.📦 Creating deployment transaction for 'program.aleo'...
Broadcast or save
Either broadcasts to network or saves to file.# Broadcast
📡 Broadcasting upgrade for program.aleo...
✅ Upgrade confirmed!
Upgrade Validation
Before upgrading, the command validates:
Program Existence
Checking if program exists on network...
✓ Found program.aleo (edition 0)
Upgrade Compatibility
Validating upgrade rules...
✓ Constructor present
✓ Mappings unchanged
✓ Naming structure valid
Warnings
⚠️ Warnings:
- The program 'token.aleo' can only ever be upgraded once
Edition System
Each upgrade increments the program’s edition number:
Current on-chain: token.aleo (edition 0)
After upgrade: token.aleo (edition 1)
- Key generation
- Transaction validation
- State migration
Cost Estimation
The command displays estimated costs before broadcasting:
Upgrade Cost Estimate:
Base Fee: 1,000,000 microcredits
Storage Fee: 2,500,000 microcredits
Priority Fee: 0 microcredits
Total: 3,500,000 microcredits
JSON Output
Enable --json-output for machine-readable results:
{
"config": {
"address": "aleo1...",
"network": "testnet",
"endpoint": "https://api.explorer.provable.com/v1"
},
"deployments": [
{
"program": "token.aleo",
"transaction_id": "at1...",
"edition": 1
}
]
}
Consensus Versions
Different consensus versions have different upgrade rules:
- V7+: Program naming structure validation
- V8+: One-time upgrades for programs without constructors
- V9+: Constructor required for all upgrades
Common Issues
Program not found on network
# Check if program is deployed
leo query program token.aleo
Invalid upgrade: mapping changed
Mapping definitions cannot be modified:
// Cannot change this in upgrade:
mapping balances: address => u64;
Constructor missing
Add a constructor to your program:
@noupgrade
constructor() {}
- Deploy - Initial program deployment
- Build - Compile programs
- Execute - Execute program functions
Best Practices
Test upgrades on testnet first: Always verify upgrade compatibility on testnet before upgrading mainnet programs.
Use version control: Tag each upgrade in git to track program evolution.
State preservation: Upgrades preserve all on-chain state including mapping values and program balance.
Troubleshooting
Upgrade transaction fails
Check the error message for specific validation failures:
leo upgrade --broadcast
# Review error output
# Fix issues in source code
# Retry upgrade
Fee estimation errors
Ensure you have sufficient balance:
Consensus version mismatch
Update the consensus heights if needed:
leo upgrade --consensus-heights "0,100,200" --broadcast
