Transaction Simulation

Validate transactions before submission with pre-flight checks that detect reversion conditions with 99.7% accuracy.

Overview

Transaction simulation executes transactions against current blockchain state without actually submitting them to the network. This pre-flight validation prevents wasted gas from failed transactions and provides detailed insight into transaction outcomes.

How simulation works

Molt402 uses eth_call to simulate transaction execution:

1. Fetch current blockchain state (balances, nonces, contract storage)

2. Execute transaction logic against state snapshot

3. Detect reversion conditions, state changes, and gas consumption

4. Return detailed simulation results

Accuracy: 99.7% of simulations accurately predict on-chain behavior. The 0.3% edge cases involve time-dependent contracts or external oracle calls.

Enable simulation

Automatic simulation

Enable simulation for all transactions:

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  simulation: {
    enabled: true,
    rejectOnFailure: true  // Auto-reject failed simulations
  }
})

Per-transaction simulation

Enable for specific transactions:

const result = await client.execute({
  instruction: "Swap 100 USDC for WETH",
  simulate: true
})

// Check simulation results
if (!result.simulationResult?.success) {
  console.error('Simulation failed:', result.simulationResult.error)
  return
}

console.log(`Estimated gas: ${result.simulationResult.gasUsed}`)

Simulation results

Success response

{
  success: true,
  gasUsed: "125000",
  returnData: "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
  logs: [
    {
      address: "0x1234...",
      topics: ["0xddf252ad...", "0x000000000000000000000000abcd...", ...],
      data: "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000"
    }
  ],
  stateChanges: {
    balances: [
      { address: "0xabcd...", asset: "USDC", before: "1000.0", after: "900.0" },
      { address: "0xabcd...", asset: "WETH", before: "0.5", after: "0.75" }
    ]
  }
}

Failure response

{
  success: false,
  error: {
    reason: "Insufficient USDC balance",
    code: "INSUFFICIENT_BALANCE",
    details: {
      required: "100000000",  // 100 USDC
      available: "50000000"   // 50 USDC
    }
  },
  gasUsed: "0",  // Failed before execution
  revertData: "0x..."
}

Validation checks

Balance verification

Simulation verifies sufficient funds for transaction value plus gas:

const result = await client.execute({
  instruction: "Transfer 100 ETH to 0x1234...",
  simulate: true
})

if (!result.simulationResult?.success) {
  // Error: Insufficient balance
  // Required: 100 ETH + gas
  // Available: 50 ETH
}

Allowance checking

For ERC-20 token operations, simulation checks approval amounts:

const result = await client.execute({
  instruction: "Swap 1000 USDC for WETH on Uniswap",
  simulate: true
})

// Simulation detects missing approval
if (result.simulationResult?.error?.code === "INSUFFICIENT_ALLOWANCE") {
  // Need to approve USDC spending first
  await client.execute({
    instruction: "Approve Uniswap router to spend 1000 USDC"
  })
}

Reversion detection

Simulation catches contract call failures:

const result = await client.execute({
  action: "call",
  contract: "0x1234...",
  method: "withdraw",
  params: [1000],
  simulate: true
})

if (!result.simulationResult?.success) {
  console.log(`Revert reason: ${result.simulationResult.error.reason}`)
  // "Withdrawal amount exceeds available balance"
}

Gas limit validation

Simulation ensures estimated gas doesn't exceed block limit:

const result = await client.execute({
  instruction: "Execute complex multi-step operation",
  simulate: true
})

if (result.simulationResult?.gasUsed > "30000000") {
  console.error('Transaction gas exceeds block limit')
}

Slippage protection

For DEX swaps, simulation validates output amounts:

const result = await client.execute({
  action: "swap",
  inputAsset: "USDC",
  inputAmount: "1000",
  outputAsset: "WETH",
  minOutputAmount: "0.28",  // Minimum acceptable output
  simulate: true
})

if (!result.simulationResult?.success) {
  // Slippage too high, expected output < minimum
}

Advanced simulation

State overrides

Simulate transactions with modified state:

