Skip to content
light theme Algorand Developer Portal dark theme Algorand Developer Portal Algorand Developer Portal

Transaction Simulation

← Back to Algod Client

Description

Section titled “Description”

This example demonstrates how to simulate transactions before submitting them to the Algorand network. Simulation allows you to:

  • Preview transaction outcomes without committing to the blockchain
  • Estimate transaction fees
  • Detect potential errors before spending fees
  • Debug smart contract execution

Prerequisites

Section titled “Prerequisites”
  • LocalNet running (via algokit localnet start)

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example algod_client/13-simulation.ts

Code

Section titled “Code”

View source on GitHub

13-simulation.ts
/**
 * Example: Transaction Simulation
 *
 * This example demonstrates how to simulate transactions before submitting them
 * to the Algorand network. Simulation allows you to:
 * - Preview transaction outcomes without committing to the blockchain
 * - Estimate transaction fees
 * - Detect potential errors before spending fees
 * - Debug smart contract execution
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


import { algo } from '@algorandfoundation/algokit-utils'
import type {
  SimulateRequest,
} from '@algorandfoundation/algokit-utils/algod-client'
import {
  createAlgodClient,
  createAlgorandClient,
  formatMicroAlgo,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js'


async function main() {
  printHeader('Transaction Simulation Example')


  // Create clients
  const algod = createAlgodClient()
  const algorand = createAlgorandClient()


  // =========================================================================
  // Step 1: Set up accounts for simulation
  // =========================================================================
  printStep(1, 'Setting up accounts for simulation')


  // Get a funded account from LocalNet (the dispenser)
  const sender = await algorand.account.dispenserFromEnvironment()
  printInfo(`Sender address: ${shortenAddress(sender.addr.toString())}`)


  // Get sender balance
  const senderInfo = await algod.accountInformation(sender.addr.toString())
  printInfo(`Sender balance: ${formatMicroAlgo(senderInfo.amount)}`)


  // Create a new random account as receiver
  const receiver = algorand.account.random()
  printInfo(`Receiver address: ${shortenAddress(receiver.addr.toString())}`)
  printInfo('Receiver is a new unfunded account')
  printInfo('')


  // =========================================================================
  // Step 2: Create a payment transaction for simulation
  // =========================================================================
  printStep(2, 'Creating a payment transaction for simulation')


  const paymentAmount = algo(1) // 1 ALGO
  printInfo(`Payment amount: ${paymentAmount.algo} ALGO`)


  // Build the transaction using AlgorandClient.createTransaction
  const paymentTxn = await algorand.createTransaction.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: paymentAmount,
  })


  // Get the transaction ID
  const txId = paymentTxn.txId()
  printInfo(`Transaction ID: ${txId}`)


  // Sign the transaction
  const signedTxn = await sender.signer([paymentTxn], [0])
  printSuccess('Transaction signed successfully!')
  printInfo('')


  // =========================================================================
  // Step 3: Simulate using simulateRawTransactions()
  // =========================================================================
  printStep(3, 'Simulating with simulateRawTransactions(signedTxns)')


  printInfo('simulateRawTransactions() is a convenience method that:')
  printInfo('  - Accepts encoded signed transactions (Uint8Array or Uint8Array[])')
  printInfo('  - Decodes and wraps them in a SimulateRequest')
  printInfo('  - Returns SimulateResponse with detailed results')
  printInfo('')


  const simResult = await algod.simulateRawTransactions(signedTxn)


  printSuccess('Simulation completed!')
  printInfo('')


  // =========================================================================
  // Step 4: Display simulation results
  // =========================================================================
  printStep(4, 'Displaying simulation results')


  printInfo('SimulateResponse structure:')
  printInfo(`  version: ${simResult.version}`)
  printInfo(`  lastRound: ${simResult.lastRound.toLocaleString('en-US')}`)
  printInfo(`  txnGroups: ${simResult.txnGroups.length} group(s)`)
  printInfo('')


  // Check if the transaction would succeed
  const txnGroup = simResult.txnGroups[0]
  const wouldSucceed = !txnGroup.failureMessage


  printInfo('Transaction Group Result:')
  printInfo(`  Would succeed: ${wouldSucceed ? 'Yes' : 'No'}`)
  if (txnGroup.failureMessage) {
    printInfo(`  Failure message: ${txnGroup.failureMessage}`)
    if (txnGroup.failedAt) {
      printInfo(`  Failed at: [${txnGroup.failedAt.join(', ')}]`)
    }
  }
  printInfo('')


  // Display budget information (for app calls)
  if (txnGroup.appBudgetAdded !== undefined || txnGroup.appBudgetConsumed !== undefined) {
    printInfo('App Budget:')
    printInfo(`  Budget added: ${txnGroup.appBudgetAdded ?? 'N/A'}`)
    printInfo(`  Budget consumed: ${txnGroup.appBudgetConsumed ?? 'N/A'}`)
    printInfo('')
  }


  // =========================================================================
  // Step 5: Display individual transaction results and fixedSigner
  // =========================================================================
  printStep(5, 'Displaying individual transaction results')


  for (let i = 0; i < txnGroup.txnResults.length; i++) {
    const txnResult = txnGroup.txnResults[i]
    printInfo(`Transaction ${i + 1}:`)


    // The txnResult contains a PendingTransactionResponse
    const pendingResponse = txnResult.txnResult
    printInfo(`  Transaction type: ${pendingResponse.txn.txn.type}`)


    // Display fixedSigner if present (indicates missing/wrong signature)
    if (txnResult.fixedSigner) {
      printInfo(`  Fixed signer: ${shortenAddress(txnResult.fixedSigner.toString())}`)
      printInfo('  ^ This indicates the correct signer when simulation used allowEmptySignatures or fixSigners')
    } else {
      printInfo('  Fixed signer: None (signature was correct)')
    }


    // Display budget consumed (for app calls)
    if (txnResult.appBudgetConsumed !== undefined) {
      printInfo(`  App budget consumed: ${txnResult.appBudgetConsumed}`)
    }


    if (txnResult.logicSigBudgetConsumed !== undefined) {
      printInfo(`  LogicSig budget consumed: ${txnResult.logicSigBudgetConsumed}`)
    }
    printInfo('')
  }


  // =========================================================================
  // Step 6: Show transaction group details
  // =========================================================================
  printStep(6, 'Show transaction group details from simulation')


  printInfo('Each SimulateTransactionResult contains txnResult (PendingTransactionResponse)')
  printInfo('which includes the transaction details as if it were confirmed.')
  printInfo('')


  const txnDetails = txnGroup.txnResults[0].txnResult
  printInfo('Simulated Transaction Details:')
  printInfo(`  Type: ${txnDetails.txn.txn.type}`)
  printInfo(`  Sender: ${shortenAddress(txnDetails.txn.txn.sender.toString())}`)
  printInfo(`  Fee: ${formatMicroAlgo(txnDetails.txn.txn.fee ?? 0n)}`)
  printInfo(`  First valid: ${txnDetails.txn.txn.firstValid.toLocaleString('en-US')}`)
  printInfo(`  Last valid: ${txnDetails.txn.txn.lastValid.toLocaleString('en-US')}`)


  if (txnDetails.txn.txn.payment) {
    printInfo('')
    printInfo('  Payment fields:')
    printInfo(`    Receiver: ${shortenAddress(txnDetails.txn.txn.payment.receiver.toString())}`)
    printInfo(`    Amount: ${formatMicroAlgo(txnDetails.txn.txn.payment.amount)}`)
  }
  printInfo('')


  // =========================================================================
  // Step 7: Demonstrate simulation with extra budget options
  // =========================================================================
  printStep(7, 'Demonstrating simulation with extra budget options')


  printInfo('simulateTransactions() accepts a SimulateRequest with various options:')
  printInfo('  - allowEmptySignatures: Simulate unsigned transactions')
  printInfo('  - allowMoreLogging: Lift limits on log opcode usage')
  printInfo('  - allowUnnamedResources: Access resources not in txn references')
  printInfo('  - extraOpcodeBudget: Add extra opcode budget for app calls')
  printInfo('  - fixSigners: Auto-fix incorrect signers in simulation')
  printInfo('')


  // Demonstrate with allowEmptySignatures (useful for fee estimation without signing)
  printInfo('Simulating an UNSIGNED transaction with allowEmptySignatures=true:')
  printInfo('')


  // Create an unsigned transaction
  const unsignedTxn = await algorand.createTransaction.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0.5),
  })


  // Import SignedTransaction type to create unsigned wrapper
  const { decodeSignedTransaction, encodeSignedTransaction } = await import('@algorandfoundation/algokit-transact')


  // Create a "signed" transaction with no actual signature for simulation
  // We encode the transaction without a signature - using the signer but only getting the transaction portion
  const unsignedForSim: SimulateRequest = {
    txnGroups: [{
      txns: [{
        txn: unsignedTxn,
        // No sig field - transaction is unsigned
      }]
    }],
    allowEmptySignatures: true,  // Key option: allow unsigned transactions
    fixSigners: true,            // Fix any signer issues during simulation
  }


  const unsignedSimResult = await algod.simulateTransactions(unsignedForSim)


  printInfo('Unsigned transaction simulation result:')
  printInfo(`  Would succeed: ${!unsignedSimResult.txnGroups[0].failureMessage ? 'Yes' : 'No'}`)


  // Check if fixedSigner shows the required signer
  const fixedSignerResult = unsignedSimResult.txnGroups[0].txnResults[0]
  if (fixedSignerResult.fixedSigner) {
    printInfo(`  Required signer: ${shortenAddress(fixedSignerResult.fixedSigner.toString())}`)
  }
  printInfo('')


  // Demonstrate with extraOpcodeBudget
  printInfo('extraOpcodeBudget is useful for complex app calls that need more compute:')
  printInfo('')


  const extraBudgetRequest: SimulateRequest = {
    txnGroups: [{
      txns: [{
        txn: unsignedTxn,
      }]
    }],
    allowEmptySignatures: true,
    extraOpcodeBudget: 10000, // Add 10,000 extra opcodes
  }


  const extraBudgetResult = await algod.simulateTransactions(extraBudgetRequest)
  printInfo('Simulation with extra budget:')
  printInfo(`  Would succeed: ${!extraBudgetResult.txnGroups[0].failureMessage ? 'Yes' : 'No'}`)
  printInfo(`  (extraOpcodeBudget is mainly useful for app calls, not simple payments)`)
  printInfo('')


  // =========================================================================
  // Step 8: Show how simulation can estimate fees and detect errors
  // =========================================================================
  printStep(8, 'Using simulation to estimate fees and detect errors')


  printInfo('Simulation helps with fee estimation by:')
  printInfo('  1. Determining minimum fee for transaction to succeed')
  printInfo('  2. Checking if your fee is sufficient before sending')
  printInfo('  3. Avoiding wasted fees on transactions that would fail')
  printInfo('')


  // Get current suggested params to show fee structure
  const params = await algod.suggestedParams()
  printInfo('Current fee structure:')
  printInfo(`  Min fee: ${formatMicroAlgo(params.minFee)}`)
  printInfo(`  Suggested fee: ${formatMicroAlgo(params.fee)}`)
  printInfo('')


  printInfo('Simulation can detect errors BEFORE spending fees:')
  printInfo('')


  // Error detection example - insufficient balance
  printInfo('Example: Detecting an overspend error')


  // Create a transaction that would overspend
  const poorAccount = algorand.account.random()
  const overspendTxn = await algorand.createTransaction.payment({
    sender: poorAccount.addr,
    receiver: receiver.addr,
    amount: algo(1000000), // 1 million ALGO - way more than account has
  })


  const overspendRequest: SimulateRequest = {
    txnGroups: [{
      txns: [{
        txn: overspendTxn,
      }]
    }],
    allowEmptySignatures: true,
  }


  const overspendResult = await algod.simulateTransactions(overspendRequest)
  const overspendGroup = overspendResult.txnGroups[0]


  printInfo('  Overspend simulation result:')
  printInfo(`    Would succeed: ${!overspendGroup.failureMessage ? 'Yes' : 'No'}`)
  if (overspendGroup.failureMessage) {
    printInfo(`    Failure: ${overspendGroup.failureMessage}`)
  }
  printInfo('')


  // =========================================================================
  // Step 9: Simulate a failing transaction and display the failure reason
  // =========================================================================
  printStep(9, 'Simulating a failing transaction')


  printInfo('Demonstrating various failure scenarios:')
  printInfo('')


  // Failure scenario 1: Insufficient funds (already shown above)
  printInfo('1. Insufficient funds:')
  printInfo(`   Error: ${overspendGroup.failureMessage}`)
  printInfo('')


  // Failure scenario 2: Invalid receiver address - let's try sending to the sender (self-send is OK, but we can show transaction with close-remainder issue)
  printInfo('2. Sending to zero balance account and closing:')
  printInfo('   Simulating a close-out transaction to demonstrate simulation details')


  // Create a transaction that closes out to a specific address
  const closeOutTxn = await algorand.createTransaction.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0),
    closeRemainderTo: receiver.addr, // Close account to receiver
  })


  const closeOutRequest: SimulateRequest = {
    txnGroups: [{
      txns: [{
        txn: closeOutTxn,
      }]
    }],
    allowEmptySignatures: true,
  }


  const closeOutResult = await algod.simulateTransactions(closeOutRequest)
  const closeOutGroup = closeOutResult.txnGroups[0]


  printInfo(`   Would succeed: ${!closeOutGroup.failureMessage ? 'Yes' : 'No'}`)
  if (closeOutGroup.failureMessage) {
    printInfo(`   Failure: ${closeOutGroup.failureMessage}`)
  } else {
    printInfo('   This would succeed (sender can close to receiver)')
  }
  printInfo('')


  // Failure scenario 3: Insufficient fee (below minimum)
  printInfo('3. Transaction with fee below minimum:')
  printInfo('   Note: Very low fees are rejected before simulation even runs')


  // Create a transaction with a fee set to 0 (below min fee of 1000)
  const lowFeeTxn = await algorand.createTransaction.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0.1),
    staticFee: algo(0), // 0 fee - below minimum
  })


  const lowFeeRequest: SimulateRequest = {
    txnGroups: [{
      txns: [{
        txn: lowFeeTxn,
      }]
    }],
    allowEmptySignatures: true,
  }


  try {
    const lowFeeResult = await algod.simulateTransactions(lowFeeRequest)
    const lowFeeGroup = lowFeeResult.txnGroups[0]
    printInfo(`   Would succeed: ${!lowFeeGroup.failureMessage ? 'Yes' : 'No'}`)
    if (lowFeeGroup.failureMessage) {
      printInfo(`   Failure: ${lowFeeGroup.failureMessage}`)
    }
  } catch (error) {
    // Fee too low errors are caught at the API level, not in simulation results
    const errorMessage = error instanceof Error ? error.message : String(error)
    if (errorMessage.includes('less than the minimum')) {
      printInfo(`   Rejected before simulation: Fee too low`)
      printInfo('   Algod validates minimum fees before running simulation')
    } else {
      printInfo(`   Error: ${errorMessage}`)
    }
  }
  printInfo('')


  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary')


  printInfo('This example demonstrated:')
  printInfo('')
  printInfo('1. simulateRawTransactions(signedTxns):')
  printInfo('   - Convenience method for simulating encoded signed transactions')
  printInfo('   - Accepts Uint8Array or Uint8Array[] (signed transaction bytes)')
  printInfo('   - Returns SimulateResponse with detailed results')
  printInfo('')
  printInfo('2. SimulateResponse structure:')
  printInfo('   - version: API version number')
  printInfo('   - lastRound: Round at which simulation was performed')
  printInfo('   - txnGroups: Array of SimulateTransactionGroupResult')
  printInfo('')
  printInfo('3. SimulateTransactionGroupResult:')
  printInfo('   - txnResults: Array of individual transaction results')
  printInfo('   - failureMessage?: Error message if group would fail')
  printInfo('   - failedAt?: Index path to failing transaction')
  printInfo('   - appBudgetAdded/Consumed: App call budget tracking')
  printInfo('')
  printInfo('4. SimulateTransactionResult:')
  printInfo('   - txnResult: PendingTransactionResponse with full details')
  printInfo('   - fixedSigner?: Address that should have signed')
  printInfo('   - appBudgetConsumed: Budget used by this transaction')
  printInfo('   - logicSigBudgetConsumed: Budget used by logic signature')
  printInfo('')
  printInfo('5. SimulateRequest options:')
  printInfo('   - allowEmptySignatures: Simulate without signatures')
  printInfo('   - allowMoreLogging: Lift log opcode limits')
  printInfo('   - allowUnnamedResources: Access unref\'d resources')
  printInfo('   - extraOpcodeBudget: Add extra compute budget')
  printInfo('   - fixSigners: Auto-fix incorrect signers')
  printInfo('')
  printInfo('6. Use cases for simulation:')
  printInfo('   - Fee estimation without signing')
  printInfo('   - Error detection before spending fees')
  printInfo('   - Debugging smart contract execution')
  printInfo('   - Validating transaction groups')
  printInfo('   - Testing complex app interactions')
}


main().catch((error) => {
  console.error('Fatal error:', error)
  process.exit(1)
})

Other examples in Algod Client

Section titled “Other examples in Algod Client”