Minimal build/deploy tool for Python NEAR smart contracts

This is a build/deploy tool for Python NEAR smart contracts for near/devtools#2

Python source files are compiled into the WASM binary via MicroPython and Emscripten and then deployed via near-cli-rs tool.

near-py-tool CLI is modelled after cargo-near

Dependencies

near-py-tool expects the following dependencies installed:

• Python>=3.9
• essential build tools like make and C compiler
• Emscripten for compiling Python into WASM via MicroPython (can be installed automatically by near-py-tool, if desired). Version 4.0.0 or above is recommended as there are issues with building some of the contracts on 3.x. Automatic installation via emsdk is offered if emcc is absent from PATH
• near-cli-rs for deployment and other NEAR Protocol interactions

Getting started

• install near-py-tool via pip install near-py-tool
• run near-py-tool new test-project to create a minimal Python smart contract project
• cd ./test-project
• run near-py-tool build to produce a standalone WASM file
• run near-py-tool create-dev-account to create a testnet account if you don't have one already
• run near-py-tool deploy to deploy the smart contract to testnet or mainnet

Examples

Please see the test suite for various low-level NEAR API usage examples:

• deploy_contract.py / promise_api.py - building and deploying a dependent contract with promises via promise_batch_action_deploy_contract()
• lowlevel_api.py - minimal storage api usage example
• fungible_token.py - low-level API port of https://github.com/near/near-sdk-rs/tree/master/near-contract-standards/src/fungible_token contract
• non_fungible_token.py - low-level API port of https://github.com/near/near-sdk-rs/tree/master/near-contract-standards/src/non_fungible_token contract

External examples:

• The smart contract that guards 3000 NEAR and gives away 2 NEAR per user and prevents double-spend: https://github.com/frol/1t-agents-fundme-agent
• The smart contract that guards 50 NEAR until it is jailbreaked: https://github.com/frol/neardevnewsletter-issue50-quest/tree/main/contract
• Demo Web4 contract in Python: https://github.com/frol/near-web4-demo-py

Platform support

Currenly Linux, MacOS and Windows (native/MSYS2/WSL) platforms are supported. Native Windows support is implemented via an automatically installed MSYS2 local copy which is utilized for MicroPython/WASM contract builds

Python library support / compatibility

Most of the MicroPython standard library is included and should be functional where applicable to WASM runtime environment.

External Python package are supported as long as they don't require native compiled code to work. near-py-tool will download any packages referenced via pyproject.toml and will try to compile them into the WASM binary alongside the main contract.py file.

Unneeded modules from the MicroPython stdlib can be excluded from the build by adding the following section to pyproject.toml: [tool.near-py-tool] exclude-micropython-stdlib-packages = [...]

Please be aware that there is no full compatibility to CPython yet since we use MicroPython as a runtime

MessagePack serialization

near-py-tool provides an built-in msgpack module, which provides fast and space-efficient MessagePack serialization of arbitrary Python data, including arbitrary-precision integers (implemented in C via cmp library)

Basic interface is equivalent to the Python msgpack module:

def packb(o: Any) -> bytes
def unpackb(b: bytes) -> Any

Arbitrary-precision integers are stored as MessagePack extension type 81; this is not portable outside of the WASM contract runtime environment, but useful for saving large numbers like account balances within the contract persistent state

NEAR WASM ABI support

Everything from https://github.com/near/near-sdk-rs/blob/master/near-sys/src/lib.rs should be available via near module, for example:

• near.input() retrieves contract input as bytes
• near.value_return(value) returns a value (str or bytes) from the contract
• near.log_utf8(message) logs a message (str)

Contract methods to be exported from the WASM binary should be decorated with @near.export

See the NEAR-ABI.md for a complete list of available methods and their type signatures.

Benchmarks

Here are some gas cost benchmark results which allow comparison to Rust and JS

Stats for similar Rust/JS contracts are available here

In general, gas costs for this Python implementation lie in between the Rust and JS values, which makes Python smart contracts practical for most use cases

Contributing

We are in the process of restructuring this into separate Python SDK / nearc compiler / test suite repositories as part of near/devtools#3, so future contributions should be directed towards the new repositories as they take shape