SophiaTX Developers logo

Quickstart

Technical Quickstart

Pre-requisites

Dedicated Operating System account to run blockchain applications

There is no urgency to install and run blockchain applications (daemon, wallet, …) under privileged account as a root.

In general, as your own user account, programs you run are restricted from writing to the rest of the system – they can only write to your “home” folder. You cannot modify system files without gaining root permissions first. This helps keep your computer secure.

To fulfil this requirement, it is recommended to create a dedicated user and group on NIX system

* Group: sphtxgrp  
* Account: sphtxamd

!!! You must gain sufficient privileges (e.g. as a root user or you can also prefix the following commands with the sudo command to run them as a non-privileged user to create a group and an account!!!

CLI commands to add group and account. The basic syntax of the command to Create/Add a new Group. As a root user you will type and run this command from command line.

# groupadd sphtxgrp

or as a john user you will type and run this command from command line.

john@EUGREEN02:~> sudo groupadd sphtxgrp

In the next steps follow the same principle for running the commands either as a root user or as any other OS user by using the sudo command The basic syntax of the command to Create/Add a new User with Specific Home Directory, Default Shell and Custom Comment from command line:

# useradd -m -g sphtxgrp -d /home/sphtxadm -s /bin/bash -c "SophiaTX Blockchain Owner" sphtxadm

To set password for user sphtxamd

# passwd sphtxadm

There are many other possibilities how to create users and groups in the NIX system – just follow NIX documentation / best praxis.

Install SophiaTX blockchain

To store blockchain data, it is suggested to create and have mounted a supplemental dedicated partition/file system. Subject of pre-requisites. Create subdirectory sphtxBCdata in the / directory and adjust ownership & permissions to user sphtxadm.

# mkdir /sphtxBCdata 
# chown sphtxadm:sphtxgrp /sphtxBCdata

Make sure that dedicated partition and file system for blockdata is mounted under previously created directory sphtxBCdata. Don’t forget to adjust /etc/fstab accordingly in order to avoid problems after rebooting the OS.
To validate that a dedicated partition is mounted under /sphtxBCdata, launch the mount command.

# mount 
sysfs on /sys type sysfs (rw,nosuid,nodev,noexec,relatime) 
proc on /proc type proc (rw,nosuid,nodev,noexec,relatime) 
devtmpfs on /dev type devtmpfs (rw,nosuid,size=2011880k,nr_inodes=502970,mode=755) 
securityfs on /sys/kernel/security type securityfs (rw,nosuid,nodev,noexec,relatime) 
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev,size=8388608k) 
devpts on /dev/pts type devpts (rw,nosuid,noexec,relatime,gid=5,mode=620,ptmxmode=000) 
tmpfs on /run type tmpfs (rw,nosuid,nodev,mode=755) 
/dev/sda2 on /sphtxBCdata type xfs (rw,relatime,attr2,inode64,noquota)

If no record about /sphtxBCdata is found in the output, then you have to mount the partition as follows: In case there exists sdb2 partition issue the following command from command line

# mount /dev/sdb2 /sphtxBCdata

There are many other options on how to check and mount the file system under specific directory and make sure it will be mounted automatically after the reboot. Just follow NIX documentation / best praxis.

The following commands to be executed as a sphtxadm user. You may log in as sphtxadm user, or switch to sphtxadm user by issuing of the following command:

# su - sphtxadm

Create and change to subdirectory sphtxd in home directory of sphtxadm user

sphtxadm@EUGREEN02:~> mkdir sphtxd 
sphtxadm@EUGREEN02:~> cd sphtxd

Go & Download the latest version of sophiatx binary and config files from the GitHub repository https://github.com/SophiaTX/SophiaTX/releases

Unpack downloaded sophiatx.tar.gz file

sphtxadm@EUGREEN02:~/sphtxd> tar -xvf sophiatx.tar.gz 
cli_wallet 
sophiatxd 
witness_config.ini 
fullnode_config.ini

If required, adjust witness_config.ini and get it copied as config.ini into the blockchain data directory. Make sure that ownership and privileges of the config file are set accordingly.

