Learn Chaincode Tutorial Using IBM Bluemix Part 1
Recently we discussed IBM Bluemix & its presence in Blockchain applications, especially in private blockchain projects. Bluemix is a new cloud solution service offered by IBM. Bluemix allows organizations as well as developers to easily and rapidly create, deploy, and manage applications on Cloud. This cloud offering utilizes the implementation of IBM’s Open Cloud Architecture relying on Cloud Foundry which is basically an open-source Platform as a Service (PaaS). The best part of Bluemix is it offers entries-level services which can be integrated effortlessly with the Cloud applications without requiring installing or configuring them. In this article, we are going to discuss chain code & how to implement it using several steps.
What is Chaincode in Blockchain?
Chaincode is a program that is written in Go. It eventually can be written in other programming languages like Java which provides a prescribed interface. Chaincode can be run in a secured Docker container which should ideally be isolated from any endorsing peer process. The very purpose of building Chaincode is to initialize and manage the ledger state through transactions submitted by applicants.
How to set up the development environment for chain code:
The developing process of chain code requires some dependencies and recommended tools. They are as follows.
1. Git is the fast, efficient, and powerful version control tool for developing chaincode and other software development. With Git for Windows comes the Git bash which is the recommended command line terminal. For downloading Git, you need to go to these links Git download page , Pro Git Book and Git Desktop (an alternative to the Git CLI). You can verify whether the Git installation is successful or not with code
$ git version
git version 2.9.0.windows.1
After completing the Git installation, you have to create an account on GitHub. Bleumix on IBM Blockchain service needs chaincode to be in a GitHub repository for deploying via the REST API.
Go is the just a supported language for designing or writing chaincode on Bluemix. Installation of Go comprises a number of useful CLI tools for writing the chaincode. For instance, with the help of go build command, it is possible to compile the chaincode before any attempt of deploying it to a network. You need to install Go v1.6 to develop Hyperledger fabric v0.6. The links are Go 1.6 install, Go installation instruction and Go documentation and tutorials. You can verify the successful installation of Go with the command
$ go version
go version go1.6.3 windows/amd64
$ echo $GOPATH
C:gopath
The GOPATH environment variable doesn’t essentially match the prior example but you still need to use a valid directory on the filesystem.
Hyperledger Fabric
Blockchain on Bluemix can support two versions of hyperledger Fabric and these versions are v0.5 and v0.6. Here it is described how the chaincode version should always align with the hyperledger version on your Bluemix network.
To decide which version of hyperledger Fabric is suitable for your Bluemix instance, you have to click the Service Status tab placed on the dashboard Monitor. Then scroll down to the Release Note section. A panel will be displayed mentioning the version you are currently using along with the Hyperledger Commit Level which is running.
The chaincode version has to align with the Hyperledger Fabric version which will deploy the chaincode.
You need to clone the Hyperledger Fabric version 0.6 preview codebase. The fabric codebase should be stored in $GOPATH/hyperledger/fabric path like v0.5 Hyperledger Fabric and v0.6 Hyperledger Fabric. For installing Hyperledger Fabric v0.5 codebase, you need to follow this git clone command # Create the parent directories on your GOPATH mkdir -p $GOPATH/src/github.com/hyperledger cd $GOPATH/src/github.com/hyperledger # Copy the appropriate release codebase into $GOPATH/src/github.com/hyperledger/fabric # Note that the v0.5 release is a branch of the repository. It is defined below after the -b argument git clone -b v0.5-developer-preview https://github.com/hyperledger-archives/fabric.git
To install the Hyperledger Fabric v0.6 codebase, you have to use the following command # The v0.6 release exists as a branch inside the Gerrit fabric repository
git clone -b v0.6
If there is any problem in proper installation in your GOPATH, building your chaincode can cause error quite similar to the following. $ go build . chaincode_example02.go:27:2: cannot find package "github.com/hyperledger/fabric/core/chaincode/shim" in any of: C:Gosrcgithub.comhyperledgerfabriccorechaincodeshim (from $GOROOT) C:gopathsrcgithub.comhyperledgerfabriccorechaincodeshim (from $GOPATH)
Steps to set up the development pipeline
Here are the simple and useful steps to set up the pipeline which is absolutely necessary for building, writing, and testing the chaincode. After writing the chaincode, you need to verify that it complies and then you have to upload this to GitHub. After this, it is required to deploy and test the chaincode on your Bluemix network with the help of fabric REST API.
- Split the right version of the learn chaincode repository for the network version to you’re the GitHub account. Fork v1.0 for a v0.5 fabric network or fork v2.0 for a v0.6 fabric network. Here, you can use the Fork button present on the top right of the repository page.
- Clone the fork to your $GOPATH by using the following command
cd $GOPATH mkdir -p src/github.com/<YOUR_GITHUB_ID_HERE>/ cd src/github.com/<YOUR_GITHUB_ID_HERE>/ git clone -b v1.0 https://github.com/ OR git clone -b v2.0 https://github.com/
Now you have a copy of the fork on your local machine. You can now write chaincode by altering or adding local files and pushing them into your fork on GitHub. After this, it is possible to deploy your chaincode to your blockchain network by using REST API on a network peer.
- There are two versions of chaincode. Start is the selection chaincode that allows you to start from and Finished is the completed chaincode that is ready to build. You need to ensure that Start first builds in your local environment.
cd $GOPATH/src/github.com/<YOUR_GITHUB_ID_HERE>/learn-chaincode/start go build ./
The start version of the learn-chaincode should always compile with no errors or messages.
- Now, you need to write the changes to your local chaincodes and then to push the updated files to your GitHub fork.
cd $GOPATH/src/github.com/<YOUR_GITHUB_ID_HERE>/learn-chaincode/
# See what files have changed locally. You should see chaincode_start.go
git status
# Stage all changes in the local repository for commit
git add --all
# Commit all staged changes. Insert a short description after the -m argument
git commit -m "Compiled my code"
# Push local commits back to https://github.com/
git push
Dependencies
After developing the pipeline, the import statement lists the dependencies for building the chaincode. They are like –
fmt- contains Printlnfor debugging/logging. Errors- standard Go error format com/hyperledger/fabric/core/chaincode/shim- this code interfaces the Golang code with a network peer Init()
The Init function is called at the time of you first deploy the chaincode. As the name indicates, by using this function you can initialize the chaincode. In the chaincode_start.go file, change the Init function in order to store the first args element to the key “hello_BlogSaays-ChainCodeDemo”.
func (t *SimpleChaincode) Init(stub shim.ChaincodeStubInterface, function string, args []string) ([]byte, error) {
if len(args) != 1 {
return nil, errors.New("Incorrect number of arguments. Expecting 1")
}
err := stub.PutState("hello_BlogSaays_ChainCodeDemo", []byte(args[0]))
if err != nil {
return nil, err
}
return nil, nil
}
It can be done by using the function stub.PutState. This function is useful in interpreting the first argument sent in the deployment request. Without any error, this function exits cleanly without returning any messages.
Invoke()
The Invoke function allows you to call chaincode functions to perform “real work” on the blockchain network. Invoke functions get grouped into several blocks to write the ledger. The structure of Invoke is pretty simple. It first receives a function and array of arguments. Depending on the functions passed in, Invoke can either call a helper function or return with an error. In the chaincode_start.go file, you have to change the Invoke function to call a generic write function.
func (t *SimpleChaincode) Invoke(stub shim.ChaincodeStubInterface, function string, args []string) ([]byte, error) {
fmt.Println("invoke is running " + function)
// Handle different functions
if function == "init" {
return t.Init(stub, "init", args)
} else if function == "write" {
return t.write(stub, args)
}
fmt.Println("invoke did not find func: " + function)
return nil, errors.New("Received unknown function invocation")
}
When the code looks for write, add the write function to the chaincode_start.go file.
func (t *SimpleChaincode) write(stub shim.ChaincodeStubInterface, args []string) ([]byte, error) {
var name, value string
var err error
fmt.Println("running write()")
if len(args) != 2 {
return nil, errors.New("Incorrect number of arguments. Expecting 2. name of the variable and value to set")
}
name = args[0] //rename for fun
value = args[1]
err = stub.PutState(name, []byte(value)) //write the variable into the chaincode state
if err != nil {
return nil, err
}
return nil, nil
}
This write function should look similar to the previous Init change.
Query()
The Quaery function is known for querying your chaincode state. It doesn’t add any block to the chain ledger. This can only read the value of the chaincode state’s key/value pairs. You need to change the Query function in your chaincode_start.go file to call a generic read function.
func (t *SimpleChaincode) Query(stub shim.ChaincodeStubInterface, function string, args []string) ([]byte, error) {
fmt.Println("query is running " + function)
// Handle different functions
if function == "read" { //read a variable
return t.read(stub, args)
}
fmt.Println("query did not find func: " + function)
return nil, errors.New("Received unknown function query")
}
Now you have to add the “read” function to your chaincode_start.go file.
func (t *SimpleChaincode) read(stub shim.ChaincodeStubInterface, args []string) ([]byte, error) {
var name, jsonResp string
var err error
if len(args) != 1 {
return nil, errors.New("Incorrect number of arguments. Expecting name of the var to query")
}
name = args[0]
valAsbytes, err := stub.GetState(name)
if err != nil {
jsonResp = "{"Error":"Failed to get state for " + name + ""}"
return nil, errors.New(jsonResp)
}
return valAsbytes, nil
}
This read function utilizes GetState which is a complement to PutState.
Main()
The Main function is performed when every peer deploys its instance of the chaincode. This starts the chaincode and also registers it with the peer. Ther is no need to update both chaincode_start.go and chaincode_finished.go. include a main function at top of each file.
func main() {
err := shim.Start(new(SimpleChaincode))
if err != nil {
fmt.Printf("Error starting Simple BlogSaays chaincode Demo: %s", err)
}
}
Interacting with the chaincode
Using the REST interface is the fastest way to test your chiancode. There is a Swagger UI on your Bluemix dashboard monitor. The Swagger UI allows you to explore deploying chaincode without writing any additional code.
To use Swagger API, you should complete the following steps.
- First, you have to log in to Bluemix and confirm that you are on the Dashboard
- Check that you are in a similar Bluemix “space” and it should contain your IBM Blockchain service. You will find the space navigation on the left.
- The services panel is near the bottom and clicks on your IBM Blockchain service.
- After clicking on the LAUNCH button on the right; you will get a “Welcome to the IBM Blockchain”.
- You can find two monitor pages. These are Network Tab and APIs Tab. The first one contains Peer Logs and ChainCode Logs. For secure enrolment click + Network’s Enroll IDs to expand the list named enrollID values and their secrets. Then copy the bunch of credentials to a text file for future reference. Now expand the register API section. Again expand the post/registrar section. Finally, fill the value field with JSON specified enrillID and ‘enrolSecret’ from your credentials. With this enrollID, you can perform deploying, invoking, and querying the chaincode.
Steps for deploying chaincode
If you are deploying the chaincode via the REST interface, your chaincode must keep safe in a public GuGub repository. During sending a deploy request to the peer, you have to specify the URL for the chaincode repository and the parameters to start the chaincode.
Before deploying the chaincode, verify that it builds locally by opening a command prompt and then browse to the directory containing go. Now enter the codego build
"./ <em><strong> </strong></em>
- Expand Chaincode API section and then expand the post/chaincode
- Set the DeploySpec text field like the example code below. Mention your chaincode repository path and the erollID that you are got from the previous /registrar The “path” should be like "https://github.com/johndoe/learn-chaincode/finished".
{
"jsonrpc": "2.0",
"method": "deploy",
"params": {
"type": 1,
"chaincodeID": {
"path": "https://github.com/ibm-blockchain/learn-chaincode/finished"
},
"ctorMsg": {
"function": "init",
"args": [
"hi welcome to BlogSaays Chaincode Demo"
]
},
"secureContext": "user_type1_xxxxxxxxx"
},
"id": 1
}
<br>
After completing this step you are good to fire some queries according to your logic and arguments of code. We successfully wrote chaincode which is ready to get invoke from the IBM Bluemix console.
In the next article, we will cover, 'Query' your chaincode and 'Invoke' your chain code using the Car Lease Demo example in IBM Bluemix.
