Getting started

August 26, 2026 · View on GitHub

This page is for people who have never worked on Neo internals. By the end you should know what this repository is, what it is not, and which guide to open next.

What is Neo?

Neo is an open-source public blockchain. Applications (smart contracts) run on every full node and must produce the same result on every machine. That is why the virtual machine is deterministic: given the same script and the same chain state, every node must agree.

Two native assets ship with the chain:

TokenWhat it isTypical use
NEOGovernance tokenVoting for committee / consensus
GASUtility tokenPaying network and system fees

On N3, GAS is claimed automatically when the NEO balance of an account changes. You do not run a separate “claim GAS” ritual like Neo 2.

Official concept pages (still accurate for N3):

Three GitHub repos, not one program

Beginners often clone this repository and expect a running node. This repo is the protocol library. The program you start is Neo-CLI, which lives in a different repository.

RepositoryWhat it containsYou clone it when…
neo-project/neo (this repo)Ledger, P2P messages, native contracts, ApplicationEngine, wallets, persistence interfacesYou change consensus rules, fees, storage keys, or native contracts
neo-project/neo-nodeNeo.CLI (the process), console commands, plugins (RPC, DBFT, LevelDB/RocksDB, Oracle, …)You want to run a node, expose JSON-RPC, or change CLI/plugins
neo-project/neo-vmStack VM: opcodes, evaluation stack, execution engine without blockchain syscallsYou change instruction semantics or embed the VM in another host

A full node is: neo-node process + neo library + neo-vm + a storage plugin.

See Architecture for a picture of the call path from “RPC invoke” down to an opcode.

What you need on your machine

  • OS: Windows, Linux, or macOS
  • SDK: .NET 10 (this tree’s projects use net10.0; package version prefix is 3.10.2)
  • Git
  • For a persisted node on Linux: LevelDB or RocksDB native libraries (see Run a node)

dotnet --version should report a 10.x SDK.

A 10-minute tour of this repo

git clone https://github.com/neo-project/neo.git
cd neo
git checkout master-n3          # N3 protocol line
dotnet test tests/Neo.UnitTests/Neo.UnitTests.csproj

That builds the core library and runs unit tests. It does not start a P2P node.

Useful folders:

FolderRole
src/Neo/Protocol: blockchain actor, mempool, native contracts, engine
src/Neo.IO/Serialization and caches
src/Neo.Json/JSON used by RPC and wallets
src/Neo.Extensions/Shared helpers
tests/Unit tests

N3 work happens on master-n3. The master branch is the next-generation (NEO-4) line. See Contribute.

A 10-minute tour of the node

The CLI is not in this repository on GitHub. Clone the node repo:

git clone https://github.com/neo-project/neo-node.git
cd neo-node
git checkout master-n3

Then follow How to: run a node. After start you should see a neo> prompt. Type help and show state.

A 10-minute tour of the VM

git clone https://github.com/neo-project/neo-vm.git
cd neo-vm
git checkout master
dotnet test tests/Neo.VM.Tests

The VM does not know about blocks. Blockchain features (storage, System.Runtime.* syscalls) are added by ApplicationEngine in this repo. Details: NeoVM.

Common mix-ups

Mix-upReality
“I cloned neo but dotnet neo-cli.dll is missing”CLI is in neo-node.
“Official page says download neo-cli from neo-project/neo-cli”That extra repo is historical. Current source is neo-node. Releases are under neo-node/releases.
“NameService is a native contract in the CLI dump I found online”In current neo source, native contracts include ContractManagement, StdLib, CryptoLib, Ledger, NeoToken, GasToken, Policy, RoleManagement, Oracle, Notary, Treasury. Name service is a non-native contract.
“I need Ubuntu 16 and .NET Core”Current projects target .NET 10. The neo-node README still mentions old Ubuntu LTS numbers; any current Linux with the SDK works.
“I will implement a dApp in this repo”Application code is compiled with neo-devpack-dotnet and deployed to the chain. This repo is the chain.

Next step