sphtxadm@EUGREEN02:~/sphtxd>  chmod 600 ./witness_config.ini 
sphtxadm@EUGREEN02:~/sphtxd>  chown sphtxadm:sphtxgrp ./witness_config.ini 
sphtxadm@EUGREEN02:~/sphtxd>  ls -l ./witness_config.ini 
-rw------- 1 sphatxdm sphtxgrp     5671 Jul 25 17:26 witness_config.ini

There might be a few reasons to update the config.ini file. Adjust witness private key and name of witness controlled by node

witness = “<name of witness>” 
private-key = <WIF Private Key>

Example

witness = "I889UHminer" 
private-key = 5IJY3b9FgfsGtxMeLkLqXzUrQDMAsqSyAZDnMBkg7PDDRhQgaV

Adjust a list of plugins

Mandatory plugin(s) – required to run witness node

plugin = witness

Optional plugin(s) – NOT required to run witness node

#plugin = alexandria_api
#plugin = block_api 
#plugin = network_broadcast_api 
#plugin = database_api 
#plugin = alexandria_api 
#plugin = account_history 
#plugin = account_history_api 
#plugin = account_by_key 
#plugin = chain_api 
#plugin = custom_api

Adjust a default port number for P2P endpoint blockchain nodes communication

p2p-endpoint = 0.0.0.0:60000

Make sure that “enable-stale-production” is set on true

enable-stale-production = true

Copy witness_config.ini into config.ini in the blockchain data directory

sphtxadm@EUGREEN02:~/sphtxd> cp ./witness_config.ini /sphtxBCdata/config.ini

To run SophiaTX Witness node and produce blocks (meaning being eligible to validate the transactions embedded in the blocks) you need to be one of the elected SophiaTX witnesses

Run SophiaTX Witness

There are two options to launch and run the SophiaTX witness node. When all mandatory parameters have been embedded in config.ini file, you may run the witness node with the following command:

sophiatxd -d <data_dir>

Example

sphtxadm@EUGREEN02:~/sphtxd> ./sophiatxd -d /sphtxBCdata

Parameters to be entered from command line.

sophiatxd -d <data_dir> --enable-stale-production true –-witness ‘<witness_name>’ --private-key <WIF Private Key> --plugin witness

Example:

sphtxadm@EUGREEN02:~/sphtxd> ./sophiatxd -d /sphtxBCdata --enable-stale-production true --witness '" I889UHminer"' --private-key 5JPwY3bwFgfsGtxMeLkLqXzUrQDMAsqSyAZDnMBkg7PDDRhQgaV --plugin witness

Build instructions

Compile-Time Options (cmake)

CMAKE_BUILD_TYPE=[Release/Debug]

Specifies whether to build with or without optimization and without or with the symbol table for debugging. Unless you are specifically debugging or running tests, it is recommended to build as release.

LOW_MEMORY_NODE=[OFF/ON]

Builds sophiatxd to be a consensus-only low memory node. Data and fields not needed for consensus are not stored in the object database. This option is recommended for witnesses and seed-nodes.

CLEAR_VOTES=[ON/OFF]

Clears old votes from memory that are no longer required for consensus.

BUILD_SOPHIATX_TESTNET=[OFF/ON]

Builds sophiatx for use in a private testnet. Also required for building unit tests.

SKIP_BY_TX_ID=[OFF/ON]

By default this is off. Enabling will prevent the account history plugin querying transactions by id, but saving around 65% of CPU time when reindexing. Enabling this option is a huge gain if you do not need this functionality.

Building on Ubuntu 18.04.1

For Ubuntu 18.04.1 users, after installing the right packages with apt SophiaTX will build out of the box without further effort:

# Required packages
sudo apt install -y \
    autoconf \
    automake \
    cmake \
    gcc \
    g++ \
    git \
    libbz2-dev \
    libssl-dev \
    libtool \
    make \
    pkg-config \
    python3 \
    python3-jinja2 \
    zlib1g-dev \
    libsqlite3-dev
    
# Boost packages (also required)
sudo apt-get install -y \
    libboost-chrono-dev \
    libboost-context-dev \
    libboost-coroutine-dev \
    libboost-date-time-dev \
    libboost-filesystem-dev \
    libboost-iostreams-dev \
    libboost-locale-dev \
    libboost-program-options-dev \
    libboost-serialization-dev \
    libboost-signals-dev \
    libboost-system-dev \
    libboost-test-dev \
    libboost-thread-dev

