Neo-Express, Neo-WorkNet and Neo-Trace

July 3, 2026 · View on GitHub

Overview
Download Links
Installation Guide
Usage Guide
New Features or issues
License

Overview

Neo-Express is a private net optimized for development scenarios, built on the same Neo platform core as neo-cli and neo-gui to maximize compatibility between local development and public chain environments. Neo-WorkNet branches a public Neo network — MainNet, TestNet or any JSON-RPC node — into a local chain for development against real network state. Neo-Trace is a tool for generating trace files for the Neo Smart Contract Debugger from public Neo N3 blocks and transactions.

These tools provide developers with a complete local development environment for building, testing, and debugging Neo smart contracts efficiently.

Key Features

Neo-Express:
- Blockchain instance management
- Wallet management
- Asset management
- Smart contract management
- Blockchain checkpoint and rollback
Neo-WorkNet:
- Branch a public Neo N3 network at any block height for local use
- Develop and test against real deployed contracts and state
- Prefetch contract storage for offline work
- Reset the local branch back to its branch point
Neo-Trace:
- Generate trace files for Neo Smart Contract Debugger
- Support specifying blocks by index or hash and transactions by hash
- Replay public-chain transactions from StateService-enabled RPC nodes

Download Links

Platform	Download Link
Windows	Latest Windows Release
macOS	Latest macOS Release
Linux	Latest Linux Release

Installation Guide

Install via Release Package

Download the latest release package from neo-express releases for your operating system.
Unzip the package on your local machine.
Run the neoxp.exe command in the terminal from the directory where you unzipped the package.

Install via .NET Tool

Requirements

.NET 10.0 or higher

Installation Steps

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

dotnet tool install Neo.Express -g

To update Neo-Express to the latest version, run the following command:

dotnet tool update Neo.Express -g

The installation and update process for Neo-WorkNet and Neo-Trace is identical:

dotnet tool install Neo.WorkNet -g
dotnet tool update Neo.WorkNet -g

dotnet tool install Neo.Trace -g
dotnet tool update Neo.Trace -g

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.

Usage Guide

Quick Start

Get started with Neo-Express in just a few commands:

# Install Neo-Express
dotnet tool install Neo.Express -g

# Create a new blockchain
neoxp create

# Start the blockchain
neoxp run

# Check wallet balances
neoxp show balances genesis

Tip: While the blockchain is running it mints a new block every 3 seconds by default, so a transaction is not reflected in queries such as show balances until the next block is produced. For faster local iteration, start the chain with a shorter block time, for example neoxp run --seconds-per-block 1.

For writing automated smart-contract tests against a Neo-Express checkpoint — including build integration, typed contract interfaces, assertions and contract code coverage — see the contract testing guide.

Neo-Express

Create a new local Neo network:
```
neoxp create
```
List all wallets:
```
neoxp wallet list
```
Show genesis account balance:

genesis to use the consensus node multi-sig account which holds the genesis NEO and GAS.
```
neoxp show balances genesis
```
Send 1 gas from genesis account to node1 account:
```
neoxp transfer 1 gas genesis node1
```
Invoke a deployed contract with an invocation file:
```
neoxp contract invoke transfer.neo-invoke.json genesis
```
Invocation files identify deployed contracts by name or script hash. See the Neo Express Invocation File guide for the supported format.

Please review the Command Reference to get an understanding of Neo-Express capabilities.

Neo-WorkNet

Branch the Neo N3 TestNet at the current block height:
```
neo-worknet create testnet
```
Run the branched chain locally:
```
neo-worknet run
```

From the point of the branch, the local chain evolves independently of the public network: transactions and blocks added locally have no effect on the public chain. This makes it possible to test contracts against real deployed contracts and live state without spending GAS on a public network.

Please review the Neo-WorkNet Command Reference for the full list of commands and options.

Note: Neo-WorkNet depends on the StateService plugin module running with FullState enabled on the node being branched. The official JSON-RPC nodes for MainNet and TestNet are configured this way.

Neo-Trace

Generate a trace file for a block:

neotrace block 365110 --rpc-uri testnet

Generate a trace file for a transaction:

neotrace tx 0xef1917b8601828e1d2f3ed0954907ea611cb734771609ce0ce2b654bb5c78005 --rpc-uri testnet

Please review the NeoTrace Command Reference for the full list of commands and options.

Note: 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. Neo-Trace does not include per-instruction storage snapshots from public-chain StateService replay. For local Neo-Express transactions with storage snapshots, use the --trace option on commands such as neoxp run, neoxp contract invoke, or neoxp contract run to write .neo-trace files locally.

New Features or issues

Thank you for using Neo-Express, Neo-WorkNet and Neo-Trace! We welcome your feedback to make these tools more accessible, intuitive, and powerful.

Please visit the issues page to report problems or suggest new features. When creating a new issue, try to keep the title and description concise and provide context, such as a code snippet or an example of a feature and its expected behavior.

License

Neo-Express, Neo-WorkNet and Neo-Trace are licensed under the MIT License.