GBBP Node Setup

The Government Business Blockchain Platform (GBBP) is a blockchain-interconnection fabric that allows blockchain-based services to be provided across numerous blockchain and non-blockchain platforms.  The Hub blockchain is the Proof-of-Authority Ethereum-based Hyperledger Besu from the Hyperledger Foundation.  It features a cross-blockchain utility token that allows value to be transmitted throughout the system to enable the inclusion of paid services.  We are attaching new blockchains and new systems every month.  It also hosts the GBA Reward token and numerous GBA DApps and will eventually serve as the basis for the Distributed Autonomous Organization (DAO) that the GBA is evolving into.

To use the GBBP, you must either be a GBA member or authorized by the GBA.  You must have EarthID (a blockchain-based identity system) installed on your mobile device with your phone number and e-mail verified.  You can then direct any Metamask-capable browser to https://gba-gbbp.azurewebsites.net and, once Metamask is installed (there are instructions on the home page), log in using EarthID.  There is a Token Tutorial that can introduce you to the cross-blockchain functionality as well as a Setup Node option.

The GBBP Hub Besu Blockchain started as an Azure Docker-based minimum blockchain core (boot node, three validator nodes, block explorer and Prometheus and Grafana dashboards) hosted on a single Azure virtual machine (VM) and has now been opened up so that any GBA member can add a node using any cloud provider (AWS, Azure) or local machine/operating system (Apple/MacOs, Linux, Raspberry Pi, Windows).  The Hub core supports the following standard Besu ports and functionality:

Any type of Besu node (expecting IBFT2 consensus) owned by a GBA member may be attached – but the GBA specifically provides instructions, software and support for our own Docker-based configuration that runs on Ubuntu 20.04.  We particularly recommend using a $100 Raspberry Pi as a simple dedicated-machine option.

If a GBA member wishes their node to be a blockchain validator (strongly recommended), it is required that it be connected to the blockchain 95%+ of the time.  In order to maintain security and prevent forks, Besu blockchains do stop producing blocks once a certain percentage of validators are offline.  It is also required that validators vote on adding new validators and removing old ones at least once per week.  Validators not meeting these requirements will be proposed for removal.

