1. Getting Started

Neo3-Boa is a tool for creating Neo Smart Contracts using Python. It compiles .py files to .nef and .manifest.json formats for usage in the Neo Virtual Machine which is used to execute contracts on the Neo Blockchain.

1.1 Installation

This version of the compiler requires Python 3.7 or later.

Set Virtual Environment

Make a Python 3 virtual environment and activate it:

On Linux/MacOS:

$ python3 -m venv venv
$ source venv/bin/activate

On Windows:

$ python3 -m venv venv
$ venv\Scripts\activate.bat

Build From Source (Alternative)

If neo3-boa is not available via pip, you can build it from source.

git clone https://github.com/CityOfZion/neo3-boa.git
pip install wheel
pip install -e .

1.2 Creating a New Smart Contract


CONTENT MISSING: Project Scaffold - GitHub #307 and #308

1.3 Compiling your Smart Contract

Using CLI

$ neo3-boa path/to/your/file.py


When resolving compilation errors it is recommended to resolve the first reported error and try to compile again. An error can have a cascading effect and throw more errors all caused by the first.

Using Python Script

from boa3.boa3 import Boa3


1.4 Testing and Debugging

Configuring the Debugger

Neo3-boa is compatible with the Neo Debugger. Debugger launch configuration example:

    //Launch configuration example for Neo3-boa.
    //Make sure you compile your smart-contract before you try to debug it.
    "version": "0.2.0",
    "configurations": [
            "name": "example.nef",
            "type": "neo-contract",
            "request": "launch",
            "program": "${workspaceFolder}\\example.nef",
            "operation": "main",
            "args": [],
            "storage": [],
            "runtime": {
                "witnesses": {
                    "check-result": true

It’s necessary to generate the nef debugger info file to use Neo Debugger.

Using CLI

$ neo3-boa path/to/your/file.py -d|--debug

Using Python Script

from boa3.boa3 import Boa3

Boa3.compile_and_save('path/to/your/file.py', debug=True)

Test Engine


Clone neo-devpack-dotnet project and compile the TestEngine.


Until neo-devpack-dotnet#365 is approved by Neo, you need to clone neo-devpack-dotnet from simplitech:test-engine-executable branch

$ git clone https://github.com/simplitech/neo-devpack-dotnet.git -b v3.5.0
$ dotnet build ./neo-devpack-dotnet/src/Neo.TestEngine/Neo.TestEngine.csproj


Go into the neo-devpack-dotnet, pull and recompile.

${path-to-folder}/neo-devpack-dotnet git pull
${path-to-folder}/neo-devpack-dotnet dotnet build ./src/Neo.TestEngine/Neo.TestEngine.csproj



If you didn’t install TestEngine in neo3-boa’s root folder, you need to change the value of TEST_ENGINE_DIRECTORY in the file boa3/env.py

Create a Python Script, import the TestEngine class, and define a function to test your smart contract. In this function you’ll need to call the method run(). Its parameters are the path of the compiled smart contract, the smart contract’s method, and the arguments if necessary. Then assert your result to see if it’s correct.

Your Python Script should look something like this:

from boa3_test.tests.test_classes.testengine import TestEngine
from boa3.internal.neo.smart_contract.VoidType import VoidType

def test_hello_world_main():
    root_folder = '{path-to-test-engine-folder}'
    path = '%s/boa3_test/examples/HelloWorld.nef' % root_folder
    engine = TestEngine(root_folder)

    result = engine.run(path, 'Main')
    assert result is VoidType

To run your tests use:

python -m unittest discover boa3_tests