Quick Start Guide

Table of Contents

1. Building and Running
2. Interacting with the Blockchain

Building and Running

The blockchain can be run in two environments. Docker is the recommended environment due to allowing multiple peer to peer nodes to be run on a single machine.

1. A single node can be run on a machine with Python 3.7 installed.
2. Multiple nodes can be run a single machine with Docker installed.

Single Machine

A single node can be on a machine with Python 3.7 installed. It may work with older versions of Python 3; however, it is not guaranteed.

All commands should be run from the root directory once the project has been cloned or downloaded.

1. Dependencies

The dependencies can be installed using pip. If you have multiple Python versions installed installed on the version, you may need to use pip3 instead.

pip3 install -r requirements.txt

2. Running

To run the project once dependencies have been installed you can use either python or python3 depending on if you have multiple Python versions installed.

python3 __main__.py

Docker

Docker allows multiple blockchain nodes to be run and communicate with each other using a virtual network on a single machine.

1. Installing Docker

Docker supports Windows, Linux, and MacOS. A guide to installing Docker can be found here.

2. Building

The Docker image can be built using the following Docker command from the project root directory. If you do not want to build the Docker image, this step can be skipped by using the allankerr/blobchain:v1 image publicly available on Docker Hub.

docker build -t blobchain:v1 ./

3. Running

Once the Docker image has been built, Docker can also be used to run the project. This can accomplished using the following command where the replicas can be changed to fit the desired number of peers in the network.

If you manually built the image, use the following command:

docker service create --replicas 3 --name blobchain -p 9998:9998/tcp -p 9999:9999/tcp -p 10000:10000/udp -p 10000:10000/tcp  blobchain:v1

If you want to use the pre-built publicly available image on Docker Hub, use the following command:

docker service create --replicas 3 --name blobchain -p 9998:9998/tcp -p 9999:9999/tcp -p 10000:10000/udp -p 10000:10000/tcp  allankerr/blobchain:v1

4. Scaling

Once the service has been created, the number of peers in the network can be scaled up and down using the following command with the desired number of replicas:

docker service scale blobchain=5

5. Logging

To view logs from the peers in the network, the following command can be used:

docker service logs -f blobchain

6. Stopping

To stop running the nodes on the machine, the following command can be used:

docker service rm blobchain

Interacting with the Blockchain

Interacting with the nodes can done using netcat. If the blockchain is being run on multiple nodes using Docker then all input will routed to the different nodes in the network using a round robin approach.

Data Input

ASCII data can be submitted to the blockchain using TCP on port 9999 using new line characters for framing. The TCP connection will be closed upon success.

Example

netcat localhost 9999 <<< "My ASCII message that I want to be stored in the blockchain"

Data Output

The blockchain can be queried using TCP on port 9998. This can be used to get the data contained in a block in the chain by transmitting the index of the block in the blockchain as an ASCII message using new line characters for framing.

Example

netcat localhost 9998 <<< "0"
3797292862 : {}

netcat localhost 9998 <<< "3"
3797292862 : {
	timestamp: 1522351989.6484513 blob: My ASCII message that I want to be stored in the blockchain
}

netcat localhost 9998 <<< "4"
Index out of bounds.