> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dotandev/hintents/llms.txt
> Use this file to discover all available pages before exploring further.

# erst compare

> Compare local WASM vs on-chain execution side-by-side

Simultaneously replay a transaction against a local WASM file and the on-chain contract, then display a side-by-side diff.

## Usage

```bash theme={null}
erst compare <transaction-hash> [flags]
```

## Description

The `compare` command is the primary tool for "What broke when I updated my contract?" debugging. It works by:

1. Fetching the transaction envelope and ledger state from the network
2. Running two simulation passes in parallel:
   * **Pass A**: Uses your local WASM file (`--wasm`)
   * **Pass B**: Uses the on-chain WASM (normal replay)
3. Displaying a color-coded side-by-side diff of the results

<Info>
  This command is essential for testing contract changes before deployment and understanding behavioral differences.
</Info>

## Examples

<CodeGroup>
  ```bash Compare on mainnet theme={null}
  erst compare abc123...def --wasm ./my_contract.wasm
  ```

  ```bash Compare on testnet theme={null}
  erst compare abc123...def --wasm ./contract.wasm --network testnet
  ```

  ```bash Verbose comparison theme={null}
  erst compare abc123...def --wasm ./contract.wasm --verbose
  ```

  ```bash Override protocol version theme={null}
  erst compare abc123...def --wasm ./contract.wasm --protocol-version 22
  ```

  ```bash With optimization theme={null}
  erst compare abc123...def --wasm ./contract.wasm --optimize
  ```
</CodeGroup>

## Arguments

<ParamField path="transaction-hash" type="string" required>
  Stellar transaction hash to replay and compare
</ParamField>

## Flags

### Required

<ParamField path="--wasm" type="string" required>
  Path to local WASM file for comparison

  This is the contract version you want to test against the on-chain version.
</ParamField>

### Network configuration

<ParamField path="--network" type="string" default="mainnet">
  Stellar network to use

  Options: `testnet`, `mainnet`, `futurenet`

  Alias: `-n`
</ParamField>

<ParamField path="--rpc-url" type="string">
  Custom Soroban RPC URL

  Can specify multiple URLs separated by commas for fallback.
</ParamField>

<ParamField path="--rpc-token" type="string">
  RPC authentication token

  Can also use `ERST_RPC_TOKEN` environment variable.
</ParamField>

### Optimization

<ParamField path="--optimize" type="boolean" default="false">
  Run dead-code elimination on local WASM before simulation

  Useful for comparing optimized vs unoptimized builds.
</ParamField>

<ParamField path="--args" type="string[]">
  Mock arguments to pass to the local WASM execution

  Can be specified multiple times: `--args arg1 --args arg2`
</ParamField>

### Output options

<ParamField path="--verbose" type="boolean" default="false">
  Print full simulation JSON for both passes

  Alias: `-v`
</ParamField>

<ParamField path="--theme" type="string">
  Color theme for diff output

  Options: `default`, `deuteranopia`, `protanopia`, `tritanopia`, `high-contrast`
</ParamField>

### Advanced options

<ParamField path="--protocol-version" type="uint32">
  Override protocol version for both simulation passes

  Examples: 20, 21, 22
</ParamField>

<ParamField path="--sim-path" type="string">
  Path to erst-sim binary

  Overrides auto-discovery.
</ParamField>

## Output

The compare command displays:

### Header

```
📊  Compare Replay
Transaction : abc123...def
Network     : mainnet
Local WASM  : ./my_contract.wasm
```

If `--optimize` is used, shows optimization report:

```
Optimization:
  Original size: 245.3 KB
  Optimized size: 189.7 KB
  Reduction: 55.6 KB (22.7%)
```

### Side-by-side diff

Displays differences in:

* **Events**: Contract events emitted during execution
* **Diagnostic output**: Debug logs and traces
* **Budget usage**: CPU instructions, memory bytes, operations
* **Call paths**: Function call trees showing divergence points
* **Return values**: Different results or error codes

<Tabs>
  <Tab title="Events diff">
    ```diff theme={null}
    Events:
    - Local:    transfer(from=G123..., to=G456..., amount=1000)
    + On-chain: transfer(from=G123..., to=G456..., amount=500)
    ```
  </Tab>

  <Tab title="Budget diff">
    ```diff theme={null}
    Budget Usage:
    - Local:    CPU=1,250,000  Mem=512KB  Ops=45
    + On-chain: CPU=1,180,000  Mem=480KB  Ops=42
    ```
  </Tab>

  <Tab title="Error diff">
    ```diff theme={null}
    Status:
    - Local:    Success
    + On-chain: Error: insufficient balance
    ```
  </Tab>
</Tabs>

## Use cases

### Pre-deployment testing

Test contract changes before deploying:

```bash theme={null}
# Build new version
cargo build --target wasm32-unknown-unknown --release

# Compare with production transaction
erst compare <prod-tx-hash> \
  --wasm ./target/wasm32-unknown-unknown/release/contract.wasm
```

### Debugging behavior changes

Understand why a transaction behaves differently:

```bash theme={null}
# Compare local fix with failing transaction
erst compare <failing-tx-hash> \
  --wasm ./target/debug/contract.wasm \
  --verbose
```

### Optimization validation

Verify optimizations don't change behavior:

```bash theme={null}
# Compare unoptimized vs optimized
erst compare <tx-hash> \
  --wasm ./contract_optimized.wasm \
  --optimize
```

### Protocol upgrade testing

Test contract behavior on new protocol versions:

```bash theme={null}
# Test on protocol 22
erst compare <tx-hash> \
  --wasm ./contract.wasm \
  --protocol-version 22
```

## Parallel execution

Both simulation passes run **in parallel** for performance:

* Faster total execution time
* Identical ledger state for both passes
* Consistent timestamp and protocol version

<Note>
  The parallel execution ensures a fair comparison by using exactly the same network conditions for both passes.
</Note>

## Verbose mode

With `--verbose`, shows full JSON output for each pass:

```json theme={null}
──── VERBOSE: LOCAL WASM ────
  Status : Success
  Events : 3
  DiagEvt: 5
    • transfer(from=..., to=..., amount=1000)
    • approval(owner=..., spender=...)
    • balance_updated(account=..., balance=5000)
  Budget : CPU=1250000  Mem=524288  Ops=45

──── VERBOSE: ON-CHAIN WASM ────
  Status : Success
  Events : 3
  DiagEvt: 5
    • transfer(from=..., to=..., amount=1000)
    • approval(owner=..., spender=...)
    • balance_updated(account=..., balance=5000)
  Budget : CPU=1180000  Mem=491520  Ops=42
```

## Error handling

Common errors and solutions:

### WASM file not found

```
Error: WASM file not found: ./contract.wasm
```

**Solution**: Check the path and ensure the file exists:

```bash theme={null}
ls -lh ./target/wasm32-unknown-unknown/release/*.wasm
```

### Invalid transaction hash

```
Error: invalid transaction hash: abc123
```

**Solution**: Provide a valid 64-character hex hash:

```bash theme={null}
erst compare 5c0a1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab --wasm ./contract.wasm
```

### Simulation failed

```
Error: local WASM simulation failed: invalid contract
```

**Solution**: Ensure WASM is valid and compatible:

```bash theme={null}
# Check WASM file
wasm-opt --validate ./contract.wasm

# Try with optimization
erst compare <tx-hash> --wasm ./contract.wasm --optimize
```

## Related commands

* [debug](/commands/debug) - Debug individual transactions
* [trace](/commands/trace) - Explore execution traces interactively
* [profile](/commands/profile) - Analyze gas consumption differences