Partner Chains Stack: Cardano Node + PC Node

Warning

This repo is under active development and may be incomplete and/or change without warning

Purpose

The purpose of this repo is to permit the rapid spin-up of any/all of the three Partner Chains node variants using only the provided setup scripts and with minimal user intervention. These node variants are:

• Chain Builder
• Permissioned Candidate
• Registered Block Producer

It includes a unified multi-application Docker configuration to encapsulate all dependencies of the partner chains stack:

• cardano-node
• cardano-db-sync
• postgres
• ogmios
• kupo
• dozzle

Environment Setup

1, The repo should be checked out and all contained submodules initialised as follows:

git clone https://github.com/m2ux/pc-cardano-node && git submodule init

Note

The latest versions of the following dependencies should be installed before attempting any PC node related operations:

• git
• docker
• docker-compose

2, Ensure that the binaries from the Partnerchains Node release package are available at:

• /usr/local/bin/partner-chains-node
• /usr/local/bin/partner-chains-cli
• /usr/local/bin/sidechain-main-cli

Node Types

Any reference henceforth to node-type corresponds to one of the following three verbatim types:

• chain-builder
• permissioned-candidate
• registered-block-producer

These are succinctly referred to in body text as CB, PC and RBP

Node Operations

Start a Cardano Node

A cardano-node may be created/started with:

./start-cardano-node <node-type>

Note

Once the node is up and running, the following services are available @ localhost:port:

• Ogmios dashboard: 1337
• Kupo server: 1442
• DB-Sync PostgreSQL server: 5432
• Dozzle Docker-log-monitor server: 8080
• Cardano Node EKG-metrics server: 12788

The exact port numbers above vary depending on the node type and are pre-configured in the file: .env in each of the respective node-type folders.

Stop a Cardano Node

To stop a running cardano node, the following command may be issued:

./stop-cardano-node <node-type>

Generate PC Node Public Keys

Public keys for any node type may be generated with:

./gen-public-keys <node-type>

Important

Prior to commencing setup of a CB node, the public keys of any/all permissioned validators must be present.

Setup Partnerchains Node

In order to setup a given partnerchains node type, run:

./setup-pc-node <node-type>

Query Node Payment Address UTXOs

To query UTXOs for the payment address after recieving funds from the testnet faucet:

./query-utxos <node-type>

Cluster Operations

Tri-node Setup (1CB + 1PC + 1RBP)

The following sequence of operations will spin-up a cluster containing one of each node type running in a single host environment. The primary use case envisaged for this configuration is PC testing & development.

1. Start each Cardano node:

./start-cardano-node chain-builder && ./start-cardano-node permissioned-candidate && ./start-cardano-node registered-block-producer

2. Check Ogmios health status and confirm that each node is showing a status of connected and syncing with the preview network.
3. Wait for each node to achieve 100% synchronisation before continuing. This may take >= 24 hours.
4. Generate the public keys for the permissioned candidate:

./gen-public-keys permissioned-candidate

5. Run the setup script for the chain-builder node:

./setup-pc-node chain-builder

6. Run the setup script for the permissioned candidate node:

./setup-pc-node permissioned-candidate

7. Fund the RBP address with tADA. The address can be found at: ./registered-block-producer/payment.addr

8. Run the setup script for the registered block producer node:

./setup-pc-node registered-block-producer

Misc. scripts

These scripts are already integrated into the above workflows however they are documented below should you want to use them in a standalone fashion.

To generate payment keys and addresses for the node:

./scripts/gen-payment-kpa.sh

To generate stake keys and addresses for the node:

./scripts/gen-stake-kpa.sh

System Requirements

The system requirements for running the above components on the same machine are:

• Any of the big well known Linux distributions (eg, Debian, Ubuntu, RHEL, CentOS, Arch etc).
• 32 Gigabytes of RAM or more.
• 4 CPU cores or more.
• Ensure that the machine has sufficient IOPS (Input/Output Operations per Second). Ie it should be 60k IOPS or better. Lower IOPS ratings will result in slower sync times and/or falling behind the chain tip.
• 320 Gigabytes or more of disk storage (preferably SSD which are 2-5 times faster than electro-mechanical disks).