Skip to content

Stealth Installation Guide

Jump to bottom
James Stroud edited this page Oct 9, 2024 · 1 revision

Stealth Daemon Installation Guide

BEFORE YOU START

Backup your wallet.dat!

For example:

StealthCoind backupwallet "${HOME}/wallet.dat.$(date +%s)"

If StealthCoind is not running, it suffices to simply make a copy:

cp "${HOME}/.StealthCoin/wallet.dat" "${HOME}/wallet.dat.$(date +%s)"

The database used for the wallet (Berkeley DB) has poor forwards-compatibility. In most cases, this incompatibility shouldn’t be a problem, but be safe and create a backup before you do anything.

If you have problems, you may have to determine the version of Berkeley DB used to build your current instance of StealthCoind and build against a custom installation.

Also, if you previously built with a custom installation of Berkeley DB, you may have to scrape it from your system. Typically, the commands are:

sudo rm /usr/local/lib/libdb*
sudo rm /usr/local/lib/db.*h

It is likely worthwhile to run these commands if you are upgrading StealthCoind.

Summary

In short, the steps to install are:

  1. Backup your wallet.dat! See above.

  2. Upgrade your operating system and package manager to the latest version.

  3. Ensure that external dependencies are installed.

  4. Download the Stealth source bundle.

  5. Within a new directory called "build" at the top of the source tree, run “cmake ..”, then “make”:

    # from the top of the downloaded source code
mkdir build
cd build
cmake ..
make

Commands

All shell commands in this document are for Bash except when otherwise noted.

Dependencies

Fortunately, all the packages mentioned below (and many more) are easily installed using package managers available to all common operating systems. Typically, the command to install every package is a single line that can be copy-pasted in one shot.

Core Dependencies

The daemon has six external dependencies that should either be installed from a package manager, supplied by the system, or built manually.

For most users, it is recommended and simplest to install these dependencies using a package manager.

System-specific instructions are given below.

Required Building Tools

Git is the recommended way to download the source, straight from GitHub. Additionally, the build system relies on GCC and CMake.

Other Essential Tools

Other tools that are useful for setting up the Stealth daemon are Wget, 7-Zip, and curl.

  • Wget is used to download source code and the Stealth blockchain as a bootstrap.

  • 7-Zip is used to decompress the blockchain bootstrap.

    7-Zip is not used in building the daemon, but it is essential to bring up a funcitonal Stealth network node. The bootstrap uses 7-Zip compression because it creates much smaller archives than most other alternatives.

  • Curl is used in some tool chains to send commands to StealthCoind as well as to download source code and blockchain data.

Testing: GoogleTest

The testing system (optional) also requires GoogleTest.

Installing the Dependencies

Because Stealth uses the CMake unified build system, the only build steps that should differ between systems are the installation of the dependencies, which is typically a single command.

Instructions for Linux (Ubuntu, Fedora, & CentOS), macOS (using Homebrew), and FreeBSD follow.

Building has been tested successfully on newer versions of each (as of September 2024).

  • Ubuntu 22.04 LTS, a.k.a "Jammy Jellyfish"

  • Fedora 40

  • CentOS 9, a.k.a "Stream"

  • MacOS 14.6.1, a.k.a "Sonoma" (on both Intel and Apple Silicon)

  • FreeBSD 13.3

Other systems may vary from the examples below. Fortunately, the six core dependencies are offered in the de facto package managers for the common operating systems, with the one notable exception being CryptoPP on CentOS/RedHat Linux. So determining the package names for operating systems not mentioned here should be straightforward.

Ubuntu (Debian)

According to Google, Ubuntu is the most popular Linux distribution as of writing (September 2024).

Ubuntu installations prior to 22.04 LTS default to OpenSSL versions that are no longer supported by the Stealth codebase. To upgrade Ubuntu from the command line, use “do-release-upgrade”, until the Ubuntu version is at least 22.04 LTS. The Ubuntu version can be determined with the command “lsb_release -a”.

Package names in the following command may differ for Debian variants other than Ubuntu.