# Optional packages (not required, but will make a nicer experience)
sudo apt install -y \
    doxygen \
    libncurses5-dev \
    libreadline-dev \
    perl
    
git clone https://github.com/SophiaTX/SophiaTX
cd SophiaTX
git checkout master
git submodule update --init --recursive
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc) sophiatxd
make -j$(nproc) cli_wallet

# optional
make install  # defaults to /usr/local

Building Boost 1.67

SophiaTX requires Boost 1.65 and works with versions up to 1.69 (including). Here is how to build and install Boost 1.67 into your user’s home directory

export BOOST_ROOT=$HOME/opt/boost_1_67_0
URL='http://sourceforge.net/projects/boost/files/boost/1.67.0/boost_1_67_0.tar.gz'
wget "$URL"
[ $( sha256sum boost_1_67_0.tar.gz | cut -d ' ' -f 1 ) == \
    "8aa4e330c870ef50a896634c931adf468b21f8a69b77007e45c444151229f665" ] \
    || ( echo 'Corrupt download' ; exit 1 )
tar xzf boost_1_67_0.tar.gz
cd boost_1_67_0
./bootstrap.sh "--prefix=$BOOST_ROOT"
./b2 -j$(nproc) install

Building on Other Platforms

Choose SDK

Getting started to develop robust and feature rich SophiaTX applications couldn’t be easier. Accessing sophiaTX data is easy from various options depending on your infrastructure and objectives.

Building a picture discovery app is a breeze with the JavaScript and C# available. More SDK’s might be developed in the future.

SophiaTX Nodes

There are basically 3 types of nodes(functionalities that a node can represent) on SophiaTX blockchain. All of them use the same binary, the only difference is in configuration:

Connection options / opened ports:

Applications that interface directly with the SophiaTX public blockchain will need to connect to a sophiatxd node. Developers may choose to use one of the public API nodes that are available, or run their own instance of a node.

SophiaTX provides separate public Full and Seed Nodes.

Public Full Nodes

Full Nodes have enabled API’s plugins so all Alexandria API calls are available.

URL Owner
socket1.sophiatx.com @sophiatx
socket2.sophiatx.com @sophiatx

Public Seed Nodes

Seed Nodes are only for syncing the state of blockchain. No API’s are enabled (only p2p port 60000 is opened). Users can setup these as “p2p-seed-node” in config.

URL Owner
seednode1.sophiatx.com @sophiatx
seednode2.sophiatx.com @sophiatx
seednode3.sophiatx.com @sophiatx
seednode4.sophiatx.com @sophiatx
seednode5.sophiatx.com @sophiatx
seednode6.sophiatx.com @sophiatx

Public Witness Nodes

There are no public witness nodes.

Syncing blockchain (public network)

Normally syncing blockchain starts from very first, 0 genesis block. It might take long time to catch up with live network. Because it connectes to various p2p nodes in the SophiaTX network and requests blocks from 0 to head block. It stores blocks in block log file and builds up the current state in the shared memory file. But there is a way to bootstrap syncing by using trusted block_log file. The block log is an external append only log of the blocks. It contains blocks that are only added to the log after they are irreversible because the log is append only.

Trusted block log file helps to download blocks faster. SophiaTX, provides public downloadable block_log and block_log.index files. As of April 2019, size of both files is ~1 GB.

To download these files, megatools can be used on linux:

sudo apt-get install megatools
megadl '<url>'

Note: as url use block_log & block_log.index links above

Block log should be place in blockchain directory below data_dir and node should be started with --replay-blockchain to ensure block log is valid and continue to sync from the point of snapshot. Replay uses the downloaded block log file to build up the shared memory file up to the highest block stored in that snapshot and then continues with sync up to the head block.

Replay helps to sync blockchain in much faster rate, but as blockchain grows in size replay might also take some time to verify blocks.

Few other tricks that might help:

For Linux users, virtual memory writes dirty pages of the shared file out to disk more often than is optimal which results in sophiatxd being slowed down by redundant IO operations. These settings are recommended to optimize reindex time.

echo    75 | sudo tee /proc/sys/vm/dirty_background_ratio
echo  1000 | sudo tee /proc/sys/vm/dirty_expire_centisecs
echo    80 | sudo tee /proc/sys/vm/dirty_ratio
echo 30000 | sudo tee /proc/sys/vm/dirty_writeback_centisecs


