erst simulate-upgrade

Simulate a transaction with upgraded contract code

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

Basic upgrade simulation

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

Testing bug fixes

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

Performance improvements

Measure the performance impact of optimizations:

# Compare CPU/memory usage
erst simulate-upgrade <tx-hash> --new-wasm ./optimized.wasm

Breaking change detection

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.

Related commands

• compare - Compare local vs on-chain execution side-by-side
• init - Initialize Erst workspace for testing
• doctor - Verify environment setup