How to run a Bitxor node with added security.

Running a secure node

The Running a node guide explains how to easily create a node using Bitxor Bootstrap. In that guide, the setup process is conducted on the same machine that will host the node, meaning that private keys are generated on a machine connected to the Internet. If you need a hardened level of security you can follow this guide instead, at the cost of a more involved setup process.

The summary of it is that the bitxor-bootstrap start command is split into a config phase run offline, which generates a configuration folder, and the rest of the start command is then run on the destination online machine that will host the node. The main account’s private key never leaves the offline machine.

Machine

Function

Configuration

  • Online to install software, then offline.

  • Creates configuration files.

  • Prepares setup transactions.

Node

  • Permanently online.

  • Runs the node.

  • Announces the setup transactions.

A node can also be setup in such a way that all harvesting rewards go to an external account without requiring this account’s private key. This is known as a non-custodial setup and must be configured once the node is up and running, so a pointer to the appropriate guide is given at the end of this page.

Configuration machine

Setup

On the Configuration machine, while still online:

  • Install Bitxor Bootstrap as instructed in the Using Bitxor Bootstrap guide. Make sure you read also the Configuration section of that guide to get acquainted with presets and assemblies.

  • Install Bitxor CLI as instructed in the bitxor-cli guide. You just need to run:

    npm install --global bitxor-cli
    
  • Run Bitxor Bootstrap a first time, so that it can download the required Docker images:

    bitxor-bootstrap config -p mainnet -a <assembly> --noPassword
    rm -rf target
    

    The output of this first run is irrelevant, that’s why --noPassword is used and the target folder is removed.

  • Disconnect the Configuration machine from the Internet since private keys will be generated on this machine from this point.

Create configuration

Profile

Create the main account profile. This is the account that will receive all harvesting fees and whose importance score will be used when harvesting.

The purpose of this guide is making sure that this account’s private key is never used on an online machine.

This step will create a bitxor-cli profile to hold the main account and sign transactions using its private key. The machine is offline now, so you need to provide some network-related data.

Note

The commands below assume you want to create a new main account and use the profile create command. If you already have an account that you would like to use as main use the profile import command instead.

bitxor-cli profile create --profile offline-main --default \
   --url http://localhost:3000 --network MAIN_NET \
   --generation-hash 57F7DA205008026C776CB6AED843393F04CD458E0AA2D9F1D5F31A402072B2D6 \
   --namespace-id bitxor --divisibility 6 \
   --epoch-adjustment 1615853185

When prompted, enter a password to secure your profile and select the PrivateKey import type:

Enter your wallet password: … *********
Select an import type: › PrivateKey

Account
┌───────────────┬──────────────────────────────────────────────────────────────────────┐
│ PropertyValue                                                                │
├───────────────┼──────────────────────────────────────────────────────────────────────┤
│ Address       │ NCCE5O-BMZHWM-IYZKR6-4WZKFD-4P7DTS-IRXJZ2-3LI                        │
├───────────────┼──────────────────────────────────────────────────────────────────────┤
│ Public Key    │ 51C2CB98B61D666A993FA9B25EEBCB48DE5F0B1B7D8B79ECB7AFCB1E5E601108     │
├───────────────┼──────────────────────────────────────────────────────────────────────┤
│ Private Key   │ ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●     │
├───────────────┼──────────────────────────────────────────────────────────────────────┤
│ Password      │ ●●●●●●●●●                                                            │
└───────────────┴──────────────────────────────────────────────────────────────────────┘

SUCCESS Stored offline-main profile

bitxor-cli is now ready to be used later on. All transactions will be signed by your main account so make sure it has some funds to pay for the Fees.

Take note of the main account’s private key and keep it in a safe place.

Preset

Create a custom preset file for Bitxor Bootstrap and name it custom.yml. It must include, at least, these lines:

privateKeySecurityMode: PROMPT_MAIN
nodes:
-
  mainPrivateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

You can read more about these properties in the security mode section in Bitxor Bootstrap’s documentation.

If you have customizations to make, like enabling voting, you can provide them too:

privateKeySecurityMode: PROMPT_MAIN
nodes:
-
  mainPrivateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
  voting: true
  host: my-bitxor-node.com # Could also be an IP address

Configure

Run Bitxor Bootstrap again, this time with all required parameters:

bitxor-bootstrap config -p mainnet -a <assembly> -c custom.yml

You will be asked for the password to use to encrypt the configuration files.

? Enter password to use to encrypt and decrypt custom presets, addresses.yml,
  and preset.yml files. When providing a password, private keys will be
  encrypted. Keep this password in a secure place! ******
info     Password has been provided
info     Generating config from preset testnet
info     Assembly preset dual
info     Generating Main account...
info     Generating Transport account...
info     Generating Remote account...
info     Generating VRF account...
info     User for docker resolved: 1000:1000
info     Running image using Exec: bitxorplatform/bitxor-server:tools-gcc-0.10.1.8 bash createNodeCertificates.sh
info     Certificate for node api-node created
info     Generating api-node server configuration
info     Generating api-broker broker configuration
info     Non-voting node api-node.
info     Configuration generated.

This generates a target directory containing an addresses.yml file and multiple configuration files.

The main account’s private key is not present in any of these files.

It is worth noting that Bitxor Bootstrap enables Remote harvesting by default, meaning that the main private key is never available in a plain text file in the client. Only the remote key is, which acts as a proxy between the node and its main account.

Copy configuration

  • Open custom.yml and remove the line containing mainPrivateKey.

    Now that Bitxor Bootstrap has already used it in the config stage, there is no need for such a sensitive key to be lying around in a plain text file.

  • Copy the whole target directory to a pen drive (or other non-networked support) to be used later.

Prepare transactions

Still in the offline Configuration machine, you are now going to prepare a series of link transactions manually. These transactions will be created by bitxor-cli, signed by your main account, and will be moved to an online machine to be announced later on.

The following commands all use --max-fee 1000000 which means that 1 BXR will be paid for each transaction. Feel free to use a different number after reading the fees documentation.

Copy payloads

Copy payloads.txt to the pen drive where you previously copied the target folder.

Online machine

Move now to the online machine, the one that is permanently connected to the Internet and will host the node. Plug in the pen drive with the node configuration.

Setup

  • Install Bitxor Bootstrap as instructed in the Using Bitxor Bootstrap guide.

  • Install Bitxor CLI as instructed in the bitxor-cli guide. You just need to run:

    npm install --global bitxor-cli
    
  • Create an announcer profile for bitxor-cli. This is only a temporary account used to announce the payloads; it does not require funds:

    Use the --url parameter to specify the NODE_URL to access the network.

    bitxor-cli profile create --profile announcer --default \
       --network MAIN_NET \
       --url <NODE_URL>
    

    When prompted, enter a password to secure your profile, and select the PrivateKey import type:

    Enter your wallet password: ... *********
    Select an import type: » PrivateKey
    ...
    SUCCESS Stored announcer profile
    

Start the node

If all key link transactions were confirmed the node is now configured and you can finally launch it.

Go to the directory containing the target directory copied from the Configuration machine and start the node:

bitxor-bootstrap start

No other parameters are required, the configuration is already present in the target directory and Bitxor Bootstrap will use it.

The node should start and a lot of debug output should appear on the screen.

info     Password has been provided
info     The generated preset target/preset.yml already exist, ignoring configuration. (run -r to reset or --upgrade to upgrade)
...

Your node should now be up and running and its main private key has never left the configuration (offline) machine.

For added security, you can now turn the node’s main account into a Multisig Account. This is useful, for example, for service providers that work in a non-custodial manner. Read about this process in the Non-custodial node setup guide.