How to build and run a hive node - witness/seed/consensus and account history nodes

This guide is for building on Ubuntu. It should work on Ubuntu 20. It is not recommended to go with older versions. It is recommended to start with a fresh install.

System requirements

Consensus/witness/seed node:

• 1TB storage**
• 32GB RAM*

Account history node:
_{Note: This type of node will be deprecated and replaced by HAFAH after the hard fork 26. But will still work.}

• 2TB storage**
• 32GB RAM*

*: The required RAM goes up over time
**: The required storage goes up over time

Building

Install dependencies:

sudo apt-get update

sudo apt-get install git wget

sudo apt-get install \
    autoconf \
    automake \
    cmake \
    g++ \
    git \
    zlib1g-dev \
    libbz2-dev \
    libsnappy-dev \
    libssl-dev \
    libtool \
    make \
    pkg-config \
    doxygen \
    libncurses5-dev \
    libreadline-dev \
    perl \
    python3 \
    python3-jinja2

sudo apt-get install \
    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-system-dev \
    libboost-test-dev \
    libboost-thread-dev

Clone the repository and select the version:

git clone https://gitlab.syncad.com/hive/hive
cd hive
git checkout v1.25.0
git submodule update --init --recursive

We selected the tag v1.25.0. You can checkout master for the latest version but it's not recommended for the witness nodes. Because witnesses vote for a hard fork by running the version of that hard fork.
This version will not work after hard fork 26.

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc) hived
make -j$(nproc) cli_wallet
make install

