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

Application Information

← Back to Algod Client

Description

Section titled “Description”

This example demonstrates how to retrieve application information using the AlgodClient method: applicationById()

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/10-application-info.ts

Code

Section titled “Code”

View source on GitHub

10-application-info.ts
/**
 * Example: Application Information
 *
 * This example demonstrates how to retrieve application information using
 * the AlgodClient method: applicationById()
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


import {
  createAlgodClient,
  createAlgorandClient,
  getFundedAccount,
  loadTealSource,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';


/** Decode a TEAL value for display */
function decodeTealValue(value: { type: number; bytes: Uint8Array; uint: bigint }): string {
  if (value.type === 2) {
    // uint
    return `${value.uint} (uint)`
  } else if (value.type === 1) {
    // bytes
    // Try to decode as UTF-8 string, fall back to hex
    try {
      const str = new TextDecoder().decode(value.bytes)
      // Check if it's a printable string
      if (/^[\x20-\x7E]*$/.test(str) && str.length > 0) {
        return `"${str}" (bytes)`
      }
    } catch {
      // Ignore decode errors
    }
    return `0x${Buffer.from(value.bytes).toString('hex')} (bytes)`
  }
  return '(unknown type)'
}


async function main() {
  printHeader('Application Information Example')


  // Create an Algod client connected to LocalNet
  const algod = createAlgodClient()


  // Create an AlgorandClient for application deployment
  const algorand = createAlgorandClient()


  // =========================================================================
  // Step 1: Get a Funded Account from LocalNet
  // =========================================================================
  printStep(1, 'Getting a funded account from LocalNet')


  let creator: Awaited<ReturnType<typeof getFundedAccount>>
  try {
    creator = await getFundedAccount(algorand)
    printSuccess(`Got funded account: ${shortenAddress(creator.addr.toString())}`)
  } catch (error) {
    printError(`Failed to get funded account: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('Make sure LocalNet is running with `algokit localnet start`')
    printInfo('If issues persist, try `algokit localnet reset`')
    process.exit(1)
  }


  // =========================================================================
  // Step 2: Deploy a Test Application using AlgorandClient
  // =========================================================================
  printStep(2, 'Deploying a test application')


  // Load approval program from shared artifacts
  // - Accepts all ApplicationCall transactions
  // - Stores a counter in global state on each call
  // - Has one global uint and one global bytes slot
  const approvalSource = loadTealSource('approval-counter-message.teal')


  // Load clear state program from shared artifacts
  const clearSource = loadTealSource('clear-state-approve.teal')


  try {
    printInfo('Compiling TEAL programs...')
    const approvalCompiled = await algod.tealCompile(approvalSource)
    const clearCompiled = await algod.tealCompile(clearSource)
    printSuccess(`Approval program hash: ${approvalCompiled.hash}`)
    printSuccess(`Clear program hash: ${clearCompiled.hash}`)


    printInfo('Deploying application...')
    const result = await algorand.send.appCreate({
      sender: creator.addr,
      approvalProgram: Buffer.from(approvalCompiled.result, 'base64'),
      clearStateProgram: Buffer.from(clearCompiled.result, 'base64'),
      schema: {
        globalInts: 1,
        globalByteSlices: 1,
        localInts: 0,
        localByteSlices: 0,
      },
    })


    const appId = result.appId
    printSuccess(`Application deployed with ID: ${appId}`)
    printInfo('')


    // =========================================================================
    // Step 3: Get Application Information using applicationById()
    // =========================================================================
    printStep(3, 'Getting application information with applicationById()')


    const app = await algod.applicationById(appId)


    printSuccess('Application information retrieved successfully!')
    printInfo('')


    // =========================================================================
    // Step 4: Display Application Params
    // =========================================================================
    printStep(4, 'Displaying application parameters')


    printInfo('Application Identification:')
    printInfo(`  Application ID: ${app.id}`)
    printInfo('')


    printInfo('Application Parameters:')
    printInfo(`  Creator:        ${app.params.creator}`)
    printInfo(`                  ${shortenAddress(app.params.creator.toString())} (shortened)`)
    printInfo('')


    // Display approval program info
    printInfo('Approval Program:')
    printInfo(`  Size:           ${app.params.approvalProgram.length} bytes`)
    const approvalPreview = Buffer.from(app.params.approvalProgram.slice(0, 20)).toString('hex')
    printInfo(`  Preview:        ${approvalPreview}... (first 20 bytes, hex)`)
    printInfo('The approval program runs when the app is called')
    printInfo('')


    // Display clear state program info
    printInfo('Clear State Program:')
    printInfo(`  Size:           ${app.params.clearStateProgram.length} bytes`)
    const clearPreview = Buffer.from(app.params.clearStateProgram.slice(0, 20)).toString('hex')
    printInfo(`  Preview:        ${clearPreview}... (first 20 bytes, hex)`)
    printInfo('The clear state program runs when an account clears its local state')
    printInfo('')


    // Display extra program pages if any
    if (app.params.extraProgramPages !== undefined && app.params.extraProgramPages > 0) {
      printInfo(`  Extra Pages:    ${app.params.extraProgramPages}`)
      printInfo('Extra program pages allow for larger smart contracts')
    }


    // Display version if available
    if (app.params.version !== undefined) {
      printInfo(`  Version:        ${app.params.version}`)
      printInfo('Version tracks number of program updates')
    }
    printInfo('')


    // =========================================================================
    // Step 5: Display State Schema
    // =========================================================================
    printStep(5, 'Displaying state schema')


    printInfo('Global State Schema:')
    if (app.params.globalStateSchema) {
      printInfo(`  Uint Slots:       ${app.params.globalStateSchema.numUints}`)
      printInfo(`  Byte Slice Slots: ${app.params.globalStateSchema.numByteSlices}`)
      printInfo('Global state is shared across all accounts')
    } else {
      printInfo(`  (no global state schema)`)
    }
    printInfo('')


    printInfo('Local State Schema:')
    if (app.params.localStateSchema) {
      printInfo(`  Uint Slots:       ${app.params.localStateSchema.numUints}`)
      printInfo(`  Byte Slice Slots: ${app.params.localStateSchema.numByteSlices}`)
      printInfo('Local state is per-account and requires opt-in')
    } else {
      printInfo(`  (no local state schema)`)
    }
    printInfo('')


    // =========================================================================
    // Step 6: Display Global State
    // =========================================================================
    printStep(6, 'Displaying global state')


    if (app.params.globalState && app.params.globalState.length > 0) {
      printInfo('Global State Values:')
      for (const kv of app.params.globalState) {
        // Decode the key (it's a Uint8Array)
        const keyStr = new TextDecoder().decode(kv.key)
        const valueStr = decodeTealValue(kv.value)
        printInfo(`  "${keyStr}": ${valueStr}`)
      }
      printInfo('')
      printInfo('Global state is stored on-chain and costs MBR')
    } else {
      printInfo('  (no global state values)')
      printInfo('This application has no global state set')
    }
    printInfo('')


    // =========================================================================
    // Step 7: Call the Application to Update Global State
    // =========================================================================
    printStep(7, 'Calling application to update global state')


    printInfo('Calling the application to increment the counter...')
    await algorand.send.appCall({
      sender: creator.addr,
      appId: appId,
    })


    // Fetch updated application info
    const updatedApp = await algod.applicationById(appId)


    printInfo('Updated Global State:')
    if (updatedApp.params.globalState && updatedApp.params.globalState.length > 0) {
      for (const kv of updatedApp.params.globalState) {
        const keyStr = new TextDecoder().decode(kv.key)
        const valueStr = decodeTealValue(kv.value)
        printInfo(`  "${keyStr}": ${valueStr}`)
      }
    }
    printSuccess('Counter was incremented from 0 to 1')
    printInfo('')


    // =========================================================================
    // Step 8: Handle Application Not Found
    // =========================================================================
    printStep(8, 'Demonstrating error handling for non-existent application')


    const nonExistentAppId = BigInt(999999999)
    try {
      printInfo(`Querying non-existent application ID: ${nonExistentAppId}`)
      await algod.applicationById(nonExistentAppId)
      printError('Expected an error but none was thrown')
    } catch (error) {
      printSuccess('Correctly caught error for non-existent application')
      if (error instanceof Error) {
        printInfo(`  Error message: ${error.message}`)
      }
      printInfo('Always handle the case where an application may not exist or has been deleted')
    }
    printInfo('')


    // =========================================================================
    // Step 9: Note about Round Information
    // =========================================================================
    printStep(9, 'Note about data validity')


    printInfo('The applicationById() method returns the current application state.')
    printInfo('Unlike some other endpoints, it does not include a round field.')
    printInfo('To get the current round, use status() or other round-aware methods.')


    // Get current round for reference
    const status = await algod.status()
    printInfo(`  Current network round: ${status.lastRound.toLocaleString('en-US')}`)
    printInfo('')
  } catch (error) {
    printError(`Failed to deploy or query application: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('If LocalNet errors occur, try `algokit localnet reset`')
    process.exit(1)
  }


  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary')
  printInfo('This example demonstrated:')
  printInfo('  1. Deploying a test application using AlgorandClient.send.appCreate()')
  printInfo('  2. applicationById(appId) - Get complete application information')
  printInfo('  3. Application params: creator, approvalProgram, clearStateProgram')
  printInfo('  4. State schema: globalStateSchema, localStateSchema')
  printInfo('  5. Displaying global state values with TEAL key-value decoding')
  printInfo('  6. Calling the application and observing state changes')
  printInfo('  7. Error handling for non-existent applications')
  printInfo('')
  printInfo('Key Application fields:')
  printInfo('  - id: Unique application identifier (bigint)')
  printInfo('  - params.creator: Address that deployed the application')
  printInfo('  - params.approvalProgram: Bytecode for app calls (Uint8Array)')
  printInfo('  - params.clearStateProgram: Bytecode for clear state (Uint8Array)')
  printInfo('  - params.globalStateSchema: { numUints, numByteSlices }')
  printInfo('  - params.localStateSchema: { numUints, numByteSlices }')
  printInfo('  - params.globalState: TealKeyValue[] (current global state)')
  printInfo('  - params.extraProgramPages: Additional program space (optional)')
  printInfo('  - params.version: Number of updates to the program (optional)')
  printInfo('')
  printInfo('Global State (TealKeyValue) structure:')
  printInfo('  - key: Uint8Array (state key, often UTF-8 string)')
  printInfo('  - value.type: 1 = bytes, 2 = uint')
  printInfo('  - value.bytes: Uint8Array (for bytes type)')
  printInfo('  - value.uint: bigint (for uint type)')
  printInfo('')
  printInfo('Use cases:')
  printInfo('  - Verify application creator and code before interaction')
  printInfo('  - Read current global state values')
  printInfo('  - Check state schema to understand storage limits')
  printInfo('  - Display application information in explorers/wallets')
}


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

Other examples in Algod Client

Section titled “Other examples in Algod Client”