Neo-Express and Neo-Trace

Note, This repo uses a branch structure similar to other repos in the Neo project. The master branch contains Neo N3 version of Neo-Express and Neo-Trace. The master-2.x branch contains Neo Legacy version of Neo-Express. There is no Neo Legacy version of Neo-Trace.

Requirements

As of Neo v3.1, Neo-Express and Neo-Trace require version 6.0 of the .NET developer platform to be installed.

Note: Neo-Express has additional, platform-specific requirements beyond .NET 6. These requirements are detailed below. Neo-Trace has no additional dependencies beyond .NET 6.

Note: the Neo v3.0 version of Neo-Express and Neo-Trace used .NET 5. .NET 5 is no longer supported by Microsoft. We strongly recommend using .NET 6 and the latest version of Neo-Express and Neo-Trace.

Installation

Neo-Express and Neo-Trace are distributed as .NET Tools. .NET tools are NuGet packages containing console applications that can be installed on a developer's machine via the dotnet tool command.

To install the latest version of Neo-Express as a global tool, run the dotnet tool install command in a terminal window.

> dotnet tool install Neo.Express -g

To update Neo-Express to the laest version, run the dotnet tool update command in a terminal window.

> dotnet tool update Neo.Express -g

Note: The process for installing and updating Neo-Trace is identical to Neo-Express except the Neo-Trace NuGet package is Neo.Trace.

.NET tools also supports "local tool" installation. This allows for different versions of a .NET tool to be installed in different directories. Full details on installing and updating .NET tools are available in the official documentation.

Installing Preview Releases

The Neo Blockchain Toolkit has a public build server and package feed. The public package feed contains unreleased builds of Neo-Express and Neo-Trace.

You can install preview builds of Neo-Express or Neo-Trace by using the --add-source option to specify the Neo Blockchain Toolkit package feed. For example, to update to the latest release branch version of Neo-Express, you would run this command:

> dotnet tool update Neo.Express -g --add-source https://pkgs.dev.azure.com/ngdenterprise/Build/_packaging/public/nuget/v3/index.json

You can also install master branch releases of these tools by using the --version and/or --prerelease command line options. For more details, please see the official dotnet tool documentation.

If you regularly use unreleased versions of these tools in a given project, you can specify the Neo Blockchain Toolkit package feed in a NuGet.config file. Several Neo sample projects like NeoContributorToken use a NuGet.config file.

Neo-Express

Neo-Express is a privatenet optimized for development scenarios. It is built on the same Neo platform core as neo-cli and neo-gui to maximize compatibility between local development and public chain environments.

Neo-Express provides the following features:

Blockchain instance management
Wallet management
Asset management
Smart contract management
Blockchain checkpoint and rollback

Docs are somewhat limited at this point. Please review the Command Reference to get an understanding of Neo-Express capabilities.

Additional Neo-Express Requirements

Ubuntu Installation

Note, while Microsoft has instructions for installing .NET via Snap, there is a known issue with this approach that leads to a segmentation fault in Neo Express. Unfortunately, this issue with the .NET snap installer has been closed and will not be fixed. As such, we recommend using APT to install .NET on Ubuntu instead.

Installing on Ubuntu requires installing libsnappy-dev, libc6-dev and librocksdb-dev via apt-get

> sudo apt install libsnappy-dev libc6-dev librocksdb-dev -y

MacOS Installation

Installing on MacOS requires installing rocksdb via Homebrew

> brew install rocksdb

Note, .NET 6 Arm64 has full support for Apple Silicon. Homebrew likewise also supports Apple Silicon. If you have any issues running Neo-Express on Apple Silicon hardware, please open an issue in the Neo-Express repo.

Neo Legacy Version Support

Neo Legacy versions of Neo-Express used older versions of .NET Core.

Note, if you need a Neo Legacy version of Neo-Express because you are still developing for the Legacy Neo Blockchain, we highly advise using the v1.1 version of Neo-Express. Pre-release versions of the Neo Legacy version of Neo-Express ran on versions of .NET Core that no longer supported by Microsoft.

Neo-Express Version	.NET Core Version
v1.1	v3.1
v1.0	v3.1
v0.9	v3.0
v0.8	v2.2

Neo-Trace

Neo-Trace is a tool to generate Neo Smart Contract Debugger trace files for existing blocks or transactions. You can specify a block by index or hash or a transaction by hash.

> neotrace block 365110 --rpc-uri testnet
> neotrace block 0xd2421d88919dccc1ac73647bf06089bae78ce02060302eff861a04e381bc91ad --rpc-uri testnet
> neotrace tx 0xef1917b8601828e1d2f3ed0954907ea611cb734771609ce0ce2b654bb5c78005--rpc-uri testnet

Neo-Trace depends on the
StateService plugin module running with FullState enabled. The official JSON-RPC nodes for MainNet and TestNet (such as http://seed1.neo.org:10332 and http://seed1t5.neo.org:20332) are configured to run the StateService plugin with FullState enabled.

A Message from the Engineer

Thanks for checking out Neo-Express and Neo-Trace! I am eager to hear your opinion of the product.

If you like these tools, please let me know on Twitter, email or the Neo Discord server.

If there are things about these tools you don't like, please file issues in our GitHub repo. You can hit me up on Twitter, Discord or email as well, but GitHub issues are how we track improvements we make. So don't be shy - file an issue if there is anything you'd like to see changed in the product.

Most software is built by teams of people. However, Neo-Express and Neo-Trace so far have been mostly a solo effort. I'm looking forward to having other folks contribute in the future, but so far it's just been me. That means that these tools have been designed around my experiences and my perspective. I can't help it, my perspective is the only one I have! :) So while I find these tools intuitive, I realize that you may not feel the same. Please let me know if this is the case! I didn't build these tools for me, I built it for the Neo developer community at large. So if there are changes we can make to make these tools more accessible, intuitive, easier to use or just flat-out better - I want to hear about them.

Thanks again for checking out these tools. I look forward to hearing from you.

- Harry Pierson (aka DevHawk), Chief Architect NGD Seattle

devhawk/neo-express