A new command line developer tool has been added to the Neo Blockchain Toolkit by NGD Enterprise. NeoTrace makes it possible to capture individual transactions or blocks from the Neo N3 MainNet or TestNet and store traces of the executions for debugging.

NeoTrace

One of the most useful applications of the NeoTrace tool is in troubleshooting bugs in smart contracts that have been deployed to MainNet. Though much testing may be done locally prior to final deployment, some bugs only arise during very specific conditions, especially in more complex contracts.

In many cases, developers will need access to those conditions, such as the current storage values being acted on, before they can understand the source of the bug. NeoTrace makes it possible to generate a trace file from any N3 transaction, acquiring the contract storage state at the time of the transaction in the process. The tool fetches the required information from RPC nodes, which must use the StateService plugin with full state enabled before they can be used to generate trace files.

Debugging a register invocation of the domain smart contract on N3 TestNet

If the source code and debug info file are also available, they can be used together with the trace file to follow the execution path of a transaction at the source code or bytecode level. Together with the original storage state included with the trace file, this allows developers to directly observe internal VM behavior during the captured transaction’s execution.

Developers can step forward or backward through the code, observing the initialization of variables, changes in storage, GAS consumption, and other operations as each line is executed. While debugging invocation traces, users can also switch back and forth between source code and bytecode views, the same as during typical contract debugging in the Toolkit.

Quickstart

The NGD Enterprise team has provided a quickstart guide which includes all the things necessary to try out the new utility. The example makes use of the Domain Registrar sample smart contract previously used to demonstrate various Neo Blockchain Toolkit features.

After cloning and opening the neo-registrar-sample repository, developers can run the default build task to ensure Neo Express, Trace, and the C# Compiler are installed and ready for use.

The next step involves running a provided VS Code Terminal Task, generate trace, which uses the newly installed NeoTrace utility to capture a transaction from the Neo N3 TestNet. This transaction is an invocation of the domain registrar contract provided in the sample directory, specifically the register command.

Now that the invocation trace has been captured, a debug session of the sample C# domain registrar contract can be launched. Debugging will follow the path of execution for the transaction and make it much more convenient for developers to observe the cause of any unexpected behavior.

Like Neo Express, NeoTrace can be installed as a dotnet tool or from the package linked below:
https://github.com/neo-project/neo-express/releases/tag/3.0.21

Tags: , ,