Truffle Visual Debugger

[acuarica]

This Epic aims to describe the current state of the Truffle Debugger for VS Code and future plans to eventually make it its own extension. By making it its own extension, users can still benefit from the Visual Debugger even if they do not use the main extension. In turn, this open the door for non-Truffle users to still use the Visual Debugger.

The only requirement for the underlying network to be used with the Truffle Visual Debugger is that it should provide the debug_Transaction RPC method.

Candidates Names.

If we effectively make the Debugger its own extension, we need to propose a name for the extension. This Epic uses Truffle Visual Debugger, but this might change in the future.

Fetch External.

The Visual Debugger now supports fetching external sources when debugging a forked network instance #252. Similar to --fetch-external flag when using the CLI, e.g,

truffle debug <transaction hash> --network sandbox --fetch-external

See https://trufflesuite.com/blog/debugging-verified-external-contracts-with-truffle-debugger/ for more information.

Startup

The VS Code extension's debugger can be triggered from three places

1. The Truffle: Debug Transaction command,
2. The launch configuration using a launch.json configuration file, or
3. A shell command using the VS Code protocol. This can be used by other tools or scripts that want to interact with the extension's debugger. Running truffle debug with appropriate flag (--vscode) - Enhancements & Fixes #254

Debugger Options

• txHash. The transaction hash to debug, for example 0x79381a69eb828558f2728900615109eb7bdeb6d216af130142341da15cc6fecd.
• workingDirectory. Directory of the Truffle project where to find the Truffle config file.
• providerUrl. Provider's URL of the Ethereum network to connect to, for examplehttp://127.0.0.1:8545.
• network. The network name to use as a provider found in truffle-config.js. Must be present if providerUrl is not. Support network option in addition to providerUrl when debugging  #261
• disableFetchExternal: boolean. When set, do not try to fetch external contract sources when debugging a forked network instance. When the network is not being forked, this flag is ignored. Include disableFetchExternal flag to avoid debugging with fetching external sources #255

Not implemented yet.

• config: For example ${workspaceFolder}/truffle-config.js or ${workspaceFolder}/hardhat.config.js. Should be implemented as part of Fix Debug Transaction command when Truffle config does not follow default name #256

These options are documented in package.json under the contributes.debuggers field.

Examples

Using VS Code protocol.

open "vscode://trufflesuite-csi.truffle-vscode/debug?txHash=0xd4290e9754d1a60cb7be5c1f6b53090fb6f047d13d325517f36aa15b6a9f46e0&workingDirectory=%2FUsers%2Fluigi%2FDownloads%2Ftruffle-sample-project&providerUrl=http%3A%2F%2F127.0.0.1%3A8545&disableFetchExternal=true

Using a launch configuration.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "truffle",
            "request": "launch",
            "name": "Truffle - Debug Transaction",
            "stopOnEntry": false,
            "txHash": "0x79381a69eb828558f2728900615109eb7bdeb6d216af130142341da15cc6fecd",
            "workingDirectory": "${workspaceFolder}",
            "providerUrl": "http://127.0.0.1:8545",
            "disableFetchExternal": true
        }
    ]
}

Networks

PR #170 restricts the Truffle: Debug Command networks to only local networks. We need to investigate if it is possible to debug remote networks, and if so, how.

The network option described above allows the user to specify networks from a Truffle config file. However, the Truffle: Debug Transaction command only shows Ganache Services from the Networks view. We should extend the network selection in Truffle: Debug Transaction command with networks from Truffle config files.

Code Sharing

Initially the Debugger run as a separate process from the main extension. Moreover, any debugger process does not have access to the VS Code API. As a result, some modules depending on the VS Code API were duplicated in the Debugger. See for example

• Unable to Debug Transaction in release 2.3.5 nor 2.3.6 #173 and
• Fixes the Debug Transaction command #174

However, this changed after #218. This PR introduced an embedded debugger, effectively removing the issue mentioned above. Nevertheless, as part of the extensions re-structuring, code duplication might be an issue again. We want to avoid code duplication. Hence, we need to think how to refactor and reuse bits used in both the extension and the Debugger.

Typings

We are integrating more and more Truffle packages into the VS Code extension, and in particular into the Debugger. See for example https://github.com/trufflesuite/vscode-ext/blob/532d70a8acdc1c308e7ea5de528b675f10efa0c9/src/debugAdapter/types/@truffle/debugger.d.ts. We should make a combined together with the Truffle team to improve typings on the Truffle side.

BSC Support

Currently the Debugger does not work in BSC network, see for example

• fork network, local debug error "Numbers can only be safely stored up to 53 bits"  #236

we found there is another issue, we get a missing trie node error coming from their RPC. We are going to discuss internally about how we are going to support BSC in the future.

Future Improvements

Integrate better with other Truffle CLI commands, for example with test command. See https://trufflesuite.com/docs/truffle/how-to/debug-test/use-the-truffle-debugger for more details on the Truffle Debugger capabilities. Debug read-only calls is of special interest to us, since it allows debugging without specifying a transaction.

There are already some issues to integrate into these other commands

• Use the Visual Debugger in truffle test #200 and
• Use Visual Debugger for call functions #201

We can evaluate

• Sidebar dedicated to the Visual Debugger
• Transaction Enumeration/Explorer right inside VS Code