sudo apt install wget git cmake autoconf build-essential \
         openssl libssl-dev pkg-config p7zip-full \
         libcurl4-openssl-dev unzip curl python3-dev \
         libboost-all-dev libdb++-dev zlib1g zlib1g-dev \
         libevent-dev libcrypto++-dev

Fedora (RedHat)

Fedora is the second most popular desktop Linux distribution, according to Google.

Fedora has extensive package support through it’s version of the DNF (dnf) package manager.

This support makes installing the required dependencies and tools easy:

sudo dnf clean all
sudo dnf update
sudo dnf install git curl gcc gcc-c++ make cmake openssl-devel \
                 libdb-cxx-devel libevent-devel \
                 boost boost-devel cryptopp-devel zlib-devel p7zip

Fedora 40 provides git, wget, curl, unzip with its default install.

CentOS Stream (RedHat)

According to the CentOS website, CentOS lies "midstream between Fedora Linux and RHEL [Red Hat Enterprise Linux]". This positioning makes CentOS a good proxy for all three, and for other variants of RedHat.

More closely aligned with RHEL than Fedora, CentOS does lack a couple of dependencies in its package manager support: CryptoPP and 7-Zip. Fortunately, installing these two dependencies amounts to a handful of commands that can be copy-pasted at once.

Because of this slight addeded complexity, building the daemon on CentOS is provided here as an example for other RedHat-based distributions that may also have less extensive package manager support.

The following instructions are for CentOS Stream 9.

Core Dependencies and Tools

CentOS and other RedHat derivatives use the DNF package manager, invoked with “dnf”.

sudo dnf clean all
sudo dnf update
sudo dnf --enablerepo=crb install git gcc gcc-c++ glibc \
                          openssl-devel bzip2-devel libffi-devel \
                          zlib-devel make cmake boost-devel \
                          libdb-cxx-devel libevent-devel

CryptoPP

CryptoPP is not available through the CentOS 9 package manager.

Fortunately, the commands to download, build, and install it are simple and can be copy-pasted in one shot:

mkdir -p ${HOME}/Deps/cryptopp/cryptopp-v8.9
cd ${HOME}/Deps/cryptopp/cryptopp-v8.9
wget https://github.com/weidai11/cryptopp/releases/download/CRYPTOPP_8_9_0/cryptopp890.zip
unzip cryptopp890.zip
NCORES=$(( $(grep -c processor /proc/cpuinfo) - 1 ))
make -j${NCORES}
sudo make install

7-Zip

The following commands:

  • Download and extract the appropriate 7-Zip in a directory called “Deps/7zip” in the user’s home directory.

  • A set of if..then..else statements determine the correct 7-Zip download, depending on whether the CPU architecture is AMD64 (x86_64) or Arm64 (aarch64).

  • These commands then install the 7zz executable to “/usr/local/bin”.

  • Finally, 7z is soft-linked to 7zz because 7z is the more typical command to invoke 7-Zip.

Despite the apparent complexity of the following commands, they can all be copy-pasted in one shot:

mkdir -p "${HOME}/Deps/7zip/7zip-v24.08"
cd "${HOME}/Deps/7zip/7zip-v24.08"
arch=$(uname -m)
base_7zip_url="https://7-zip.org/a"
_7zip_archive_prefix="7z2408-linux"
if [[ "$arch" == "x86_64" ]]; then
    base_7zip_archive="${_7zip_archive_prefix}-x64"
elif [[ "$arch" == "aarch64" ]]; then
    base_7zip_archive="${_7zip_archive_prefix}-amd64"
else
    base_7zip_archive=""
    echo "Unsupported architecture: $arch"
fi
if [ "${base_7zip_archive}" != "" ]; then
  _7zip_archive="${base_7zip_archive}.tar.xz"
  echo "Downloading 7-Zip (${_7zip_archive}) for ${arch} with:"
  file_url="${base_7zip_url}/${_7zip_archive}"
  echo '   wget '"${file_url} ..."
  wget "${file_url}"
  tar xvf "${_7zip_archive}"
  sudo cp 7zz /usr/local/bin
  cd /usr/local/bin
  sudo ln -s 7zz 7z
fi

MacOS

These instructions have been tested on macOS Sonoma 14.6, running on both Intel and Apple Silicon processors.

Package Manager