const result = await client.simulate({
  instruction: "Withdraw 1000 USDC from vault",
  stateOverrides: {
    // Simulate with higher balance
    "0xabcd...": {
      balance: "1000000000000000000000"  // 1000 ETH
    },
    // Override contract storage
    "0x1234...": {
      storage: {
        "0x0": "0x0000000000000000000000000000000000000000000000000000000000000001"
      }
    }
  }
})

Use cases:

• Test transactions with different balance scenarios

• Simulate contract upgrades

• Validate emergency procedures

• Test edge cases

Block number simulation

Simulate at specific block heights:

const result = await client.simulate({
  instruction: "Claim vested tokens",
  blockNumber: 12345678  // Simulate at future block
})

Use cases:

• Validate time-locked operations

• Test vesting schedules

• Simulate governance proposal outcomes

Trace analysis

Get detailed execution trace:

const result = await client.simulate({
  instruction: "Complex DeFi operation",
  trace: true
})

// Detailed call stack
console.log(result.simulationResult.trace)
/*
[
  {
    type: "CALL",
    from: "0xabcd...",
    to: "0x1234...",
    value: "0",
    gas: "100000",
    input: "0x...",
    output: "0x...",
    calls: [
      { type: "DELEGATECALL", ... }
    ]
  }
]
*/

Simulation vs actual execution

When simulations differ

0.3% of cases where simulation != actual execution:

Time-dependent contracts: Block timestamp affects outcome

// Contract behavior depends on block.timestamp
require(block.timestamp > vestingEnd, "Still vesting");

External oracle calls: Price feeds update between simulation and execution

// Oracle price changes after simulation
uint256 price = oracle.getLatestPrice();

Mempool state changes: Other transactions modify state before yours

Block-dependent logic: Contracts that check block.number

Handling discrepancies

Use deadlines for time-sensitive operations:

const result = await client.execute({
  action: "swap",
  inputAsset: "USDC",
  inputAmount: "1000",
  outputAsset: "WETH",
  deadline: Date.now() + 300000,  // 5 minute deadline
  simulate: true
})

Set slippage tolerance for DEX operations:

const result = await client.execute({
  action: "swap",
  inputAsset: "USDC",
  inputAmount: "1000",
  outputAsset: "WETH",
  maxSlippagePercent: 0.5,  // 0.5% maximum slippage
  simulate: true
})

Implement retry logic for oracle-dependent transactions:

try {
  const result = await client.execute({
    instruction: "Execute oracle-dependent operation",
    simulate: true
  })

  if (result.simulationResult?.success) {
    // Proceed with submission
  }
} catch (error) {
  if (error.code === "SIMULATION_MISMATCH") {
    // Re-simulate and retry
    await client.execute({ ... })
  }
}

Performance optimization

Simulation caching

Cache simulation results for repeated operations:

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  simulation: {
    enabled: true,
    cache: {
      enabled: true,
      ttl: 30000,  // Cache for 30 seconds
      maxSize: 100  // Cache up to 100 simulations
    }
  }
})

Parallel simulation

Simulate multiple transactions concurrently:

const results = await Promise.all([
  client.simulate({ instruction: "Transfer 10 USDC to Alice" }),
  client.simulate({ instruction: "Transfer 15 USDC to Bob" }),
  client.simulate({ instruction: "Transfer 20 USDC to Carol" })
])

// Check all succeeded
const allSucceeded = results.every(r => r.success)

Lightweight simulation

Skip detailed traces for faster validation:

const result = await client.simulate({
  instruction: "Simple transfer",
  lightweight: true  // Skip trace generation
})

// Only success/failure + gas estimate
console.log(result.success)
console.log(result.gasUsed)

Error handling

Simulation failures

Handle simulation errors gracefully:

const result = await client.execute({
  instruction: "Risky operation",
  simulate: true
})

