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

App Deployer

← Back to Algorand Client

Description

Section titled “Description”

This example demonstrates the AppDeployer functionality for idempotent application deployment with create, update, and replace strategies:

  • algorand.appDeployer.deploy() for initial deployment
  • Deploy parameters: name, version, approvalProgram, clearProgram, schema, onUpdate, onSchemaBreak
  • Idempotency: calling deploy() again with same version does nothing
  • onUpdate: ‘update’ to update existing app when version changes
  • onUpdate: ‘replace’ to delete and recreate app when version changes
  • onUpdate: ‘fail’ to fail if app already exists with different code
  • onSchemaBreak: ‘replace’ when schema changes require new app
  • Deployment metadata stored in app global state
  • App name used for idempotent lookups

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/13-app-deployer.ts

Code

Section titled “Code”

View source on GitHub

13-app-deployer.ts
/**
 * Example: App Deployer
 *
 * This example demonstrates the AppDeployer functionality for idempotent
 * application deployment with create, update, and replace strategies:
 * - algorand.appDeployer.deploy() for initial deployment
 * - Deploy parameters: name, version, approvalProgram, clearProgram, schema, onUpdate, onSchemaBreak
 * - Idempotency: calling deploy() again with same version does nothing
 * - onUpdate: 'update' to update existing app when version changes
 * - onUpdate: 'replace' to delete and recreate app when version changes
 * - onUpdate: 'fail' to fail if app already exists with different code
 * - onSchemaBreak: 'replace' when schema changes require new app
 * - Deployment metadata stored in app global state
 * - App name used for idempotent lookups
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


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


// ============================================================================
// TEAL Programs - Versioned Application (loaded from shared artifacts)
// ============================================================================


/**
 * Generate a versioned approval program that supports updates and deletes.
 * Uses TMPL_UPDATABLE and TMPL_DELETABLE for deploy-time control.
 * The version parameter changes the bytecode to simulate code updates.
 */
function getVersionedApprovalProgram(version: number): string {
  return loadTealSource('teal-template-versioned.teal').replace(/TMPL_VERSION/g, String(version))
}


// Clear state program (always approves)
const CLEAR_STATE_PROGRAM = loadTealSource('clear-state-approve.teal')


