You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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 <neil.campbell@makerx.com.au>
* 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 <neil.campbell@makerx.com.au>
Copy file name to clipboardExpand all lines: README.md
+41-15
Original file line number
Diff line number
Diff line change
@@ -55,27 +55,37 @@ Before you can use the AVM Debugger extension, you need to ensure that you have
55
55
56
56
## Usage
57
57
58
-
In order to use the AVM Debugger extension, you need:
58
+
The AVM Debugger extension automatically detects and operates on the following files:
59
59
60
-
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).
61
-
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).
60
+
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).
61
+
2. Source Maps. Source maps for the programs executed within the trace. These can be either a
62
+
- 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).
63
+
- a Puya source map, produced when compiling a Smart Contract with the Puya compiler [example](examples/multiRootWorkspace/puya/ProofOfAttendance.approval.puya.map).
64
+
65
+
> 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.
62
66
63
67
### a. AlgoKit based project (recommended)
64
68
65
-
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:
69
+
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.
70
+
71
+
#### Python
66
72
67
73
```py
68
74
# Place this code in a project entry point (e.g. main.py)
69
75
from algokit_utils.config import config
70
76
config.configure(debug=True, trace_all=True)
71
77
```
72
78
79
+
#### TypeScript
80
+
73
81
```ts
74
82
// Place this code in a project entry point (e.g. index.ts)
75
83
import { config } from'algokit-utils-ts'
76
84
config.configure({ debug: true, traceAll: true })
77
85
```
78
86
87
+
> 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).
88
+
79
89
### b. Custom Project
80
90
81
91
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
85
95
86
96
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`.
87
97
98
+
### Puya Source Maps
99
+
100
+
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.
101
+
88
102
### Launch Configurations
89
103
90
104
The extension supports the following launch configurations:
@@ -153,17 +167,29 @@ The extension also offers an interactive picker for simulation trace files. The
153
167
154
168
This document outlines the features supported by the AVM debugger. Screenshots and features are based on the VS Code client.
| View transaction groups | Every execution starts with a top-level transaction group. ||
159
-
| Step into programs | LogicSig and application programs associated with transactions can be stepped into. Source maps show the original source code. ||
160
-
| Step into inner transactions | The debugger can step into inner transactions spawned by an application. The entire call stack can be seen and inspected. ||
| Breakpoint support | Breakpoints can be set in program source files. The debugger pauses when code corresponding to a breakpoint is about to be executed. ||
163
-
| 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. ||
164
-
| 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. ||
165
-
| 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. ||
166
-
| Inspect application state | The debugger allows inspection and watching of any available application state from the execution. ||
| View transaction groups | Every execution starts with a top-level transaction group. ||
173
+
| Step into programs | LogicSig and application programs associated with transactions can be stepped into. Source maps show the original source code. ||
174
+
| Step into inner transactions | The debugger can step into inner transactions spawned by an application. The entire call stack can be seen and inspected. ||
| Breakpoint support | Breakpoints can be set in program source files. The debugger pauses when code corresponding to a breakpoint is about to be executed. ||
177
+
| 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. ||
178
+
| 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. ||
179
+
| 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. ||
180
+
| Inspect application state | The debugger allows inspection and watching of any available application state from the execution. ||
181
+
| Support for Puya sourcemaps | The debugger now supports Puya sourcemaps, allowing debugging of contracts written in Puya. ||
182
+
| 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. ||
| 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. |
191
+
| Clear AVM Debug Registry | extension.avmDebugger.clearAvmDebugRegistry | Clears the AVM debug registry (contents of sources.avm.json). |
192
+
| Edit AVM Debug Registry | extension.avmDebugger.editAvmDebugRegistry | Edits the AVM debug registry (contents of sources.avm.json). |
0 commit comments