This guide provides an overview on how to build a Cardano Ada Pool. Instead of writing the same stuff twice, this guide refers you, when needed, to specific pages on the official Cardano documentation site. As such, this guide aim is to glue all pieces of information together and to provide a context in which to comphrehend the procedure of building a Cardano Ada Pool.

I believe that once it is clear how the Cardano directory structure is build and which support files are needed, the reader will find the installation process much easier to follow.

It is assumed that you are comfortable with the Linux command-line-interface.

In order to run a Cardano node, we need 2 binaries and one single directory structure containing some json data files, which we have to download from the Cardano website (later on the exact location is provided).

On the official Cardano site, the procedure to compile the binaries is explained on one single page.

To compile and install the binaries, you can follow the steps on the following link.

Install the node from source

In the above link, “install the node from source”, you are instructed to put the binaries in;

/home/cardano/.local/bin

In this guide, we put all the remaining files under the following directory;

/home/cardano/cnode

In the above link, you were instructed to extend the PATH.

PATH=$PATH:/home/cardano/.local/bin via source .bashrc

You will be suprised to know how many binaries/executables are needed to run a cardano node.

In order to run a Cardano node, only one binary is needed and a helper binary to create the support files
  1. cabal - Tool to build the cardano-cli and cardano-node binaries.
  2. cardano-cli - Tool to create keys, wallet and to interact with the blockchain.
  3. cardano-node - This is the node software.

Once you have these binaries, all what is left is to use the “cardano-cli” to make the necessary keys and wallet and to query the blockchain.

A thorough explanation on these two Cardano binaries can be found on the official Github link:

IOHK Cardano Node

The “cardano-node” binary depends on the keys and wallet which needs to be generated by the “cardano-cli” binary.

Now, to make things easier, we use scripts instead of manually providing the often lengthy command line options to cardano-cli. These scripts make it easy to use the “cardano-cli” binary without having to remember the correct set and syntax of the command line options.

What is left is to make a directory structure in which we place all the necessary keys, scripts, configurations and the blockchain data. When this directory structure is setup for the first time, the only files necessary are the files in the scripts directory and the json’s file in the “core” and “relay1” subdirectories. All remaining files will be build using the “cntools.sh” script or are created while running the core-node and relay-node.

As mentioned before, contrary to some other guides, we will use a single directory structure for this. This directory structure is first displayed such that you can verify that you have the correct directory structure. Download links to some support files are given so that you can download these files from the right sources. Later on in this document, the remaining support files will be created with the “cntools.sh” script.

ls -latR cnode | grep -Ev "*.*.chunk|*.*.primary|*.*.secondary|*.*.dat"

Only the files denoted as “core” need to be initially present, all other files will be created during the process. You have to make sure that all directories and subdirectories are created.

Remember to only make the necessary directories and to only download the necessary files when provided with the download link.
cnode: --> This is the base directory structure, you need 6 toplevel directories.
total 36
drwxr-xr-x 9 cardano cardano 4096 Aug  8 20:29 ..
drwxrwxr-x 3 cardano cardano 4096 Aug  8 18:28 scripts
drwxrwxr-x 9 cardano cardano 4096 Aug  8 18:07 .
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:34 sockets
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:30 config
drwxrwxr-x 4 cardano cardano 4096 Aug  6 14:35 priv
drwxrwxr-x 4 cardano cardano 4096 Aug  6 04:30 db
drwxrwxr-x 2 cardano cardano 4096 Aug  5 15:51 logs

The cnode helper scripts below can be downloaded using the following link:

CNODE Helper Scripts

