avm-debug-adapter
v0.3.0
Published
Algorand AVM transaction and smart contract debugger using the Debugger Adapter Protocol
Downloads
5
Readme
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
- Clone the repo.
npm i
to install dependencies.- Open the project folder in VS Code.
- From the Run and Debug menu, run the
Extension
configuration to open the AVM Debug extension in another VS Code window. - In the new window, go to its Run and Debug menu to select and launch one of the existing configurations.
- 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.