AlgoKit Python Utilities

A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand. This project is part of AlgoKit.

The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand. Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.

Note

If you prefer TypeScript there’s an equivalent TypeScript utility library.

Core principles | Installation | Usage | Config and logging | Capabilities | Reference docs

Contents

• Account management
  • AccountManager
  • TransactionSignerAccountProtocol
  • Registering a signer
  • Default signer
  • Get a signer
  • Accounts
  • Rekey account
  • KMD account management
• Algorand client
  • Accessing SDK clients
  • Accessing manager class instances
  • Creating and issuing transactions
• Algo amount handling
  • AlgoAmount
• App client and App factory
  • AppFactory
  • AppClient
  • Dynamically creating clients for a given app spec
  • Creating and deploying an app
  • Updating and deleting an app
  • Calling the app
  • Funding the app account
  • Reading state
  • Handling logic errors and diagnosing errors
  • Default arguments
• App deployment
  • Smart contract development lifecycle
  • AppDeployer
  • Deployment metadata
  • Lookup deployed apps by name
  • Performing a deployment
• App management
  • AppManager
  • Calling apps
  • Accessing state
  • Getting app information
  • Box references
  • Common app parameters
• Assets
  • AssetManager
  • Asset Information
  • Bulk Operations
  • Get Asset Information
• Client management
  • ClientManager
  • Network configuration
  • Clients
  • Automatic retry
  • Network information
• Debugger
  • Configuration
  • AlgoKitLogger
  • Debugging Utilities
• TestNet Dispenser Client
  • Creating a Dispenser Client
  • Funding an Account
  • Registering a Refund
  • Getting Current Limit
  • Error Handling
• Testing
  • Basic Test Setup
  • Creating Test Assets
  • Testing Application Deployments
  • Testing Asset Transfers
  • Testing Application Calls
  • Testing Box Storage
• Transaction composer
  • Constructing a transaction
  • Simulating a transaction
• Transaction management
  • Transaction Results
  • Further reading
• Algo transfers (payments)
  • payment
  • ensure_funded
  • Dispenser
• Typed application clients
  • Generating an app spec
  • Generating a typed client
  • Getting a typed client instance
  • Client usage
• Migration Guide - v3
  • Migration Steps
  • Breaking Changes
  • Best Practices
  • Troubleshooting
• API Reference
  • algokit_utils

Core principles

This library follows the Guiding Principles of AlgoKit and is designed with the following principles:

• Modularity - This library is a thin wrapper of modular building blocks over the Algorand SDK; the primitives from the underlying Algorand SDK are exposed and used wherever possible so you can opt-in to which parts of this library you want to use without having to use an all or nothing approach.

• Type-safety - This library provides strong type hints with effort put into creating types that provide good type safety and intellisense when used with tools like MyPy.

• Productivity - This library is built to make solution developers highly productive; it has a number of mechanisms to make common code easier and terser to write.

Installation

This library can be installed from PyPi using pip or poetry:

pip install algokit-utils
# or
poetry add algokit-utils

Usage

The main entrypoint to the bulk of the functionality in AlgoKit Utils is the AlgorandClient class. You can get started by using one of the static initialization methods to create an Algorand client:

# Point to the network configured through environment variables or
# if no environment variables it will point to the default LocalNet configuration
algorand = AlgorandClient.from_environment()
# Point to default LocalNet configuration
algorand = AlgorandClient.default_localnet()
# Point to TestNet using AlgoNode free tier
algorand = AlgorandClient.testnet()
# Point to MainNet using AlgoNode free tier
algorand = AlgorandClient.mainnet()
# Point to a pre-created algod client
algorand = AlgorandClient.from_clients(algod=...)
# Point to a pre-created algod and indexer client
algorand = AlgorandClient.from_clients(algod=..., indexer=..., kmd=...)
# Point to custom configuration for algod
algod_config = AlgoClientNetworkConfig(server=..., token=..., port=...)
algorand = AlgorandClient.from_config(algod_config=algod_config)
# Point to custom configuration for algod and indexer and kmd
algod_config = AlgoClientNetworkConfig(server=..., token=..., port=...)
indexer_config = AlgoClientNetworkConfig(server=..., token=..., port=...)
kmd_config = AlgoClientNetworkConfig(server=..., token=..., port=...)
algorand = AlgorandClient.from_config(algod_config=algod_config, indexer_config=indexer_config, kmd_config=kmd_config)

Testing

AlgoKit Utils provides a dedicated documentation page on various useful snippets that can be reused for testing with tools like Pytest:

• Testing

Types

The library leverages Python’s native type hints and is fully compatible with MyPy for static type checking.

All public abstractions and methods are organized in logical modules matching their domain functionality. You can import types either directly from the root module or from their source submodules. Refer to API documentation for more details.

Config and logging

To configure the AlgoKit Utils library you can make use of the Config object, which has a configure method that lets you configure some or all of the configuration options.

Config singleton

The AlgoKit Utils configuration singleton can be updated using config.configure(). Refer to the Config API documentation for more details.

Logging

AlgoKit has an in-built logging abstraction through the algokit_utils.config.AlgoKitLogger class that provides standardized logging capabilities. The logger is accessible through the config.logger property and provides various logging levels.

Each method supports optional suppression of output using the suppress_log parameter.

Debug mode

To turn on debug mode you can use the following:

from algokit_utils.config import config
config.configure(debug=True)

To retrieve the current debug state you can use debug property.

This will turn on things like automatic tracing, more verbose logging and advanced debugging. It’s likely this option will result in extra HTTP calls to algod and it’s worth being careful when it’s turned on.

Capabilities

The library helps you interact with and develop against the Algorand blockchain with a series of end-to-end capabilities as described below:

• AlgorandClient - The key entrypoint to the AlgoKit Utils functionality

• Core capabilities

  • Client management - Creation of (auto-retry) algod, indexer and kmd clients against various networks resolved from environment or specified configuration, and creation of other API clients (e.g. TestNet Dispenser API and app clients)

  • Account management - Creation, use, and management of accounts including mnemonic, rekeyed, multisig, transaction signer, idempotent KMD accounts and environment variable injected

  • Algo amount handling - Reliable, explicit, and terse specification of microAlgo and Algo amounts and safe conversion between them

  • Transaction management - Ability to construct, simulate and send transactions with consistent and highly configurable semantics, including configurable control of transaction notes, logging, fees, validity, signing, and sending behaviour

• Higher-order use cases

  • Asset management - Creation, transfer, destroying, opting in and out and managing Algorand Standard Assets

  • Typed application clients - Type-safe application clients that are generated from ARC-56 or ARC-32 application spec files and allow you to intuitively and productively interact with a deployed app, which is the recommended way of interacting with apps and builds on top of the following capabilities:

    • ARC-56 / ARC-32 App client and App factory - Builds on top of the App management and App deployment capabilities (below) to provide a high productivity application client that works with ARC-56 and ARC-32 application spec defined smart contracts

    • App management - Creation, updating, deleting, calling (ABI and otherwise) smart contract apps and the metadata associated with them (including state and boxes)

    • App deployment - Idempotent (safely retryable) deployment of an app, including deploy-time immutability and permanence control and TEAL template substitution

  • Algo transfers (payments) - Ability to easily initiate Algo transfers between accounts, including dispenser management and idempotent account funding

  • Automated testing - Reusable snippets to leverage AlgoKit Utils abstractions in a manner that are useful for when writing tests in tools like Pytest.

Reference documentation

For detailed API documentation, see the algokit_utils