cnode/scripts: --> These are the core files/scripts to build the remaining files.
total 1292
drwxrwxr-x 3 cardano cardano    4096 Aug  8 18:28 .
-rwxr-x--- 1 cardano cardano     325 Aug  8 18:28 relay1.sh
-rwxr-x--- 1 cardano cardano     710 Aug  8 18:21 start_all.sh
-rw-r----- 1 cardano cardano     989 Aug  8 18:15 env
-rwxr-x--- 1 cardano cardano     533 Aug  8 18:15 core.sh
drwxrwxr-x 9 cardano cardano    4096 Aug  8 18:07 ..
-rw-r----- 1 cardano cardano    2601 Aug  8 17:43 cntools.config
drwxr-xr-x 2 cardano cardano    4096 Aug  8 17:12 todo
-rwxr-x--- 1 cardano cardano     441 Aug  8 16:50 stop_all.sh
-rwxr-x--- 1 cardano cardano  138779 Aug  6 05:43 cntools.sh
-rw-r----- 1 cardano cardano   66984 Aug  6 05:43 cntools.library
-rwxr-x--- 1 cardano cardano    4059 Aug  6 05:42 cntoolsBlockCollector.sh
-rw-rw-r-- 1 cardano cardano   15188 Aug  6 05:28 cntools-changelog.md

Since the cardano node currently doesn’t support peer to peer detection for automatic peer addition to the topology, some helper scripts are needed for this.

cnode/scripts/todo: --> Workaround for the missing p2p detection.
total 16
drwxrwxr-x 3 cardano cardano 4096 Aug  8 18:28 ..
drwxr-xr-x 2 cardano cardano 4096 Aug  8 17:12 .
-r-xr-xr-x 1 cardano cardano  597 Aug  8 11:09 relay-topology_pull.sh
-r-xr-xr-x 1 cardano cardano  597 Aug  8 11:09 topologyUpdater.sh

The socket files for the core and relay node will be created once the core and relay nodes are running.

cnode/sockets:
total 16
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:42 relay1
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:42 core
drwxrwxr-x 9 cardano cardano 4096 Aug  8 18:07 ..
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:34 .

cnode/sockets/relay1: --> This socket file will be created automatically.
total 8
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:42 .
srwxrwxr-x 1 cardano cardano    0 Aug  8 18:42 relay1.socket
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:34 ..

cnode/sockets/core: --> This socket file will be created automatically.
total 8
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:42 .
srwxrwxr-x 1 cardano cardano    0 Aug  8 18:42 core.socket
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:34 ..

cnode/config:
total 16
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:17 core
drwxrwxr-x 2 cardano cardano 4096 Aug  8 18:13 relay1
drwxrwxr-x 9 cardano cardano 4096 Aug  8 18:07 ..
drwxrwxr-x 4 cardano cardano 4096 Aug  8 17:30 .

The core-node data files below can be downloaded using the folllowing link:

Cardano Mainnet Configurations

cnode/config/core: --> These are the core data files.
total 1056
drwxrwxr-x 2 cardano cardano    4096 Aug  8 18:17 .
drwxrwxr-x 4 cardano cardano    4096 Aug  8 17:30 ..
-rw-rw-r-- 1 cardano cardano     128 Aug  5 15:11 mainnet-topology.json
-rw-rw-r-- 1 cardano cardano    2486 Aug  5 15:09 mainnet-shelley-genesis.json
-rw-rw-r-- 1 cardano cardano 1056360 Aug  5 15:09 mainnet-byron-genesis.json
-rw-rw-r-- 1 cardano cardano    4200 Aug  5 15:09 mainnet-config.json

The relay-node data files below can be downloaded using the same link again:

Cardano Mainnet Configurations

cnode/config/relay1: --> These are the core data files.
total 1056
drwxrwxr-x 2 cardano cardano    4096 Aug  8 18:13 .
drwxrwxr-x 4 cardano cardano    4096 Aug  8 17:30 ..
-rw-rw-r-- 1 cardano cardano     213 Aug  5 15:14 mainnet-topology.json
-rw-rw-r-- 1 cardano cardano    2486 Aug  5 15:09 mainnet-shelley-genesis.json
-rw-rw-r-- 1 cardano cardano 1056360 Aug  5 15:09 mainnet-byron-genesis.json
-rw-rw-r-- 1 cardano cardano    4200 Aug  5 15:09 mainnet-config.json

The remaining files will be created with the “cntools.sh” script (the procedure will be explained later on) or during or after the blockchain sync:

cnode/priv:
total 16
drwxrwxr-x 9 cardano cardano 4096 Aug  8 18:07 ..
drwxrwxr-x 4 cardano cardano 4096 Aug  6 14:35 .
drwxrwxr-x 3 cardano cardano 4096 Aug  6 14:35 pool
drwxrwxr-x 3 cardano cardano 4096 Aug  6 13:41 wallet

cnode/priv/pool:
total 12
drwxrwxr-x 2 cardano cardano 4096 Aug  7 18:39 prime
drwxrwxr-x 3 cardano cardano 4096 Aug  6 14:35 .
drwxrwxr-x 4 cardano cardano 4096 Aug  6 14:35 ..

cnode/priv/pool/prime: --> All files created with the "cntools.sh" script.
total 60
drwxrwxr-x 2 cardano cardano 4096 Aug  7 18:39 .
-rw-rw-r-- 1 cardano cardano  583 Aug  6 17:17 pool.cert
-rw-rw-r-- 1 cardano cardano  207 Aug  6 17:17 pool.config
-rw-rw-r-- 1 cardano cardano  202 Aug  6 15:52 cold.counter
-rw-rw-r-- 1 cardano cardano  364 Aug  6 15:52 op.cert
-rw-rw-r-- 1 cardano cardano    3 Aug  6 15:52 kes.start
-rw-rw-r-- 1 cardano cardano  114 Aug  6 15:50 poolmeta.json
-rw-rw-r-- 1 cardano cardano  114 Aug  6 15:49 poolmeta-20200806154922.json
-rw-rw-r-- 1 cardano cardano  121 Aug  6 14:40 poolmeta-20200806144014.json
-rw-rw-r-- 1 cardano cardano  229 Aug  6 14:35 vrf.skey
-rw-rw-r-- 1 cardano cardano  175 Aug  6 14:35 vrf.vkey
-rw-rw-r-- 1 cardano cardano   57 Aug  6 14:35 pool.id
-rw-rw-r-- 1 cardano cardano 1326 Aug  6 14:35 hot.skey
-rw-rw-r-- 1 cardano cardano  182 Aug  6 14:35 hot.vkey
drwxrwxr-x 3 cardano cardano 4096 Aug  6 14:35 ..

cnode/priv/wallet:
total 12
drwxrwxr-x 2 cardano cardano 4096 Aug  7 18:39 wallet-node
drwxrwxr-x 4 cardano cardano 4096 Aug  6 14:35 ..
drwxrwxr-x 3 cardano cardano 4096 Aug  6 13:41 .

cnode/priv/wallet/wallet-node: --> All files created with the "cntools.sh" script.
total 36
-rw-rw-r-- 1 cardano cardano   59 Aug  8 14:20 reward.addr
-rw-rw-r-- 1 cardano cardano   58 Aug  8 14:20 payment.addr
-rw-rw-r-- 1 cardano cardano  103 Aug  8 14:20 base.addr
drwxrwxr-x 2 cardano cardano 4096 Aug  7 18:39 .
-rw-rw-r-- 1 cardano cardano  242 Aug  6 15:52 delegation.cert
-rw-rw-r-- 1 cardano cardano  184 Aug  6 14:46 stake.cert
-rw-rw-r-- 1 cardano cardano  185 Aug  6 13:41 stake.vkey
-rw-rw-r-- 1 cardano cardano  189 Aug  6 13:41 payment.vkey
drwxrwxr-x 3 cardano cardano 4096 Aug  6 13:41 ..

cnode/db: --> This file will be created automatically during syncing.
total 20
drwxrwxr-x 9 cardano cardano 4096 Aug  8 18:07 ..
drwxrwxr-x 4 cardano cardano 4096 Aug  6 04:30 .
-rw-rw-r-- 1 cardano cardano    4 Aug  6 04:30 shelley_trans_epoch
drwxrwxr-x 5 cardano cardano 4096 Aug  5 19:04 relay1
drwxrwxr-x 5 cardano cardano 4096 Aug  5 15:18 core

