Common Utilities

← Back to Examples Overview

Utility functions and helpers.

Examples (12)

Example	Description
Address Basics	This example demonstrates basic address operations using the algokit_common module: Parsing addresses from base32 strings with public_key_from_address() Creating addresses from public keys with address_from_public_key() Using the zero address constant ZERO_ADDRESS Computing the 4-byte checksum via SHA-512/256 Validating addresses by attempting to parse them Accessing the 32-byte public key from an address Using address constants: ADDRESS_LENGTH, ZERO_ADDRESS
Address Encoding	This example demonstrates how to encode and decode addresses between different formats and compute application addresses: address_from_public_key() to convert 32-byte public key to base32 string public_key_from_address() to convert base32 string to public key bytes get_application_address() to compute an app’s escrow address from app ID Round-trip verification: encode(decode(address)) equals original Understanding the relationship between public key bytes and checksum
Array Utilities	This example demonstrates array utility operations for comparing and concatenating byte arrays in Python: Comparing arrays with == operator for element-by-element comparison Concatenating arrays using + operator or bytes concatenation Using list comprehensions for array manipulation Note: Python’s bytes type provides native support for these operations, unlike JavaScript’s Uint8Array which needs utility functions.
Constants Reference	This example displays all the protocol constants available in the algokit_common package. These constants define limits, sizes, and separators used throughout Algorand.
Crypto Hash (SHA-512/256)	This example demonstrates the sha512_256() function for computing Algorand-compatible SHA-512/256 hashes. This hash algorithm is used throughout Algorand for: Transaction IDs Address checksums Application escrow addresses State proof verification
Example	Logger Type Example This example demonstrates the Logger protocol/interface for consistent logging across the AlgoKit Utils SDK. Topics covered: Logger protocol definition with all log levels Console-based Logger implementation No-op (silent) logger for production Custom formatting logger Compatibility with common logging patterns
JSON BigInt Support	This example demonstrates how Python handles large integers in JSON, which is simpler than JavaScript due to Python’s native arbitrary-precision integers. Topics covered: Python’s int type has unlimited precision (no MAX_SAFE_INTEGER limit) json.dumps() and json.loads() work with large integers natively Round-trip preservation of large numbers Comparison with JavaScript’s precision issues Algorand-relevant examples with microAlgo amounts Custom JSON encoders for specific serialization needs
MessagePack Encoding	This example demonstrates encoding and decoding MessagePack data, which is used for Algorand transaction encoding. Topics covered: encode_msgpack() to serialize data to MessagePack format decode_msgpack() to deserialize MessagePack bytes Encoding simple objects with various types (strings, numbers, bytes) Key handling in MessagePack Uint8Array (bytes) encoding Size comparison: MessagePack vs JSON
Primitive Serde (Serialization/Deserialization)	This example demonstrates how to use primitive serialization patterns in Python for encoding/decoding basic values in wire format. Note: Unlike the TypeScript SDK which uses explicit codec classes (numberCodec, bigIntCodec, etc.), the Python SDK uses a dataclass-based approach with field metadata helpers. This example shows both native Python serialization and the serde utilities available in algokit_common. Topics covered: Python’s native type handling for serialization Using wire() metadata for dataclass fields Address encoding/decoding with addr() helper Bytes encoding (base64 for JSON, raw for msgpack) Round-trip verification for various types The serde module’s to_wire() and from_wire() functions
Composite Serde (Serialization/Deserialization)	This example demonstrates how to serialize/deserialize composite data structures like arrays, maps, and records in Python using the serde utilities. Note: Unlike the TypeScript SDK which uses explicit ArrayCodec, MapCodec, and RecordCodec classes, the Python SDK handles these natively through: Native Python lists for arrays Native Python dicts for records/maps Dataclass fields with serde helpers for structured data Topics covered: Encoding/decoding typed arrays (lists) Encoding/decoding maps (dictionaries) Using bytes_seq(), int_seq(), addr_seq() helpers Nested structures (list of lists, dict of lists) Round-trip verification for composite types
Model Serde (Object Model Serialization)	This example demonstrates how to use dataclass-based serialization for complex object structures with field metadata in Python. Note: Unlike the TypeScript SDK which uses ObjectModelCodec, PrimitiveModelCodec, and ArrayModelCodec classes, the Python SDK uses dataclasses with field metadata helpers. This is a more Pythonic approach that achieves the same goals. Topics covered: Defining dataclasses with field metadata using wire() Encoding format options: to_wire() produces dict for JSON or msgpack Handling optional fields with omit_if_none Field renaming with wire key aliases Nested dataclasses Round-trip encoding with to_wire() and from_wire() Default values and omission rules
Sourcemap for TEAL Debugging	This example demonstrates how to use ProgramSourceMap for mapping TEAL program counters (PC) to source locations for debugging purposes. Topics covered: ProgramSourceMap class construction from sourcemap data Sourcemap format: version, sources, mappings get_line_for_pc() to get source line for a specific PC get_pcs_for_line() to find PCs for a source line pc_to_line and line_to_pc dictionaries How sourcemaps enable TEAL debugging by mapping PC to source

Quick Start

Run any example from the repository’s examples directory:

cd examples
uv run python common/01_address_basics.py