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

Primitive Codecs

← Back to Common Utilities

Description

Section titled “Description”

This example demonstrates how to use primitive codec types for encoding/decoding basic values in wire format (JSON or MessagePack). Topics covered:

  • Codec interface: encode(), decode(), defaultValue() methods
  • numberCodec for encoding/decoding numbers
  • bigIntCodec for encoding/decoding BigInt values
  • booleanCodec for encoding/decoding boolean values
  • stringCodec for encoding/decoding UTF-8 strings
  • bytesCodec for encoding/decoding raw bytes
  • bytesBase64Codec for base64 encoding
  • addressCodec for encoding/decoding Algorand addresses
  • Round-trip verification: decode(encode(value)) equals original

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 common/09-primitive-codecs.ts

Code

Section titled “Code”

View source on GitHub

09-primitive-codecs.ts
/**
 * Example: Primitive Codecs
 *
 * This example demonstrates how to use primitive codec types for encoding/decoding
 * basic values in wire format (JSON or MessagePack).
 *
 * Topics covered:
 * - Codec interface: encode(), decode(), defaultValue() methods
 * - numberCodec for encoding/decoding numbers
 * - bigIntCodec for encoding/decoding BigInt values
 * - booleanCodec for encoding/decoding boolean values
 * - stringCodec for encoding/decoding UTF-8 strings
 * - bytesCodec for encoding/decoding raw bytes
 * - bytesBase64Codec for base64 encoding
 * - addressCodec for encoding/decoding Algorand addresses
 * - Round-trip verification: decode(encode(value)) equals original
 *
 * Prerequisites:
 * - No LocalNet required
 */


