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

ABI Primitive Types

← Back to ABI Encoding

Description

Section titled “Description”

This example demonstrates how to encode and decode primitive ABI types:

  • ABIUintType: Unsigned integers of various bit sizes (8, 16, 32, 64, 128, 256, 512)
  • ABIBoolType: Boolean values encoded as a single byte
  • ABIByteType: Single byte values Shows encode() and decode() methods, hex format display, and round-trip verification.

Prerequisites

Section titled “Prerequisites”
  • No LocalNet required

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example abi/02-primitive-types.ts

Code

Section titled “Code”

View source on GitHub

02-primitive-types.ts
/**
 * Example: ABI Primitive Types
 *
 * This example demonstrates how to encode and decode primitive ABI types:
 * - ABIUintType: Unsigned integers of various bit sizes (8, 16, 32, 64, 128, 256, 512)
 * - ABIBoolType: Boolean values encoded as a single byte
 * - ABIByteType: Single byte values
 *
 * Shows encode() and decode() methods, hex format display, and round-trip verification.
 *
 * Prerequisites:
 * - No LocalNet required
 */


import { ABIBoolType, ABIByteType, ABIUintType } from '@algorandfoundation/algokit-utils/abi'
import { formatHex, printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js'


function main() {
  printHeader('ABI Primitive Types Example')


  // Step 1: ABIUintType with various bit sizes
  printStep(1, 'ABIUintType - Various Bit Sizes')


  const uintSizes = [8, 16, 32, 64, 128, 256, 512]


  for (const bitSize of uintSizes) {
    const uintType = new ABIUintType(bitSize)
    printInfo(`\n${uintType.toString()}:`)
    printInfo(`  bitSize: ${uintType.bitSize}`)
    printInfo(`  byteLen: ${uintType.byteLen()}`)
    printInfo(`  isDynamic: ${uintType.isDynamic()}`)
  }


  // Step 2: Encoding and decoding small uint values
  printStep(2, 'Encoding/Decoding Small Uint Values')


  const uint8Type = new ABIUintType(8)
  const uint8Value = 42
  const uint8Encoded = uint8Type.encode(uint8Value)
  const uint8Decoded = uint8Type.decode(uint8Encoded)


  printInfo(`uint8 value: ${uint8Value}`)
  printInfo(`  encoded: ${formatHex(uint8Encoded)}`)
  printInfo(`  decoded: ${uint8Decoded}`)
  printInfo(`  round-trip verified: ${Number(uint8Decoded) === uint8Value}`)


  const uint16Type = new ABIUintType(16)
  const uint16Value = 1000
  const uint16Encoded = uint16Type.encode(uint16Value)
  const uint16Decoded = uint16Type.decode(uint16Encoded)


  printInfo(`uint16 value: ${uint16Value}`)
  printInfo(`  encoded: ${formatHex(uint16Encoded)}`)
  printInfo(`  decoded: ${uint16Decoded}`)
  printInfo(`  round-trip verified: ${Number(uint16Decoded) === uint16Value}`)


  const uint32Type = new ABIUintType(32)
  const uint32Value = 1_000_000
  const uint32Encoded = uint32Type.encode(uint32Value)
  const uint32Decoded = uint32Type.decode(uint32Encoded)


  printInfo(`uint32 value: ${uint32Value}`)
  printInfo(`  encoded: ${formatHex(uint32Encoded)}`)
  printInfo(`  decoded: ${uint32Decoded}`)
  printInfo(`  round-trip verified: ${Number(uint32Decoded) === uint32Value}`)


  const uint64Type = new ABIUintType(64)
  const uint64Value = 9_007_199_254_740_991n // Max safe integer as BigInt
  const uint64Encoded = uint64Type.encode(uint64Value)
  const uint64Decoded = uint64Type.decode(uint64Encoded)


  printInfo(`uint64 value: ${uint64Value}`)
  printInfo(`  encoded: ${formatHex(uint64Encoded)}`)
  printInfo(`  decoded: ${uint64Decoded}`)
  printInfo(`  round-trip verified: ${uint64Decoded === uint64Value}`)


  // Step 3: Encoding BigInt values for large uint types
  printStep(3, 'Encoding BigInt Values for Large Uint Types')


  const uint128Type = new ABIUintType(128)
  const uint128Value = 340282366920938463463374607431768211455n // 2^128 - 1 (max uint128)
  const uint128Encoded = uint128Type.encode(uint128Value)
  const uint128Decoded = uint128Type.decode(uint128Encoded)


  printInfo(`uint128 max value: ${uint128Value}`)
  printInfo(`  encoded: ${formatHex(uint128Encoded)}`)
  printInfo(`  decoded: ${uint128Decoded}`)
  printInfo(`  round-trip verified: ${uint128Decoded === uint128Value}`)


  const uint256Type = new ABIUintType(256)
  // Example: a large 256-bit value
  const uint256Value = 115792089237316195423570985008687907853269984665640564039457584007913129639935n // 2^256 - 1 (max uint256)
  const uint256Encoded = uint256Type.encode(uint256Value)
  const uint256Decoded = uint256Type.decode(uint256Encoded)


  printInfo(`uint256 max value: ${uint256Value}`)
  printInfo(`  encoded: ${formatHex(uint256Encoded)}`)
  printInfo(`  decoded: ${uint256Decoded}`)
  printInfo(`  round-trip verified: ${uint256Decoded === uint256Value}`)


  const uint512Type = new ABIUintType(512)
  // Example: a moderately large 512-bit value
  const uint512Value =
    13407807929942597099574024998205846127479365820592393377723561443721764030073546976801874298166903427690031858186486050853753882811946569946433649006084095n // 2^512 - 1 (max uint512)
  const uint512Encoded = uint512Type.encode(uint512Value)
  const uint512Decoded = uint512Type.decode(uint512Encoded)


  printInfo(`uint512 max value: ${uint512Value}`)
  printInfo(`  encoded: ${formatHex(uint512Encoded)}`)
  printInfo(`  decoded: ${uint512Decoded}`)
  printInfo(`  round-trip verified: ${uint512Decoded === uint512Value}`)


  // Step 4: ABIBoolType encoding true/false
  printStep(4, 'ABIBoolType - Encoding Boolean Values')


  const boolType = new ABIBoolType()


  printInfo(`bool type: ${boolType.toString()}`)
  printInfo(`  byteLen: ${boolType.byteLen()}`)
  printInfo(`  isDynamic: ${boolType.isDynamic()}`)


  // Encode true
  const trueEncoded = boolType.encode(true)
  const trueDecoded = boolType.decode(trueEncoded)


  printInfo(`\nbool value: true`)
  printInfo(`  encoded: ${formatHex(trueEncoded)}`)
  printInfo(`  decoded: ${trueDecoded}`)
  printInfo(`  round-trip verified: ${trueDecoded === true}`)


  // Encode false
  const falseEncoded = boolType.encode(false)
  const falseDecoded = boolType.decode(falseEncoded)


  printInfo(`\nbool value: false`)
  printInfo(`  encoded: ${formatHex(falseEncoded)}`)
  printInfo(`  decoded: ${falseDecoded}`)
  printInfo(`  round-trip verified: ${falseDecoded === false}`)


  // Step 5: ABIByteType encoding single byte values
  printStep(5, 'ABIByteType - Encoding Single Byte Values')


  const byteType = new ABIByteType()


  printInfo(`byte type: ${byteType.toString()}`)
  printInfo(`  byteLen: ${byteType.byteLen()}`)
  printInfo(`  isDynamic: ${byteType.isDynamic()}`)


  // Encode minimum byte value (0)
  const byte0Value = 0
  const byte0Encoded = byteType.encode(byte0Value)
  const byte0Decoded = byteType.decode(byte0Encoded)


  printInfo(`\nbyte value: ${byte0Value} (0x00)`)
  printInfo(`  encoded: ${formatHex(byte0Encoded)}`)
  printInfo(`  decoded: ${byte0Decoded}`)
  printInfo(`  round-trip verified: ${byte0Decoded === byte0Value}`)


  // Encode a middle byte value (127)
  const byte127Value = 127
  const byte127Encoded = byteType.encode(byte127Value)
  const byte127Decoded = byteType.decode(byte127Encoded)


  printInfo(`\nbyte value: ${byte127Value} (0x7F)`)
  printInfo(`  encoded: ${formatHex(byte127Encoded)}`)
  printInfo(`  decoded: ${byte127Decoded}`)
  printInfo(`  round-trip verified: ${byte127Decoded === byte127Value}`)


  // Encode maximum byte value (255)
  const byte255Value = 255
  const byte255Encoded = byteType.encode(byte255Value)
  const byte255Decoded = byteType.decode(byte255Encoded)


  printInfo(`\nbyte value: ${byte255Value} (0xFF)`)
  printInfo(`  encoded: ${formatHex(byte255Encoded)}`)
  printInfo(`  decoded: ${byte255Decoded}`)
  printInfo(`  round-trip verified: ${byte255Decoded === byte255Value}`)


  // Step 6: Summary of encoded byte lengths
  printStep(6, 'Summary - Encoded Byte Lengths')


  printInfo('Primitive type byte lengths:')
  printInfo(`  uint8:   ${new ABIUintType(8).byteLen()} byte`)
  printInfo(`  uint16:  ${new ABIUintType(16).byteLen()} bytes`)
  printInfo(`  uint32:  ${new ABIUintType(32).byteLen()} bytes`)
  printInfo(`  uint64:  ${new ABIUintType(64).byteLen()} bytes`)
  printInfo(`  uint128: ${new ABIUintType(128).byteLen()} bytes`)
  printInfo(`  uint256: ${new ABIUintType(256).byteLen()} bytes`)
  printInfo(`  uint512: ${new ABIUintType(512).byteLen()} bytes`)
  printInfo(`  bool:    ${new ABIBoolType().byteLen()} byte`)
  printInfo(`  byte:    ${new ABIByteType().byteLen()} byte`)


  printSuccess('ABI Primitive Types example completed successfully!')
}


main()

Other examples in ABI Encoding

Section titled “Other examples in ABI Encoding”