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

Pip Install (Recommended)¶

pip install neo3-boa

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¶

Warning

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

1.3 Compiling your Smart Contract¶

Using CLI¶

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

Note

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

Boa3.compile_and_save('path/to/your/file.py')

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¶

Downloading¶

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

Note

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

Updating¶

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

Testing¶

Note

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