feat: puya debugging support; improved source map management (#37)

* feat: wip on updating source registry assembly * chore: wip - initial drafts around refined ui * feat: initial draft on puya support changes * feat: draft support for prompting for tmpl vars * chore: adding branch based avm package * refactor: loading from txn group sources * chore: testing ci * chore: testing ci * chore: puya and teal example * chore: passing contents of the sourcemap and its containing folder * chore: removing tmpl var tweaks; importing ProgramSourceEntryFile from avm debugger * chore: refining examples structure * chore: transferring the advanced examples from avm-debug * chore: downgrading types vscode to patch npm package Fixes the error thrown during npm package invocation: ERROR @types/vscode ^1.92.0 greater than engines.vscode ^1.80.0. Either upgrade engines.vscode or use an older @types/vscode version * fix: relative path resolution in monorepos * docs: update docs url in markdown * docs: adding extra docs into readme on debugging puya * chore: update README.md Co-authored-by: Neil Campbell <[email protected]> * docs: addressing pr comments * chore: bump debug extension to 0.3.0 * docs: update guideline to refer to v2 and v6 of utils py|ts until v7 ts is out --------- Co-authored-by: Neil Campbell <[email protected]>
algorandfoundation · Oct 29, 2024 · 4a740db · 4a740db
1 parent 372ee5a
commit 4a740db
Show file tree

Hide file tree

Showing 63 changed files with 185,063 additions and 9,462 deletions.
diff --git a/.gitignore b/.gitignore
@@ -66,3 +66,5 @@ out/
 
 # webdriver.io
 .wdio-vscode-service/
+
+examples/multiRootWorkspace/.algokit/sources/sources.avm.json
diff --git a/.prettierignore b/.prettierignore
@@ -10,3 +10,4 @@ coverage
 **/generated/types.ts
 # don't format ide files
 .idea
+**/*sources.avm.json
diff --git a/README.md b/README.md
@@ -55,27 +55,37 @@ Before you can use the AVM Debugger extension, you need to ensure that you have
 
 ## Usage
 
-In order to use the AVM Debugger extension, you need:
+The AVM Debugger extension automatically detects and operates on the following files:
 
-1. TEAL Source Maps. A `*.trace.avm.json` file that maps the compiled TEAL source maps to the original source code. See an example [here](./examples/multiRootWorkspace/slot-machine/debug_traces/simulate-response.trace.avm.json).
-2. Simulate Traces. A `sources.avm.json` file that contains the traces obtained from algod's [`simulate` endpoint](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/debugging/?from_query=simulate#simulate). This serves as an entry point for the debugger. See an example [here](./examples/multiRootWorkspace/slot-machine/.algokit/sources/sources.avm.json).
+1. Simulate Traces. A `*.trace.avm.json` file that contains the traces obtained from algod's [`simulate` endpoint](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/debugging/?from_query=simulate#simulate). This serves as an entry point for the debugger. See an example [here](./examples/multiRootWorkspace/slot-machine/debug_traces/simulate-response.trace.avm.json).
+2. Source Maps. Source maps for the programs executed within the trace. These can be either a
+   - a TEAL source map, obtained from algod when compiling a TEAL program [example](examples/multiRootWorkspace/slot-machine/.algokit/sources/contract/fake-random.teal.tok.map).
+   - a Puya source map, produced when compiling a Smart Contract with the Puya compiler [example](examples/multiRootWorkspace/puya/ProofOfAttendance.approval.puya.map).
+
+> Additionally, it maintains a file named `sources.avm.json` in the root of your project (defaults to `.algokit/sources/sources.avm.json`), which contains a mapping of the compiled source maps to the original source code.
 
 ### a. AlgoKit based project (recommended)
 
-If you are aiming to debug TEAL code in a project generated via [`algokit init`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/init.md), follow the steps below:
+If you are aiming to debug TEAL code in a project generated via [`algokit init`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/init.md), follow the steps below.
+
+#### Python
 
 ```py
 # 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)
 ```
 
+#### TypeScript
+
 ```ts
 // Place this code in a project entry point (e.g. index.ts)
 import { config } from 'algokit-utils-ts'
 config.configure({ debug: true, traceAll: true })
 ```
 
+> NOTE: Storing debug traces is not possible in browser environments, your contract project needs access to filesystem via `node`. If you wish to extract simulate traces manually from an app running in a browser that uses `algokit-utils-ts`, refer to [algokit-utils-ts docs](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md#debugging-in-browser-environment).
+
 ### 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:
@@ -85,6 +95,10 @@ Alternatively, if you are using `algokit-utils` in a project that is not generat
 
 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`.
 
+### Puya Source Maps
+
+To obtain puya source maps, ensure to set the `--output-source-map` flag to `true` when compiling your smart contract with `puya` and using the latest version of the `puya` compiler.
+
 ### Launch Configurations
 
 The extension supports the following launch configurations:
@@ -153,17 +167,29 @@ The extension also offers an interactive picker for simulation trace files. The
 
 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.                                                                                                                                | ![A transaction group being debugged](images/transaction%20group.png)                    |
-| Step into programs           | LogicSig and application programs associated with transactions can be stepped into. Source maps show the original source code.                                                            | ![A program being debugged](images/app%20call.png)                                       |
-| Step into inner transactions | The debugger can step into inner transactions spawned by an application. The entire call stack can be seen and inspected.                                                                 | ![An inner transaction group being debugged](images/inner%20transaction%20group.png)     |
-| 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.                                                      | ![Breakpoints in program code](images/breakpoints.png)                                   |
-| 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.         | ![An error in the debugger](images/error.png)                                            |
-| 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. | ![Inspecting program state](images/program%20state%20variables.png)                      |
-| 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.                                                        | ![Watched values](images/watch%20values.png)                                             |
-| Inspect application state    | The debugger allows inspection and watching of any available application state from the execution.                                                                                        | ![Inspecting application state variables](images/app%20state%20variables%20expanded.png) |
+| Feature                                         | Description                                                                                                                                                                                                                    | Screenshot                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| View transaction groups                         | Every execution starts with a top-level transaction group.                                                                                                                                                                     | ![A transaction group being debugged](images/transaction%20group.png)                    |
+| Step into programs                              | LogicSig and application programs associated with transactions can be stepped into. Source maps show the original source code.                                                                                                 | ![A program being debugged](images/app%20call.png)                                       |
+| Step into inner transactions                    | The debugger can step into inner transactions spawned by an application. The entire call stack can be seen and inspected.                                                                                                      | ![An inner transaction group being debugged](images/inner%20transaction%20group.png)     |
+| 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.                                                                                           | ![Breakpoints in program code](images/breakpoints.png)                                   |
+| 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.                                              | ![An error in the debugger](images/error.png)                                            |
+| 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.                                      | ![Inspecting program state](images/program%20state%20variables.png)                      |
+| 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.                                                                                             | ![Watched values](images/watch%20values.png)                                             |
+| Inspect application state                       | The debugger allows inspection and watching of any available application state from the execution.                                                                                                                             | ![Inspecting application state variables](images/app%20state%20variables%20expanded.png) |
+| Support for Puya sourcemaps                     | The debugger now supports Puya sourcemaps, allowing debugging of contracts written in Puya.                                                                                                                                    | ![Puya sourcemap](images/puya-sources.png)                                               |
+| Ability to ignore or select external sourcemaps | Users can browse and select external sourcemap files if they're not found in the workspace. Additionaly providing an option to ignore sourcemaps for specific hashes, which can be reset via the 'Clear AVM Registry' command. | ![Picker v2](images/pickerv2.png)                                                        |
+
+### VSCode Commands
+
+The extension provides the following commands:
+
+| Name                     | Command                                     | Description                                                                                                         |
+| ------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Debug AVM Trace File     | extension.avmDebugger.debugOpenTraceFile    | Opens a trace file for debugging. Also accessible via debug icon visible when a trace file is opened in the editor. |
+| Clear AVM Debug Registry | extension.avmDebugger.clearAvmDebugRegistry | Clears the AVM debug registry (contents of sources.avm.json).                                                       |
+| Edit AVM Debug Registry  | extension.avmDebugger.editAvmDebugRegistry  | Edits the AVM debug registry (contents of sources.avm.json).                                                        |
 
 ## How can I contribute?
 

diff --git a/examples/multiRootWorkspace/.gitignore b/examples/multiRootWorkspace/.gitignore
@@ -0,0 +1 @@
+!.algokit/sources/sources.avm.json
diff --git a/examples/multiRootWorkspace/puya/.algokit/sources/opup/approval.teal.map b/examples/multiRootWorkspace/puya/.algokit/sources/opup/approval.teal.map
@@ -0,0 +1,8 @@
+{
+    "version": 3,
+    "sources": [
+      "opup.teal"
+    ],
+    "names": [],
+    "mappings": ";AACA"
+  }
diff --git a/examples/multiRootWorkspace/puya/.algokit/sources/opup/opup.teal b/examples/multiRootWorkspace/puya/.algokit/sources/opup/opup.teal
@@ -0,0 +1,2 @@
+#pragma version 6
+int 1
diff --git a/examples/multiRootWorkspace/puya/.algokit/sources/sources.avm.json b/examples/multiRootWorkspace/puya/.algokit/sources/sources.avm.json
@@ -0,0 +1,12 @@
+{
+  "txn-group-sources": [
+    {
+      "sourcemap-location": "../../ProofOfAttendance.approval.puya.map",
+      "hash": "9OQMiPyi2J20NA7qdxurd6RlJi8dTAlzNxPzdR7pjPc="
+    },
+    {
+      "sourcemap-location": "opup/approval.teal.map",
+      "hash": "p0zHRDBy7V/S2TDcAaXYEd2OF8KSxV/1y0ceYEL6qxU="
+    }
+  ]
+}
diff --git a/examples/multiRootWorkspace/puya/.vscode/launch.json b/examples/multiRootWorkspace/puya/.vscode/launch.json
@@ -0,0 +1,13 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "avm",
+      "request": "launch",
+      "name": "Debug Puya App",
+      "simulateTraceFile": "${workspaceFolder}/debug_traces/simulate-response.trace.avm.json",
+      "programSourcesDescriptionFile": "${workspaceFolder}/.algokit/sources/sources.avm.json",
+      "stopOnEntry": true
+    }
+  ]
+}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -66,3 +66,5 @@ out/

		# webdriver.io
		.wdio-vscode-service/

		examples/multiRootWorkspace/.algokit/sources/sources.avm.json