import type { EncodingFormat } from '@algorandfoundation/algokit-utils/common'
import {
  Address,
  addressCodec,
  arrayEqual,
  bigIntCodec,
  booleanCodec,
  bytesBase64Codec,
  bytesCodec,
  numberCodec,
  stringCodec,
} from '@algorandfoundation/algokit-utils/common'
import { formatHex, printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js'


// ============================================================================
// Main Example
// ============================================================================


printHeader('Primitive Codecs Example')


// ============================================================================
// Step 1: The Codec Interface
// ============================================================================
printStep(1, 'The Codec Interface')


printInfo('Codecs provide bidirectional transformation between app types and wire formats.')
printInfo('Each codec has these core methods:')
printInfo('')
printInfo('  encode(value, format)  - Transform app value to wire format')
printInfo('  decode(value, format)  - Transform wire value to app value')
printInfo('  defaultValue()         - Get the default value for this type')
printInfo('')
printInfo('Format can be "json" or "msgpack" - some codecs behave differently per format.')
printInfo('')


// Show default values for each codec
printInfo('Default values for each primitive codec:')
printInfo(`  numberCodec.defaultValue()   = ${numberCodec.defaultValue()}`)
printInfo(`  bigIntCodec.defaultValue()   = ${bigIntCodec.defaultValue()}n`)
printInfo(`  booleanCodec.defaultValue()  = ${booleanCodec.defaultValue()}`)
printInfo(`  stringCodec.defaultValue()   = "${stringCodec.defaultValue()}" (empty string)`)
printInfo(`  bytesCodec.defaultValue()    = Uint8Array(${bytesCodec.defaultValue().length}) (empty)`)
printInfo(`  addressCodec.defaultValue()  = ${addressCodec.defaultValue().toString().slice(0, 10)}... (zero address)`)
printInfo('')
printSuccess('Codec interface provides consistent encode/decode methods')


// ============================================================================
// Step 2: numberCodec - Encoding/Decoding Numbers
// ============================================================================
printStep(2, 'numberCodec - Encoding/Decoding Numbers')


printInfo('numberCodec handles JavaScript number values.')
printInfo('Numbers pass through unchanged in both JSON and msgpack formats.')
printInfo('')


const testNumbers = [0, 42, -100, 3.14159, Number.MAX_SAFE_INTEGER]


for (const num of testNumbers) {
  const encodedJson = numberCodec.encode(num, 'json')
  const encodedMsgpack = numberCodec.encode(num, 'msgpack')
  const decodedJson = numberCodec.decode(encodedJson, 'json')
  const decodedMsgpack = numberCodec.decode(encodedMsgpack, 'msgpack')


  printInfo(`  ${num}:`)
  printInfo(`    JSON:    encode=${encodedJson}, decode=${decodedJson}, matches=${num === decodedJson}`)
  printInfo(`    msgpack: encode=${encodedMsgpack}, decode=${decodedMsgpack}, matches=${num === decodedMsgpack}`)
}
printInfo('')


// Round-trip verification
const roundTripNum = 12345
const rtEncoded = numberCodec.encode(roundTripNum, 'json')
const rtDecoded = numberCodec.decode(rtEncoded, 'json')
if (rtDecoded === roundTripNum) {
  printSuccess(`Round-trip: decode(encode(${roundTripNum})) === ${rtDecoded}`)
}


// ============================================================================
// Step 3: bigIntCodec - Encoding/Decoding BigInt Values
// ============================================================================
printStep(3, 'bigIntCodec - Encoding/Decoding BigInt Values')


printInfo('bigIntCodec handles JavaScript BigInt values (uint64 on Algorand).')
printInfo('Essential for values exceeding Number.MAX_SAFE_INTEGER (9007199254740991).')
printInfo('')


const testBigInts: bigint[] = [0n, 100n, 9007199254740993n, 18446744073709551615n] // 0, 100, MAX_SAFE+2, max uint64


for (const big of testBigInts) {
  const encodedJson = bigIntCodec.encode(big, 'json')
  const encodedMsgpack = bigIntCodec.encode(big, 'msgpack')
  const decodedJson = bigIntCodec.decode(encodedJson, 'json')
  const decodedMsgpack = bigIntCodec.decode(encodedMsgpack, 'msgpack')


  printInfo(`  ${big}n:`)
  printInfo(`    JSON:    encode=${encodedJson}${typeof encodedJson === 'bigint' ? 'n' : ''}, decode=${decodedJson}n, matches=${big === decodedJson}`)
  printInfo(`    msgpack: encode=${encodedMsgpack}${typeof encodedMsgpack === 'bigint' ? 'n' : ''}, decode=${decodedMsgpack}n, matches=${big === decodedMsgpack}`)
}
printInfo('')


// Round-trip verification with large value
const roundTripBig = 18446744073709551615n // max uint64
const rtBigEncoded = bigIntCodec.encode(roundTripBig, 'msgpack')
const rtBigDecoded = bigIntCodec.decode(rtBigEncoded, 'msgpack')
if (rtBigDecoded === roundTripBig) {
  printSuccess(`Round-trip: decode(encode(${roundTripBig}n)) === ${rtBigDecoded}n`)
}


// ============================================================================
// Step 4: booleanCodec - Encoding/Decoding Boolean Values
// ============================================================================
printStep(4, 'booleanCodec - Encoding/Decoding Boolean Values')


printInfo('booleanCodec handles true/false values.')
printInfo('Default value is false.')
printInfo('')


const testBools = [true, false]


for (const bool of testBools) {
  const encodedJson = booleanCodec.encode(bool, 'json')
  const encodedMsgpack = booleanCodec.encode(bool, 'msgpack')
  const decodedJson = booleanCodec.decode(encodedJson, 'json')
  const decodedMsgpack = booleanCodec.decode(encodedMsgpack, 'msgpack')


  printInfo(`  ${bool}:`)
  printInfo(`    JSON:    encode=${encodedJson}, decode=${decodedJson}, matches=${bool === decodedJson}`)
  printInfo(`    msgpack: encode=${encodedMsgpack}, decode=${decodedMsgpack}, matches=${bool === decodedMsgpack}`)
}
printInfo('')


// Round-trip verification
const roundTripBool = true
const rtBoolEncoded = booleanCodec.encode(roundTripBool, 'json')
const rtBoolDecoded = booleanCodec.decode(rtBoolEncoded, 'json')
if (rtBoolDecoded === roundTripBool) {
  printSuccess(`Round-trip: decode(encode(${roundTripBool})) === ${rtBoolDecoded}`)
}


// ============================================================================
// Step 5: stringCodec - Encoding/Decoding UTF-8 Strings
// ============================================================================
printStep(5, 'stringCodec - Encoding/Decoding UTF-8 Strings')


printInfo('stringCodec handles UTF-8 string values.')
printInfo('In msgpack, strings may be received as Uint8Array (normalized on decode).')
printInfo('')


const testStrings = ['', 'Hello', 'Hello, Algorand!', 'Unicode: \u00e9\u00e8\u00ea']


for (const str of testStrings) {
  const encodedJson = stringCodec.encode(str, 'json')
  const encodedMsgpack = stringCodec.encode(str, 'msgpack')
  const decodedJson = stringCodec.decode(encodedJson, 'json')
  const decodedMsgpack = stringCodec.decode(encodedMsgpack, 'msgpack')


  const displayStr = str === '' ? '(empty)' : `"${str}"`
  printInfo(`  ${displayStr}:`)
  printInfo(`    JSON:    encode="${encodedJson}", decode="${decodedJson}", matches=${str === decodedJson}`)
  printInfo(`    msgpack: encode="${encodedMsgpack}", decode="${decodedMsgpack}", matches=${str === decodedMsgpack}`)
}
printInfo('')


// Round-trip verification
const roundTripStr = 'Algorand SDK'
const rtStrEncoded = stringCodec.encode(roundTripStr, 'json')
const rtStrDecoded = stringCodec.decode(rtStrEncoded, 'json')
if (rtStrDecoded === roundTripStr) {
  printSuccess(`Round-trip: decode(encode("${roundTripStr}")) === "${rtStrDecoded}"`)
}


// ============================================================================
// Step 6: bytesCodec - Encoding/Decoding Raw Bytes
// ============================================================================
printStep(6, 'bytesCodec - Encoding/Decoding Raw Bytes')


printInfo('bytesCodec handles Uint8Array values (raw binary data).')
printInfo('JSON format: encodes to base64 string')
printInfo('msgpack format: encodes as raw bytes')
printInfo('')


const testBytes = [
  new Uint8Array([]),
  new Uint8Array([0x01, 0x02, 0x03]),
  new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
  new Uint8Array(32).fill(0xab), // 32-byte key simulation
]


for (const bytes of testBytes) {
  const encodedJson = bytesCodec.encode(bytes, 'json')
  const encodedMsgpack = bytesCodec.encode(bytes, 'msgpack')
  const decodedJson = bytesCodec.decode(encodedJson, 'json')
  const decodedMsgpack = bytesCodec.decode(encodedMsgpack, 'msgpack')


  const displayBytes = bytes.length === 0 ? '(empty)' : formatHex(bytes.slice(0, 8)) + (bytes.length > 8 ? '...' : '')
  printInfo(`  ${displayBytes} (${bytes.length} bytes):`)
  printInfo(`    JSON:    encode="${encodedJson}" (base64)`)
  printInfo(`             decode=${formatHex(decodedJson.slice(0, 8))}${decodedJson.length > 8 ? '...' : ''}, matches=${arrayEqual(bytes, decodedJson)}`)
  printInfo(`    msgpack: encode=${formatHex((encodedMsgpack as Uint8Array).slice(0, 8))}${(encodedMsgpack as Uint8Array).length > 8 ? '...' : ''}`)
  printInfo(`             decode=${formatHex(decodedMsgpack.slice(0, 8))}${decodedMsgpack.length > 8 ? '...' : ''}, matches=${arrayEqual(bytes, decodedMsgpack)}`)
}
printInfo('')


// Round-trip verification
const roundTripBytes = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05])
const rtBytesEncodedJson = bytesCodec.encode(roundTripBytes, 'json')
const rtBytesDecodedJson = bytesCodec.decode(rtBytesEncodedJson, 'json')
if (arrayEqual(rtBytesDecodedJson, roundTripBytes)) {
  printSuccess(`Round-trip (JSON): decode(encode(${formatHex(roundTripBytes)})) matches original`)
}