If you opt not to use a Raspberry Pi, Windows machines can easily run Ubuntu at the same time as Windows by installing the Windows Subsystem for Linux (WSL2) per Microsoft’s instructions (https://docs.microsoft.com/en-us/windows/wsl/install-win10) — thus, the machine does not have to be solely dedicated to being a validator node but does have to be left turned on and active 24/7.  Apple machines require a dual-boot setup and MacOS can not be run at the same time as Ubuntu so the machine must be dedicated to running Ubuntu if it is to be a validator node.

Node setup and connection to the blockchain is done via the Connect Node option on the GBBP left-menu.  Instructions are provided there and repeated below.

  1. Ensure that you have your machine prepared as described below.
  2. Ensure that your router has port 30303 open to the Internet as described below.
  3. Fill-in the initial form on the Connect Node page.  It will ask for your machine type, whether you are using GBBP software and whether you wish to become a validator.
  4. Download the provided GBBPNode.config file.  If you are using a Raspberry Pi, save it to a thumb drive
  5. Edit the GBBPNode.config file replacing <home network name> and <home network password> with their corresponding values.  These values are used solely locally to allow your Pi to connect to the Internet and they will *never* leave your local machine.
  6. Plug the thumb drive into your Raspberry Pi or copy the GBBPNode.config to the GBBPNode directory of your non-Raspberry machine.
  7. Insert the thumb drive and turn on your Raspberry Pi or execute the command sudo ./init from the GBBPNode directory of your non-Raspberry machine.
  8. You can watch its progress by refreshing the Connect Node page.  Setup steps include:
    Checking for new software and updating
    Starting up Besu (the GBBP Node POA Ethereum software)
    Writing final configuration info to the GBBPNode.config file on the thumb drive
  9. The GBBPNode.config file will now contain the public key for your GBBP Node and the key file will contain your private key.
    *** NEVER let anyone know what your private key is and store it in multiple safe places ***  It cannot be recovered if you lose it.
    Your public key will always be used to identify your Besu node.
  10. If you don’t wish to become a validator, click on the Finished button.  Your node has been added to the network!
  11. If you wish to be a validator, import a New Account into Metamask via the private key option.  This will be the account that you must use for all validator operations.  It is recommended that you not use it for anything else.
  12. Click on the Request to Become a Validator button on Your GBBP Node page.  When Metamask pops up, make sure that you sign with your validator account.  Note that voting is likely to take up to a week.  Your node will sync during that time but will not participate in the consensus process.  Remember that validator nodes must maintain 95%+ up time and validator accounts are expected to vote on new validators and removals at least once a week.  Validators consistently failing to vote or whose nodes have <95% uptime will be submitted for removal.

 

Buying and Assembling a Raspberry Pi

As stated above, GBBP node can be hosted on virtually any machine or platform.  The GBA only recommends the Raspberry Pi due to its low cost.

  1. The recommended version is the CanaKit Raspberry Pi 4 4GB Starter Kit – 4GB RAM which can be purchased from Amazon.com for USD $99.99 (https://www.amazon.com/gp/product/B07V5JTMV9/ref=ppx_yo_dt_b_asin_title_o00_s00).  WARNING: Do NOT get a version without a fan!
  2. The instructions in the included Quick-Start Guide (https://www.canakit.com/pi) are fairly good but the YouTube video at https://www.youtube.com/watch?v=7rcNjgVgc-I is excellent. First time assembly is likely to take half an hour but could be done in ten minutes once you know what you are doing.  If you have a monitor (or HDMI-equipped TV) and a mouse, the provided NOOBS MicroSD card can be used to test that the Raspberry Pi is functioning correctly, this step is not necessary.
  3. Some form of additional data storage is also necessary – either a hard disk or an SD card. The GBA is selling 256GB MicroSD cards pre-loaded with the GBBP Node software at cost which can be ordered here. If you wish to buy your own, the GBA recommends a 256GB card in the $25-35 range (e.g. https://www.amazon.com/Micro-Center-256GB-Adapter-Memory/dp/B07K81C9XN/ref=sr_1_7_sspa).  We *are* aware of off-brand cards with 1TB storage in this price range and lower as well, but the reviews have been terrible.  The GBBP can then be downloaded from https://github.com/GovtBlockchainAssoc/GBBP/RaspberryPi and loaded onto your microSD card by following the instructions in Appendix 2 – Imaging a MicroSD Card in the Raspberry Pi Quick-Start Guide that you used above.

IMPORTANT:

  1. To avoid data corruption, always shut down properly before turning off the power.  If you have a monitor (or HDMI-equipped TV) and a mouse, you can either select Menu/Shutdown from the GUI or enter sudo shutdown –h now from the terminal.  You can also shut the Raspberry Pi down via the My Node page on the GBBP.
  2. Sometimes the Raspberry Pi loses connectivity to the wireless router and internet.  If the disconnection lasts long enough, the Raspberry Pi will reboot in an attempt to restore the connection.  If a couple of reboots don’t solve the problem, the Raspberry Pi will shut down.  This should only occur if you lose your connection with your ISP.  The My Node page on the GBBP will tell you if your node has been disconnected long enough for this to happen so that you can turn it off safely.

Setting Up Port Forwarding

Besu nodes use port 30303 to communicate.  It is likely that this port is not open between your node and the Internet.  If your node is behind a business firewall, you will have to modify its configuration so that the port is open.  If you have your node at home, you will have to configure the router that connects you to the Internet.  Normally, this can be done quite easily from the app provided by your Internet provider.  Googling the phrase port forwarding <your internet provider> (e.g. “port forwarding xfinity”) should lead you to instructions telling you how to do so (e.g. https://www.xfinity.com/support/articles/xfi-port-forwarding).

Installing Docker, Docker-Compose and the GBA Software on Windows

  1. You are going to want/need a good text editor. Download and install Visual Studio Code from https://code.visualstudio.com/docs/?dv=win .
  2. Add the Remote-WSL extension so that you can edit in WSL and add the Docker extension to facilitate creating, managing and debugging Docker applications.
  3. From Windows, download the Docker Desktop Installer from https://hub.docker.com/editions/community/docker-ce-desktop-windows/
  4. Run the installer you just downloaded
  5. Start Docker Desktop
  6. Switch to WSL2 and add permission to run the Docker daemon

sudo chmod 666 /var/run/docker.sock

  1. Use the command code to open Visual Studio Code in WSL2
  2. Use Visual Studio Code to open the file ~/.docker/config.json and add an underscore to line 2 to change {“credsStore”:”desktop.exe”} to {“_credsStore”:”desktop.exe”}
  3. Test the installation

docker run hello-world

  1. Download the GBA software from https://github.com/GovtBlockchainAssoc/GBBP/Windows into a new GBBPNode directory

 

Installing the GBA Software on Linux Machines

Download the GBA software from https://github.com/GovtBlockchainAssoc/GBBP/Linux into a new GBBPNode directory

 

Testing the Installation (All Machines)

The My Node page on the GBBP will tell you your machine’s status and provide a link to your Grafana and Prometheus dashboards.