Installing Node Software

Installing Leap

Leap is a C++ implementation of the Antelope protocol, which Telos is built on. It contains blockchain node software and supporting tools for developers and node operators.

Leap currently supports the following operating systems:

Ubuntu 22.04 Jammy
Ubuntu 20.04 Focal

Other Unix derivatives such as macOS are tended to on a best-effort basis and may not be full featured. If you aren't using Ubuntu, please visit the Build Unsupported OS page to explore your options.

If you are running an unsupported Ubuntu derivative, such as Linux Mint, you can find the version of Ubuntu your distribution was based on by using this command:

cat /etc/upstream-release/lsb-release

If you are running an unsupported Ubuntu derivative, such as Linux Mint, you can find the version of Ubuntu your distribution was based on by using this command:

NOTE: If you are new to EOSIO, it is recommended that you install the EOSIO Prebuilt Binaries. If you are an advanced developer, a block producer, or no binaries are available for your platform, you may need to Build EOSIO from source depending on your OS.

Binary Installation

This is the fastest way to get started. From the latest release page, download a binary for one of our supported operating systems, or visit the release tags page to download a binary for a specific version of Leap.

Once you have a *.deb file downloaded for your version of Ubuntu, you can install it as follows:

sudo apt-get update
sudo apt-get install -y ~/Downloads/leap*.deb

Your download path may vary. If you are in an Ubuntu docker container, omit sudo because you run as root by default.

Finally, verify Leap was installed correctly:

nodeos --full-version

You should see a semantic version string followed by a git commit hash with no errors. For example:

v3.1.2-0b64f879e3ebe2e4df09d2e62f1fc164cc1125d1

Build and Install from Source

You can also build and install Leap from source.

Prerequisites

You will need to build on a supported operating system.

Requirements to build:

C++20 compiler and standard library
CMake 3.16+
LLVM 7 - 11 - for Linux only
- newer versions do not work
libcurl 7.40.0+
git
GMP
Python 3
python3-numpy
zlib

Step 1 - Clone

If you don't have the Leap repo cloned to your computer yet, open a terminal and navigate to the folder where you want to clone the Leap repository:

cd ~/Downloads

Clone Leap using either HTTPS...

git clone --recursive https://github.com/AntelopeIO/leap.git

...or SSH:

git clone --recursive git@github.com:AntelopeIO/leap.git

HTTPS vs. SSH Clone
Both an HTTPS or SSH git clone will yield the same result - a folder named leap containing our source code. It doesn't matter which type you use.

Navigate into that folder:

cd leap

Step 2 - Checkout Release Tag or Branch

Choose which release or branch you would like to build, then check it out. If you are not sure, use the latest release. For example, if you want to build release 3.1.2 then you would check it out using its tag, v3.1.2. In the example below, replace v0.0.0 with your selected release tag accordingly:

git fetch --all --tags
git checkout v0.0.0

Once you are on the branch or release tag you want to build, make sure everything is up-to-date:

git pull
git submodule update --init --recursive

Step 3 - Build

Select build instructions below for a pinned build (preferred) or an unpinned build.

Pinned vs. Unpinned Build
We have two types of builds for Leap: "pinned" and "unpinned." A pinned build is a reproducible build with the build environment and dependency versions fixed by the development team. In contrast, unpinned builds use the dependency versions provided by the build platform. Unpinned builds tend to be quicker because the pinned build environment must be built from scratch. Pinned builds, in addition to being reproducible, ensure the compiler remains the same between builds of different Leap major versions. Leap requires the compiler version to remain the same, otherwise its state might need to be recovered from a portable snapshot or the chain needs to be replayed.

A Warning On Parallel Compilation Jobs (-j flag)
When building C/C++ software, often the build is performed in parallel via a command such as make -j "$(nproc)" which uses all available CPU threads. However, be aware that some compilation units (*.cpp files) in Leap will consume nearly 4GB of memory. Failures due to memory exhaustion will typically, but not always, manifest as compiler crashes. Using all available CPU threads may also prevent you from doing other things on your computer during compilation. For these reasons, consider reducing this value.

Docker and sudo If you are in an Ubuntu docker container, omit sudo from all commands because you run as root by default. Most other docker containers also exclude sudo, especially Debian-family containers. If your shell prompt is a hash tag (#), omit sudo.

Pinned Reproducible Build

The pinned reproducible build requires Docker. Make sure you are in the root of the leap repo and then run

DOCKER_BUILDKIT=1 docker build -f tools/reproducible.Dockerfile -o . .

This command will take a substantial amount of time because a toolchain is built from scratch. Upon completion, the current directory will contain a built .deb and .tar.gz (you can change the -o . argument to place the output in a different directory). If needing to reduce the number of parallel jobs as warned above, run the command as,

DOCKER_BUILDKIT=1 docker build --build-arg LEAP_BUILD_JOBS=4 -f tools/reproducible.Dockerfile -o . .

Unpinned Build

The following instructions are valid for this branch. Other release branches may have different requirements, so ensure you follow the directions in the branch or release you intend to build. If you are in an Ubuntu docker container, omit sudo because you run as root by default.

Install dependencies:

sudo apt-get update
sudo apt-get install -y \
        build-essential \
        cmake \
        git \
        libcurl4-openssl-dev \
        libgmp-dev \
        llvm-11-dev \
        python3-numpy \
        file \
        zlib1g-dev

On Ubuntu 20.04, install gcc-10 which has C++20 support:

sudo apt-get install -y g++-10

To build, make sure you are in the root of the leap repo, then run the following command:

mkdir -p build
cd build

## on Ubuntu 20, specify the gcc-10 compiler
cmake -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..

## on Ubuntu 22, the default gcc version is 11, using the default compiler is fine
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..

make -j "$(nproc)" package

Now you can optionally test your build, or install the *.deb binary packages, which will be in the root of your build directory.

Step 4 - Test

Leap supports the following test suites:

Test Suite	Test Type	Test Size	Notes
Parallelizable tests	Unit tests	Small
WASM spec tests	Unit tests	Small	Unit tests for our WASM runtime, each short but very CPU-intensive
Serial tests	Component/Integration	Medium
Long-running tests	Integration	Medium-to-Large	Tests which take an extraordinarily long amount of time to run

When building from source, we recommended running at least the parallelizable tests.

Parallelizable Tests

This test suite consists of any test that does not require shared resources, such as file descriptors, specific folders, or ports, and can therefore be run concurrently in different threads without side effects (hence, easily parallelized). These are mostly unit tests and small tests which complete in a short amount of time.