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

TEAL Compile and Disassemble

← Back to Algod Client

Description

Section titled “Description”

This example demonstrates how to compile TEAL source code to bytecode and disassemble bytecode back to TEAL using the AlgodClient methods:

  • tealCompile(source, options?) - Compile TEAL source to bytecode
  • tealDisassemble(bytecode) - Disassemble bytecode back to TEAL

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/12-teal-compile.ts

Code

Section titled “Code”

View source on GitHub

12-teal-compile.ts
/**
 * Example: TEAL Compile and Disassemble
 *
 * This example demonstrates how to compile TEAL source code to bytecode and
 * disassemble bytecode back to TEAL using the AlgodClient methods:
 * - tealCompile(source, options?) - Compile TEAL source to bytecode
 * - tealDisassemble(bytecode) - Disassemble bytecode back to TEAL
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


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


async function main() {
  printHeader('TEAL Compile and Disassemble Example')


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


  // =========================================================================
  // Step 1: Compile a Simple Approval Program
  // =========================================================================
  printStep(1, 'Compiling a simple approval program')


  // A minimal approval program that always succeeds
  const simpleSource = loadTealSource('simple-approve.teal')


  try {
    const compiled = await algod.tealCompile(simpleSource)


    printSuccess('Compilation successful!')
    printInfo('')
    printInfo('Compilation Result:')
    printInfo(`  Hash:   ${compiled.hash}`)
    printInfo(`          (base32 SHA512/256 of program bytes, Address-style)`)
    printInfo(`  Result: ${compiled.result}`)
    printInfo(`          (base64 encoded bytecode)`)
    printInfo('')


    // Decode bytecode to show the raw bytes
    const bytecode = Buffer.from(compiled.result, 'base64')
    printInfo('Bytecode Details:')
    printInfo(`  Size:   ${bytecode.length} bytes`)
    printInfo(`  Hex:    ${bytecode.toString('hex')}`)
    printInfo('')
    printInfo('The hash can be used as a Logic Signature address')
    printInfo('The bytecode (result) is what gets stored on-chain')
    printInfo('')
  } catch (error) {
    printError(`Compilation failed: ${error instanceof Error ? error.message : String(error)}`)
    process.exit(1)
  }


  // =========================================================================
  // Step 2: Compile a More Complex Program
  // =========================================================================
  printStep(2, 'Compiling a more complex approval program')


  // A program that checks sender and approves specific transaction types
  const complexSource = loadTealSource('complex-approve.teal')


  try {
    const compiled = await algod.tealCompile(complexSource)


    printSuccess('Complex program compiled successfully!')
    printInfo('')
    printInfo('Compilation Result:')
    printInfo(`  Hash:   ${compiled.hash}`)
    printInfo(`  Result: ${compiled.result}`)
    printInfo('')


    const bytecode = Buffer.from(compiled.result, 'base64')
    printInfo('Bytecode Details:')
    printInfo(`  Size:   ${bytecode.length} bytes`)
    printInfo(`  Hex:    ${bytecode.toString('hex')}`)
    printInfo('')
    printInfo('Complex programs compile to larger bytecode')
    printInfo('')
  } catch (error) {
    printError(`Compilation failed: ${error instanceof Error ? error.message : String(error)}`)
    process.exit(1)
  }


  // =========================================================================
  // Step 3: Compile with Sourcemap Option
  // =========================================================================
  printStep(3, 'Compiling with sourcemap option')


  // Program with multiple lines for meaningful sourcemap
  const sourcemapSource = loadTealSource('counter-init.teal')


  try {
    const compiled = await algod.tealCompile(sourcemapSource, { sourcemap: true })


    printSuccess('Compilation with sourcemap successful!')
    printInfo('')
    printInfo('Compilation Result:')
    printInfo(`  Hash:   ${compiled.hash}`)
    printInfo(`  Result: ${compiled.result}`)
    printInfo('')


    if (compiled.sourcemap) {
      printInfo('Source Map:')
      printInfo(`  Version:  ${compiled.sourcemap.version}`)
      printInfo(`  Sources:  ${JSON.stringify(compiled.sourcemap.sources)}`)
      printInfo(`  Names:    ${JSON.stringify(compiled.sourcemap.names)}`)
      printInfo(`  Mappings: ${compiled.sourcemap.mappings}`)
      printInfo('')
      printInfo('Sourcemaps enable debugging by mapping bytecode to source lines')
      printInfo('The mappings string uses VLQ (Variable Length Quantity) encoding')
    } else {
      printInfo('Sourcemap was not returned (may depend on node configuration)')
    }
    printInfo('')
  } catch (error) {
    printError(`Compilation failed: ${error instanceof Error ? error.message : String(error)}`)
    process.exit(1)
  }


  // =========================================================================
  // Step 4: Disassemble Bytecode Back to TEAL
  // =========================================================================
  printStep(4, 'Disassembling bytecode back to TEAL')


  try {
    // First compile, then disassemble to show round-trip
    const compiled = await algod.tealCompile(simpleSource)
    const bytecode = new Uint8Array(Buffer.from(compiled.result, 'base64'))


    printInfo('Original Source:')
    printInfo(`  ${simpleSource.split('\n').join('\n  ')}`)
    printInfo('')


    const disassembled = await algod.tealDisassemble(bytecode)


    printSuccess('Disassembly successful!')
    printInfo('')
    printInfo('Disassembled Output:')
    printInfo(`  ${disassembled.result.trim().split('\n').join('\n  ')}`)
    printInfo('')
    printInfo('Disassembled output may differ from original (comments removed, labels renamed)')
    printInfo('')
  } catch (error) {
    printError(`Disassembly failed: ${error instanceof Error ? error.message : String(error)}`)
    process.exit(1)
  }


  // =========================================================================
  // Step 5: Compare Original Source with Disassembled Output
  // =========================================================================
  printStep(5, 'Comparing original source with disassembled output')


  try {
    // Use the complex source for a more interesting comparison
    const compiled = await algod.tealCompile(complexSource)
    const bytecode = new Uint8Array(Buffer.from(compiled.result, 'base64'))
    const disassembled = await algod.tealDisassemble(bytecode)


    printInfo('Original Source:')
    const originalLines = complexSource.trim().split('\n')
    originalLines.forEach((line, i) => printInfo(`  ${(i + 1).toString().padStart(2)}: ${line}`))
    printInfo('')


    printInfo('Disassembled Output:')
    const disassembledLines = disassembled.result.trim().split('\n')
    disassembledLines.forEach((line, i) => printInfo(`  ${(i + 1).toString().padStart(2)}: ${line}`))
    printInfo('')


    printInfo('Key Differences:')
    printInfo('  - Comments are removed during compilation')
    printInfo('  - Labels are converted to numeric addresses')
    printInfo('  - The semantic meaning remains identical')
    printInfo('')
  } catch (error) {
    printError(`Comparison failed: ${error instanceof Error ? error.message : String(error)}`)
    process.exit(1)
  }


  // =========================================================================
  // Step 6: Handle Compilation Errors
  // =========================================================================
  printStep(6, 'Handling compilation errors for invalid TEAL')


  // Invalid TEAL source - unknown opcode
  const invalidSource1 = `#pragma version 10
invalid_opcode
int 1`


  try {
    printInfo('Attempting to compile invalid TEAL (unknown opcode):')
    printInfo(`  ${invalidSource1.split('\n').join('\n  ')}`)
    printInfo('')
    await algod.tealCompile(invalidSource1)
    printError('Expected compilation to fail but it succeeded')
  } catch (error) {
    printSuccess('Correctly caught compilation error!')
    if (error instanceof Error) {
      printInfo(`  Error: ${error.message}`)
    }
    printInfo('')
  }


  // Invalid TEAL source - syntax error
  const invalidSource2 = `#pragma version 10
int`


  try {
    printInfo('Attempting to compile invalid TEAL (missing operand):')
    printInfo(`  ${invalidSource2.split('\n').join('\n  ')}`)
    printInfo('')
    await algod.tealCompile(invalidSource2)
    printError('Expected compilation to fail but it succeeded')
  } catch (error) {
    printSuccess('Correctly caught syntax error!')
    if (error instanceof Error) {
      printInfo(`  Error: ${error.message}`)
    }
    printInfo('')
  }


  // Invalid TEAL source - invalid version
  const invalidSource3 = `#pragma version 999
int 1`


  try {
    printInfo('Attempting to compile invalid TEAL (invalid version):')
    printInfo(`  ${invalidSource3.split('\n').join('\n  ')}`)
    printInfo('')
    await algod.tealCompile(invalidSource3)
    printError('Expected compilation to fail but it succeeded')
  } catch (error) {
    printSuccess('Correctly caught version error!')
    if (error instanceof Error) {
      printInfo(`  Error: ${error.message}`)
    }
    printInfo('')
  }


  printInfo('Always validate TEAL source before deployment')
  printInfo('Compilation errors include line numbers and descriptions')
  printInfo('')


  // =========================================================================
  // Step 7: Understanding Disassembly Behavior
  // =========================================================================
  printStep(7, 'Understanding disassembly behavior with various bytecode')


  // The disassembler does best-effort interpretation of bytecode
  // Even invalid patterns may produce some output


  // Example 1: Bytecode with invalid version (version 0)
  const invalidVersionBytecode = new Uint8Array([0x00, 0x00, 0x00])
  printInfo('Disassembling bytecode with version 0:')
  printInfo(`  Bytes: ${Buffer.from(invalidVersionBytecode).toString('hex')}`)
  try {
    const result = await algod.tealDisassemble(invalidVersionBytecode)
    printInfo('  Result:')
    printInfo(`    ${result.result.trim().split('\n').join('\n    ')}`)
    printInfo('Version 0 is disassembled but is not a valid TEAL version')
    printInfo('')
  } catch (error) {
    printError(`Disassembly failed: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
  }


  // Example 2: Single byte (just version, no opcodes)
  const minimalBytecode = new Uint8Array([0x0a]) // version 10
  printInfo('Disassembling minimal bytecode (just version byte):')
  printInfo(`  Bytes: ${Buffer.from(minimalBytecode).toString('hex')}`)
  try {
    const result = await algod.tealDisassemble(minimalBytecode)
    printInfo('  Result:')
    printInfo(`    ${result.result.trim().split('\n').join('\n    ')}`)
    printInfo('Minimal valid bytecode: version byte only')
    printInfo('')
  } catch (error) {
    printError(`Disassembly failed: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
  }


  printInfo('The disassembler does best-effort interpretation')
  printInfo('Always verify disassembled output matches expected behavior')
  printInfo('')


  // =========================================================================
  // Step 8: Compile Different TEAL Versions
  // =========================================================================
  printStep(8, 'Compiling programs with different TEAL versions')


  const versions = [6, 8, 10]


  for (const version of versions) {
    const source = `#pragma version ${version}
int 1`


    try {
      const compiled = await algod.tealCompile(source)
      const bytecode = Buffer.from(compiled.result, 'base64')


      printInfo(`TEAL Version ${version}:`)
      printInfo(`  Hash:     ${compiled.hash}`)
      printInfo(`  Size:     ${bytecode.length} bytes`)
      printInfo(`  Bytecode: ${bytecode.toString('hex')}`)
      printInfo('')
    } catch (error) {
      printError(`Version ${version} failed: ${error instanceof Error ? error.message : String(error)}`)
    }
  }


  printInfo('Different TEAL versions may produce different bytecode')
  printInfo('Newer versions support more opcodes and features')
  printInfo('')


  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary')
  printInfo('This example demonstrated:')
  printInfo('  1. tealCompile(source) - Compile TEAL source code to bytecode')
  printInfo('  2. CompileResponse fields: hash (base32), result (base64 bytecode)')
  printInfo('  3. tealCompile(source, { sourcemap: true }) - Get source map for debugging')
  printInfo('  4. tealDisassemble(bytecode) - Convert bytecode back to TEAL')
  printInfo('  5. Comparing original source with disassembled output')
  printInfo('  6. Handling compilation errors for invalid TEAL')
  printInfo('  7. Handling disassembly errors for invalid bytecode')
  printInfo('  8. Compiling programs with different TEAL versions')
  printInfo('')
  printInfo('Key CompileResponse fields:')
  printInfo('  - hash: base32 SHA512/256 of program bytes (Address-style)')
  printInfo('  - result: base64 encoded bytecode')
  printInfo('  - sourcemap?: { version, sources, names, mappings } (optional)')
  printInfo('')
  printInfo('Key DisassembleResponse fields:')
  printInfo('  - result: Disassembled TEAL source code (string)')
  printInfo('')
  printInfo('Use cases:')
  printInfo('  - Compile TEAL before deploying smart contracts')
  printInfo('  - Get program hash for Logic Signature addresses')
  printInfo('  - Debug bytecode by disassembling to readable TEAL')
  printInfo('  - Validate TEAL syntax before deployment')
  printInfo('  - Generate sourcemaps for debugging tools')
}


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

Other examples in Algod Client

Section titled “Other examples in Algod Client”