Kadena Public Blockchain

Kadena is a fast, secure, and scalable blockchain using the Chainweb consensus protocol. Chainweb is a braided, parallelized Proof Of Work consensus mechanism that improves throughput and scalability in executing transactions on the blockchain while maintaining the security and integrity found in Bitcoin.

Read our whitepapers:

• Chainweb: A Proof-of-Work Parallel-Chain Architecture for Massive Throughput
• Agent-based Simulations of Blockchain Protocols illustrated via Kadena's Chainweb

For additional information, press, and development inquires, please refer to the Kadena website

Table of Contents

• Kadena Docs Site
• Installing Chainweb
• Bootstrap Nodes
• Configuring, running, and monitoring the health of a Chainweb Node
• Mining for a Chainweb Network
• Chainweb Design
  • Component Structure Details
  • Architecture Overview

Docs

The Kadena Docs site, which can be found here serves as a source of information about Kadena. You can find information about how to interact with the public chain, including how to get keys, view network activity, explore blocks, etc. here.

If you have additions or comments, please submit a pull request or raise an issue - the GitHub project can be found here

Installing Chainweb

Installing dependencies

Apt-based Linux distributions

If you are on Ubuntu, Debian, CentOS or any other Apt-based distribution, you will need to install rocksdb with the following command:

sudo apt-get update

sudo apt-get install -y librocksdb-dev zlib1g-dev libtinfo-dev libsqlite3-dev libz3-dev

If this is not available, then please view the Rocksdb site for alternative modes of installation.

Other Linux distributions

For all other distributions not using Apt (RHEL, Gentoo, Arch, etc), please consult your distro's repositories for librocksdb5.8, tinfo, zlib and install with its preferred package manager, or follow the alternative modes of installation described in Rocksdb.

Mac OSX

Using the brew package manager, issue the following commands to install Chainweb's dependencies

brew update
brew install sqlite
brew install rocksdb

Installing Chainweb-node

Chainweb-node binaries for ubuntu-16.04, ubuntu-18.04, and MacOSX can be found here.

Download the archive for your system and extract the binaries and place them into a directory from where they can be executed.

At this point, you are ready to run a Chainweb node

Docker

A docker image is available at from here and can be used with the following commands:

# Initialize the database (optional, but avoids several hours of initial db synchronization)
docker run -ti --rm -v chainweb-db:/root/.local/share/chainweb-node/mainnet01/0/ kadena/chainweb-node /chainweb/initialize-db.sh

# Run a chainweb-node in Kadena's mainnet
docker run -d -p 443:443 -v chainweb-db:target=/root/.local/share/chainweb-node/mainnet01/0/ kadena/chainweb-node

Further details can be found in the README of the docker repository.

Building from Source

IMPORTANT NODE: We recommend the use of officially released chainweb-node binaries, which can be found in the release section of this repository. If you decide to build your own binaries, please make sure to only use officially released and tagged versions of the code. Those versions are extensively tested to ensure that they are compatible with all other nodes in the chainweb network. It is generally not safe to run arbitrary builds of the master branch in the Kadena mainnet.

Chainweb is a Haskell project. After cloning the code with git from this GitHub repository the chainweb-node application can be built in several ways.

Building with Nix

The fastest way to build and run chainweb is to use the Nix package manager which has binary caching capabilities that allow you to download pre-built binaries for everything needed by Chainweb. For detailed instructions see our wiki.

When the build is finished, you can run chainweb with the following command:

./result/ghc/chainweb/bin/chainweb-node

Building with Stack

In order to build with stack you need stack >= 1.9, which can be obtain via

• Mac (Homebrew): brew install haskell-stack
• General Linux / Mac

(You may also need to install zlib, openssl, and sqlite.)

Stack is a Haskell build tool that manages compiler and dependency versions for you. It's easy to install and use.

To build a chainweb-node binary:

stack build

This will compile a runnable version of chainweb-node, which you can run via:

stack exec -- chainweb-node

Alternatively, stack install will install the binary to ~/.local/bin/, which you may need to add to your path. Then, you can call chainweb-node as-is.

Building with Cabal