const rtBytesEncodedMsgpack = bytesCodec.encode(roundTripBytes, 'msgpack')
const rtBytesDecodedMsgpack = bytesCodec.decode(rtBytesEncodedMsgpack, 'msgpack')
if (arrayEqual(rtBytesDecodedMsgpack, roundTripBytes)) {
  printSuccess(`Round-trip (msgpack): decode(encode(${formatHex(roundTripBytes)})) matches original`)
}


// ============================================================================
// Step 7: bytesBase64Codec - Base64 Encoding for Bytes
// ============================================================================
printStep(7, 'bytesBase64Codec - Base64 Encoding for Bytes')


printInfo('bytesBase64Codec always encodes to base64 (both JSON and msgpack).')
printInfo('Used for fields that are always base64 in wire format.')
printInfo('')


const testBase64Bytes = [
  new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]), // "Hello" in ASCII
  new Uint8Array([0xff, 0xfe, 0xfd]),
]


for (const bytes of testBase64Bytes) {
  const encodedJson = bytesBase64Codec.encode(bytes, 'json')
  const encodedMsgpack = bytesBase64Codec.encode(bytes, 'msgpack')
  const decodedJson = bytesBase64Codec.decode(encodedJson, 'json')
  const decodedMsgpack = bytesBase64Codec.decode(encodedMsgpack, 'msgpack')


  printInfo(`  ${formatHex(bytes)}:`)
  printInfo(`    JSON:    encode="${encodedJson}" (base64)`)
  printInfo(`             decode=${formatHex(decodedJson)}, matches=${arrayEqual(bytes, decodedJson)}`)
  printInfo(`    msgpack: encode="${encodedMsgpack}" (base64)`)
  printInfo(`             decode=${formatHex(decodedMsgpack)}, matches=${arrayEqual(bytes, decodedMsgpack)}`)
}
printInfo('')


