picarodias / neo3-boa

write smart contracts for Neo3 in python

Write smart contracts for Neo3 in Python
Made by COZ.IO

neo3-boa · neo-mamba

Table of Contents

• Overview
  • Product Strategy
  • Project Structure
• Quickstart
  • Installation
    • Pip (Recommended)
    • Build from Source (Optional)
  • Compiling your Smart Contract
    • Using CLI
    • Using Python Script
  • Configuring the Debugger
  • TestEngine
    • Downloading
    • Updating
    • Testing
• Docs
• Reference Examples
• Python Supported Features
• Neo Python Suite Projects
• Opening a New Issue
• License

Overview

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

Neo-boa is part of the Neo Python Framework, aimed to allow the full development of dApps using Python alone.

Product Strategy

Pure Python

We want Python developers to feel comfortable when trying neo3-boa for the first time. It should look and behave like regular Python. For this reason we decided to avoid adding new keywords, but use decorators and helper functions instead.

Neo Python Framework

In the real world, simply coding a smart contract is not enough. Developers need to debug, deploy and invoke it. Therefore, it’s important for this tool to be part of a bigger Python framework. To help the developers and avoid a bad user experience, we need to use logs and inform errors with details.

Testing against Neo VM

We need to ensure that the code works as expected, and the only way to do that is to run our tests against the official Neo 3 VM. Neo repository already contains a class called TestEngine that is capable of running tests using C# smart-contracts. It will be adjusted to support compiled smart-contracts.

Maintenance

Create a product that is easy to maintain and upgrade. Use Unit tests, typed and documented code to ensure its maintainability.

Project Structure

The diagram bellow shows the basic building blocks of the Neo3-Boa project.

Quickstart

Installation requires Python 3.7 or later.

Installation

Make a Python 3 virtual environment and activate it:

On Linux / Mac OS:

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

On Windows:

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

Pip (Recommended)

Install Neo3-Boa using Pip:

$ pip install neo3-boa

Build from Source (Optional)

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

Clone neo3-boa:

$ git clone https://github.com/CityOfZion/neo3-boa.git

Install project dependencies:

$ pip install wheel
$ pip install -e .

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')

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
                }
            }
        }
    ]
}

TestEngine

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.0.3
$ 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

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.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

Docs

You can read the docs here. Please check our examples for reference.

Reference Examples

For an extensive collection of examples:

• Smart contract examples
• Features tests

Tests

Install neo3-boa and the TestEngine and run the following command

Note: If you didn't install TestEngine in neo3-boa's root folder, you need to change the value of TEST_ENGINE_DIRECTORY in this file

python -m unittest discover boa3_test

Python Supported Features

Status	Release	Converts	Example Code	Contract Example Test
✅	v0.3	Local variable declarations and assignments	def func(): foo: int = 42 bar = foo	List of examples
✅	v0.3	Global variable declarations and assignments	foo: int = 42 bar = foo	List of examples
✅	v0.4	Global keyword	foo: int = 42 bar = foo def func(): global foo foo = 1	List of examples
✅	v0.3	Arithmetic operations	+, -, *, //, %	List of examples
✅	v0.8	Arithmetic operations	**	List of examples
🔜	backlog	Arithmetic operations	/
✅	v0.3	Arithmetic augmented assignment operators	+=, -=, *=, //=, %=	List of examples
✅	v0.8	Arithmetic augmented assignment operators	**=	List of examples
🔜	backlog	Arithmetic augmented assignment operators	/=
✅	v0.3	Relational operations	==, !=, <, <=, >, >=, is None, is not None	List of examples
✅	v0.8.3	Relational operations	is, is not	List of examples
✅	v0.3	Bitwise operations	&, |, ~, ^, <<, >>	List of examples
✅	v0.8.3	Bitwise augmented assignment operators	&=, |=, ~=, ^=, <<=, >>=	List of examples
✅	v0.3	Boolean logic operations	and, or, not	List of examples
✅	v0.3	Tuple type	a = ('1', '2', '3')	List of examples
✅	v0.3	List type	a = ['1', '2', '3']	List of examples
✅	v0.4	List type	a.pop()	List of examples
✅	v0.7	List type	a.remove(1) a.insert('example', 2)	List of examples
✅	v0.3	Dict type	a = {1:'1', 2:'2', 3:'3'}	List of examples
🔜	backlog	Set type	a = {'1', '2', '3'}
✅	v0.3	Bytes type	a = b'\x01\x02\x03\x04'	List of examples
✅	v0.3	Bytearray type	a = bytearray(b'\x01\x02\x03\x04')	List of examples
✅	v0.8.2	Optional type	a: Optional[int] = 5 a = 142 a = None	List of examples
✅	v0.6.1	Union type	a: Union[int, str] = 5 a = 142 a = 'example'	List of examples
✅	v0.3	While statement	foo = 0 while condition: foo = foo + 2	List of examples
✅	v0.3	If, elif, else statements	if condition1: foo = 0 elif condition2: foo = 1 else: bar = 2	List of examples
✅	v0.3	For statement	for x in (1, 2, 3): ...	List of examples
✅	v0.3	Function call	def Main(num: int): a = foo(num) ... def foo(num: int) -> int: ...	List of examples
✅	v0.3	Built in function	a = len('hello')	List of examples
✅	v0.4	Built in function	a = range(1, 5, 2) b = isinstance(5, str) print(42)	List of examples
✅	v0.7	Built in function	a = max(7, 12) b = min(1, 6)	List of examples
✅	v0.8	Built in function	a = abs(-5)	List of examples
✅	v0.8.1	Built in function	a = sum(list_of_num, 0)	List of examples
✅	v0.8.3	Built in function	a = max(7, 0, 12, 8) b = min(1, 6, 2) c = reversed([1, 2, 3, 4])	List of examples
🔜	backlog	Built in function	a = pow(2, 2)
✅	v0.3	Multiple expressions in the same line	i = i + h; a = 1; b = 3 + a; count = 0	List of examples
✅	v0.4	Chained assignment	x = y = foo()
✅	v0.3	Sequence slicing	x = 'example'[2:4] x = [1, 2, 3][:2] x = 'example'[4:] x = (1, 2, 3)[:] x = 'example'[-4:-2] x = 'example'[:-4]	List of examples
🔜	backlog	Sequence slicing	x = 'example'[2:4:2] x = 'example'[::2]
✅	v0.3	Assert	assert x % 2 == 0 assert x % 3 != 2, 'error message'	List of examples
✅	v0.4	Try except	try: a = foo(b) except Exception as e: a = foo(b)	List of examples
✅	v0.5	Try except with finally	try: a = foo(b) except Exception as e: a = zubs(b) finally: b = zubs(a)	List of examples
✅	v0.4	Continue, break
🔜	backlog	Pass
✅	v0.3	Import	Support to boa3.builtin packages.	List of examples
✅	v0.8.3	Import	Support to user created modules.	List of examples
🔜	next release	Class	class Foo: def __init__(self, bar: Any): pass

Neo Python Suite Projects

• neo3-boa: Python smart contracts' compiler.
  
• neo3-mamba: Python SDK for interacting with neo.
  

Opening a New Issue

• Open a new issue if you encounter a problem.
• Pull requests are welcome. New features, writing tests and documentation are all needed.

License

• Open-source Apache 2.0.