In order to build with cabal you have to install ghc >= 8.4 (Haskell compiler) and cabal >= 2.4 (Haskell build-tool)

• Linux / Mac

(You may also need to install zlib, openssl, and sqlite.)

Cabal is the original build tool for Haskell. You will need a version of GHC installed on your machine to use it.

To build a chainweb-node binary:

# Only necessary if you haven't done this recently.
cabal v2-update

# Build the project.
cabal v2-build

To install a runnable binary to ~/.cabal/bin/:

cabal v2-install

Bootstrap Nodes

Testnet Nodes

• us1.testnet.chainweb.com
• us2.testnet.chainweb.com
• eu1.testnet.chainweb.com
• eu2.testnet.chainweb.com
• ap1.testnet.chainweb.com
• ap2.testnet.chainweb.com

Mainnet Nodes

All bootstrap nodes are running on port 443.

• us-e1.chainweb.com
• us-e2.chainweb.com
• us-e3.chainweb.com
• us-w1.chainweb.com
• us-w2.chainweb.com
• us-w3.chainweb.com
• jp1.chainweb.com
• jp2.chainweb.com
• jp3.chainweb.com
• fr1.chainweb.com
• fr2.chainweb.com
• fr3.chainweb.com

Configuring, running, and monitoring the health of a Chainweb Node

This section assumes you've installed the chainweb-node binary somewhere sensible, or otherwise have a simple way to refer to it. For running chainweb-node via docker, please see the instruction above in this document or visit our docker repository.

To configure your node, please use our minimal node configuration. You need to update only one section, hostaddress:

hostaddress:
  hostname: your-public-ip-or-domain
  port: 443

Note: You will have to perform Port Forwarding if your machine is behind a router.

Then, to run your node:

chainweb-node --config-file=minimal-config.yaml

Monitoring the health of a Chainweb Node

The following outlines how you can check that your chainweb-node is healthy

chainweb-node should be running from the public IP address and a port that is open to the other chainweb nodes.

If you're behind a NAT, it is VERY IMPORTANT that your network allows external nodes to connect to the node you are running. If you provide us with your ip address and port number in our Discord mining channel, we can verify whether your node is reachable to the rest of the network.

When running the chainweb-node binary, you can indicate your hostname and port number directly in the config-file, or you can set it via command line flags like such:

$ chainweb-node --config-file <path-to-config-file> --hostname <public-ip> --port <port> --log-level <desired-log-level>

Once you're node is running, go through the following checks to verify that you have a healthy node:

• run the command in your terminal:

$ curl -sk "https://<public-ip>:<port>/chainweb/0.0/mainnet01/cut"

• navigate to this website on your browser: https://yourPublicIp:port/chainweb/0.0/mainnet01/cut
• check logs for whether services are started
• check if the node is receiving cuts
• look for errors in the logs
• look for warnings in the logs

Usually, when a node is receiving and publishing cuts (i.e. block heights at every chain), it's working correctly.

The /cut endpoint will return the latest cut that your node has. It's possible that your node is falling behind, so make sure to compare its cut height with the cut heights of the bootstrap nodes. It's also possible that you are mining to a node that is catching up to the rest of the network. Before you start mining to a node, you SHOULD verify that this node has the most up-to-date cut.

You can get the cut height of any node by running the following:

$ curl -sk https://<bootstrap-node-url>/chainweb/0.0/mainnet01/cut | jq '.height'

Miscellaneous

To find your public ip:

$ curl 'https://api.ipify.org?format=text'

Mine for a Chainweb Network

Detailed mining instructions can be found in our Mining Guide.

Chainweb Design

Component Structure

The chainweb package contains the following buildable components:

• chainweb library: It provides the implementation for the different components of a chainweb-node.

• chainweb-node: An application that runs a Chainweb node. It maintains copies of a number of chains from a given Chainweb instance. It provides interfaces (command-line and RPC) for directly interacting with the Chainweb or for implementing applications such as miners and transaction management tools.

• chainweb-tests: A test suite for the Chainweb library and chainweb-node.

• cwtool: A collection of tools that are helpful for maintaining, testing, and debugging chainweb.

• bench: a collection of benchmarks

Architecture Overview