async function main() {
  printHeader('App Deployer 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: Create and fund test accounts
  printStep(1, 'Create and fund test accounts')
  printInfo('Creating account for app deployment demonstrations')


  const deployer = algorand.account.random()


  printInfo(`\nCreated account:`)
  printInfo(`  Deployer: ${shortenAddress(deployer.addr.toString())}`)


  // Fund account generously for multiple deployments
  await algorand.account.ensureFundedFromEnvironment(deployer.addr, algo(50))


  printSuccess('Created and funded test account')


  // Step 2: Initial deployment with appDeployer.deploy()
  printStep(2, 'Initial deployment with algorand.appDeployer.deploy()')
  printInfo('Deploying a versioned application for the first time')


  const appName = 'MyVersionedApp'


  const result1 = await algorand.appDeployer.deploy({
    metadata: {
      name: appName,
      version: '1.0.0',
      updatable: true, // Allow updates via TMPL_UPDATABLE
      deletable: true, // Allow deletion via TMPL_DELETABLE
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(1),
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 2, // version, counter
        globalByteSlices: 0,
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
  })


  printInfo(`\nDeployment result:`)
  printInfo(`  Operation performed: ${result1.operationPerformed}`)
  printInfo(`  App ID: ${result1.appId}`)
  printInfo(`  App Address: ${shortenAddress(result1.appAddress.toString())}`)
  printInfo(`  App Name: ${result1.name}`)
  printInfo(`  Version: ${result1.version}`)
  printInfo(`  Updatable: ${result1.updatable}`)
  printInfo(`  Deletable: ${result1.deletable}`)
  if ('transaction' in result1) {
    printInfo(`  Transaction ID: ${result1.txIds[0]}`)
  }


  printSuccess('Initial deployment completed (operation: create)')


  // Step 3: Demonstrate idempotency - same version does nothing
  printStep(3, 'Demonstrate idempotency - deploy same version again')
  printInfo('Calling deploy() again with the same version should do nothing')


  const result2 = await algorand.appDeployer.deploy({
    metadata: {
      name: appName,
      version: '1.0.0', // Same version
      updatable: true,
      deletable: true,
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(1), // Same code
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 2,
        globalByteSlices: 0,
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
  })


  printInfo(`\nIdempotent deployment result:`)
  printInfo(`  Operation performed: ${result2.operationPerformed}`)
  printInfo(`  App ID: ${result2.appId} (same as before)`)
  printInfo(`  Version: ${result2.version}`)
  if (result2.operationPerformed === 'nothing') {
    printInfo(`  Note: No transaction was sent - app is unchanged`)
  }


  printSuccess('Idempotency verified - no action taken for same version')


  // Step 4: Demonstrate onUpdate: 'update'
  printStep(4, "Demonstrate onUpdate: 'update' - update existing app")
  printInfo('Deploying version 2.0.0 with onUpdate: "update" to update the existing app')


  const result3 = await algorand.appDeployer.deploy({
    metadata: {
      name: appName,
      version: '2.0.0', // New version
      updatable: true,
      deletable: true,
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(2), // Updated code
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 2,
        globalByteSlices: 0,
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
    onUpdate: 'update', // Update the existing app
  })


  printInfo(`\nUpdate deployment result:`)
  printInfo(`  Operation performed: ${result3.operationPerformed}`)
  printInfo(`  App ID: ${result3.appId} (same app, updated in place)`)
  printInfo(`  Version: ${result3.version}`)
  printInfo(`  Created round: ${result3.createdRound}`)
  printInfo(`  Updated round: ${result3.updatedRound}`)
  if ('transaction' in result3) {
    printInfo(`  Transaction ID: ${result3.txIds[0]}`)
  }


  // Verify the global state was preserved but version updated
  const globalState = await algorand.app.getGlobalState(result3.appId)
  printInfo(`\nGlobal state after update:`)
  printInfo(`  version: ${globalState['version']?.value ?? 'N/A'} (from TEAL)`)
  printInfo(`  counter: ${globalState['counter']?.value ?? 'N/A'} (preserved)`)


  printSuccess('App updated in place with new code')


  // Step 5: Demonstrate onUpdate: 'fail'
  printStep(5, "Demonstrate onUpdate: 'fail' - fails if update detected")
  printInfo('Trying to deploy version 3.0.0 with onUpdate: "fail" should throw an error')


  try {
    await algorand.appDeployer.deploy({
      metadata: {
        name: appName,
        version: '3.0.0', // New version
        updatable: true,
        deletable: true,
      },
      createParams: {
        sender: deployer.addr,
        approvalProgram: getVersionedApprovalProgram(3),
        clearStateProgram: CLEAR_STATE_PROGRAM,
        schema: {
          globalInts: 2,
          globalByteSlices: 0,
          localInts: 0,
          localByteSlices: 0,
        },
      },
      updateParams: {
        sender: deployer.addr,
      },
      deleteParams: {
        sender: deployer.addr,
      },
      onUpdate: 'fail', // Fail if update detected
    })
    printError('Expected an error but deployment succeeded')
  } catch (error) {
    printInfo(`\nExpected error caught:`)
    printInfo(`  ${error instanceof Error ? error.message : String(error)}`)
    printSuccess('onUpdate: "fail" correctly prevents updates')
  }


  // Step 6: Demonstrate onUpdate: 'replace'
  printStep(6, "Demonstrate onUpdate: 'replace' - delete and recreate app")
  printInfo('Deploying version 3.0.0 with onUpdate: "replace" deletes old app and creates new one')


  const oldAppId = result3.appId


  const result4 = await algorand.appDeployer.deploy({
    metadata: {
      name: appName,
      version: '3.0.0',
      updatable: true,
      deletable: true,
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(3),
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 2,
        globalByteSlices: 0,
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
    onUpdate: 'replace', // Delete old and create new
  })


  printInfo(`\nReplace deployment result:`)
  printInfo(`  Operation performed: ${result4.operationPerformed}`)
  printInfo(`  Old App ID: ${oldAppId} (deleted)`)
  printInfo(`  New App ID: ${result4.appId}`)
  printInfo(`  App Address: ${shortenAddress(result4.appAddress.toString())}`)
  printInfo(`  Version: ${result4.version}`)
  if (result4.operationPerformed === 'replace' && 'deleteResult' in result4) {
    printInfo(`  Delete transaction confirmed: round ${result4.deleteResult.confirmation.confirmedRound}`)
  }


  printSuccess('Old app deleted and new app created')


  // Step 7: Demonstrate onSchemaBreak: 'replace'
  printStep(7, "Demonstrate onSchemaBreak: 'replace' - handle schema changes")
  printInfo('Deploying version 4.0.0 with increased schema (more global ints)')
  printInfo('Schema changes cannot be done via update, so replace is required')


  const result5 = await algorand.appDeployer.deploy({
    metadata: {
      name: appName,
      version: '4.0.0',
      updatable: true,
      deletable: true,
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(4),
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 3, // Schema break: increased from 2 to 3
        globalByteSlices: 1, // Schema break: increased from 0 to 1
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
    onUpdate: 'update', // Would normally try to update
    onSchemaBreak: 'replace', // But schema change forces replace
  })


  printInfo(`\nSchema break deployment result:`)
  printInfo(`  Operation performed: ${result5.operationPerformed}`)
  printInfo(`  Previous App ID: ${result4.appId}`)
  printInfo(`  New App ID: ${result5.appId}`)
  printInfo(`  Version: ${result5.version}`)


  // Verify new schema
  const appInfo = await algorand.app.getById(result5.appId)
  printInfo(`\nNew app schema:`)
  printInfo(`  globalInts: ${appInfo.globalInts}`)
  printInfo(`  globalByteSlices: ${appInfo.globalByteSlices}`)


  printSuccess('Schema break handled with replace strategy')


  // Step 8: Show deployment metadata in global state
  printStep(8, 'Show deployment metadata lookup by name')
  printInfo('The appDeployer uses app name for idempotent lookups across deployments')


  // Look up the app by creator
  const creatorApps = await algorand.appDeployer.getCreatorAppsByName(deployer.addr)


  printInfo(`\nApps deployed by ${shortenAddress(deployer.addr.toString())}:`)
  for (const [name, appMeta] of Object.entries(creatorApps.apps)) {
    printInfo(`\n  App Name: "${name}"`)
    printInfo(`    App ID: ${appMeta.appId}`)
    printInfo(`    Version: ${appMeta.version}`)
    printInfo(`    Updatable: ${appMeta.updatable}`)
    printInfo(`    Deletable: ${appMeta.deletable}`)
    printInfo(`    Created Round: ${appMeta.createdRound}`)
    printInfo(`    Updated Round: ${appMeta.updatedRound}`)
    printInfo(`    Deleted: ${appMeta.deleted}`)
    printInfo(`    Created Metadata:`)
    printInfo(`      Name: ${appMeta.createdMetadata.name}`)
    printInfo(`      Version: ${appMeta.createdMetadata.version}`)
  }


  printSuccess('Deployment metadata retrieved')


  // Step 9: Demonstrate how name enables idempotency
  printStep(9, 'Demonstrate how app name enables idempotent deployments')
  printInfo('Deploy a second app with a different name to show name-based lookup')


  const result6 = await algorand.appDeployer.deploy({
    metadata: {
      name: 'AnotherApp', // Different name
      version: '1.0.0',
      updatable: false,
      deletable: false,
    },
    createParams: {
      sender: deployer.addr,
      approvalProgram: getVersionedApprovalProgram(100),
      clearStateProgram: CLEAR_STATE_PROGRAM,
      schema: {
        globalInts: 2, // version, counter
        globalByteSlices: 0,
        localInts: 0,
        localByteSlices: 0,
      },
    },
    updateParams: {
      sender: deployer.addr,
    },
    deleteParams: {
      sender: deployer.addr,
    },
  })


  printInfo(`\nSecond app deployment:`)
  printInfo(`  Name: AnotherApp`)
  printInfo(`  App ID: ${result6.appId}`)
  printInfo(`  Operation: ${result6.operationPerformed}`)


  // Now list all apps again
  const allApps = await algorand.appDeployer.getCreatorAppsByName(deployer.addr)
  printInfo(`\nAll apps by creator (${Object.keys(allApps.apps).length} apps):`)
  for (const name of Object.keys(allApps.apps)) {
    printInfo(`  - "${name}" (App ID: ${allApps.apps[name].appId})`)
  }


  printSuccess('Multiple apps tracked by name')


  // Step 10: Summary
  printStep(10, 'Summary - App Deployer API')
  printInfo('The AppDeployer provides idempotent application deployment:')
  printInfo('')
  printInfo('algorand.appDeployer.deploy(params):')
  printInfo('  - Deploys applications with idempotent behavior based on app name')
  printInfo('  - Returns: AppDeployResult with operationPerformed discriminator')
  printInfo('')
  printInfo('Key parameters:')
  printInfo('  metadata: { name, version, updatable, deletable }')
  printInfo('    - name: Unique identifier for idempotent lookups')
  printInfo('    - version: Semantic version string')
  printInfo('    - updatable/deletable: Deploy-time controls (TMPL_UPDATABLE/TMPL_DELETABLE)')
  printInfo('')
  printInfo('  createParams: { sender, approvalProgram, clearStateProgram, schema }')
  printInfo('  updateParams: { sender } - Used for update operations')
  printInfo('  deleteParams: { sender } - Used for replace operations')
  printInfo('')
  printInfo('  onUpdate: Controls behavior when code changes:')
  printInfo("    'fail' - Throw error (default)")
  printInfo("    'update' - Update app in place (preserves app ID)")
  printInfo("    'replace' - Delete old app, create new one")
  printInfo("    'append' - Create new app, leave old one")
  printInfo('')
  printInfo('  onSchemaBreak: Controls behavior when schema changes:')
  printInfo("    'fail' - Throw error (default)")
  printInfo("    'replace' - Delete old app, create new one")
  printInfo("    'append' - Create new app, leave old one")
  printInfo('')
  printInfo('operationPerformed values:')
  printInfo("  'create' - New app was created")
  printInfo("  'update' - Existing app was updated in place")
  printInfo("  'replace' - Old app deleted, new app created")
  printInfo("  'nothing' - No changes (idempotent)")
  printInfo('')
  printInfo('algorand.appDeployer.getCreatorAppsByName(creator):')
  printInfo('  - Lists all apps deployed by a creator with their metadata')
  printInfo('  - Used internally for idempotent lookup by name')


  printSuccess('App Deployer 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”