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

Suggested Params Configuration

← Back to Algorand Client

Description

Section titled “Description”

This example demonstrates how to configure suggested transaction parameters:

  • setDefaultValidityWindow() to set the number of rounds a transaction is valid
  • setSuggestedParamsCache() to enable/disable caching
  • setSuggestedParamsCacheTimeout() to set cache duration in milliseconds
  • getSuggestedParams() to manually fetch suggested params
  • Performance benefits of caching when sending multiple transactions

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 algorand_client/04-params-config.ts

Code

Section titled “Code”

View source on GitHub

04-params-config.ts
/**
 * Example: Suggested Params Configuration
 *
 * This example demonstrates how to configure suggested transaction parameters:
 * - setDefaultValidityWindow() to set the number of rounds a transaction is valid
 * - setSuggestedParamsCache() to enable/disable caching
 * - setSuggestedParamsCacheTimeout() to set cache duration in milliseconds
 * - getSuggestedParams() to manually fetch suggested params
 * - Performance benefits of caching when sending multiple transactions
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


import { AlgorandClient, algo } from '@algorandfoundation/algokit-utils'
import { printError, printHeader, printInfo, printStep, printSuccess, shortenAddress } from '../shared/utils.js'


async function main() {
  printHeader('Suggested Params Configuration Example')


  // Initialize client and verify LocalNet is running
  const algorand = AlgorandClient.defaultLocalNet()


  try {
    await algorand.client.algod.status()
    printSuccess('Connected to LocalNet')
  } catch (error) {
    printError(`Failed to connect to LocalNet: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('Make sure LocalNet is running (e.g., algokit localnet start)')
    return
  }


  // Step 1: Understanding suggested params
  printStep(1, 'Understanding suggested params')
  printInfo('Suggested params contain network information needed for transactions:')
  printInfo('  - firstValid: The first round the transaction is valid')
  printInfo('  - lastValid: The last round the transaction is valid (set during tx building)')
  printInfo('  - genesisHash: The hash of the genesis block')
  printInfo('  - genesisId: The network identifier (e.g., "localnet-v1")')
  printInfo('  - fee: The minimum transaction fee')
  printInfo('  - minFee: The minimum fee per byte')


  const params = await algorand.getSuggestedParams()
  printInfo(`\nCurrent suggested params from LocalNet:`)
  printInfo(`  firstValid: ${params.firstValid}`)
  printInfo(`  genesisId: ${params.genesisId}`)
  printInfo(`  fee: ${params.fee} microALGO`)
  printInfo(`  minFee: ${params.minFee} microALGO`)


  printSuccess('Retrieved suggested params from LocalNet')


  // Step 2: Default validity window behavior
  printStep(2, 'Understand default validity window behavior')
  printInfo('The validity window determines: lastValid = firstValid + validityWindow')
  printInfo('Default is 10 rounds, but LocalNet uses 1000 rounds for convenience')
  printInfo('This is set during transaction building, not in suggested params')


  // Create accounts for demonstrating transactions
  const dispenser = await algorand.account.dispenserFromEnvironment()
  const sender = algorand.account.random()
  const receiver = algorand.account.random()


  // Fund the sender
  await algorand.send.payment({
    sender: dispenser.addr,
    receiver: sender.addr,
    amount: algo(10),
  })


  printInfo(`\nSender: ${shortenAddress(sender.addr.toString())}`)
  printInfo(`Receiver: ${shortenAddress(receiver.addr.toString())}`)


  // Send a transaction and inspect its validity window
  const txResult = await algorand.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0.1),
    note: 'Transaction 1',
  })


  // Access the transaction directly from the result
  const tx = txResult.transactions[0]
  printInfo(`\nTransaction built with LocalNet default:`)
  printInfo(`  firstValid: ${tx.firstValid}`)
  printInfo(`  lastValid: ${tx.lastValid}`)
  printInfo(`  Validity window: ${Number(tx.lastValid - tx.firstValid)} rounds (LocalNet default)`)


  printSuccess('Demonstrated default validity window')


  // Step 3: Set custom validity window
  printStep(3, 'Demonstrate setDefaultValidityWindow()')
  printInfo('Use setDefaultValidityWindow() to override the default validity window')
  printInfo('This affects all transactions built by this client')


  // Create a new client with custom validity window
  const algorandCustom = AlgorandClient.defaultLocalNet().setDefaultValidityWindow(50)
  algorandCustom.setSignerFromAccount(sender)


  const txResultCustom = await algorandCustom.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0.1),
    note: 'Transaction with custom validity',
  })


  // Access the transaction directly from the result
  const txCustom = txResultCustom.transactions[0]
  printInfo(`\nTransaction built with setDefaultValidityWindow(50):`)
  printInfo(`  firstValid: ${txCustom.firstValid}`)
  printInfo(`  lastValid: ${txCustom.lastValid}`)
  printInfo(`  Validity window: ${Number(txCustom.lastValid - txCustom.firstValid)} rounds`)


  printSuccess('Demonstrated custom validity window')


  // Step 4: When to use different validity windows
  printStep(4, 'When to use longer vs shorter validity windows')
  printInfo('')
  printInfo('Shorter validity windows (5-10 rounds):')
  printInfo('  - High-frequency trading applications')
  printInfo('  - When you want quick transaction expiration')
  printInfo('  - Reduces risk of delayed/stale transactions being confirmed')
  printInfo('')
  printInfo('Longer validity windows (100-1000 rounds):')
  printInfo('  - Batch operations with many transactions')
  printInfo('  - When network congestion is expected')
  printInfo('  - When user confirmation takes time')
  printInfo('  - Offline signing scenarios')


  printSuccess('Explained validity window use cases')


  // Step 5: Suggested params caching basics
  printStep(5, 'Demonstrate getSuggestedParams() caching')
  printInfo('getSuggestedParams() caches results to avoid repeated network calls')
  printInfo('Default cache timeout is 3 seconds (3000ms)')


  // Create a fresh client to demonstrate caching
  const algorandCache = AlgorandClient.defaultLocalNet()


  // Demonstrate that the cache is working
  printInfo('\nFetching params twice in quick succession...')
  const startTime1 = Date.now()
  await algorandCache.getSuggestedParams()
  const duration1 = Date.now() - startTime1


  const startTime2 = Date.now()
  await algorandCache.getSuggestedParams()
  const duration2 = Date.now() - startTime2


  printInfo(`  First call: ~${duration1}ms (includes network fetch)`)
  printInfo(`  Second call: ~${duration2}ms (from cache)`)


  printSuccess('Demonstrated params caching')


  // Step 6: Configure cache timeout
  printStep(6, 'Demonstrate setSuggestedParamsCacheTimeout()')
  printInfo('Use setSuggestedParamsCacheTimeout() to set how long params are cached')
  printInfo('Value is in milliseconds')


  // Create a client with longer cache timeout
  const algorandLongCache = AlgorandClient.defaultLocalNet().setSuggestedParamsCacheTimeout(60_000)
  printInfo('\nWith setSuggestedParamsCacheTimeout(60_000): 60 second cache')
  printInfo('Good for: High-throughput apps sending many transactions quickly')


  // Create a client with shorter cache timeout
  const algorandShortCache = AlgorandClient.defaultLocalNet().setSuggestedParamsCacheTimeout(500)
  printInfo('With setSuggestedParamsCacheTimeout(500): 0.5 second cache')
  printInfo('Good for: Apps that need the most current round information')


  // Fetch to demonstrate they work
  await algorandLongCache.getSuggestedParams()
  await algorandShortCache.getSuggestedParams()


  printSuccess('Demonstrated cache timeout configuration')


  // Step 7: Manual cache control with setSuggestedParamsCache()
  printStep(7, 'Demonstrate setSuggestedParamsCache()')
  printInfo('Use setSuggestedParamsCache() to manually set cached params')
  printInfo('Useful when you already have params from another source')


  // Get params and set them in a new client
  const cachedParams = await algorand.getSuggestedParams()
  const algorandCached = AlgorandClient.defaultLocalNet()


  // Set cache with explicit expiry
  const cacheExpiry = new Date(Date.now() + 30_000) // 30 seconds from now
  algorandCached.setSuggestedParamsCache(cachedParams, cacheExpiry)


  printInfo(`\nSet cached params with expiry: ${cacheExpiry.toISOString()}`)
  printInfo('Now getSuggestedParams() will return cached value without network call')


  // Verify the cache is being used
  const startCached = Date.now()
  const fromCache = await algorandCached.getSuggestedParams()
  const durationCached = Date.now() - startCached


  printInfo(`Retrieved from cache in ~${durationCached}ms`)
  printInfo(`Cached firstValid: ${fromCache.firstValid}`)


  printSuccess('Demonstrated manual cache setting')


  // Step 8: Performance benefit with multiple transactions
  printStep(8, 'Show performance benefit of caching with multiple transactions')
  printInfo('When sending many transactions, caching reduces network calls')
  printInfo('Each transaction needs suggested params to set validity window')


  // Send 5 transactions with unique notes and measure time
  const numTransactions = 5
  printInfo(`\nSending ${numTransactions} transactions with caching enabled (default)...`)


  const startWithCache = Date.now()
  for (let i = 0; i < numTransactions; i++) {
    await algorand.send.payment({
      sender: sender.addr,
      receiver: receiver.addr,
      amount: algo(0.01),
      note: `Performance test transaction ${i + 1} at ${Date.now()}`,
    })
  }
  const durationWithCache = Date.now() - startWithCache


  printInfo(`  Total time: ${durationWithCache}ms`)
  printInfo(`  Average per transaction: ${(durationWithCache / numTransactions).toFixed(0)}ms`)
  printInfo('  Note: Params are fetched once and cached for subsequent transactions')


  printSuccess('Demonstrated caching performance benefit')


  // Step 9: Method chaining
  printStep(9, 'Method chaining - Configure params fluently')
  printInfo('All configuration methods return the AlgorandClient for chaining')


  const configuredClient = AlgorandClient.defaultLocalNet()
    .setDefaultValidityWindow(25)
    .setSuggestedParamsCacheTimeout(10_000)
    .setSignerFromAccount(sender)


  printInfo(`\nConfigured client with:`)
  printInfo(`  .setDefaultValidityWindow(25)`)
  printInfo(`  .setSuggestedParamsCacheTimeout(10_000)`)
  printInfo(`  .setSignerFromAccount(sender)`)


  // Send a transaction to verify the configuration
  const chainedTxResult = await configuredClient.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(0.01),
    note: 'Chained config test',
  })


  // Access the transaction directly from the result
  const chainedTx = chainedTxResult.transactions[0]
  printInfo(`\nResulting transaction validity window: ${Number(chainedTx.lastValid - chainedTx.firstValid)} rounds`)


  printSuccess('Demonstrated method chaining')


  // Step 10: Summary
  printStep(10, 'Summary')
  printInfo('Suggested params configuration methods:')
  printInfo('')
  printInfo('getSuggestedParams():')
  printInfo('  - Returns cached params or fetches from network')
  printInfo('  - Automatically manages cache expiry')
  printInfo('  - Use for manual param inspection or custom transactions')
  printInfo('')
  printInfo('setDefaultValidityWindow(rounds):')
  printInfo('  - Sets how many rounds a transaction stays valid')
  printInfo('  - Default is 10 rounds (1000 for LocalNet)')
  printInfo('  - Affects lastValid = firstValid + validityWindow')
  printInfo('')
  printInfo('setSuggestedParamsCacheTimeout(milliseconds):')
  printInfo('  - Sets how long params are cached before refresh')
  printInfo('  - Default is 3000ms (3 seconds)')
  printInfo('  - Longer = fewer network calls, possibly stale data')
  printInfo('  - Shorter = more network calls, fresher data')
  printInfo('')
  printInfo('setSuggestedParamsCache(params, until?):')
  printInfo('  - Manually sets cached params')
  printInfo('  - Optional expiry date (defaults to timeout)')
  printInfo('  - Useful when you have params from another source')
  printInfo('')
  printInfo('Best practices:')
  printInfo('  - Use default settings for most applications')
  printInfo('  - Increase cache timeout for high-throughput apps')
  printInfo('  - Use shorter validity windows for time-sensitive transactions')
  printInfo('  - Use longer validity windows for batch operations')


  printSuccess('Suggested Params Configuration example completed!')
}


main().catch((error) => {
  printError(`Unhandled error: ${error instanceof Error ? error.message : String(error)}`)
  process.exit(1)
})

Other examples in Algorand Client

Section titled “Other examples in Algorand Client”