if (!result.simulationResult?.success) {
  const error = result.simulationResult.error

  switch (error.code) {
    case "INSUFFICIENT_BALANCE":
      console.log(`Need ${error.details.required}, have ${error.details.available}`)
      break

    case "INSUFFICIENT_ALLOWANCE":
      console.log(`Approve ${error.details.required} ${error.details.asset}`)
      break

    case "SLIPPAGE_TOO_HIGH":
      console.log(`Expected ${error.details.minOutput}, got ${error.details.actualOutput}`)
      break

    case "REVERT":
      console.log(`Contract reverted: ${error.reason}`)
      break

    default:
      console.log(`Simulation failed: ${error.message}`)
  }
}

Automatic rejection

Configure automatic rejection on simulation failure:

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  simulation: {
    enabled: true,
    rejectOnFailure: true,  // Never submit failed simulations
    notifyOnFailure: true   // Alert when simulation fails
  }
})

Testing with simulation

Unit tests

import { Molt402Client } from '@molt402/sdk'

describe('Transaction validation', () => {
  let client: Molt402Client

  beforeEach(() => {
    client = new Molt402Client({
      network: 'x402-testnet',
      wallet: testWalletConfig,
      simulation: { enabled: true }
    })
  })

  it('should detect insufficient balance', async () => {
    const result = await client.simulate({
      instruction: "Transfer 1000 ETH to 0x1234..."
    })

    expect(result.success).toBe(false)
    expect(result.error.code).toBe('INSUFFICIENT_BALANCE')
  })

  it('should validate gas estimates', async () => {
    const result = await client.simulate({
      instruction: "Transfer 1 ETH to 0x1234..."
    })

    expect(result.success).toBe(true)
    expect(parseInt(result.gasUsed)).toBeGreaterThan(21000)
  })
})

Integration tests

describe('End-to-end transaction flow', () => {
  it('should simulate, then execute', async () => {
    // Simulate first
    const simulation = await client.simulate({
      instruction: "Swap 100 USDC for WETH"
    })

    expect(simulation.success).toBe(true)

    // Execute if simulation passed
    const result = await client.execute({
      instruction: "Swap 100 USDC for WETH"
    })

    expect(result.txHash).toBeDefined()
  })
})

Production best practices

Always enable simulation: Set simulation.enabled: true in production config

Monitor simulation success rate: Track ratio of successful simulations to failed

Alert on failures: Configure notifications for simulation failures

Log simulation details: Capture full simulation results for debugging

Set rejection policy: Use rejectOnFailure: true to prevent invalid submissions

Test edge cases: Simulate boundary conditions (max balance, zero amounts, etc.)

Cache aggressively: Use simulation cache for repeated operations

Validate assumptions: Don't assume simulation success guarantees execution success

Example: Production configuration

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  simulation: {
    // Always simulate
    enabled: true,

    // Never submit failed simulations
    rejectOnFailure: true,

    // Alert on failures
    notifyOnFailure: true,
    notificationChannels: ['slack', 'email'],

    // Cache for performance
    cache: {
      enabled: true,
      ttl: 30000,
      maxSize: 100
    },

    // Log all simulations
    logging: {
      enabled: true,
      level: 'debug',
      includeTraces: true
    }
  },

  // Alert on anomalies
  alerts: {
    highSimulationFailureRate: {
      threshold: 0.1,  // >10% failure rate
      window: 3600,    // Over 1 hour
      action: 'notify'
    }
  }
})

Troubleshooting

Simulation succeeds but execution fails

Check for time-sensitive contracts or oracle-dependent logic. Add appropriate deadlines and slippage protection.

Simulation too slow

Enable lightweight mode or reduce trace detail. Use caching for repeated operations.

False positive failures

Verify state overrides are correct. Check for stale cached simulations.

Gas estimates inaccurate

Increase gas buffer percentage. Some contracts have variable gas usage based on state.

Next steps

• Gas optimization: Optimize transaction costs

• Error handling: Implement robust retry logic

• Approval policies: Configure transaction permissions

• Monitoring and alerts: Production observability

Support

Questions about transaction simulation?

• Discord: discord.gg/molt402 (#simulation channel)

• Documentation: docs.molt402.dev

• Email: [email protected]