algorand / avm-debugger

Debug Adapter Protocol Debugger for the Algorand Virtual Machine

AVM Debugger

Summary

This repo contains an AVM debugger which adheres to the Debug Adapter Protocol. This protocol is used by a variety of clients, and this repo additionally implements a basic client for VS Code.

Unlike traditional debuggers, which typically execute code as it is being debugged, this debugger operates on an execution trace. The trace is created by the algod simulate API. This debugger is not responsible for compiling programs, assembling transaction groups, or executing transactions/programs. It is only responsible for replaying the execution trace, which must already exist.

This code is based on the vscode-mock-debug repo.

Usage

There are multiple ways to invoke the debug adapter exported by this package.

CLI

The debug adapter can be invoked from the command line using the avm-debug-adapter command.

If given no arguments, the debug adapter will use stdin and stdout to process messages.

To run as a server, use the --port option, shown below:

$ npm exec avm-debug-adapter -- --port=8080
>> running as a server, listening on 8080

Programmatically

// AvmDebugSession is a vscode.DebugAdapter implementation and can be imported
// directly if you don't want to run it as a server.
import { AvmDebugSession } from 'avm-debug-adapter';

// From node, you can create a debug adapter server like so
import { Server, nodeFileAccessor } from 'avm-debug-adapter/node';

const server = new Server({
  fileAccessor: nodeFileAccessor,
  port: 8080,
  onSocketError: (err) => {
    console.error(err);
  },
  onServerError: (err) => {
    console.error(err);
  },
});

console.log('Server listening on port ' + server.port());

process.on('SIGTERM', () => {
  server.close();
});

Features

See FEATURES.md for a list of features this debugger supports.

Build and Run

1. Clone the repo.
2. npm i to install dependencies.
3. Open the project folder in VS Code.
4. From the Run and Debug menu, run the Extension configuration to open the AVM Debug extension in another VS Code window.
5. In the new window, go to its Run and Debug menu to select and launch one of the existing configurations.
6. You are now in a debugging session of a transaction group. You can step through the transaction group, inspect variables, set breakpoints and more. See FEATURES.md for more details.

avm-debugger's Issues

Add test coverage for step in/over/out/back

Handle app and LogicSig failures properly

Right now program failures are not properly handled. This issue is to make sure these cases are handled properly and result in the error being displayed by the debugger at the appropriate time. Needs test coverage as well.

Add test coverage for inner transaction call frames

Improve source map support

Add support for source map columns, and other improvements made available by algorand/js-algorand-sdk#834

Also, use the sourcemap "sources" key to find source files, instead of the "file-location" key from the program source description file.

Add test coverage for LogicSig evaluation

General behavior cleanup

This catch-all issue should fix the following:

• Remove exception breakpoint filters (or only have one for inner txns)
• Remove evaluate on hover support
• Fix TEAL syntax highlighting
• If available, show UTF-8 values for byte strings instead of ASCII
• Enable/be compatible with web builds
• Rename from TEAL Debugger to AVM Debugger
• Have a separate package.json for debug adaptor code so that it can be packed and released separately

Teal Debugger Near Term Priorities

Improve how the debugger gets invoked

Specifically,

• Stop loading launch.json at initialization -- instead consume it the standard way, once debugging starts
• launch.json should contain only two items: programSourceDescriptionFile and program simulateTraceFile (which will be the simulation trace file)
• Remove debug icon from .teal files (this is misleading, since traces the main "program" that gets debugged)