Local Multichain (20 pts.)

What you need:

Purpose

Multichain is a very nice, free product that allows you to easily set up blockchains and to customize them. For an excellent explanation of possible business cases for such blockchains, read:

Four genuine blockchain use cases

Choosing a Platform

I recommend using two local Ubuntu virtual machines, or, even better, using two cloud servers. Digital Ocean cloud machines are fast and very cheap, and a minimal Ubuntu server works fine.

Don't waste your time attempting this project on any 32-bit OS, a Mac, any version of Windows, or any version of Kali. It is possible to get the blockchain running on 64-bit Windows, but not this GUI.

The instructions below use two VMware virtual machines.

Overview

The two machines will be the Primary Node and the the Secondary Node for a blockchain.

A good way to do this project is with two students working together. You can also do it with one student and two machines (real or virtual).

Installing the OS

Use Easy Install to make a default Ubuntu 16.04 server. I recommend a username and password of student for this project (obviously that is an insecure choice for production servers).

Installing SSH (Both Machines)

The best way to control a server is via SSH.

In a Terminal window, execute these commands: 

sudo apt update
sudo apt install openssh-server -y
Execute this command to find your Linux server's IP address: 
ip addr show
Find your IP address, as highlighted in the image below.

Connecting Via SSH

Use a Terminal on Mac or Linux, or PuTTY on Windows to connect to your server over SSH, as shown below.

Installing Multichain (Both Machines)

Do this on both machines.

In a Terminal window, execute these commands: 

cd /tmp
wget https://www.multichain.com/download/multichain-latest.tar.gz
tar -xvzf multichain-latest.tar.gz
cd multichain-1.0.5
sudo mv multichaind multichain-cli multichain-util /usr/local/bin

Creating a Blockchain (Primary Node)

Do this on the Primary Node: 
multichain-util create chain1
multichaind chain1 -daemon
The response contains the command to use to join the blockchain, as highlighted in the image below.

Joining a Blockchain (Secondary Node)

On the Secondary Node, execute the command to join the blockchain, appending "-daemon to it, like this: 
multichaind chain1@172.16.1.253:6457 -daemon
The node can't join the blockchain, because it lacks "connect" permission.

The command that must be executed on the Primary Node is shown, as highlighted in the image below.

Granting Permission (Primary Node)

On the Primary Node, execute the command shown on the Secondary Node, as shown below: 
multichain-cli chain1 grant 13r9FcgicW5pCLGBvuw8cZXLBYVXEQ7nbuR4Nj connect
The command succeeds, returning a long Transaction ID number, as shown below.

Joining a Blockchain (Secondary Node)

On the Secondary Node, execute the command to join the blockchain, appending "-daemon to it, like this: 
multichaind chain1@172.16.1.253:6457 -daemon
The node joins the blockchain successfully this time, as shown below.

Using multichain-cli (Either Node)

On either node, execute this command: 
multichain-cli chain1 help
A long list of commands appears, including the "getinfo" command, as shown below.

On either node, execute this command: 

multichain-cli chain1 getinfo
Information about the blockchain appears, as shown below. Notice that the blockchain is very small, containing only 69 blocks. Multichain doesn't mine blocks when there are no new transactions, making it far more efficient for small, closed blockchains than Bitcoin or Ethereum.

On either node, execute this command: 

multichain-cli chain1 help getinfo
The help message explains how the "getinfo" command works, and ends with examples, including one starting with "curl", as highlighted in the image below.

The "curl" commands show how to use the RPC, which is designed for Web-based clients and GUI's.

On either node, execute this command: 

multichain-cli chain1 getchaintips
Find the "status" of your blockchain, redacted in the image below.

Recording Your Success

Use the form below to put your name on the WINNERS PAGE.
Your Name:
Status:

Installing Git and Curl

Execute these commands: 
sudo apt install git curl -y

Installing PHP 7.2

For the GUI, we need PHP 7.2, with the php-curl module. That combination is not possible with the Ubuntu repositories, so we need to add a supplementary repository.

Execute these commands: 

sudo apt update
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php
When you are prompted to, press ENTER to continue.

Execute these commands: 

sudo apt update
sudo apt install php7.2 -y
sudo apt install php7.2-curl php7.2-dev -y

Installing the GUI (Both Nodes)

Execute these commands: 
cd /var/www/html
sudo git clone https://github.com/MultiChain/multichain-web-demo.git
cd multichain-web-demo/
sudo cp config-example.txt config.txt

Finding the RCP Credentials (Both Nodes)

Multichain randomly chooses credentials when you create a blockchain. To see them, execute these commands: 
cat ~/.multichain/chain1/multichain.conf
grep rpc-port ~/.multichain/chain1/params.dat
You see the username, password, and port number, as shown below.

Now you need to enter those credentials into the GUI configufation file.

Execute this command: 

sudo nano config.txt
Enter the port and password into this file, as shown below.

To save the file, press Ctrl+X, Y, Enter.

Execute this command to restart Apache: 

sudo service apache2 restart

Troubleshooting

If you have a Multichain node running and you want to delete it and start over, execute these commands: 
pkill multichain
cd
sudo rm -r .multichain
sudo rm -r /var/www/html/multichain-web-demo

Troubleshooting

If you are developing more PHP pages, it helps to turn on PHP error reporting. This is insecure, and should not be enabled on production servers.

