ARC-56 Storage Helpers

← Back to ABI Encoding

Description

This example demonstrates how to use ARC-56 storage helpers to inspect contract state key definitions and maps from an ARC-56 contract specification: Storage Key Functions:

• getGlobalABIStorageKeys(): Get all global state key definitions
• getLocalABIStorageKeys(): Get all local state key definitions
• getBoxABIStorageKeys(): Get all box key definitions Storage Map Functions:
• getBoxABIStorageMaps(): Get box map definitions ABIStorageKey properties:
• key: Base64-encoded key bytes
• keyType: The type of the key (ABIType or AVMType)
• valueType: The type of the value (ABIType or AVMType)
• desc?: Optional description ABIStorageMap properties:
• keyType: The type of keys in the map
• valueType: The type of values in the map
• desc?: Optional description
• prefix?: Base64-encoded prefix for map keys The example also deploys a contract to LocalNet and reads actual state values.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example abi/15-arc56-storage.ts

Code

View source on GitHub

15-arc56-storage.ts

/**
 * Example: ARC-56 Storage Helpers
 *
 * This example demonstrates how to use ARC-56 storage helpers to inspect
 * contract state key definitions and maps from an ARC-56 contract specification:
 *
 * Storage Key Functions:
 * - getGlobalABIStorageKeys(): Get all global state key definitions
 * - getLocalABIStorageKeys(): Get all local state key definitions
 * - getBoxABIStorageKeys(): Get all box key definitions
 *
 * Storage Map Functions:
 * - getBoxABIStorageMaps(): Get box map definitions
 *
 * ABIStorageKey properties:
 * - key: Base64-encoded key bytes
 * - keyType: The type of the key (ABIType or AVMType)
 * - valueType: The type of the value (ABIType or AVMType)
 * - desc?: Optional description
 *
 * ABIStorageMap properties:
 * - keyType: The type of keys in the map
 * - valueType: The type of values in the map
 * - desc?: Optional description
 * - prefix?: Base64-encoded prefix for map keys
 *
 * The example also deploys a contract to LocalNet and reads actual state values.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient, algo } from '@algorandfoundation/algokit-utils'
import type { ABIStorageKey, ABIStorageMap, Arc56Contract } from '@algorandfoundation/algokit-utils/abi'
import {
  ABIType,
  decodeAVMValue,
  getBoxABIStorageKeys,
  getBoxABIStorageMaps,
  getGlobalABIStorageKeys,
  getLocalABIStorageKeys,
  isAVMType,
} from '@algorandfoundation/algokit-utils/abi'
import { readFileSync } from 'fs'
import { join } from 'path'
import { formatBytes, formatHex, printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js'

// tsx provides __dirname in CJS-compatibility mode
declare const __dirname: string

/**
 * Formats a storage key type for display (either ABI type or AVM type)
 */
function formatKeyOrValueType(type: ABIType | string): string {
  if (typeof type === 'string') {
    return type // AVM type (e.g., "AVMUint64", "AVMString", "AVMBytes")
  }
  return type.toString() // ABI type
}

/**
 * Displays ABIStorageKey properties
 */
function displayStorageKey(name: string, storageKey: ABIStorageKey): void {
  printInfo(`  ${name}:`)
  printInfo(`    key (base64): ${storageKey.key}`)
  printInfo(`    key (decoded): "${Buffer.from(storageKey.key, 'base64').toString('utf-8')}"`)
  printInfo(`    keyType: ${formatKeyOrValueType(storageKey.keyType)}`)
  printInfo(`    valueType: ${formatKeyOrValueType(storageKey.valueType)}`)
  if (storageKey.desc) {
    printInfo(`    desc: ${storageKey.desc}`)
  }
}

/**
 * Displays ABIStorageMap properties
 */
function displayStorageMap(name: string, storageMap: ABIStorageMap): void {
  printInfo(`  ${name}:`)
  printInfo(`    keyType: ${formatKeyOrValueType(storageMap.keyType)}`)
  printInfo(`    valueType: ${formatKeyOrValueType(storageMap.valueType)}`)
  if (storageMap.desc) {
    printInfo(`    desc: ${storageMap.desc}`)
  }
  if (storageMap.prefix !== undefined) {
    printInfo(`    prefix (base64): "${storageMap.prefix}"`)
    if (storageMap.prefix) {
      printInfo(`    prefix (decoded): "${Buffer.from(storageMap.prefix, 'base64').toString('utf-8')}"`)
    }
  }
}