Another settings that can be changed in config.ini is flush-state-interval - it is to specify a target number of blocks to process before flushing the chain database to disk. This is needed on Linux machines and a value of 100000 is recommended. It is not needed on OS X, but can be used if desired.

SophiaTX testnet

SophiaTX blockchain software is written in C++ and in order to modify the source code you need some understanding of the C++ programming language. Each SophiaTX node runs an instance of this software, so in order to test your changes, you will need to know how to install dependencies which can be found in the SophiaTX repo. This also means that some knowledge of System administration is also required. There are multiple advantages of running a testnet, you can test your scripts or applications on a testnet without extra spam on the live network, which allows much more flexibility to try new things. Having access to a testnet also helps you to work on new features and possibly submit new or improved pull requests to official the SophiaTX GitHub repository.

SophiaTX’s Testnet

SophiaTX maintains a live testnet to which you can connect. In the near future, we expect the chain id to update with every code change. To get the current chain id for any HF20+ SophiaTX testnet you can use the database_api.get_version api call (curl example included for your convenience). Be sure to point it at an api node on the testnet for which you want information!

At the time of this writing, the connection information for SophiaTX’s testnet is as follows:

Running a Testnet Node

First, let’s build sophiatxd specifically for testnet. Recommended specs:

TODO: provide testnet build instructions

config.ini

log-console-appender = {"appender":"stderr","stream":"std_error"}
log-file-appender = {"appender":"p2p","file":"logs/p2p/p2p.log"}
log-logger = {"name":"default","level":"info","appender":"stderr"}
log-logger = {"name":"p2p","level":"warn","appender":"p2p"}

backtrace = yes
plugin = chain p2p webserver witness database_api network_broadcast_api block_api 

shared-file-dir = "blockchain"
shared-file-size = 12G
p2p-endpoint = 0.0.0.0:2001
webserver-http-endpoint = 0.0.0.0:8751
webserver-ws-endpoint = 0.0.0.0:8752

# testnet.sophiatx.com
p2p-seed-node = 

sophiatxd --data-dir=. --chain-id=46d82ab7d8db682eb1959aed0ada039a6d49afa1602491f93dde9cac3e8e6c32

Now let it sync, and you’ll have a shiny new testnet seed node to play with.

Custom Testnet

In order to create a custom, isolated, testnet separate from the SophiaTX’s we need to modify a few things mentioned in the previous section.

In the file named SophiaTX/libraries/protocol/include/SophiaTX/protocol/config.hpp, we can see the first few lines dedicated to the Testnet section. The line starts with #ifdef IS_TEST_NET.

Let’s say we want to create a custom testnet with an initial supply of 1,000,000 sphtx. We can change SOPHIATX_INIT_SUPPLY 1,000,000 and by changing SOPHIATX_CHAIN_ID_NAME "testnet", testnet to mytestnet we will automatically get a unique Chain ID for our testnet. The address prefix can be set to something like MTN and of course, we need to change the public and private keys to the genesis account. Note that the genesis account will receive the entire pre-mined supply of 1,000,000. That way, you can execute a setup script to fund any newly created accounts. Such a custom testnet will not have any additional hardware requirements to run.

A minimum of 8GB RAM should be sufficient to run a custom testnet. Currently, SophiaTX only has Linux and Mac compiling guides to build. A testnet can either be hosted locally, on a rented AWS, or dedicated bare metal servers so one can start testing functionality, explore different APIs, and start developing.

One more crucial point to modify is to change the number of witnesses required to accept hardforks for a custom testnet, by default it is set to 17, we can change it to 1 SOPHIATX_HARDFORK_REQUIRED_WITNESSES 1 so that only one node instance would be sufficient and the network will be still functional and fast.

Another thing to note is that you can start a new chain with all previous hardforks already accepted, by changing the file named SophiaTX/blob/master/libraries/chain/database.cpp with the following function:

void database::init_genesis( uint64_t init_supply ) inside try add this line:

set_hardfork( 19, true );

This would mean that 19 hardforks have been accepted by witnesses and the new chain will start with all previous forks included.

After these changes, all we have to do is compile the source code and get the sophiatxd executable. And once we fire up the custom testnet we can start testing and experimenting.

↑ Back to top