The following is a list of prerequisites required to start developing on Oasis Core:

  • Linux (if you are not on Linux, you will need to either set up a VM with the proper environment or, if Docker is available for your platform, use the provided Docker image which does this for you, see below).

  • System packages:

    On Fedora 29+, you can install all the above with:

    sudo dnf install bubblewrap gcc gcc-c++ protobuf-compiler make cmake openssl-devel libseccomp-devel pkg-config

    On Ubuntu 18.10+ (18.04 LTS provides overly-old bubblewrap), you can install all the above with:

    sudo apt install bubblewrap gcc g++ protobuf-compiler make cmake libssl-dev libseccomp-dev pkg-config
  • Go (at least version 1.16.3).

    If your distribution provides a new-enough version of Go, just use that.


    • install the Go version provided by your distribution,

    • [ensure $GOPATH/bin is in your PATH](,

    • install the desired version of Go, e.g. 1.16.3, with:

      go get
      go1.16.3 download
    • instruct the build system to use this particular version of Go by setting the OASIS_GO environment variable in your ~/.bashrc:

      export OASIS_GO=go1.16.3
  • Rust.

    We follow Rust upstream's recommendation on using rustup to install and manage Rust versions.

    NOTE: rustup cannot be installed alongside a distribution packaged Rust version. You will need to remove it (if it's present) before you can start using rustup.

    Install it by running:

    curl --proto '=https' --tlsv1.2 -sSf | sh

    NOTE: If you want to avoid directly executing a shell script fetched the internet, you can also download rustup-init executable for your platform and run it manually.

    This will run rustup-init which will download and install the latest stable version of Rust on your system.

  • Fortanix Rust EDP utilities.

    Make sure a nightly version of the Rust toolchain is installed:

    rustup install nightly

    Then install the Fortanix Rust EDP utilities by running:

    cargo +nightly install --version 0.4.0 fortanix-sgx-tools
    cargo +nightly install --version 0.8.2 sgxs-tools

    NOTE: These utilities must be compiled with a nightly version of the Rust toolchain since they use the #![feature] macro.

  • Oasis Core's Rust toolchain version with Fortanix SGX target.

    The version of the Rust toolchain we use in Oasis Core is specified in the rust-toolchain file.

    The rustup-installed versions of cargo, rustc and other tools will automatically detect this file and use the appropriate version of the Rust toolchain when invoked from the Oasis core git checkout directory.

    To install the appropriate version of the Rust toolchain, make sure you are in an Oasis Core git checkout directory and run:

    rustup show

    This will automatically install the appropriate Rust toolchain (if not present) and output something similar to:

    active toolchain
    nightly-2021-05-20-x86_64-unknown-linux-gnu (overridden by '/code/rust-toolchain')
    rustc 1.54.0-nightly (f94942d84 2021-05-19)

    Then add the Fortanix SGX Rust target to this version of the Rust toolchain by running:

    rustup target add x86_64-fortanix-unknown-sgx
  • (OPTIONAL) gofumpt and gofumports.

    Required if you plan to change any of the Go code in order for automated code formatting (make fmt) to work.

    Download and install it with:

    export GOFUMPT_VERSION=abc0db2c416aca0f60ea33c23c76665f6e7ba0b6
    GO111MODULE=on ${OASIS_GO:-go} get[email protected]${GOFUMPT_VERSION}
    GO111MODULE=on ${OASIS_GO:-go} get[email protected]${GOFUMPT_VERSION}
  • (OPTIONAL) protoc-gen-go.

    Download and install it with:

    GO111MODULE=on ${OASIS_GO:-go} get[email protected]

    NOTE: If you didn't/can't add $GOPATH/bin to your PATH, you can install protoc-gen-go to /usr/local/bin (which is in $PATH) with:

    sudo GOBIN=/usr/local/bin GO111MODULE=on ${OASIS_GO:-go} install[email protected]

    NOTE: The repository has the most up-to-date files generated by protoc-gen-go committed for convenience. Installing protoc-gen-go is only required if you are a developer making changes to protobuf definitions used by Go.

  • (OPTIONAL) jemalloc (version 5.2.1, built with 'je_' jemalloc-prefix)

    Alternatively set OASIS_BADGER_NO_JEMALLOC="1" environment variable when building oasis-node code, to build BadgerDB without jemalloc support.

    Download and install jemalloc with:

    pushd $(mktemp -d)
    wget \
    -O jemalloc.tar.bz2 \
    # Ensure checksum matches.
    echo "${JEMALLOC_CHECKSUM} jemalloc.tar.bz2" | sha256sum -c
    tar -xf jemalloc.tar.bz2
    cd jemalloc-${JEMALLOC_VERSION}
    # Ensure reproducible jemalloc build.
    EXTRA_CXXFLAGS=-ffile-prefix-map=$(pwd -L)=. \
    EXTRA_CFLAGS=-ffile-prefix-map=$(pwd -L)=. \
    ./configure \
    --with-jemalloc-prefix='je_' \
    sudo make install

    NOTE: jemalloc needs to be installed to the (default) /usr/local prefix (i.e. you can't use ./configure --prefix=$HOME/.local ...) because upstream authors hardcode its path.

In the following instructions, the top-level directory is the directory where the code has been checked out.

Using the Development Docker Image

If for some reason you don't want or can't install the specified prerequisites on the host system, you can use our development Docker image. This requires that you have a recent version of Docker installed.

Oasis development environment with all the dependencies preinstalled is available in the oasisprotocol/oasis-core-dev:master image. To run a container, do the following in the top-level directory:

make docker-shell

If you are curious, this target will internally run the following command:

docker run -t -i \
--name oasis-core \
--security-opt apparmor:unconfined \
--security-opt seccomp=unconfined \
-v $(pwd):/code \
-w /code \
oasisprotocol/oasis-core-dev:master \

All the following commands can then be used from inside the container. See the Docker documentation for detailed instructions on working with Docker containers.