To build the Stealth daemon, the recommended macOS package manager is Homebrew.

The installation instructions for Homebrew are at its home page.

Libraries

For Homebrew, the package names of the core dependencies are:

  • berkeley-db@18

  • boost

  • libevent

  • openssl@3

  • cryptopp

Note that ZLib is already provided by the OS X system as of OS X Catalina (version 10.15.3).

Compiler

Fortunately, macOS provides C and C++ compilers with Xcode, which should be installed with the following command:

xcode-select --install
Important

When running the “cmake” step to build the daemon, you might get an error that contains the following:

The C compiler

  "/usr/bin/cc"

is not able to compile a simple test program.

More than likely, you simply need to accept the XCode license agreement with:

sudo xcodebuild -license

Then try again.

Other Tools

MacOS also provides the curl and Git utilities, leaving only Wget (wget) and 7-Zip (sevenzip) for installation with Homebrew.

Homebrew Command

The Homebrew command to install the necessary dependencies and tools on macOS is:

brew install cmake wget berkeley-db@18 boost libevent openssl@3 \
             cryptopp sevenzip

FreeBSD

FreeBSD is considered the most popular version of BSD, and is typically used for servers.

Fixing FreeBSD’s make Command

FreeBSD has a few differences from Linux-based operating systems. Among those, one is relevant to building the Stealth daemon: the use of BSD make, which offers only a subset of features supported by the more common GNU Make (gmake).

To remedy this deficiency, it is necessary to:

  1. Install gmake with pkg, the BSD package manager.

  2. Re-order the $PATH environment variable.

  3. Create a soft-link for gmake called “make” that is found earlier in $PATH than BSD make.

The following commands accomplish all three:

pkg install gmake
# set PATH for current shell
export PATH="${HOME}/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin"
# set PATH for future shells
echo 'export PATH="${HOME}/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin"' >> "${HOME}/.profile"
mkdir "${HOME}/bin"
cd "${HOME}/bin"
ln -s /usr/local/bin/gmake make

Core Dependencies and Tools

The FreeBSD package manager, pkg, has excellent coverage of tools and libraries, making their installation a single command:

pkg install lang/gcc autoconf automake bash cmake gmake libtool \
            pkgconf openssl boost-all db18 cryptopp libevent git

Note that ZLib and OpenSSL are installed with the FreeBSD operating system.

Windows

The daemon can build under MinGW, but Windows is not supported at the moment.

To host StealthCoind on Windows, users are encouraged to use Docker with the “Dockerfile” in the “contrib/docker” directory.

Download the Stealth Source for Building

The Stealth source is hosted on GitHub at https://github.com/Stealth-R-D-LLC/Stealth/. The default branch therein is “master” and will contain the latest stable Stealth codebase.

mkdir -p ${HOME}/Code
cd ${HOME}/Code
# creates the directory called "Stealth" that contains the source code
git clone https://github.com/Stealth-R-D-LLC/Stealth.git

Making the Stealth Daemon

The recommended way to build the Stealth daemon is from a directory called “build”, created at the top of the source bundle obtained from “git clone”. In the following commands, the number of cores is set to the maximum for the system minus 1, speeding up the build concomitant with the number of cores.

NCORES=$(( $(grep -c processor /proc/cpuinfo) - 1 ))
# Stealth directory created by "git clone"
cd Stealth
mkdir build
cd build
cmake ..
make -j${NCORES}

Testing

Building and running the tests are optional, and typically used by developers. The following discussion is therefore aimed at advanced users.

Presently, the new testing framework is split into functional parts, divided by the code units tested. In the future, it will be possible to run all the tests in a unified fashion.

Build GoogleTest

Because each project should have its own GoogleTest environment configured specifically for the needs of that project, it is usually necessary to manually build and install GoogleTest to a custom location, unique to the project.

In the following commands, the GoogleTest installation we use will reside in a folder identified by the variable named “$STEALTH_GTEST”.

You may want want to modify these commands to your needs:

mkdir -p "${HOME}/Code/googletest"
cd "${HOME}/Code/googletest"
git clone https://github.com/google/googletest.git
cd googletest
mkdir build
cd build
cmake -DBUILD_GMOCK=OFF ..
NCORES=$(( $(grep -c processor /proc/cpuinfo) - 1 ))
make -j${NCORES}
cd ..
STEALTH_GTEST="${HOME}/Code/googletest/stealth-gtest"
mkdir -p "${STEALTH_GTEST}"
rm -rf "${STEALTH_GTEST}/*"
cp -a googletest/include/ "${STEALTH_GTEST}/include"
cp -a build/lib "${STEALTH_GTEST}/lib"
Important
GoogleTest Installation

The “make install” command is purposefully not called.

Instead the headers and libraries are manually put in place to ensure an installation path that works on all platforms.

Building and Running the Tests

Tests are located in “src/test”.

Currently, viable tests exist in the following directories, each testing a specific unit of code:

  • bip32-hash-test

  • core-hashes-test

  • key-test

  • secp256k1_openssl-test

  • util-test

Note

These tests all have in common that they test the core cryptographic functionality of the Stealth protocol.

You may also notice a “boost-tests” directory. These are legacy tests that are in the process of being converted to the new GoogleTest framework.

Assuming GoogleTest was built according to the commands above, instructions to build and test the “bip32-hash-test” suite are:

cd "${HOME}/Code/Stealth/src/test/bip32-hash-test"
mkdir build
cd build
cmake -DGTEST_ROOT="${STEALTH_GTEST}" ..
NCORES=$(( $(grep -c processor /proc/cpuinfo) - 1 ))
make -j${NCORES}

Building the test produces an executable that starts “test-”. In the present example, this executable is “test-bip32-hash”:

./test-bip32-hash

Debugging the Tests

Each test supports a “-d” debugging flag:

./test-bip32-hash -d

The debugging flag prints helpful output about the data used and produced in the tests.

For example, the first few lines of output from the above “./test-bip32-hash -d” command is:

[==========] Running 13 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 13 tests from HashTest
[ RUN      ] HashTest.SHA256Test
======================
Test of SHA256 - Input
======================
        0x73, 0xe0, 0x66, 0x77, 0xa8, 0xf2, 0x1e, 0xa1, 0x6f, 0x50, 0x23, 0x0b,
        0xf4, 0x5f, 0x2b, 0x3e, 0x20, 0x7d, 0xea, 0x66, 0xf1, 0x55, 0x54, 0xbb,
        0xbb, 0x09, 0xcb, 0x15, 0xae, 0x49, 0xc4, 0x71, 0x17, 0x56, 0xf3, 0x36,
        0xf4, 0xf8, 0x33, 0x62, 0x3a, 0xa6, 0x08, 0xcc, 0xf7, 0xf4, 0xd2, 0x47,
        0xc4, 0x2e, 0xb9, 0xae, 0x0a, 0x5a, 0x99, 0xf5, 0x33, 0x89, 0x29, 0xb6,
        0x2c, 0x2a, 0xbb, 0xa6

=======================
Test of SHA256 - Output
=======================
        0x21, 0x7d, 0x44, 0xae, 0x39, 0xb5, 0x3e, 0x33, 0xc6, 0x97, 0x1d, 0xcf,
        0x7f, 0x95, 0xdc, 0x1f, 0x40, 0x32, 0x0e, 0x1b, 0xb6, 0x93, 0x1a, 0x53,
        0x86, 0x6b, 0x12, 0x8a, 0x0c, 0x8a, 0xfb, 0x86

================================
Test of SHA256 - Expected Output
================================
        0x21, 0x7d, 0x44, 0xae, 0x39, 0xb5, 0x3e, 0x33, 0xc6, 0x97, 0x1d, 0xcf,
        0x7f, 0x95, 0xdc, 0x1f, 0x40, 0x32, 0x0e, 0x1b, 0xb6, 0x93, 0x1a, 0x53,
        0x86, 0x6b, 0x12, 0x8a, 0x0c, 0x8a, 0xfb, 0x86

[       OK ] HashTest.SHA256Test (1 ms)
[ RUN      ] HashTest.SHA256_2Test

Other Testing Options

Please see the readme files (“README.md” or “README.adoc”) within the unit testing folders and in their parent folder “src/test” for further options when building the tests.

Clone this wiki locally