// Round-trip verification
const rtB64Bytes = new Uint8Array([0x01, 0x02, 0x03])
const rtB64Encoded = bytesBase64Codec.encode(rtB64Bytes, 'json')
const rtB64Decoded = bytesBase64Codec.decode(rtB64Encoded, 'json')
if (arrayEqual(rtB64Decoded, rtB64Bytes)) {
  printSuccess(`Round-trip: decode(encode(${formatHex(rtB64Bytes)})) via base64 "${rtB64Encoded}" matches original`)
}


// ============================================================================
// Step 8: addressCodec - Encoding/Decoding Algorand Addresses
// ============================================================================
printStep(8, 'addressCodec - Encoding/Decoding Algorand Addresses')


printInfo('addressCodec handles Algorand Address objects.')
printInfo('JSON format: encodes to 58-character base32 string')
printInfo('msgpack format: encodes to 32-byte public key')
printInfo('')


// Create test addresses
const zeroAddr = Address.zeroAddress()
const testAddrBytes = new Uint8Array(32)
for (let i = 0; i < 32; i++) testAddrBytes[i] = i
const testAddr = new Address(testAddrBytes)


const testAddresses = [zeroAddr, testAddr]


for (const addr of testAddresses) {
  const encodedJson = addressCodec.encode(addr, 'json')
  const encodedMsgpack = addressCodec.encode(addr, 'msgpack')
  const decodedJson = addressCodec.decode(encodedJson, 'json')
  const decodedMsgpack = addressCodec.decode(encodedMsgpack, 'msgpack')


  const displayAddr = `${addr.toString().slice(0, 12)  }...`
  printInfo(`  ${displayAddr}:`)
  printInfo(`    JSON:    encode="${(encodedJson as string).slice(0, 12)}..." (base32 string)`)
  printInfo(`             decode=${decodedJson.toString().slice(0, 12)}..., matches=${addr.equals(decodedJson)}`)
  printInfo(`    msgpack: encode=${formatHex((encodedMsgpack as Uint8Array).slice(0, 8))}... (32-byte pubkey)`)
  printInfo(`             decode=${decodedMsgpack.toString().slice(0, 12)}..., matches=${addr.equals(decodedMsgpack)}`)
}
printInfo('')


// Round-trip verification
const roundTripAddr = testAddr
const rtAddrEncodedJson = addressCodec.encode(roundTripAddr, 'json')
const rtAddrDecodedJson = addressCodec.decode(rtAddrEncodedJson, 'json')
if (rtAddrDecodedJson.equals(roundTripAddr)) {
  printSuccess(`Round-trip (JSON): decode(encode(${roundTripAddr.toString().slice(0, 12)}...)) matches original`)
}


const rtAddrEncodedMsgpack = addressCodec.encode(roundTripAddr, 'msgpack')
const rtAddrDecodedMsgpack = addressCodec.decode(rtAddrEncodedMsgpack, 'msgpack')
if (rtAddrDecodedMsgpack.equals(roundTripAddr)) {
  printSuccess(`Round-trip (msgpack): decode(encode(${roundTripAddr.toString().slice(0, 12)}...)) matches original`)
}


// ============================================================================
// Step 9: Format Differences Summary
// ============================================================================
printStep(9, 'Format Differences Summary')


printInfo('Codec behavior differs by format (json vs msgpack):')
printInfo('')
printInfo('  Codec              | JSON Encoding         | msgpack Encoding')
printInfo('  -------------------|----------------------|-------------------')
printInfo('  numberCodec        | number               | number')
printInfo('  bigIntCodec        | bigint               | bigint')
printInfo('  booleanCodec       | boolean              | boolean')
printInfo('  stringCodec        | string               | string (or Uint8Array)')
printInfo('  bytesCodec         | base64 string        | Uint8Array')
printInfo('  bytesBase64Codec   | base64 string        | base64 string')
printInfo('  addressCodec       | 58-char base32 string| 32-byte Uint8Array')
printInfo('')
printSuccess('Codecs handle format-specific transformations automatically')