_{In case the original repository is down, you can use the mirror at https://gitlab.com/hiveblocks/hive}

Data directory

Now you can make another folder as a data directory to hold block_log and the config file. I will use /root/hive-data directory.

cd /root
mkdir hive-data
hived -d /root/hive-data --dump-config

The above command will create the config file. We will edit that later depending on the type of node that we need.

It is highly recommended to download block_log to speed up the sync/replay time. The one I linked below is hosted by the great wizard @gtg (make sure to vote him as a witness).

cd /root/hive-data/blockchain
wget https://gtg.openhive.network/get/blockchain/block_log

After downloading the block_log, choose one of the configs from below and move on to the replay section.

---

Seed node

The config file is located at hive-data/config.ini.
Edit the following parameters in the config file. Add them if they don't exist.

# Plugin(s) to enable, may be specified multiple times
plugin = witness condenser_api network_broadcast_api database_api block_api
# account_by_key is enabled by default - required to use 'get_witness' and 'get_account' in cli_wallet
plugin = account_by_key account_by_key_api
# required for creating and importing Hive 1.24+ State Snapshots
plugin = state_snapshot

shared-file-size = 30G
shared-file-dir = /dev/shm/
p2p-endpoint = 0.0.0.0:2001

The seed node will be open on port 2001.
Ready to replay the node.

---

Account history node

The exact same config as the seed node but with additional config:

# open the port for RPC connections
webserver-http-endpoint = 127.0.0.1:8091

# edit depending on the load on the RPC node - 64-256 for high traffic
webserver-thread-pool-size = 2

# additional alongside the other plugins
plugin = account_history_rocksdb account_history_api

# The location of the rocksdb database for account history. By default it is $DATA_DIR/blockchain/account-history-rocksdb-storage
account-history-rocksdb-path = "blockchain/account-history-rocksdb-storage"

# optionally you can comment out this
#p2p-endpoint = 0.0.0.0:2001

Ready to replay the node.

---

Witness node

To run cli_wallet in offline mode, you will need to build it from the develop branch instead of v1.25.0 or master. Or just replay the node and then come back here and run the cli_wallet without -o.

Run cli_wallet in offline mode and generate a pair of keys.

cli_wallet -o # important notes are above

Then

suggest_brain_key

You should get a pair of keys like this.

{
  "brain_priv_key": "LOGIUM SPANNEL QUETCH LOOPIST NUTGALL LAMINAR PASMO SPRUE TEINDER ECHO WIVE AGREER LOON DIELIKE HIVE MERROW",
  "wif_priv_key": "5HqrGLNrHVuKUHCW5VopRykStsek9WA4tWWhtcx9zjnSUHg38kX",
  "pub_key": "STM8SqT7hHVyzuxkt6yVdUH6rzvCUDqAmaPLZx3UtSDTxPHRMNLFa"
}

Copy both the private and public keys. We will add the public key to our witness account's signing key. And the private key will be added to the config file only to sign the blocks that we produce.

The config file is located at hive-data/config.ini.
Edit the following parameters in the config file. Add them if they don't exist.

# witness account - with double quotes
witness= "username"
# witness account's signing private key - NO double quotes
private-key= 5HqrGLNrHVuKUHCW5VopRykStsek9WA4tWWhtcx9zjnSUHg38kX

# Plugin(s) to enable, may be specified multiple times
plugin = witness condenser_api network_broadcast_api database_api block_api
# account_by_key is enabled by default - required to use 'get_witness' and 'get_account' in cli_wallet
plugin = account_by_key account_by_key_api
# required for creating and importing Hive 1.24+ State Snapshots
plugin = state_snapshot

shared-file-size = 30G
shared-file-dir = /dev/shm/
# open the ports for cli_wallet connections
webserver-http-endpoint = 127.0.0.1:8091
webserver-ws-endpoint = 127.0.0.1:8090

# Remove the following if exists
#p2p-endpoint = 0.0.0.0:2001

Replace the witness and private_key values with your username and the private key generated by cli_wallet.
Ready to replay the node.

*** Come back here after replaying. The guide is available under this section.

After finishing the replay, you need to broadcast an operation on your witness account to add/edit the signing key on your account and enable production.
We can use cli_wallet to do so but there are open source witness tools that can do the same thing. cli_wallet will connect to the local node that we are running.

cli_wallet
# OR
cli_wallet -s ws://127.0.0.1:8090

Add a password, unlock, and import your active private key.

set_password "mypoassword"
unlock "mypassword"
import_key 5jxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Edit the following operation before broadcasting:

update_witness "username" "https://hive.blog/witness-category/@username/my-witness-thread" "STMxxxxxxx" {"account_creation_fee":"3.000 HIVE","maximum_block_size":65536,"hbd_interest_rate":0} true

I think it is very clear what you need to edit. Your username, a link to post (or something similar), and signing public key (generated by cli_wallet).
Note: If you take too long inside cli_wallet, it might time out and not broadcast the operation.

After broadcasting, you can see the signing key at https://hiveblocks.com/@username under the "Authorities" tab on the left side.

Your witness information will be visible on the witnesses lists only after producing a block.

---

tmux/screen

You will need screen or tmux to keep hived running. I prefer tmux.

sudo apt-get install tmux

A simple cheatsheet for tmux:

tmux # start a new session
tmux attach # open the recently created session
tmux ls # list all the active sessions
tmux attach -t <target> # attach to a certain session

# Commands while attached to a tmux session:
ctrl+b, d # detach from session
ctrl+d # end the session

Replay

First, adjust the size for /dev/shm on your machine:
_{Note: This is where we hold the shared_memory.bin file. It is growing over time so keep an eye on it. /dev/shm is on RAM. You can edit the config file and choose another location for shared_memory on storage but it will greatly increase the time of replay.}

sudo mount -o "remount,size=30G" /dev/shm

Depending on your CPU/RAM/storage speed, this will take a few hours. We open a tmux session by typing tmux and run the following command.

hived -d /root/hive-data --replay-blockchain

You can detach by ctrl+b then d and let it run in the background.
You can tmux attach to attach and see the progress. Remember to not press ctrl+c inside the session, as it will terminate the hived.

When the replay is done, you should see the newly produced blocks in your logs every 3 seconds.

2022-06-14T08:46:38.741642 p2p_plugin.cpp:187            handle_block         ] Got 47 transactions on block 65253208 by deathwing -- Block Time Offset: -258 ms
2022-06-14T08:46:41.789187 p2p_plugin.cpp:187            handle_block         ] Got 64 transactions on block 65253209 by pharesim -- Block Time Offset: -210 ms
2022-06-14T08:46:44.790889 p2p_plugin.cpp:187            handle_block         ] Got 56 transactions on block 65253210 by therealwolf -- Block Time Offset: -209 ms
2022-06-14T08:46:47.749655 p2p_plugin.cpp:187            handle_block         ] Got 58 transactions on block 65253211 by blocktrades -- Block Time Offset: -250 ms
2022-06-14T08:46:50.704510 p2p_plugin.cpp:187            handle_block         ] Got 70 transactions on block 65253212 by stoodkev -- Block Time Offset: -295 ms
2022-06-14T08:46:54.577980 p2p_plugin.cpp:187            handle_block         ] Got 49 transactions on block 65253213 by jesta -- Block Time Offset: 577 ms

---

Start/Stop

After finishing the replay, you can just stop and start the node again.
ctrl+c one time to gracefully stop the node
hived -d /root/hive-data to start the node

Notes

Note #1: If you reboot the system, you have to replay the node again. Because the shared_memory.bin file is located on the ram at /dev/shm and it will be removed on reboot. You can back up that file after gracefully closing the node before rebooting.

Note #2: If you close the hived node forcefully, most likely you will have to replay the node again. You might need to redownload the block_log file too.

Note #3: If your block_log file gets corrupted by forcefully closing the node or by a crash, instead of redownloading you can trim the end of the file by a few MB or GB and fix it using wget -c https://gtg.openhive.network/get/blockchain/block_log. This will only download the remaining end of the file.

Note #4: You need to stop/start the node after editing the config.ini file for changes to take effect.

Note #5: Make sure the time on your machine is in sync with an online source.

Note #6: It is recommended to not share the IP of your witness node.

---

And 3 cute kittens as bonus content.

I read all the comments. Ask your questions or add anything that I missed in the post.