Hyperledger Fabric Tutorial - cogeorg/teaching GitHub Wiki

Instead of doing a long introduction into how to setup a network, we will jump right into developing chaincode. If you are interested in configuring your own network, feel free to also walk through this tutorial.

IBM, who is the main contributer to Hyperledger, published an introductory chaincode tutorial, which can be found here. It explains how to install the the VSCode Extension and how to use it to develop and deploy chaincode to a local network, as well as interacting with it.

Since the technology is also still quite new, there are some quirks you need to know about to successfully follow the tutorial. Here are some additional information that are meant to help you.

Prerequisites

The tutorial states that any version of nodegreater than 8.x is supposed to work. I found that this is not the case. The version that is working is v8.12.0. Thus, I recommend switching to this version:

$ nvm install v8.12.0
$ nvm use v8.12.0

Step 0

The tutorial starts by opening VSCode somewhere and then creating the directory and adding it to the workspace when you create the chaincode project. However, this tends to mess up the paths. This, I recommend creating the directory before you open VSCode and then opening it from inside the directory.

$ mkdir -p ~/hyperledgerTut/demoContract
$ cd ~/hyperledgerTut/demoContract
$ code .

Step 2

When you create the smart contract project, note that there may not be an option Create when you create the project but only Browse. Select the directory ~/hyperledgerTut/demoContract that you created in step 0. Even though it is already included in your workspace, select Add to Workspace again when asked.

What has been created?

The smart contract project is a typical node project/package that includes:

.
β”œβ”€β”€ index.js
β”œβ”€β”€ lib
β”‚   └── demo-contract-contract.js
β”œβ”€β”€ package.json
└── test
    └── demo-contract-contract.js
  • package.json includes the setup details for the node package like name, version, dependencies, etc.
  • index.js is the main entry point to this node package. Whenever it is imported into another js file, whatever index.js exports is imported there.
  • lib/demo-contract-contract.js is the dummy contract that is created when a project is initialized.
  • test/demo-contract-contract.js contains the tests for the dummy contract lib/demo-contract-contract.js.

Note: The tutorial is a little outdated such that you contract file is not called my-contract.js but demo-contract-contract.js.

There are also some hidden files created. These are all some kind of config files.

Step 3

Before you copy the code example from the tutorial webpage, delete the code that is in the demo-contract-contract.js file.

Step 5

The tutorial briefly mentions that docker containers are started that together form the test network. These are the following: Orderer, Certificate Authority, CouchDB, Peer, and Logs. Once you have clicked on Start Fabric Runtime you can see those running when you execute the following in your terminal

$ docker ps

which should look something like this:

CONTAINER ID        IMAGE                               COMMAND                  CREATED             STATUS              PORTS                                                                       NAMES
d8b7d1b93a94        hyperledger/fabric-peer:1.4.0       "peer node start"        45 seconds ago      Up 43 seconds       0.0.0.0:17051->7051/tcp, 0.0.0.0:17052->7052/tcp, 0.0.0.0:17053->7053/tcp   fabricvscodelocalfabric_peer0.org1.example.com
cb1bf018d57b        hyperledger/fabric-couchdb:0.4.14   "tini -- /docker-ent…"   49 seconds ago      Up 45 seconds       4369/tcp, 9100/tcp, 0.0.0.0:17055->5984/tcp                                 fabricvscodelocalfabric_couchdb
50b615f18369        hyperledger/fabric-orderer:1.4.0    "orderer"                49 seconds ago      Up 44 seconds       0.0.0.0:17050->7050/tcp                                                     fabricvscodelocalfabric_orderer.example.com
7298972efa3a        hyperledger/fabric-ca:1.4.0         "sh -c 'fabric-ca-se…"   49 seconds ago      Up 48 seconds       0.0.0.0:17054->7054/tcp                                                     fabricvscodelocalfabric_ca.example.com
c2891e3c39f3        gliderlabs/logspout                 "/bin/logspout"          49 seconds ago      Up 47 seconds       0.0.0.0:17056->80/tcp                                                       fabricvscodelocalfabric_logs

What are these docker containers?

  • Peer: receives ordered state updates in the form of blocks from the ordering service and maintains the state and the ledger. Clients "install" their chaincode on one or several peers.

  • Orderer/Ordering Service: is a communication service. It provides a shared communication channel for Peers and Clients. Clients connect to the orderer and communicate their transactions in form of messages to it. The orderer then delivers these messages to all peers. The ordering service can be implemented in different ways: ranging from a centralized service (used e.g., in development and testing, which is what we are doing) to distributed protocols that target different network and node fault models.

  • Certification Authority: provides a number of certificate services to users of a blockchain. More specifically, these services relate to user enrollment, transactions invoked on the blockchain, and TLS-secured connections between users or components of the blockchain.

  • CouchDB: stores the ledger state.

  • Logs: collects all the logs from the other containers.

Step 6

When you call the instantiate function, there are no parameters and no transient data. Hence, hit enter twice.

Step 7

In step 7 you are supposed to clone a GitHub repository. Navigate back to ~/hyperledgerTut and do so:

$ cd ~/hyperledgerTut
$ git clone https://github.com/horeaporutiu/VSCodeTutorialBlockchain

Continue with the rest of the instructions included in this step.

In my opinion, this step occurs a little bit premature. Transacting with the smart contract is currently possible via the VSCode extension, however, querying requires an extra script. This is what this GitHub repository is for.

In order to query the information stored within the contract, the connection details and the identity of the transacting entity have to be known to the query script. Thus, you are required to export those information and import them into the directory containing the query script (i.e. the cloned repository). You will see a new directory called local_fabric that includes a connection.json that stores the connection details as well as a folder called wallet that includes the organization's admin's certificate (here, the admin is called [email protected]) plus its private and public key.

Step 8

Step 8 mentions the Fabric Gateway but gives no explanation what that actually is. The Fabric Gateway manages the network interactions on behalf of an application, allowing it to focus on business logic. Applications connect to a gateway and then all subsequent interactions are managed using that gateway's configuration. It is necessary because a Hyperledger Fabric channel can constantly change. Thus, the Fabric Gateway serves as a layer of abstraction.

Step 12

I could not get the tests to run, so don't worry if they don't run for you.