cnode/db/relay1: --> These files will be created automatically during syncing.
total 52
drwxrwxr-x 2 cardano cardano  4096 Aug  8 18:43 volatile
drwxrwxr-x 2 cardano cardano  4096 Aug  8 17:23 ledger
drwxrwxr-x 2 cardano cardano 28672 Aug  8 15:44 immutable
drwxrwxr-x 4 cardano cardano  4096 Aug  6 04:30 ..
drwxrwxr-x 5 cardano cardano  4096 Aug  5 19:04 .
-rw-rw-r-- 1 cardano cardano     0 Aug  5 15:18 lock
-rw-rw-r-- 1 cardano cardano     9 Aug  5 15:18 protocolMagicId

cnode/db/relay1/volatile: --> These files will be created automatically during syncing.
total 6364
drwxrwxr-x 2 cardano cardano    4096 Aug  8 18:43 .
drwxrwxr-x 5 cardano cardano    4096 Aug  5 19:04 ..

cnode/db/relay1/ledger: --> These files will be created automatically during syncing.
total 176572
drwxrwxr-x 2 cardano cardano     4096 Aug  8 17:23 .
-rw-rw-r-- 1 cardano cardano 90416630 Aug  8 17:23 108
-rw-rw-r-- 1 cardano cardano 90380923 Aug  8 16:11 107
drwxrwxr-x 5 cardano cardano     4096 Aug  5 19:04 ..

cnode/db/relay1/immutable: --> These files will be created automatically during syncing.
total 4738228
drwxrwxr-x 2 cardano cardano    28672 Aug  8 15:44 .
drwxrwxr-x 5 cardano cardano     4096 Aug  5 19:04 ..

cnode/db/core: --> These files will be created automatically during syncing.
total 52
drwxrwxr-x 2 cardano cardano  4096 Aug  8 18:43 volatile
drwxrwxr-x 2 cardano cardano  4096 Aug  8 17:22 ledger
drwxrwxr-x 2 cardano cardano 28672 Aug  8 15:44 immutable
drwxrwxr-x 4 cardano cardano  4096 Aug  6 04:30 ..
drwxrwxr-x 5 cardano cardano  4096 Aug  5 15:18 .
-rw-rw-r-- 1 cardano cardano     0 Aug  5 15:18 lock
-rw-rw-r-- 1 cardano cardano     9 Aug  5 15:18 protocolMagicId

cnode/db/core/volatile: --> These files will be created automatically during syncing.
total 6364
drwxrwxr-x 2 cardano cardano    4096 Aug  8 18:43 .
drwxrwxr-x 5 cardano cardano    4096 Aug  5 15:18 ..

cnode/db/core/ledger: --> These files will be created automatically during syncing.
total 176572
drwxrwxr-x 2 cardano cardano     4096 Aug  8 17:22 .
-rw-rw-r-- 1 cardano cardano 90416630 Aug  8 17:22 108
-rw-rw-r-- 1 cardano cardano 90380923 Aug  8 16:10 107
drwxrwxr-x 5 cardano cardano     4096 Aug  5 15:18 ..

cnode/db/core/immutable: --> These files will be created automatically during syncing.
total 4738188
drwxrwxr-x 2 cardano cardano    28672 Aug  8 15:44 .
drwxrwxr-x 5 cardano cardano     4096 Aug  5 15:18 ..

cnode/logs: --> This log file will be created automatically during operation.
total 56
-rw-rw-r-- 1 cardano cardano 44862 Aug  8 20:07 cntools-history.log
drwxrwxr-x 9 cardano cardano  4096 Aug  8 18:07 ..
drwxrwxr-x 2 cardano cardano  4096 Aug  5 15:51 .

Using the cntools.sh script

The “cntools.sh” script is pretty self explenatory.

Before using the cntools.sh you need to set the correct paths
  1. cntools.sh - you can use relative or static paths
  2. env - you can use relative or static paths
  3. cntools.config - you can use relative or static paths

Registering a pool basically boils down to the following steps:

  1. First, wait for your nodes to fully sync. <use core.sh, relay1.sh and relay2.sh>
  2. Next, create a wallet on your core-node. <use cntools.sh>
  3. Next, fund your wallet with 1005 ADA’s. <use cntools.sh>
  4. Next, create a Pool name. <use cntools.sh>
  5. Next, Adjust the “core.sh” script to point to the correct keys (example below).
  6. Next, restart the core node (use core.sh)
  7. Lastly, register your pool by following the instructions of the cntools.sh script. <use cntools.sh>

