*Read this in other languages: 中国, 한국어, 日本, português

Marbles Demo

About Marbles

The underlying network for this application is the Hyperledger Fabric, a Linux Foundation project. You may want to review these instructions to understand a bit about the Hyperledger Fabric.
This demo is to aid a developer learn the basics of chaincode and app development with a Fabric network.
This is a very simple asset transfer demonstration. Multiple users can create and transfer marbles with each other.

Versions

There are multiple versions of marbles. This version is compatible with Hyperledger Fabric v1.1x. You can find the other marble versions by checking out other branches.

Application Background

Hold on to your hats everyone, this application is going to demonstrate transferring marbles between many marble owners leveraging Hyperledger Fabric. We are going to do this in Node.js and a bit of GoLang. The backend of this application will be the GoLang code running in our blockchain network. From here on out the GoLang code will be referred to as 'chaincode' or 'cc'. The chaincode itself will create a marble by storing it to the chaincode state. The chaincode itself can store data as a string in a key/value pair setup. Thus, we will stringify JSON objects to store more complex structures.

Attributes of a marble:

id (unique string, will be used as key)
color (string, css color names)
size (int, size in mm)
owner (string)

We are going to create a UI that can set these values and store them in our blockchain's ledger. The marble is really a key value pair. The key is the marble id, and the value is a JSON string containing the attributes of the marble (listed above). Interacting with the cc is done by using the gRPC protocol to a peer on the network. The details of the gRPC protocol are taken care of by an SDK called Hyperledger Fabric Client SDK. Check the picture below for topology details.

Application Communication Flow

The admin will interact with Marbles, our Node.js application, in their browser.
This client side JS code will open a websocket to the backend Node.js application. The client JS will send messages to the backend when the admin interacts with the site.
Reading or writing the ledger is known as a proposal. This proposal is built by Marbles (via the SDK) and then sent to a blockchain peer.
The peer will communicate to its Marbles chaincode container. The chaincode will run/simulate the transaction. If there are no issues it will endorse the transaction and send it back to our Marbles application.
Marbles (via the SDK) will then send the endorsed proposal to the ordering service. The orderer will package many proposals from the whole network into a block. Then it will broadcast the new block to peers in the network.
Finally the peer will validate the block and write it to its ledger. The transaction has now taken effect and any subsequent reads will reflect this change.

Marbles Setup

Before you tackle the various instructions below decide what type of setup you really want. It is possible to skip the developer setup and get Marbles running with 2-3 brainless clicks. If you want a developer's setup, follow the instructions 0 - 4 below. By the end of it you will be a hyperledger fabric pro, and have the setup to develop an application of your own design. If you want to skip all of that and simply try marbles on a IBP (IBM Blockchain Platform) network then follow the Toolchain setup flow. If you really want to impress your friends, do both.

If you already used the Toolchain setup then skip down to the Use Marbles section. If you are choosing the dev setup, then keep reading. The good news is marbles and the blockchain network can be setup for different configurations depending on your preference. The bad news is this makes the instructions complicated. If you are new to Hyperledger Fabric and want the simplest setup then follow the :lollipop: emoji. Whenever there are options and you must choose your own adventure, I'll drop a :lollipop: emoji on the option that is the simplest. This is the option for you.

0. Setup Local Environment

Follow these environment setup instructions to install Git, Go and Node.js.

When you have finished come back to this tutorial. Start the next section "Download Marbles" below.

1. Download Marbles

We need to download marbles to your local system. Let’s do this with Git by cloning this repository. You will need to do this step even if you plan on hosting marbles in IBM Cloud.

Open a command prompt/terminal and browse to your desired working directory

Run the following command:

git clone https://github.com/IBM-Blockchain/marbles.git --depth 1
cd marbles

Great I'll meet you at step 2.

2. Get a Network

Hello again. Now we need a blockchain network.

Choose 1 option below:

Option 1: Create a network with the IBM Cloud IBM Blockchain Service - instructions
Option 2: :lollipop: Use a locally hosted Hyperledger Fabric Network - instructions

3. Install and Instantiate Chaincode

OK, almost there! Now we need to get our marbles chaincode running. Remember the chaincode is a vital component that ultimately creates our marbles transactions on the ledger. It is GoLang code that needs to be installed on our peer, and then instantiated on a channel. The code is already written for you! We just need to get it running. There are two ways to do this.

Choose the only option that is relevant for your setup:

Option 1: Install and instantiate chaincode with your IBM Blockchain Service - instructions
Option 2: :lollipop: Install and instantiate chaincode with the SDK locally - instructions

4. Host Marbles

Last but not least we need marbles running somewhere.

Choose 1 option below:

Option 1: Host marbles on IBM Cloud - instructions
Option 2: :lollipop: Host marbles locally - instructions

Use Marbles

If you are at this step, you should have your environment setup, blockchain network created, marbles app and chaincode running. Right? If not look up for help (up the page, not literally upwards).
Open up your favorite browser and browse to http://localhost:3001 or your IBM Cloud www route.
- If the site does not load, check your node console logs for the hostname/ip and port marbles is using.
Finally we can test the application. Click the "+" icon on one of your users in the "United Marbles" section
Fill out all the fields, then click the "CREATE" button
After a few seconds your new marble should have appeared.
- If not refresh the page by hitting the refresh button in your browser
Next let’s trade a marble. Drag and drop a marble from one owner to another. Only trade it to owners within "United Marbles" if you have multiple marble companies. It should temporary disappear and then redraw the marble within its new owner. That means it worked!
- If not refresh the page
Now let’s delete a marble by dragging and dropping it into the trash can. It should disappear after a few seconds.
Refresh the page to double check that your actions "stuck".
Use the search box to filter on marble owners or marble company names. This is helpful when there are many companies/owners.
- The pin icon will prevent that user from being filtered out by the search box.
Now let's turn on the special walkthrough. Click the "Settings" button near the top of the page.
- A dialog box will open.
- Click the "Enabled" button to enabled Story Mode
- Click the "x" in the top right to close the menu.
- Now pick another marble and drag it to another user. You should see a breakdown of the transaction process. Hopefully it gives you a better idea of how Fabric works.
- Remember you can disable story mode when it becomes frustratingly repetitive and you are a cold husk of your former self.
Congratulations you have a working marbles application :)!

Blockchain Background

Before we talk about how Marbles works let’s discuss the flow and topology of Hyperledger Fabric. Let's get some definitions out of the way first.

Definitions:

Peer - A peer is a member of the blockchain and is running Hyperledger Fabric. From marble's context, the peers are owned and operated by my marble company.

CA - The CA (Certificate Authority) is responsible for gatekeeping our blockchain network. It will provide transaction certificates for clients such as our marbles node.js application.

Orderer - An orderer or ordering service is a member of the blockchain network whose main responsibility is to package transactions into blocks.

Users - A user is an entity that is authorized to interact with the blockchain. In the Marbles context, this is our admin. The user can query and write to the ledger.

Blocks - Blocks contain transactions and a hash to verify integrity.

Transactions or Proposals - These represent interactions to the blockchain ledger. A read or write request of the ledger is sent as a transaction/proposal.

Ledger - This is the storage for the bl

Marbles

Install / Use

README