First steps in hyperledger fabric v0.6

To explore the fabric, we started by following a basic tutorial to set-up the fabric, as well as the chaincode. There are different options for setting up the fabric. This can be done by using Vagrant or Docker. Viktor and I first started with the vagrant development environment. We made this choice because it’s simpeler than docker. You don’t have to set up the images yourself, Vagrant will do this for you. So for ease of use, we decided to start with Vagrant. The plusside of starting with Vagrant is that it gives you the time to get to know the fabric and all the files associated with the it. So before you start, make sure the Vagrant and fabric environment is installed. You can follow this link, https://github.com/hyperledger/fabric/blob/master/docs/dev-setup/devenv.md to set it up! Note: we are both currently working in ubuntu 16.04, when using windows you might experience some additional problems.

Setting up the membership (optional, but awesome!)

The first thing we do, is start up the membershipservice. This step is an optional step, the membershipservice is only needed when you want to set-up a permissioned ledger. A permissioned ledger means that the network is private and users have to register to it. Only if a user is registered, he will be allowed to interact on the network. This feature is, in our vision, one of the greatest powers of hyperledger! The set-up of the membership is as follows:

Open a terminal and go to the devnev subdirectory of you fabric workspace environment. Once you are in the devnev subdirectory, use the “vagrant up” command followed by “vagrant ssh”. The vagrant up command is needed to start the virtual machine and it is only required once.

To get a local development environment with enabled security, the first thing you need to do is build and run the Certificate Authority server, aka CA server. This server takes care of the membership service, the set-up of this server is defind in the membersrvc.yaml file. This files containes the different users that are allowed on the network and thus own the right certificates. The different users can be found in the eca.users section of the file. Besides from the users, the membersrvc file also keeps track of the roles of every user. A role can limit what a user can do on the network (deploy, invoke and/or query). To build and run this environment, go to the fabric subdirectory in the same terminal you used to get into Vagrant. Once in the fabric subdirectory simply use the following command line to build and run the membership service.

Running your validating peer

The next step will be to run a validating peer. The validating peer is a computer node on the fabric network. This node, or validating peer, is responsible for running the consensus, validating transaction and mainting the ledger. This node will try to hash transactions and make new blocks.

Next to validating peers, the fabric also has non-validating peers. These peers can be seen as reduced-functionality validating peers, that are used to take the workload of the validating peers. So they basically serve as a proxy which connects the transactors to the neighboring validating peers. A transactor is a client on the network which can issue transactions upon the network.

But first, since we enabled security, the core.yaml file should be edited first. This file can be found under the peer subdirectory ($GOPATH/src/github.com/hyperledger/fabric/peer). Open the core.yaml file and set the security.enabled value to true. Also modify the security.value to true. This will make sure that the privacy and confidentiality of transactions is enabled.

Now open a new terminal, and let the previous terminal open because this one is running the membership service. In the new terminal, again go to the devnev subdirectory so that you can “ssh vagrant” in to Vagrant. Once you are into Vagrant, go the the fabric subdirectory and execute the “make peer” command. Once the peer is made, run the following command:

peer node start –-peer-chaincodedev 

Congratulations, you now got a running validating peer!

Building the chaincode

For now you should have two terminals open, one is running the membershipservice and the other runs the validating peer. Now we can start running the chaincode. Again open a terminal and go the to the devnev subdirectory and run “vagrant ssh” to get into Vagrant.

The next step is to build the chaincode using go. We will use the example code “authorizable counter” that is provided in the Hyperledger fabric source code repository. To build the chaincode, go the subdirectory of the chaincode, in our case the directory where the code of authorizable counter is. Once in the subdirectory simply run the “go build” command to build the chaincode.

Registering the chaincode

We are now ready to start and register the chaincode. Remember that up to now, you should have three terminals running. Now run the following command in the third terminal you’ve opened:

CORE_CHAINCODE_ID_NAME=mycc CORE_PEER_ADDRESS=0.0.0.0:7051 ./authorizable_counter

After running the command, the message that you see above should be displayed: “Received REGISTERED, ready for invocations”. Wauw, you now have your chaincode running, pretty awesome right? Now let’s run the CLI or REST API.

Using the CLI and REST API to register, deploy, query and/or invoke the chaincode

REST API: The Application Programming Interface provides the participants a way to interact with the fabric over a REST API and its variations over Swagger 2.0.The API allows applications to register users, query the blockchain and execute transactions. The default REST interface port is on port 7050. This is configured in the core.yaml file using the rest.address property. With Vagrant the REST port mapping is defined in the Vagrantfile.

CLI: The Command Line Interface implements a subset of the REST API, so that developpers can quickly test their chaincode. The CLI makes it possible for developpers to quickly query or test chaincode transactions.

Before you can deploy, query or invoke, you should register to the network. Remember that we are running the membersrvc service, which means only registered users, found in the membersrvc.yaml file, can acces this network.

Using the CLI: Start by opening a new terminal, go to the devenev subdirectory and use the “vagrant ssh” to go into Vagrant. Once in Vagrant, go to the peer subdirectory and run the following command:

To know which users can be ‘logged’ in, go to the membersrvc file and check the eca.users sections. E.g; you can login lukas, jim, … The password of the users is right behind the username. If you want to login by your own name, just modify the membersrvc.yaml file and add your name with your password to the file.

Using the REST API: If you prefer working with the REST API, you can login via REST by sending a login request to the /registrar endpoint. The request will look as follows:

After registering to the network, you can start by deploying, querying and invoking the chaincode. This can be done using the CLI or REST API. We will discuss how to do it with both options.

First of all, we will have to deploy our chainchode to the validating peer. Normally you should give a pathparameter to locate, build and deploy the chaincode. But since we deploy the chaincode manually we can simply use the name parameter.

CLI: Use the following command to deploy your chaincode via the CLI:

peer chaincode deploy -u jim -n mycc -c ‘{“Args”:[“init”]}’

As argument we give the init, this will make sure that after the deploy, the init function will be called and the counter will be initialised to zero. The “-u jim” is needed because security is enabled, so a username should be given to check if he is part of the network and/or if he has the right to deploy, invoke or query. Invoking or Querying the chaincode is very similar to the Deploy. The right syntax is put right next to in the comments.

REST: The secure context parameter is the equivalent of the “-u jim”.

POST <host:port>/chaincode
{
“jsonrpc”:”2,0”,
“method”:”deploy”,
“params”:{
“type”:1,
“chaincodeID”:{
“name”: “mycc”
},
“ctorMsg”:{
“args”:[“init”]
},
“secureContext”:”jim”
},
“id”:1
}

The method parameter should contain the type of transaction, e.g. deploy, query or invoke. 
ChaincodeID is the parameter that contains the name of the deployed chaincode, mycc in our case. As an alternative the chaincodeID can contain a “path” parameter, containing the path to the chaincode. 
The ctorMsg parameter holds the arguments that you want to pass. E.g. the “init” parameter will activite the init function of the chaincode. 
Last but not least the secureContext is only needed when you are running a membership. This just contains the name of the user.

Congratz! You reached the end of our article, and should now be able to write your own smart contract and deploy it. We wish you the best of luck in the further exploration of the fabric.

Senne Theunis & Viktor Desaeytyd

http://theledger.be

http://craftworkz.co

http://hyperledger.org