To find the PHP configuration file, execute these commands: 

sudo updatedb
locate php.ini
Find the file in an "apache2" folder, as highlighted in the image below.

Execute this command to edit that file, adjusting the file path as necessary: 

sudo nano /etc/php/7.2/apache2/php.ini
Change display_errors to On, as shown in the image below.

Save the file with Ctrl+X, Y, Enter.

Execute this command to restart Apache: 

sudo service apache2 restart

Using the GUI (Both Nodes)

Execute this command to find your Linux server's IP address: 
ip addr show
Find your IP address, as highlighted in the image below.

In a Web browser, enter your IP address followed by /multichain-web-demo.

The GUI opens, as shown below. Click Default.

You see basic information about your blockchain, as shown below.

Primary Node

Notice on the right side that the Primary Node has many Permissions, including "send", "receive", "create", and "admin".

Troubleshooting

Here are some common problems and solutions.

Multichain Not Running

Problem: "Error: HTTP 0", as shown below.

Solution: on the primary node, execute this command: 

multichaind chain1 -daemon
Solution: on a secondary node, execute this command, adjusting the IP and port number as needed. 
multichaind chain1@172.16.1.253:6457 -daemon

Incorrect RPC Password

Problem: "Error 401 Unauthorized", as shown below.

Solution: execute this command to find the correct password: 

cat ~/.multichain/chain1/multichain.conf
Execute this command to correct it: 
sudo nano /var/www/html/multichain-web-demo/config.txt

Secondary Node

The Secondary Node has only "connect" permission.

Issuing An Asset

In the Primary Node's GUI, in the top menu bar, click "Issue Asset".

Fill in these fields, leaving the other fields at their default values, and replacing "YOURNAME" with your own name, as shown below.

Scroll to the bottom of the page and click the "Issue Asset" button.

A green message says "Asset successfully issued...", as shown below.

There's also a "Warning" message reminding us that this is all beta software, not a professional financial product.

Sending Coins to the Secondary Node

In the Primary Node's GUI, in the top menu bar, click Send.

On the right side, in the "Send Asset" section, click the "To address" field. Only one address is available, as shown below, and it's "local" -- that is, the Primary Node itself.

We can't send assets to the Secondary Node, because it doesn't have receive permission.

Granting Permissions to the Secondary Node

In the Primary Node's GUI, in the top menu bar, click Permissions.

On the right side, in the "Change Permissions" section, the "For address" is empty, as shown below.

In the Secondary Node's GUI, at the top right, in the "My Addresses" section, highlight the address, right-click, and click Copy, as shown below.

In the Primary Node's GUI, in the right side, in the "Change Permissions" section, paste the address into the "For address" field.

Check Send and Receive, as shown below.

Click the "Change Permissions" button. A green message says "Permissions successfully changed...".

Sending Coins to the Secondary Node

In the Primary Node's GUI, in the top menu bar, click Send.

On the right side, in the "Send Asset" section, click the "To address" field and select the second address, the one that is not "local".

Enter a Quantity of 50, as shown below.

Click the "Send Asset" button.

A green message says "Asset successfully sent...".

In the Secondary Node's GUI, in the top menu bar, click Send.

On the left side, the "Available Balances" section now shows 50 "YOURNAME-Coin", as shown below.

Issuing Another Asset

In the Primary Node's GUI, in the top menu bar, click "Issue Asset".

Fill in these fields, leaving the other fields at their default values, and replacing "YOURNAME" with your own name, as shown below.

Scroll to the bottom of the page and click the "Issue Asset" button.

A green message says "Asset successfully issued...".

Preparing an Atomic Exchange Transaction

This is one of the most important features of Multichain: the ability to exchange one asset for another in a single "atomic" transaction, to avoid errors in which payment is sent but goods are not received.

In the Primary Node's GUI, in the top menu bar, click "Create Offer".

On the right side, in the "Create Offer" section, enter these values:

Click the "Create Offer" button.

A green message says "Offer successfully prepared...", as shown below.

On the left side, in the "Available Balances" section, one YOURNAME-GoldCoin is now "locked" -- that is, it cannot be spent for any other purpose, to ensure that it remains available for the atomic exchange.

Under the green message a long line of hexadecimal text appears, as highlighted in the image below. Double-click it and copy it to the Clipboard.

Performing the Exchange

In the Secondary Node's GUI, in the top menu bar, click Accept.

On the right side, in the "Decode Offer" field, paste in the hexadecimal text, as shown below.

Click the "Decode Offer" button.

The "Complete Offer" section appears, as shown below, showing that we can get a YOURNAME-GoldCoin for ten YOURNAME-Coins.

Click the "Complete Offer" button.

The exchange is successful, and you now have a GoldCoin, as shown below.

Viewing the Secondary Node

In the Secondary Node's GUI, in the top menu bar, click Node.

On the right side, in the "Permissions" line, find the word that is redacted in the image below.

Recording Your Success

Use the form below to put your name on the WINNERS PAGE.
Your Name:
Redacted Word:

Sources

Installing MultiChain

Posted 6-4-16 by Sam Bowne
Revised 6-11-17
Updated to 1.0.1 10-16-17
Changed to a Windows project 6-15-18
GUI Troubleshooting images added 7-20-18