ABI Bool Array Packing

← Back to ABI Encoding

Description

This example demonstrates how bool arrays are packed efficiently in ARC-4:

• 8 booleans fit in 1 byte (1 bit per boolean)
• bool[8] encodes to exactly 1 byte
• bool[16] encodes to 2 bytes
• Partial byte arrays (e.g., bool[5]) still use full bytes Key characteristics of bool array packing:
• Each bool is stored as a single bit, not a full byte
• Bools are packed left-to-right starting from the MSB (most significant bit)
• Array length is rounded up to the next full byte
• This is much more space-efficient than storing each bool as uint8

Prerequisites

• No LocalNet required

Run This Example

From the repository root:

cd examples
npm run example abi/10-bool-packing.ts

Code

View source on GitHub

10-bool-packing.ts

/**
 * Example: ABI Bool Array Packing
 *
 * This example demonstrates how bool arrays are packed efficiently in ARC-4:
 * - 8 booleans fit in 1 byte (1 bit per boolean)
 * - bool[8] encodes to exactly 1 byte
 * - bool[16] encodes to 2 bytes
 * - Partial byte arrays (e.g., bool[5]) still use full bytes
 *
 * Key characteristics of bool array packing:
 * - Each bool is stored as a single bit, not a full byte
 * - Bools are packed left-to-right starting from the MSB (most significant bit)
 * - Array length is rounded up to the next full byte
 * - This is much more space-efficient than storing each bool as uint8
 *
 * Prerequisites:
 * - No LocalNet required
 */

