The AlgoKit AVM VS Code Debugger extension provides a convenient way to debug any Algorand Smart Contracts written in TEAL.
It is built on top of the official AVM Debug Adapter provided by Algorand Technologies. Additionally, a set of companion utilities are provided in the TypeScript and Python versions of algokit-utils, making it easier for developers to set up the required prerequisites and run the debugger.
To skip straight to the list of features, go to Features.
Contents
Prerequisites
Before you can use the AVM Debugger extension, you need to ensure that you have the following installed:
- Visual Studio Code: Version 1.80.0 or higher. You can check your version by going to
Help > About in VS Code.
- Node.js: Version 18.x or higher. The extension is built with Node.js. Check your Node.js version by running
node -v in your terminal/command prompt.
The extension is designed to debug TEAL programs running on the Algorand Virtual Machine. It provides a step-by-step debugging experience by utilizing transaction execution traces and compiled source maps of your smart contract. However, it's crucial to understand that debugging a smart contract language like TEAL has its unique aspects compared to general-purpose languages. For a comprehensive guide on how to initiate a debugging session, please refer to the Usage section.
Installation
- Install the extension from the VS Code Marketplace.
- Follow the next steps in the Usage section.
Usage
In order to use the AVM Debugger extension, you need:
- TEAL Source Maps. A
*.trace.avm.json file that maps the compiled TEAL source maps to the original source code. See an example here.
- Simulate Traces. A
sources.avm.json file that contains the traces obtained from algod's simulate endpoint. This serves as an entry point for the debugger. See an example here.
a. AlgoKit based project (recommended)
If you are aiming to debug TEAL code in a project generated via algokit init, follow the steps below:
# Place this code in a project entry point (e.g. main.py)
from algokit_utils.config import config
config.configure(debug=True, trace_all=True)
// Place this code in a project entry point (e.g. index.ts)
import { config } from 'algokit-utils-ts'
config.configure({ debug: true, traceAll: true })
b. Custom Project
Alternatively, if you are using algokit-utils in a project that is not generated via algokit init, refer to the following utilities:
Depending on the language you are using, you can use the above utilities to generate source maps for your TEAL as well as debug traces obtained from algod's simulate endpoint (which is also an entry point for this debugger extension). Alternatively, you can use the utilities as a reference for obtaining source maps and traces without algokit-utils.
Launch Configurations
The extension supports the following launch configurations:
- Debug Session from a Simulate Trace File
This is the simplest way to launch a debug session. The simulateTraceFile property in the launch configuration specifies the path to the simulate trace file *.trace.avm.json. The sources.avm.json file is automatically selected from the working directory. If there is more than one sources.avm.json file in the working directory, you will be prompted to choose one. The debugger expects the launch configuration to be of type avm (Algorand Virtual Machine).
{
"version": "0.2.0",
"configurations": [
{
"type": "avm",
"request": "launch",
"name": "Debug TEAL Program with auto-picked sources",
"simulateTraceFile": "${workspaceFolder}/debug_traces/simulate-response.trace.avm.json",
"stopOnEntry": true // optional
}
]
}
- Debug Session Using Specific Debug Config Paths
If you want to target a specific sources.avm.json file, you can specify the path to the file using the programSourcesDescriptionFile property in the launch configuration.
{
"version": "0.2.0",
"configurations": [
{
"type": "avm",
"request": "launch",
"name": "Debug TEAL Program from hardcoded sources and traces",
"simulateTraceFile": "${workspaceFolder}/debug_traces/simulate-response.trace.avm.json",
"programSourcesDescriptionFile": "${workspaceFolder}/.algokit/sources/sources.avm.json",
"stopOnEntry": true // optional
}
]
}
- Debug Session with Interactive File Picker
The extension also offers an interactive picker for simulation trace files. The PickSimulateTraceFile command can be used to interactively select a simulation trace file from the working directory. The following launch configuration will also prompt a second picker for the sources.avm.json file if it detects more than one sources.avm.json file in the working directory.
{
"version": "0.2.0",
"configurations": [
{
"type": "avm",
"request": "launch",
"name": "Debug TEAL Program with interactive trace and source picker",
"simulateTraceFile": "${workspaceFolder}/${command:PickSimulateTraceFile}",
"stopOnEntry": true // optional
}
]
}
Please note the limit for max visible items in the extension picker is 100. If you have more than 100 sources.avm.json files in the working directory, consider using the programSourcesDescriptionFile property to specify the path to a specific file.
Features
This document outlines the features supported by the AVM debugger. Screenshots and features are based on the VS Code client.
| Feature |
Description |
Screenshot |
| View transaction groups |
Every execution starts with a top-level transaction group. |
 |
| Step into programs |
LogicSig and application programs associated with transactions can be stepped into. Source maps show the original source code. |
 |
| Step into inner transactions |
The debugger can step into inner transactions spawned by an application. The entire call stack can be seen and inspected. |
 |
| Step-by-step debugging |
Supports step into, over, out, and back. |
|
| Breakpoint support |
Breakpoints can be set in program source files. The debugger pauses when code corresponding to a breakpoint is about to be executed. |
 |
| Error reporting |
Execution errors are reported by the debugger. The debugger will not allow you to advance after an error, but you can step backwards to inspect what happened prior to the error. |
 |
| Inspect program state |
The debugger allows inspection of the state of the program being debugged, including the PC (program counter), stack, and scratch space. Byte arrays can be displayed in various formats. |
 |
| Watch values |
Specific values can be added to the watch list. Negative indexing is supported to look up values relative to the top of the stack. |
 |
| Inspect application state |
The debugger allows inspection and watching of any available application state from the execution. |
 |
How can I contribute?
This is an open source project managed by the Algorand Foundation. See the contributing page to learn about making improvements, including developer setup instructions.
If you have any issues or feature requests, please open an issue.