// ============================================================================
// Step 10: Round-Trip Verification Summary
// ============================================================================
printStep(10, 'Round-Trip Verification Summary')


printInfo('All primitive codecs support perfect round-trip encoding:')
printInfo('')


// Aggregate all round-trip results
const roundTrips: Array<{ name: string; value: string; format: EncodingFormat; success: boolean }> = []


// Number
const numVal = 42
roundTrips.push({
  name: 'numberCodec',
  value: String(numVal),
  format: 'json',
  success: numberCodec.decode(numberCodec.encode(numVal, 'json'), 'json') === numVal,
})


// BigInt
const bigVal = 9007199254740993n
roundTrips.push({
  name: 'bigIntCodec',
  value: `${bigVal}n`,
  format: 'msgpack',
  success: bigIntCodec.decode(bigIntCodec.encode(bigVal, 'msgpack'), 'msgpack') === bigVal,
})


// Boolean
const boolVal = true
roundTrips.push({
  name: 'booleanCodec',
  value: String(boolVal),
  format: 'json',
  success: booleanCodec.decode(booleanCodec.encode(boolVal, 'json'), 'json') === boolVal,
})


// String
const strVal = 'Algorand'
roundTrips.push({
  name: 'stringCodec',
  value: `"${strVal}"`,
  format: 'json',
  success: stringCodec.decode(stringCodec.encode(strVal, 'json'), 'json') === strVal,
})


// Bytes
const bytesVal = new Uint8Array([1, 2, 3, 4, 5])
roundTrips.push({
  name: 'bytesCodec',
  value: formatHex(bytesVal),
  format: 'json',
  success: arrayEqual(bytesCodec.decode(bytesCodec.encode(bytesVal, 'json'), 'json'), bytesVal),
})
roundTrips.push({
  name: 'bytesCodec',
  value: formatHex(bytesVal),
  format: 'msgpack',
  success: arrayEqual(bytesCodec.decode(bytesCodec.encode(bytesVal, 'msgpack'), 'msgpack'), bytesVal),
})


// BytesBase64
const b64Val = new Uint8Array([0xff, 0xfe, 0xfd])
roundTrips.push({
  name: 'bytesBase64Codec',
  value: formatHex(b64Val),
  format: 'json',
  success: arrayEqual(bytesBase64Codec.decode(bytesBase64Codec.encode(b64Val, 'json'), 'json'), b64Val),
})


// Address
const addrVal = testAddr
roundTrips.push({
  name: 'addressCodec',
  value: `${addrVal.toString().slice(0, 12)  }...`,
  format: 'json',
  success: addressCodec.decode(addressCodec.encode(addrVal, 'json'), 'json').equals(addrVal),
})
roundTrips.push({
  name: 'addressCodec',
  value: `${addrVal.toString().slice(0, 12)  }...`,
  format: 'msgpack',
  success: addressCodec.decode(addressCodec.encode(addrVal, 'msgpack'), 'msgpack').equals(addrVal),
})


for (const rt of roundTrips) {
  const status = rt.success ? 'PASS' : 'FAIL'
  printInfo(`  [${status}] ${rt.name} (${rt.format}): ${rt.value}`)
}


const allPassed = roundTrips.every((rt) => rt.success)
if (allPassed) {
  printInfo('')
  printSuccess('All round-trip verifications passed!')
}


// ============================================================================
// Summary
// ============================================================================
printStep(11, 'Summary')


printInfo('Primitive codecs for Algorand wire format encoding:')
printInfo('')
printInfo('  Codec Interface:')
printInfo('    - encode(value, format) - Transform to wire format')
printInfo('    - decode(value, format) - Transform from wire format')
printInfo('    - defaultValue() - Get type default (0, false, "", etc.)')
printInfo('')
printInfo('  Available Primitive Codecs:')
printInfo('    - numberCodec     - JavaScript numbers')
printInfo('    - bigIntCodec     - BigInt for uint64 values')
printInfo('    - booleanCodec    - true/false values')
printInfo('    - stringCodec     - UTF-8 strings')
printInfo('    - bytesCodec      - Raw binary data (Uint8Array)')
printInfo('    - bytesBase64Codec - Always base64 encoded bytes')
printInfo('    - addressCodec    - Algorand Address objects')
printInfo('')
printInfo('  Format Support:')
printInfo('    - "json" - JSON wire format (strings for bytes/addresses)')
printInfo('    - "msgpack" - MessagePack format (binary for bytes/addresses)')
printInfo('')
printSuccess('Primitive Codecs Example completed!')

Other examples in Common Utilities

Section titled “Other examples in Common Utilities”