/**
 * Decodes a raw state value using the storage key's valueType
 */
function decodeStateValue(storageKey: ABIStorageKey, rawBytes: Uint8Array | undefined): string {
  // Handle undefined or empty bytes
  if (!rawBytes || rawBytes.length === 0) {
    return '(empty)'
  }

  const valueType = storageKey.valueType
  try {
    if (typeof valueType === 'string' && isAVMType(valueType)) {
      // AVM type
      const decoded = decodeAVMValue(valueType, rawBytes)
      if (decoded instanceof Uint8Array) {
        return formatHex(decoded)
      }
      return String(decoded)
    } else if (valueType instanceof ABIType) {
      // ABI type
      const decoded = valueType.decode(rawBytes)
      if (decoded instanceof Uint8Array) {
        return formatHex(decoded)
      }
      return JSON.stringify(decoded)
    }
  } catch {
    // If decoding fails, fall through to raw bytes display
  }
  return formatBytes(rawBytes)
}

async function main() {
  printHeader('ARC-56 Storage Helpers Example')

  // Step 1: Load ARC-56 contract specification
  printStep(1, 'Load ARC-56 Contract Specification')

  // Load the application.json (ARC-56 format with TEAL source) from tests/example-contracts/state
  const arc56Path = join(__dirname, '..', '..', '..', 'tests', 'example-contracts', 'state', 'application.json')
  const arc56Content = readFileSync(arc56Path, 'utf-8')
  const appSpec: Arc56Contract = JSON.parse(arc56Content)

  printInfo(`Loaded contract: ${appSpec.name}`)
  printInfo(`ARC standards supported: ${appSpec.arcs.join(', ')}`)
  printInfo('')
  printInfo('State schema:')
  printInfo(`  Global: ${appSpec.state.schema.global.ints} ints, ${appSpec.state.schema.global.bytes} bytes`)
  printInfo(`  Local: ${appSpec.state.schema.local.ints} ints, ${appSpec.state.schema.local.bytes} bytes`)

  // Step 2: Demonstrate getGlobalABIStorageKeys()
  printStep(2, 'Get Global State Key Definitions')

  printInfo('Using getGlobalABIStorageKeys() to get all global state keys:')
  printInfo('')

  const globalKeys = getGlobalABIStorageKeys(appSpec)
  const globalKeyNames = Object.keys(globalKeys)

  printInfo(`Found ${globalKeyNames.length} global state keys:`)
  printInfo('')

  for (const name of globalKeyNames) {
    displayStorageKey(name, globalKeys[name])
    printInfo('')
  }

  // Step 3: Demonstrate getLocalABIStorageKeys()
  printStep(3, 'Get Local State Key Definitions')

  printInfo('Using getLocalABIStorageKeys() to get all local state keys:')
  printInfo('')

  const localKeys = getLocalABIStorageKeys(appSpec)
  const localKeyNames = Object.keys(localKeys)

  printInfo(`Found ${localKeyNames.length} local state keys:`)
  printInfo('')

  for (const name of localKeyNames) {
    displayStorageKey(name, localKeys[name])
    printInfo('')
  }

  // Step 4: Demonstrate getBoxABIStorageKeys()
  printStep(4, 'Get Box Key Definitions')

  printInfo('Using getBoxABIStorageKeys() to get all box storage keys:')
  printInfo('')

  const boxKeys = getBoxABIStorageKeys(appSpec)
  const boxKeyNames = Object.keys(boxKeys)

  if (boxKeyNames.length === 0) {
    printInfo('No box storage keys defined in this contract.')
  } else {
    printInfo(`Found ${boxKeyNames.length} box storage keys:`)
    printInfo('')
    for (const name of boxKeyNames) {
      displayStorageKey(name, boxKeys[name])
      printInfo('')
    }
  }

  // Step 5: Demonstrate getBoxABIStorageMaps()
  printStep(5, 'Get Box Map Definitions')

  printInfo('Using getBoxABIStorageMaps() to get box map definitions:')
  printInfo('')

  const boxMaps = getBoxABIStorageMaps(appSpec)
  const boxMapNames = Object.keys(boxMaps)

  if (boxMapNames.length === 0) {
    printInfo('No box maps defined in this contract.')
  } else {
    printInfo(`Found ${boxMapNames.length} box maps:`)
    printInfo('')
    for (const name of boxMapNames) {
      displayStorageMap(name, boxMaps[name])
      printInfo('')
    }
  }

  // Step 6: Deploy contract and read actual state values
  printStep(6, 'Deploy Contract and Read Actual State Values')

  printInfo('Connecting to LocalNet and deploying State contract...')
  printInfo('')

  const algorand = AlgorandClient.defaultLocalNet()
  const deployer = await algorand.account.kmd.getLocalNetDispenserAccount()

  // Register the deployer's signer with AlgorandClient
  algorand.setSignerFromAccount(deployer)

  // Create app factory from spec (use deployer as default sender with its signer)
  const factory = algorand.client.getAppFactory({
    appSpec,
    defaultSender: deployer,
  })

  // Deploy the app with template parameters
  const { result, appClient } = await factory.deploy({
    deployTimeParams: { VALUE: 1 },
  })
  const appId = result.appId
  printInfo(`Contract deployed with App ID: ${appId}`)
  printInfo('')

  // Set some global state values using the set_global method
  // Method signature: set_global(uint64,uint64,string,byte[4])void
  printInfo('Setting global state values...')
  await appClient.send.call({
    method: 'set_global',
    args: [100n, 200n, 'hello', new Uint8Array([0x41, 0x42, 0x43, 0x44])], // int1, int2, bytes1, bytes2
  })
  printInfo('Global state values set successfully.')
  printInfo('')

  // Read global state using app client
  printInfo('Reading global state and decoding using storage key types:')
  printInfo('')

  const globalState = await appClient.getGlobalState()

  for (const name of globalKeyNames) {
    const storageKey = globalKeys[name]
    const stateEntry = Object.values(globalState).find((entry) => entry.keyBase64 === storageKey.key)

    if (stateEntry) {
      // State can be either uint64 (value is bigint) or bytes (value is string with valueRaw)
      const hasRawValue = 'valueRaw' in stateEntry
      printInfo(`  ${name}:`)
      if (hasRawValue) {
        const rawValue = (stateEntry as { valueRaw: Uint8Array }).valueRaw
        printInfo(`    Raw value: ${rawValue ? formatBytes(rawValue) : '(empty)'}`)
        printInfo(`    Decoded (${formatKeyOrValueType(storageKey.valueType)}): ${decodeStateValue(storageKey, rawValue)}`)
      } else {
        // For uint64 values, the state stores value directly as bigint
        const value = (stateEntry as { value: bigint }).value
        printInfo(`    Value (uint64): ${value}`)
      }
    } else {
      printInfo(`  ${name}: (not set)`)
    }
  }

  // Step 7: Opt-in and set local state
  printStep(7, 'Opt-in and Set Local State')

  printInfo('Opting in to the contract...')
  try {
    await appClient.send.optIn({ method: 'opt_in' })
    printInfo('Opted in successfully.')
  } catch (e) {
    if (String(e).includes('already opted in')) {
      printInfo('Already opted in - skipping.')
    } else {
      throw e
    }
  }
  printInfo('')

  // Method signature: set_local(uint64,uint64,string,byte[4])void
  printInfo('Setting local state values...')
  await appClient.send.call({
    method: 'set_local',
    args: [10n, 20n, 'local', new Uint8Array([0x4c, 0x4f, 0x43, 0x41])], // int1, int2, bytes1, bytes2
  })
  printInfo('Local state values set successfully.')
  printInfo('')

  // Read local state
  printInfo('Reading local state and decoding using storage key types:')
  printInfo('')

  const localState = await appClient.getLocalState(deployer.addr)

  for (const name of localKeyNames) {
    const storageKey = localKeys[name]
    const stateEntry = Object.values(localState).find((entry) => entry.keyBase64 === storageKey.key)

    if (stateEntry) {
      // State can be either uint64 (value is bigint) or bytes (value is string with valueRaw)
      const hasRawValue = 'valueRaw' in stateEntry
      printInfo(`  ${name}:`)
      if (hasRawValue) {
        const rawValue = (stateEntry as { valueRaw: Uint8Array }).valueRaw
        printInfo(`    Raw value: ${rawValue ? formatBytes(rawValue) : '(empty)'}`)
        printInfo(`    Decoded (${formatKeyOrValueType(storageKey.valueType)}): ${decodeStateValue(storageKey, rawValue)}`)
      } else {
        // For uint64 values, the state stores value directly as bigint
        const value = (stateEntry as { value: bigint }).value
        printInfo(`    Value (uint64): ${value}`)
      }
    } else {
      printInfo(`  ${name}: (not set)`)
    }
  }

  // Step 8: Set and read box storage map
  printStep(8, 'Set and Read Box Storage Map')

  if (boxMapNames.length > 0) {
    try {
      printInfo('Setting a box map entry...')

      // Fund the app for minimum balance requirement for box storage
      await algorand.send.payment({
        sender: deployer,
        receiver: appClient.appAddress,
        amount: algo(1), // 1 ALGO for box storage minimum balance
      })

      // Set a box using the set_box method
      // Method signature: set_box(byte[4],string)void
      await appClient.send.call({
        method: 'set_box',
        args: [new Uint8Array([0x62, 0x6f, 0x78, 0x31]), 'Box content here!'], // name, value
        boxReferences: [{ appId: 0n, name: new Uint8Array([0x62, 0x6f, 0x78, 0x31]) }],
      })
      printInfo('Box value set successfully.')
      printInfo('')

      // Read the box value
      const boxMap = boxMaps[boxMapNames[0]]
      printInfo(`Reading box map '${boxMapNames[0]}':`)
      printInfo(`  Key type: ${formatKeyOrValueType(boxMap.keyType)}`)
      printInfo(`  Value type: ${formatKeyOrValueType(boxMap.valueType)}`)

      const boxValue = await appClient.getBoxValue(new Uint8Array([0x62, 0x6f, 0x78, 0x31]))
      printInfo(`  Raw box value: ${formatBytes(boxValue)}`)

      // Decode the box value using the valueType from the storage map
      const valueType = boxMap.valueType
      if (typeof valueType !== 'string') {
        const decoded = valueType.decode(boxValue)
        printInfo(`  Decoded value: "${decoded}"`)
      }
    } catch (e) {
      printInfo(`Box storage demo skipped due to error: ${e instanceof Error ? e.message : String(e)}`)
      printInfo('(This can happen if LocalNet state is stale - try running "algokit localnet reset")')
    }
  } else {
    printInfo('No box maps to demonstrate.')
  }

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

  printInfo('ARC-56 Storage Helper Functions:')
  printInfo('')
  printInfo('Storage Key Functions:')
  printInfo('  getGlobalABIStorageKeys(contract) - Get all global state keys')
  printInfo('  getLocalABIStorageKeys(contract)  - Get all local state keys')
  printInfo('  getBoxABIStorageKeys(contract)    - Get all box storage keys')
  printInfo('')
  printInfo('Storage Map Functions:')
  printInfo('  getBoxABIStorageMaps(contract)    - Get all box maps')
  printInfo('')
  printInfo('ABIStorageKey Properties:')
  printInfo('  key       - Base64-encoded key bytes')
  printInfo('  keyType   - Type of the key (ABIType or AVMType)')
  printInfo('  valueType - Type of the value (ABIType or AVMType)')
  printInfo('  desc      - Optional description')
  printInfo('')
  printInfo('ABIStorageMap Properties:')
  printInfo('  keyType   - Type of keys in the map')
  printInfo('  valueType - Type of values in the map')
  printInfo('  desc      - Optional description')
  printInfo('  prefix    - Base64-encoded prefix for map keys')
  printInfo('')
  printInfo('Use Cases:')
  printInfo('  - Inspect contract state schema from ARC-56 spec')
  printInfo('  - Decode raw state bytes using typed definitions')
  printInfo('  - Build generic contract explorers/tools')
  printInfo('  - Validate state key/value types at runtime')

  printSuccess('ARC-56 Storage Helpers example completed successfully!')
}

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

---

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