Getting Started

Check out our GitHub README page to see how you can install Neo3-Boa.

Writing a smart contract

It’s pretty easy to write a Python3 script with Neo3-Boa, since it is compatible with a lot of Python features. However, there are some key differences that you should be aware of, here’s the 4 most prominent ones:

  • there is no floating point arithmetic, only the int type is implemented;

  • you need to specify a function’s return type and parameter types;

  • if you want to call other smart contracts, you can only call public functions;

  • to interact with the Neo blockchain, you need to use a function, variable, or class inside the boa3.builtin package.

Overview of Neo3-Boa features

Packages

Contains:

Important features

boa3.builtin

all packages below, it also contains an env variable that lets you change the value of a variable when compiling the smart contract.

env

boa3.builtin.compile_time

methods and classes that are needed when you are compiling your smart contract, as opposed to when it’s being executed on the blockchain.

public, metadata, contract, CreateNewEvent, NeoMetadata

boa3.builtin.contract

events and methods that might help when writing something specific about Neo blockchain

abort, Nep17TransferEvent, Nep11TransferEvent

boa3.builtin.interop

other packages that have a lot of helpful interoperable services. Has some overlap with the native contracts.

storage, runtime, contract, blockchain

boa3.builtin.interop.blockchain

features to get information on the Neo blockchain.

current_hash, get_contract, Transaction

boa3.builtin.interop.contract

features related to smart contracts.

call_contract, update_contract, Contract

boa3.builtin.interop.crypto

features related to cryptography.

sha256, hash160, hash256, check_sig

boa3.builtin.interop.iterator

the iterator class.

Iterator

boa3.builtin.interop.json

methods to serialize and deserialize JSON.

json_serialize, json_deserialize

boa3.builtin.interop.oracle

features related with Neo Oracle, it is used to get information from outside the blockchain.

Oracle

boa3.builtin.interop.policy

features related to policies that affect the entire Neo blockchain.

get_exec_fee_factor, get_storage_price

boa3.builtin.interop.role

methods to get information about the nodes on the blockchain.

get_designated_by_role

boa3.builtin.interop.runtime

features to get information that can only be acquired when running the smart contract.

check_witness, calling_script_hash, executing_script_hash, script_container, Notification

boa3.builtin.interop.stdlib

methods that convert one data to another or methods that can check and compare memory.

serialize, deserialize

boa3.builtin.interop.storage

features to store, get, or change values inside the blockchain.

get, put, find, FindOptions

boa3.builtin.nativecontract

classes that interface Neo’s native contracts.

ContractManagement, GAS, NEO, StdLib

boa3.builtin.type

Neo types.

UInt160, UInt256, Event, ECPoint

boa3.builtin.vm

Opcodes used internally by the Neo VM, used to create scripts dynamically.

Opcode

boa3.builtin.math

a small sample of functions similar to Python’s math.

sqrt, floor, ceil

Hello World

Let’s write a quick Hello World script that has a method that will save "Hello World" on the blockchain and another method that will return the string.

Those 2 functions will need to be callable and will also need to change the values inside the storage, so let’s import both the public decorator and the storage package.

# hello_world.py
from boa3.builtin.compile_time import public
from boa3.builtin.interop import storage


@public     # the public decorator will make this method callable
def save_hello_world():             # an empty return type indicates that the return is None
    storage.put_str(b"first script", "Hello World")  # the put method will store the "Hello World" value with the "first script" key


@public     # the public decorator will make this method callable too
def get_hello_world() -> str:       # this method will return a string, so it needs to specify it
    return storage.get_str(b"first script")               # the get method will return the value associated with "first script" key

Neo Methods

Neo currently has 2 special methods: _deploy and verify:

from typing import Any
from boa3.builtin.compile_time import public

@public
def _deploy(data: Any, update: bool):
    """
    This method will automatically be called when the smart contract is deployed or updated.
    """
    pass

@public
def verify() -> bool:
    """
    When this contract address is included in the transaction signature,
    this method will be triggered as a VerificationTrigger to verify that the signature is correct.
    For example, this method needs to be called when withdrawing token from the contract.

    :return: whether the transaction signature is correct
    """
    pass

So, using the example above, if you want to set the "Hello World" message when you deploy your smart contract and have another method to save a given string you could do the following:

# hello_world_with_deploy.py
from typing import Any

from boa3.builtin.compile_time import public
from boa3.builtin.interop import storage


@public
def _deploy(data: Any, update: bool):               # the _deploy function needs to have this signature
    storage.put_str(b"second script", "Hello World")  # "Hello World" will be stored when this smart contract is deployed


@public
def get_message() -> str:                       # this method will still try to get the value saved on the blockchain
    return storage.get_str(b"second script")            


@public
def set_message(new_message: str):              # now this method will overwrite a new string on the blockchain
    storage.put_str(b"second script", new_message)

Compiling your Smart Contract

Using CLI

$ neo3-boa compile 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')

Reference Examples and Tutorials

Check out Neo3-boa tutorials on Neo Developer.

For an extensive collection of examples:

What’s next