import { ABIArrayDynamicType, ABIArrayStaticType, ABIType } from '@algorandfoundation/algokit-utils/abi'
import { formatHex, printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js'

/**
 * Format a byte as a binary string showing all 8 bits
 */
function formatBinary(byte: number): string {
  return byte.toString(2).padStart(8, '0')
}

/**
 * Format a byte array as binary showing the bit layout
 */
function formatBinaryBytes(bytes: Uint8Array): string {
  return Array.from(bytes)
    .map((b) => formatBinary(b))
    .join(' ')
}

function main() {
  printHeader('ABI Bool Array Packing Example')

  // Step 1: Introduction to bool array packing
  printStep(1, 'Introduction to Bool Array Packing')

  printInfo('In ARC-4 ABI encoding, boolean arrays use bit-packing:')
  printInfo('  - Each bool takes 1 bit (not 1 byte)')
  printInfo('  - 8 bools fit in 1 byte')
  printInfo('  - Bools are packed from MSB (bit 7) to LSB (bit 0)')
  printInfo('  - true = 1, false = 0')

  // Step 2: bool[8] - exactly 1 byte
  printStep(2, 'bool[8] Encoding - Exactly 1 Byte')

  const bool8Type = ABIType.from('bool[8]') as ABIArrayStaticType

  printInfo(`Type: ${bool8Type.toString()}`)
  printInfo(`childType: ${bool8Type.childType.toString()}`)
  printInfo(`length: ${bool8Type.length}`)
  printInfo(`byteLen(): ${bool8Type.byteLen()}`)
  printInfo(`isDynamic(): ${bool8Type.isDynamic()}`)

  // All true - should be 0b11111111 = 0xFF
  const allTrue8 = [true, true, true, true, true, true, true, true]
  const allTrue8Encoded = bool8Type.encode(allTrue8)

  printInfo(`\nAll true: [${allTrue8.join(', ')}]`)
  printInfo(`  Encoded: ${formatHex(allTrue8Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(allTrue8Encoded)}`)
  printInfo(`  Length:  ${allTrue8Encoded.length} byte`)

  // All false - should be 0b00000000 = 0x00
  const allFalse8 = [false, false, false, false, false, false, false, false]
  const allFalse8Encoded = bool8Type.encode(allFalse8)

  printInfo(`\nAll false: [${allFalse8.join(', ')}]`)
  printInfo(`  Encoded: ${formatHex(allFalse8Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(allFalse8Encoded)}`)
  printInfo(`  Length:  ${allFalse8Encoded.length} byte`)

  // Alternating pattern - should be 0b10101010 = 0xAA
  const alternating8 = [true, false, true, false, true, false, true, false]
  const alternating8Encoded = bool8Type.encode(alternating8)

  printInfo(`\nAlternating: [${alternating8.join(', ')}]`)
  printInfo(`  Encoded: ${formatHex(alternating8Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(alternating8Encoded)}`)
  printInfo(`  Expected: 10101010 = 0xAA`)
  printInfo(`  Matches: ${alternating8Encoded[0] === 0xaa}`)

  // Step 3: Bit position mapping
  printStep(3, 'Bit Position Mapping')

  printInfo('Bools map to bit positions (MSB first):')
  printInfo('  Array index:  [0]  [1]  [2]  [3]  [4]  [5]  [6]  [7]')
  printInfo('  Bit position: b7   b6   b5   b4   b3   b2   b1   b0')
  printInfo('  Bit value:    128  64   32   16   8    4    2    1')

  // Single true at each position
  printInfo('\nSingle true at each position:')

  for (let i = 0; i < 8; i++) {
    const bools = new Array(8).fill(false)
    bools[i] = true
    const encoded = bool8Type.encode(bools)
    const expectedByte = 1 << (7 - i) // MSB first
    printInfo(`  Index ${i}: ${formatBinary(encoded[0])} = 0x${encoded[0].toString(16).padStart(2, '0')} (expected: 0x${expectedByte.toString(16).padStart(2, '0')})`)
  }

  // Step 4: bool[16] - 2 bytes
  printStep(4, 'bool[16] Encoding - 2 Bytes')

  const bool16Type = ABIType.from('bool[16]') as ABIArrayStaticType

  printInfo(`Type: ${bool16Type.toString()}`)
  printInfo(`byteLen(): ${bool16Type.byteLen()}`)

  // First 8 true, rest false
  const firstHalf16 = [true, true, true, true, true, true, true, true, false, false, false, false, false, false, false, false]
  const firstHalf16Encoded = bool16Type.encode(firstHalf16)

  printInfo(`\nFirst 8 true, rest false:`)
  printInfo(`  Encoded: ${formatHex(firstHalf16Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(firstHalf16Encoded)}`)
  printInfo(`  Byte 0:  ${formatBinary(firstHalf16Encoded[0])} (positions 0-7)`)
  printInfo(`  Byte 1:  ${formatBinary(firstHalf16Encoded[1])} (positions 8-15)`)

  // All true 16
  const allTrue16 = new Array(16).fill(true)
  const allTrue16Encoded = bool16Type.encode(allTrue16)

  printInfo(`\nAll 16 true:`)
  printInfo(`  Encoded: ${formatHex(allTrue16Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(allTrue16Encoded)}`)
  printInfo(`  Length:  ${allTrue16Encoded.length} bytes`)

  // Step 5: Partial byte arrays (bool[5])
  printStep(5, 'Partial Byte Arrays - bool[5]')

  const bool5Type = ABIType.from('bool[5]') as ABIArrayStaticType

  printInfo(`Type: ${bool5Type.toString()}`)
  printInfo(`byteLen(): ${bool5Type.byteLen()}`)
  printInfo(`Note: 5 bools still require 1 full byte (bits 0-4 used, bits 5-7 are padding zeros)`)

  const bool5Values = [true, true, true, true, true]
  const bool5Encoded = bool5Type.encode(bool5Values)

  printInfo(`\nAll 5 true: [${bool5Values.join(', ')}]`)
  printInfo(`  Encoded: ${formatHex(bool5Encoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(bool5Encoded)}`)
  printInfo(`  Expected: 11111000 (5 ones + 3 padding zeros)`)
  printInfo(`  Expected value: 0xF8 = ${0xf8}`)
  printInfo(`  Matches: ${bool5Encoded[0] === 0xf8}`)

  // Different bool[5] patterns
  const bool5Pattern = [true, false, true, false, true]
  const bool5PatternEncoded = bool5Type.encode(bool5Pattern)

  printInfo(`\nPattern [T,F,T,F,T]:`)
  printInfo(`  Encoded: ${formatHex(bool5PatternEncoded)}`)
  printInfo(`  Binary:  ${formatBinaryBytes(bool5PatternEncoded)}`)
  printInfo(`  Expected: 10101000 (pattern + 3 padding zeros)`)

  // Step 6: Various partial byte sizes
  printStep(6, 'Byte Length Formula for Bool Arrays')

  printInfo('Formula: byteLen = ceil(arrayLength / 8)')
  printInfo('')
  printInfo('Length | Bytes | Formula')
  printInfo('-------|-------|--------')

  const boolSizes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 16, 17, 24, 32]

  for (const size of boolSizes) {
    const type = ABIType.from(`bool[${size}]`) as ABIArrayStaticType
    const expectedBytes = Math.ceil(size / 8)
    printInfo(`${String(size).padStart(6)} | ${String(type.byteLen()).padStart(5)} | ceil(${size}/8) = ${expectedBytes}`)
  }

  // Step 7: Compare bool[] vs uint8[] encoding size
  printStep(7, 'Size Comparison: bool[] vs uint8[]')

  printInfo('Comparison of encoded sizes for same element count:')
  printInfo('')
  printInfo('Count | bool[N] bytes | uint8[N] bytes | Savings')
  printInfo('------|---------------|----------------|--------')

  const counts = [8, 16, 32, 64, 100, 256]

  for (const count of counts) {
    const boolType = ABIType.from(`bool[${count}]`) as ABIArrayStaticType
    const uint8Type = ABIType.from(`uint8[${count}]`) as ABIArrayStaticType

    const boolBytes = boolType.byteLen()
    const uint8Bytes = uint8Type.byteLen()
    const savings = ((1 - boolBytes / uint8Bytes) * 100).toFixed(1)

    printInfo(`${String(count).padStart(5)} | ${String(boolBytes).padStart(13)} | ${String(uint8Bytes).padStart(14)} | ${savings}%`)
  }

  printInfo('\nBool arrays use 8x less space than uint8 arrays for boolean data!')

  // Step 8: Dynamic bool arrays
  printStep(8, 'Dynamic Bool Arrays')

  const boolDynamicType = ABIType.from('bool[]') as ABIArrayDynamicType

  printInfo(`Type: ${boolDynamicType.toString()}`)
  printInfo(`childType: ${boolDynamicType.childType.toString()}`)
  printInfo(`isDynamic(): ${boolDynamicType.isDynamic()}`)

  // Encode a dynamic bool array
  const dynamicBools = [true, true, false, true, true, false, false, true, true, false]
  const dynamicEncoded = boolDynamicType.encode(dynamicBools)

  printInfo(`\nDynamic array: [${dynamicBools.join(', ')}] (${dynamicBools.length} elements)`)
  printInfo(`  Encoded: ${formatHex(dynamicEncoded)}`)
  printInfo(`  Length:  ${dynamicEncoded.length} bytes`)

  // Break down the encoding
  const lengthPrefix = (dynamicEncoded[0] << 8) | dynamicEncoded[1]
  const dataBytes = dynamicEncoded.slice(2)

  printInfo(`\nEncoding breakdown:`)
  printInfo(`  Length prefix: ${formatHex(dynamicEncoded.slice(0, 2))} = ${lengthPrefix} elements`)
  printInfo(`  Data bytes:    ${formatHex(dataBytes)}`)
  printInfo(`  Data binary:   ${formatBinaryBytes(dataBytes)}`)

  // Step 9: Decoding packed bool arrays
  printStep(9, 'Decoding Packed Bool Arrays')

  // Static array decode
  const encodeValues = [true, false, true, true, false, false, true, false]
  const encoded = bool8Type.encode(encodeValues)
  const decoded = bool8Type.decode(encoded) as boolean[]

  printInfo(`Original:  [${encodeValues.join(', ')}]`)
  printInfo(`Encoded:   ${formatHex(encoded)} = ${formatBinaryBytes(encoded)}`)
  printInfo(`Decoded:   [${decoded.join(', ')}]`)
  printInfo(`Round-trip: ${decoded.every((v, i) => v === encodeValues[i])}`)

  // Dynamic array decode
  const dynamicDecoded = boolDynamicType.decode(dynamicEncoded) as boolean[]

  printInfo(`\nDynamic original: [${dynamicBools.join(', ')}]`)
  printInfo(`Dynamic decoded:  [${dynamicDecoded.join(', ')}]`)
  printInfo(`Round-trip: ${dynamicDecoded.every((v, i) => v === dynamicBools[i])}`)

  // Step 10: Bit-level view visualization
  printStep(10, 'Bit-Level View Visualization')

  printInfo('Detailed bit-level view of bool[8] encoding:')
  printInfo('')

  const visualBools = [true, false, true, true, false, true, false, true]
  const visualEncoded = bool8Type.encode(visualBools)

  printInfo(`Values: [${visualBools.join(', ')}]`)
  printInfo(`Byte:   ${formatHex(visualEncoded)} = ${formatBinary(visualEncoded[0])}`)
  printInfo('')
  printInfo('Position |  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |')
  printInfo('---------|-----|-----|-----|-----|-----|-----|-----|-----|')
  printInfo(`Value    |  ${visualBools.map((b) => (b ? 'T' : 'F')).join('  |  ')}  |`)
  printInfo(`Bit      |  ${Array.from(formatBinary(visualEncoded[0])).join('  |  ')}  |`)
  printInfo(`Weight   | 128 |  64 |  32 |  16 |  8  |  4  |  2  |  1  |`)

  // Calculate the byte value step by step
  let byteValue = 0
  const contributions: string[] = []

  for (let i = 0; i < 8; i++) {
    if (visualBools[i]) {
      const bitValue = 1 << (7 - i)
      byteValue += bitValue
      contributions.push(String(bitValue))
    }
  }

  printInfo('')
  printInfo(`Byte value = ${contributions.join(' + ')} = ${byteValue} = 0x${byteValue.toString(16).padStart(2, '0')}`)

  // Step 11: Summary
  printStep(11, 'Summary')

  printInfo('Bool array packing in ARC-4:')
  printInfo('')
  printInfo('Packing rules:')
  printInfo('  - Each bool = 1 bit')
  printInfo('  - 8 bools pack into 1 byte')
  printInfo('  - Bit order: MSB first (index 0 = bit 7)')
  printInfo('  - Padding: zeros added to complete the last byte')
  printInfo('')
  printInfo('Size formula:')
  printInfo('  - Static:  byteLen = ceil(arrayLength / 8)')
  printInfo('  - Dynamic: 2 (length prefix) + ceil(arrayLength / 8)')
  printInfo('')
  printInfo('Space efficiency:')
  printInfo('  - 8x more efficient than storing bools as uint8')
  printInfo('  - bool[256] = 32 bytes vs uint8[256] = 256 bytes')
  printInfo('')
  printInfo('Bit values by position:')
  printInfo('  Position 0 (MSB): 0x80 = 128')
  printInfo('  Position 1:       0x40 = 64')
  printInfo('  Position 2:       0x20 = 32')
  printInfo('  Position 3:       0x10 = 16')
  printInfo('  Position 4:       0x08 = 8')
  printInfo('  Position 5:       0x04 = 4')
  printInfo('  Position 6:       0x02 = 2')
  printInfo('  Position 7 (LSB): 0x01 = 1')

  printSuccess('ABI Bool Array Packing example completed successfully!')
}

main()

---

Other examples in ABI Encoding

• ABI Type Parsing
• ABI Primitive Types
• ABI Address Type
• ABI String Type
• ABI Static Array Type
• ABI Dynamic Array Type
• ABI Tuple Type
• ABI Struct Type
• ABI Struct and Tuple Conversion
• ABI Bool Array Packing
• ABI Method
• AVM Type Encoding
• Type Guards
• ABI Complex Nested Types
• ARC-56 Storage Helpers