You can never really stop your machine from ever being hacked, but you can mitigate the consequences. You can take all kind of measurements to make your machine pretty secure but there are always 0 days exploits. To mitigate the consequences of your machine ever being hacked, I advise you to remove the private keys from your core-node

Never leave your private keys online on the core-node. Make a backup of your cnode directory and then remove the following files;
cnode/priv/pool/prime:
-rw-rw-r-- 1 cardano cardano  202 Aug  6 15:52 cold.vkey
-rw-rw-r-- 1 cardano cardano  202 Aug  6 15:52 cold.skey


cnode/priv/wallet/wallet-node:
-rw-rw-r-- 1 cardano cardano  185 Aug  6 13:41 stake.skey
-rw-rw-r-- 1 cardano cardano  189 Aug  6 13:41 payment.skey

Only the “core.sh” script needs to be adjusted to point to the correct keys. The core-node is the block producing node. The relay nodes are the workers/minions.

The core node must provide prove of authority for running the pool (again, the relay or minions nodes don’t have to provide this proof). This show of proof has been provided in step 5 above by adjusting the “core.sh” script to point to the correct keys which are now shown;

--config /home/cardano/cnode/config/core/mainnet-config.json \
--shelley-kes-key /home/cardano/cnode/priv/pool/prime/hot.skey \
--shelley-vrf-key /home/cardano/cnode/priv/pool/prime/vrf.skey \
--shelley-operational-certificate /home/cardano/cnode/priv/pool/prime/op.cert

You only have to edit one file to get your pool operational:

  1. mainnet-topology.json - you have 1 block producing node and at least 2 relay nodes.

Now, to start your core node and relay node, you need startup scripts

  1. core.sh - Use a standalone script or the systemd service
  2. relayx.sh - Use a standalone script or the systemd service

Migrate or replicate a Relay-Node

Once you have one relay-node running, migrating or replicating a relay-node to another virtual machine is just a matter of copying files over and adjusting the topology file and the startup script to reflect the new node.

The benefit of this is that you don’t have to compile the same binaries over and over again since you already have them. Another benefit is that you don’t have to begin syncing from scratch again since you have already synced. So, if you need more than 1 relay-node, the fastest way to do it is to finish one relay-mode and replicate it as many times you want.

The procedure to migrate or replicate a relay-node is as follows
  1. First you need to stop the pool.
  2. On the new machine create the cardano user.
  3. Next, copy the binaries to the new machine and copy the “cnode” directory containing only the relay-node data, skip the core-node data.
  4. You will have to change the IP addresses in the topology files on all nodes to reflect your new topology (e.g. one core-node and two relay-nodes).
  5. For the second relay-node, you can rename the “relay1” subdirectories and filenames to “relay2”.
  6. Adjust your $PATH statement just like you did before.
  7. Finally, you can start the pool by first starting relay1, relay2 and finally the core-node.

Add a Secure Wallet

After you have done all pool configuration with your semi-secure-wallet, it is time to change to a secure-wallet. The semi-secure-wallet can be categorized as the operational-wallet. Next, you need a none-operational-wallet, that is, a wallet which has been produced on an air-gapped VM and from which the private key has never left the air-gapped VM.

To add the none-operational-wallet (secure-wallet) to your pool, you need to add a second owner to your pool, essentialy modifying your pool to a multi-owner stake-pool. In this multi-owner stake-pool, the primary address (first owner) is used as the fees payment (operational) wallet and the secondary address (second owner) functions as the secure-wallet. The operational-wallet will contain only a small amount of ADA to cover eventual fees. The secure-wallet is where the actual pledge will be placed. The pledging is done by delegating the pledge amount from the secure-wallet. Since the delegation is from a pool owner’s address, this delegation is treated as a pledge. If you have used the mnemonic method to extract the owner’s wallet from Daedalus, then you can make the delegation right from your Daedalus wallet.

Comments

So what do you think? Did I miss something? Is any part unclear? Leave your comment below.

comments powered by Disqus