Skip to main content
The simulate-upgrade command replays a transaction with new contract code to verify if a planned upgrade will break existing functionality.

​
Usage

erst simulate-upgrade <transaction-hash> --new-wasm <path>

​
Description

This command:
  • Fetches an existing transaction from the network
  • Replaces the contract code with your new WASM file
  • Re-simulates the transaction execution
  • Reports any behavioral changes or failures
This allows you to test contract upgrades before deploying them to the network.

​
Examples

erst simulate-upgrade 5c0a3f2b8e7d... --new-wasm ./contract_v2.wasm

​
Flags

​
--new-wasm
string
required
Path to the new WASM file to test
​
--optimize
boolean
default:"false"
Run dead-code elimination on the WASM before simulation
​
--network
string
default:"mainnet"
Network to fetch transaction from: testnet, mainnet, or futurenet
​
--rpc-url
string
Custom Soroban RPC URL (overrides default for network)

​
Workflow

1

Fetch original transaction

Downloads the transaction envelope and ledger state from the network
2

Load new WASM

Reads and optionally optimizes your new contract code
3

Replace contract code

Substitutes the old contract WASM with your new version
4

Simulate execution

Re-runs the transaction with the new code
5

Compare results

Shows differences in events, budget usage, and outcomes

​
Understanding the output

The simulation output shows: 
Fetching transaction: 5c0a3f2b8e7d... from mainnet
Loaded new WASM code: 45320 bytes

Original execution:
  CPU instructions: 1,245,678
  Memory bytes: 2,345,678
  Events: 12
  Status: Success

Simulated with new WASM:
  CPU instructions: 1,298,432 (+52,754)
  Memory bytes: 2,456,789 (+111,111)
  Events: 12
  Status: Success

✓ Upgrade compatible - no breaking changes detected
If the simulation fails or produces different events, review the changes carefully before deploying the upgrade.

​
Common use cases

Verify that your bug fix resolves the issue without changing behavior for other transactions:
# Simulate the failing transaction with the fix
erst simulate-upgrade <failing-tx-hash> --new-wasm ./fixed_contract.wasm
Measure the performance impact of optimizations:
# Compare CPU/memory usage
erst simulate-upgrade <tx-hash> --new-wasm ./optimized.wasm
Ensure API changes don’t break existing callers:
# Test against real production transactions
erst simulate-upgrade <prod-tx-hash> --new-wasm ./v2.wasm --network mainnet

​
Best practices

Test multiple transactions: Don’t rely on a single transaction. Test your upgrade against a variety of real transactions to catch edge cases.
Use optimization: Always test with --optimize to ensure the deployed WASM will behave the same as your simulation.
Automate testing: Integrate simulate-upgrade into your CI/CD pipeline to catch breaking changes before deployment.
  • compare - Compare local vs on-chain execution side-by-side
  • init - Initialize Erst workspace for testing
  • doctor - Verify environment setup