|
| 1 | +**@algorandfoundation/algokit-utils** |
| 2 | + |
| 3 | +*** |
| 4 | + |
| 5 | +# AlgoKit TypeScript Utilities |
| 6 | + |
| 7 | +A set of core Algorand utilities written in TypeScript and released via npm that make it easier to build, test and deploy solutions on the Algorand Blockchain, including APIs, console apps and dApps. This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit). |
| 8 | + |
| 9 | +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 provide a higher level interface with sensible defaults and capabilities for common tasks that make development faster and easier. |
| 10 | + |
| 11 | +Note: If you prefer Python there's an equivalent [Python utility library](https://github.com/algorandfoundation/algokit-utils-py). |
| 12 | + |
| 13 | +## Quick Links |
| 14 | + |
| 15 | +- **New to AlgoKit?** Start with the [Quick Start Tutorial](_media/quick-start.md) |
| 16 | +- **Building an app?** See [Concepts](_media/algorand-client.md) and [Examples](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples) |
| 17 | +- **API Reference** - [Auto-generated docs](_media/README.md) |
| 18 | +- **Upgrading?** See [Migration Guides](_media/v7-migration.md) |
| 19 | + |
| 20 | +[Core principles](#core-principles) | [Installation](#installation) | [Usage](#usage) | [Config and logging](#config-and-logging) | [Concepts](#concepts) | [Reference docs](#reference-documentation) |
| 21 | + |
| 22 | +# Core principles |
| 23 | + |
| 24 | +This library is designed with the following principles: |
| 25 | + |
| 26 | +- **Modularity** - This library is built with modular building blocks; you can opt-in to which parts of this library you want to use without having to use an all or nothing approach. Subpath imports enable tree-shaking for optimal bundle sizes. |
| 27 | +- **Type-safety** - This library provides strong TypeScript support with effort put into creating types that provide good type safety and intellisense. |
| 28 | +- **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 |
| 29 | + |
| 30 | +# Installation |
| 31 | + |
| 32 | +This library can be installed from NPM using your preferred npm client, e.g.: |
| 33 | + |
| 34 | +``` |
| 35 | +npm install @algorandfoundation/algokit-utils |
| 36 | +``` |
| 37 | + |
| 38 | +# Usage |
| 39 | + |
| 40 | +To use this library simply include the following at the top of your file: |
| 41 | + |
| 42 | +```typescript |
| 43 | +import { AlgorandClient, Config } from '@algorandfoundation/algokit-utils' |
| 44 | +``` |
| 45 | + |
| 46 | +As well as `AlgorandClient` and `Config`, you can use intellisense to auto-complete the various types that you can import within the `{}` in your favourite Integrated Development Environment (IDE), or you can refer to the [reference documentation](_media/README.md). |
| 47 | + |
| 48 | +> [!WARNING] |
| 49 | +> Previous versions of AlgoKit Utils encouraged you to include an import that looks like this (note the subtle difference of the extra `* as algokit`): |
| 50 | +> |
| 51 | +> ```typescript |
| 52 | +> import * as algokit from '@algorandfoundation/algokit-utils' |
| 53 | +> ``` |
| 54 | +> |
| 55 | +> This version will still work until at least v9, but it exposes an older, function-based interface to the functionality that is deprecated. The new way to use AlgoKit Utils is via the `AlgorandClient` class, which is easier, simpler and more convenient to use and has powerful new features. |
| 56 | +> |
| 57 | +> If you are migrating from the old functions to the new ones then you can follow the [migration guide](_media/v7-migration.md). |
| 58 | +
|
| 59 | +The main entrypoint to the bulk of the functionality is the `AlgorandClient` class, most of the time you can get started by typing `AlgorandClient.` and choosing one of the static initialisation methods to create an [Algorand client](_media/algorand-client.md), e.g.: |
| 60 | +
|
| 61 | +```typescript |
| 62 | +// Point to the network configured through environment variables or |
| 63 | +// if no environment variables it will point to the default LocalNet |
| 64 | +// configuration |
| 65 | +const algorand = AlgorandClient.fromEnvironment() |
| 66 | +// Point to default LocalNet configuration |
| 67 | +const algorand = AlgorandClient.defaultLocalNet() |
| 68 | +// Point to TestNet using AlgoNode free tier |
| 69 | +const algorand = AlgorandClient.testNet() |
| 70 | +// Point to MainNet using AlgoNode free tier |
| 71 | +const algorand = AlgorandClient.mainNet() |
| 72 | +// Point to a pre-created algod client |
| 73 | +const algorand = AlgorandClient.fromClients({ algod }) |
| 74 | +// Point to pre-created algod, indexer and kmd clients |
| 75 | +const algorand = AlgorandClient.fromClients({ algod, indexer, kmd }) |
| 76 | +// Point to custom configuration for algod |
| 77 | +const algorand = AlgorandClient.fromConfig({ algodConfig }) |
| 78 | +// Point to custom configuration for algod, indexer and kmd |
| 79 | +const algorand = AlgorandClient.fromConfig({ algodConfig, indexerConfig, kmdConfig }) |
| 80 | +``` |
| 81 | +
|
| 82 | +## Testing |
| 83 | + |
| 84 | +AlgoKit Utils contains a module that helps you write automated tests against an Algorand network (usually LocalNet). These tests can run locally on a developer's machine, or on a Continuous Integration server. |
| 85 | + |
| 86 | +To use the automated testing functionality, you can import the testing module: |
| 87 | + |
| 88 | +```typescript |
| 89 | +import * as algotesting from '@algorandfoundation/algokit-utils/testing' |
| 90 | +``` |
| 91 | + |
| 92 | +Or, you can generally get away with just importing the `algorandFixture` since it exposes the rest of the functionality in a manner that is easy to integrate with an underlying test framework like Jest or vitest: |
| 93 | + |
| 94 | +```typescript |
| 95 | +import { algorandFixture } from '@algorandfoundation/algokit-utils/testing' |
| 96 | +``` |
| 97 | + |
| 98 | +To see how to use it consult the [testing capability page](_media/testing.md) or to see what's available look at the [reference documentation](_media/README.md). |
| 99 | + |
| 100 | +## Types |
| 101 | + |
| 102 | +All types are exported directly from the main package or from specific subpaths: |
| 103 | + |
| 104 | +```typescript |
| 105 | +import { AlgorandClient, type AccountInformation, type AppDeployParams } from '@algorandfoundation/algokit-utils' |
| 106 | +``` |
| 107 | + |
| 108 | +Or from specific subpaths: |
| 109 | + |
| 110 | +```typescript |
| 111 | +import { type SendParams } from '@algorandfoundation/algokit-utils/transaction' |
| 112 | +import { type ABIType } from '@algorandfoundation/algokit-utils/abi' |
| 113 | +``` |
| 114 | + |
| 115 | +Use intellisense in your IDE to discover available types, or refer to the [reference documentation](_media/README.md). |
| 116 | + |
| 117 | +> [!NOTE] |
| 118 | +> The `/types/*` subpath imports are deprecated. Import types directly from the main package or relevant subpaths instead. |
| 119 | +
|
| 120 | +## Modular Imports |
| 121 | + |
| 122 | +AlgoKit Utils provides modular subpath imports for tree-shaking and focused functionality: |
| 123 | + |
| 124 | +| Subpath | Description | |
| 125 | +| ----------------- | --------------------------------------------- | |
| 126 | +| Main | Core functionality including `AlgorandClient` | |
| 127 | +| `/testing` | Testing utilities and fixtures | |
| 128 | +| `/abi` | ABI encoding/decoding utilities | |
| 129 | +| `/transact` | Low-level transaction construction | |
| 130 | +| `/transaction` | Transaction types and utilities | |
| 131 | +| `/algo25` | Algorand 25-word mnemonic utilities | |
| 132 | +| `/algod-client` | Typed Algod client | |
| 133 | +| `/indexer-client` | Typed Indexer client | |
| 134 | +| `/kmd-client` | Typed KMD client | |
| 135 | + |
| 136 | +> [!TIP] |
| 137 | +> Using specific subpath imports can help reduce bundle size through tree-shaking. |
| 138 | +
|
| 139 | +# Config and logging |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +## Logging |
| 144 | + |
| 145 | +AlgoKit has an in-built logging abstraction that allows the library to issue log messages without coupling the library to a particular logging library. This means you can access the AlgoKit Utils logs within your existing logging library if you have one. |
| 146 | + |
| 147 | +To do this you need to create a logging translator that exposes the following interface (`Logger`): |
| 148 | + |
| 149 | +```typescript |
| 150 | +export type Logger = { |
| 151 | + error(message: string, ...optionalParams: unknown[]): void |
| 152 | + warn(message: string, ...optionalParams: unknown[]): void |
| 153 | + info(message: string, ...optionalParams: unknown[]): void |
| 154 | + verbose(message: string, ...optionalParams: unknown[]): void |
| 155 | + debug(message: string, ...optionalParams: unknown[]): void |
| 156 | +} |
| 157 | +``` |
| 158 | +
|
| 159 | +Note: this interface type is directly compatible with [Winston](https://github.com/winstonjs/winston) so you should be able to pass AlgoKit a Winston logger. |
| 160 | +
|
| 161 | +By default, the `consoleLogger` is set as the logger, which will send log messages to the various `console.*` methods for all logs apart from verbose logs. There is also a `nullLogger` if you want to disable logging, or various leveled console loggers: `verboseConsoleLogger` (also outputs verbose logs), `infoConsoleLogger` (only outputs info, warning and error logs), `warningConsoleLogger` (only outputs warning and error logs). |
| 162 | +
|
| 163 | +If you want to override the logger you can use the following: |
| 164 | +
|
| 165 | +```typescript |
| 166 | +Config.configure({ logger: myLogger }) |
| 167 | +``` |
| 168 | +
|
| 169 | +To retrieve the current debug state you can use `Config.logger`. To get a logger that is optionally set to the null logger based on a boolean flag you can use the `Config.getLogger(useNullLogger)` function. |
| 170 | +
|
| 171 | +## Debug mode |
| 172 | +
|
| 173 | +To turn on debug mode you can use the following: |
| 174 | +
|
| 175 | +```typescript |
| 176 | +Config.configure({ debug: true }) |
| 177 | +``` |
| 178 | +
|
| 179 | +To retrieve the current debug state you can use `Config.debug`. |
| 180 | +
|
| 181 | +This will turn on things like automatic tracing, more verbose logging and [advanced debugging](_media/debugging.md). It's likely this option will result in extra HTTP calls to algod so worth being careful when it's turned on. |
| 182 | +
|
| 183 | +If you want to temporarily turn it on you can use the `withDebug` function: |
| 184 | +
|
| 185 | +```typescript |
| 186 | +Config.withDebug(() => { |
| 187 | + // Do stuff with Config.debug set to true |
| 188 | +}) |
| 189 | +``` |
| 190 | +
|
| 191 | +# Concepts |
| 192 | +
|
| 193 | +The library helps you interact with and develop against the Algorand blockchain with a series of end-to-end concepts as described below: |
| 194 | +
|
| 195 | +- [**AlgorandClient**](_media/algorand-client.md) - The key entrypoint to the AlgoKit Utils functionality |
| 196 | +- **Core capabilities** |
| 197 | + - [**Client management**](_media/client.md) - 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) |
| 198 | + - [**Account management**](_media/account.md) - Creation, use, and management of accounts including mnemonic, rekeyed, multisig, transaction signer ([useWallet](https://github.com/TxnLab/use-wallet) for dApps and Atomic Transaction Composer compatible signers), idempotent KMD accounts and environment variable injected |
| 199 | + - [**Algo amount handling**](_media/amount.md) - Reliable, explicit, and terse specification of microAlgo and Algo amounts and safe conversion between them |
| 200 | + - [**Transaction management**](_media/transaction.md) - 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 |
| 201 | +- **Higher-order use cases** |
| 202 | + - [**Asset management**](_media/asset.md) - Creation, transfer, destroying, opting in and out and managing Algorand Standard Assets |
| 203 | + - [**Typed application clients**](_media/typed-app-clients.md) - Type-safe application clients that are [generated](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) 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: |
| 204 | + - [**ARC-56 / ARC-32 App client and App factory**](_media/app-client.md) - 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 |
| 205 | + - [**App management**](_media/app.md) - Creation, updating, deleting, calling (ABI and otherwise) smart contract apps and the metadata associated with them (including state and boxes) |
| 206 | + - [**App deployment**](_media/app-deploy.md) - Idempotent (safely retryable) deployment of an app, including deploy-time immutability and permanence control and TEAL template substitution |
| 207 | + - [**Algo transfers (payments)**](_media/transfer.md) - Ability to easily initiate Algo transfers between accounts, including dispenser management and idempotent account funding |
| 208 | + - [**Automated testing**](_media/testing.md) - Terse, robust automated testing primitives that work across any testing framework (including jest and vitest) to facilitate fixture management, quickly generating isolated and funded test accounts, transaction logging, indexer wait management and log capture |
| 209 | + - [**Indexer lookups / searching**](_media/indexer.md) - Type-safe indexer API wrappers (no `Record<string, any>` pain from the SDK client), including automatic pagination control |
| 210 | +
|
| 211 | +# Examples |
| 212 | +
|
| 213 | +We maintain [runnable examples](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples) organized by feature: |
| 214 | +
|
| 215 | +- **[AlgorandClient](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/algorand_client)** - High-level API usage |
| 216 | +- **[Transact](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/transact)** - Transaction construction |
| 217 | +- **[ABI](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/abi)** - ABI encoding/decoding |
| 218 | +- **[Testing](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/testing)** - Testing utilities |
| 219 | +- **[Algod Client](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/algod_client)** - Node operations |
| 220 | +- **[Indexer Client](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/indexer_client)** - Blockchain queries |
| 221 | +- **[KMD Client](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/kmd_client)** - Key management |
| 222 | +- **[Algo25](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/algo25)** - Mnemonic utilities |
| 223 | +- **[Common](https://github.com/algorandfoundation/algokit-utils-ts/tree/decoupling/examples/common)** - Utility functions |
| 224 | +
|
| 225 | +# Reference documentation |
| 226 | +
|
| 227 | +We have [auto-generated reference documentation](_media/README.md) including: |
| 228 | +
|
| 229 | +**Key Classes:** |
| 230 | +
|
| 231 | +- [`AlgorandClient`](_media/AlgorandClient.md) - Main entry point |
| 232 | +- [`TransactionComposer`](_media/TransactionComposer.md) - Transaction composition |
| 233 | +- [`AppClient`](_media/AppClient.md) - Smart contract interaction |
| 234 | +- [`AppFactory`](_media/AppFactory.md) - Contract deployment |
| 235 | +- [`AccountManager`](_media/AccountManager.md) - Account management |
| 236 | +- [`AssetManager`](_media/AssetManager.md) - Asset operations |
| 237 | +
|
| 238 | +**Migration Guides:** |
| 239 | +
|
| 240 | +- [v7 Migration](_media/v7-migration.md) - Function-based to class-based API |
| 241 | +- [v8 Migration](_media/v8-migration.md) - Previous algosdk v3 upgrade |
0 commit comments