Contract developer guide

Build with docker

There is a provided Docker image that contains all dependencies required to build a smart contract. You will need to install Docker Desktop on Mac and Windows or use Docker from the terminal on Linux. The CDT images are uploaded to Docker Hub. You can pull the image from koinos/koinos-cdt. The tag latest will point to the most recent build of the CDT. Any release versions will be tagged appropriatelt (e.g. v0.2.0 will be koinos/koinos-cdt:v0.2.0)

$ docker pull koinos/koinos-cdt

Next, cd to whatever directory your contract lives in. This directory must contain all source and headers for your contract and any .proto files required for it. Only the contract you wish to build must be in the directory.

$ docker run -t --mount type=bind,source="$(pwd)",target=/src --name <CONTRACT_NAME> koinos/koinos-cdt

You will see the compiler output from building the contract. If successful, there will be two build artifacts in your current directory.

  • The WASM binary (contract.wasm)

  • A type descriptor file (types.pb)

At the moment, we must manually create an Application Binary Interface (ABI) file to use with koinos-cli. This will require utilizing the type descriptor file. For more information on how that file is structured see the Contract ABI documentation.

If building your contract failed, you will see the compilation errors in the terminal log. To rebuild your contract you can restart the continer.

$ docker start -a <CONTRACT_NAME>

The CDT image is fully re-entrant and can be restarted any number of times.

Build manually

If you do not want to build using docker, you can set up the toolchain manually.

For the purposes of this tutorial, we will install the Contract Development Kit (CDT) as well as its dependencies to ~/opt. This is just a suggestion and will work if you decide another location is more appropriate for you.

Retrieving dependencies

The Koinos CDT has three dependencies.

  • Protobuf 3.17.3

  • WASI SDK 12.0

  • EmbeddedProto

Protocol buffers

First, we will install the Protobuf dependency. While it is possible to install this via a package manager such as Homebrew or Aptitude, we will build the dependency from source so that we may target the exact version of Protobuf required by the CDT without regard to version available in your preferred pacakage manager.

$ git clone --recursive https://github.com/protocolbuffers/protobuf.git
$ cd protobuf
$ git checkout v3.17.3
$ mkdir _build
$ cd _build
$ cmake -DCMAKE_INSTALL_PREFIX=~/opt/protobuf-3.17.3 -DCMAKE_BUILD_TYPE=Release ../cmake
$ make -j install

WASI SDK

Because WASI SDK provides adequate release packages on GitHub, we will simply grab the package for our operating system and extract it to the correct location.

macOS
$ wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-macos.tar.gz
$ tar -xvf wasi-sdk-12.0-macos.tar.gz -C ~/opt
Linux
$ wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-linux.tar.gz -C ~/opt2
$ tar -xvf wasi-sdk-12.0-linux.tar.gz -C ~/opt

EmbeddedProto

We will only need to clone this repository. We leverage the protoc plugin provided by this repository for serialization within the virtual machine.

$ cd ~/opt
$ git clone --recursive https://github.com/koinos/EmbeddedProto.git

Building the CDT

In order to build Koinos smart contracts you must first install the Koinos CDT. Navigate to the Koinos CDT and clone the repository.

The CDT relies on WASI SDK in order to build. We let the project know the location of WASI SDK using the environment variable KOINOS_WASI_SDK_ROOT.

$ export KOINOS_WASI_SDK_ROOT=~/opt/wasi-sdk-12.0
$ git clone --recursive https://github.com/koinos/koinos-cdt.git
$ cd koinos-cdt
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=~/opt/koinos-cdt ..
$ make -j install

Using the Koinos CDT

You are now prepared to compile Koinos smart contracts. Koinos smart contracts are built using the CMake build system. Using the provided CMake toolchain file, along with a few environment variables, you can now build contracts.

Assuming you have placed the Koinos CDT and the associated dependencies in ~/opt, you can set the necessary environment variables as follows:

$ export KOINOS_WASI_SDK_ROOT=~/opt/wasi-sdk-12.0
$ export KOINOS_PROTOBUF_ROOT=~/opt/protobuf-3.17.3
$ export KOINOS_EMBEDDED_PROTO_ROOT=~/opt/EmbeddedProto
$ export KOINOS_CDT_ROOT=~/opt/koinos-cdt

You are now ready to configure your smart contract project. From your project root directory, use the provided toolchain file and build:

$ mkdir build
$ cd build
$ cmake -DCMAKE_TOOLCHAIN_FILE=${KOINOS_CDT_ROOT}/cmake/koinos-wasm-toolchain.cmake -DCMAKE_BUILD_TYPE=Release ..
$ make -j

There is a skeleton cmake project in Koinos Contract Examples that you can use for your own smart contracts.

After building your smart contract you will find two important artifacts in your build directory.

  • The WASM binary (*.wasm)

  • A type descriptor file (*.pb)

At the moment, we must manually create an Application Binary Interface (ABI) file to use with koinos-cli. This will require utilizing the type descriptor file. For more information on how that file is structured see the Contract ABI documentation.