Requirements
Hyperledger and Fabric
The fabric is a ledger of digital events, called transactions. A transaction is a request to the blockchain to execute a function on the ledger. The function is implemented by a chaincode. Chaincode is application code (aka a smart contract) stored on the ledger as part of the transaction. Chaincode runs transactions that can modify state. In a permissioned blockchain, entities register to acquire identity credentials.
Create Blockchain Service
This tutorial is a re-cap of this tutorial: learn chaincode.
First create an application on Bluemix:
- Login to Bluemix and go to the Bluemix catalog, browse to ‘Runtimes’ and click the ‘Node.js Runtime’. Populate the application configuration fields, name the application ‘<username>-blockchain1’, and click the ‘CREATE’ button.
- Go to the application ‘OVERVIEW’ page, and click the ‘ADD A SERVICE OR API’ link, in the catalog, browse to the ‘Network’ category or in the left menu under Services select the ‘Network’ filter, and click the ‘Blockchain’ service, accept the default settings and click ‘CREATE’, accept the ‘Restage’ popup window.
- In the left menu of the application detail page, under ‘SERVICES’, click the new ‘Blockchain’ service, and on the service page, click the ‘LAUNCH’ button,
- You should not see the Monitor page of the Blockchain cloud service. The web address or URL should look something like this ‘https://obc-service-broker-prod.mybluemix.net/v2/monitor’, make sure you are on ‘v2’ or version two. The Blockchain service has its own pre-configured Blockchain network, including one Certificate Authority, and two validating peers, each has a ‘Discovery’ and an ‘API’ endpoint.
- Click the ‘APIs’ tab to see the API documentation.
Login with
Unfold the ‘Network’s Enroll IDs’ to see the pre-registered users.
Select and copy an ‘ID’ with its ‘Secret’, e.g. ‘user_type1_1a1ab1234a’ and ‘a123ab123a’. Unfold the ‘Registrar’ endpoint and the ‘POST /registrar’ REST API.
Try out the ‘POST /registrar’ request, by adding the ‘secret’ parameter using the ID and Secret values as follows, and press the ‘Try it out!’ button.
You should get a successful HTTP response code of 200 with the following response.
{
"OK": "Login successful for user 'user_type1_1a1ab1234a'."
}
Or try from the commandline using cUrl:
curl -X POST --data '{"enrollId": "user_type1_1a1ab1234a","enrollSecret": "a123ab123a"}' "https://<organization-id>_vp1-api.blockchain.ibm.com:443/registrar"
You now have successfully registered a user with the Certificate Authority (CA), and the required transaction certificates were received and stored locally.
Fork a Simple Blockchain Code Example
Now, you have registered a user with the Certificate Authority, you can can create and deploy some actual chaincode that users can call to Invoke and Query. Chaincode on a Bluemix Blockchain service can currently only pull the source code from a Github repository. I will fork an existing simple example ‘learn-chaincode’.
First, fork the Learn-Chaincode repository to your own Github account, and then clone the repository to your local machine.
git clone https://github.com/<username>/learn-chaincode.git
Open the local repository in your editor, and open the file ‘~/start/chaincode_start.go’. You see 1 function ‘main’ and 3 Blockchain functions: Init, Invoke and Query.
Custom Blockchain Code
There are three folders in the ‘learn-chaincode’ repository: ‘start’, ‘imgs’ and ‘finished.’ The ‘start’ folder contains an empty skeleton for the 3 Blockchain functions. The ‘finished’ folder contains a ‘hello world’ implementation of the 3 functions, which we will use to deploy the example.
Deploying Custom Blockchain Code
To deploy the example Blockchain code, first make sure a ‘network enroll id’ is logged in, browse to your Blockchain v2 API, browse to the /Registrar endpoint and register a ‘network enroll id’ with the certificate authority.
curl -X POST --data '{"enrollId": "user_type1_1a1ab1234a","enrollSecret": "a123ab123a"}' "https://<organization-id>_vp1-api.blockchain.ibm.com:443/registrar"
From the commandline, browse to the ‘~/finished’ project directory and build the ‘~/finished/chaincode_finished.go’ file.
$ go build ./
Expand the Chaincode, and ‘POST Chaincode’ endpoint, and set the body of the DeploySpec parameter. Note that the ‘path’ property is set to your Github account’s repository that we forked from the ‘learn-chaincode’ repository, and the ‘secureContext’ property is set to the .
{
"jsonrpc": "2.0",
"method": "deploy",
"params": {
"type": 1,
"chaincodeID": {
"path": "https://github.com/remkohdev/learn-chaincode/finished"
},
"ctorMsg": {
"function": "init",
"args": [
"hello_world"
]
},
"secureContext": "user_type1_1a1ab1234a"
},
"id": 1
}or from the cUrl commandline:
curl -X POST -d '{"jsonrpc": "2.0", "method": "deploy", "params": { "type": 1, "chaincodeID": { "path": "https://github.com/remkohdev/learn-chaincode/finished"
}, "ctorMsg": { "function": "init", "args": [ "hello_world" ] }, "secureContext": "user_type1_1a1ab1234a" }, "id": 1 }' "https://<org_id>_vp1-api.blockchain.ibm.com:443/chaincode"
which should on successful execution respond with the following message.
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "1a1ab12345a1a1234567a1ab12abcd1a1234a123ab1234567a1ab12a1a12a123a123a12a1a12a1a1a12a12a1234a1a12a1234a1a12ab1abc123a12345a1a123ab"
},
"id": 1
}Note that the ‘message’ property in the response body is a hashcode you need to include in query or invoke requests. You now have deployed custom Blockchain code.
Query Custom Blockchain Code
Next, expand the Chaincode API and expand the ‘POST /chaincode’ endpoint, in the ‘QuerySpec’ enter the following JSON.
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID": {
"name": "1a1ab12345a1a1234567a1ab12abcd1a1234a123ab1234567a1ab12a1a12a123a123a12a1a12a1a1a12a12a1234a1a12a1234a1a12ab1abc123a12345a1a123ab"
},
"ctorMsg": {
"function": "read",
"args": [
"hello_world"
]
},
"secureContext": "user_type1_1a1ab1234a"
},
"id": 2
}
Or using cUrl use the following command.
curl -X POST -d '{ "jsonrpc": "2.0", "method": "query", "params": { "type": 1, "chaincodeID": { "name": "1a1ab12345a1a1234567a1ab12abcd1a1234a123ab1234567a1ab12a1a12a123a123a12a1a12a1a1a12a12a1234a1a12a1234a1a12ab1abc123a12345a1a123ab" }, "ctorMsg": { "function": "read", "args": [ "hello_world" ] }, "secureContext": "user_type1_1a1ab1234a" }, "id": 2 }' "https://<org_id>_vp1-api.blockchain.ibm.com:443/chaincode"
A successful response looks as follows.
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "hello_world"
},
"id": 2
}Invoke Custom Blockchain Code
Expand the ‘Chaincode’ API and expand the ‘POST /chaincode’ endpoint, in the ‘InvokeSpec’ enter the following JSON.
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID": {
"name": "1a1ab12345a1a1234567a1ab12abcd1a1234a123ab1234567a1ab12a1a12a123a123a12a1a12a1a1a12a12a1234a1a12a1234a1a12ab1abc123a12345a1a123ab"
},
"ctorMsg": {
"function": "write",
"args": [
"hello_world",
"go away"
]
},
"secureContext": "user_type1_1a1ab1234a"
},
"id": 3
}
Or from the commandline in cUrl.
curl -X POST -d '{ "jsonrpc": "2.0", "method": "invoke", "params": { "type": 1, "chaincodeID": { "name": "1a1ab12345a1a1234567a1ab12abcd1a1234a123ab1234567a1ab12a1a12a123a123a12a1a12a1a1a12a12a1234a1a12a1234a1a12ab1abc123a12345a1a123ab" }, "ctorMsg": { "function": "write", "args": [ "hello_world", "go away" ] }, "secureContext": "user_type1_c9f6ec6e1f" }, "id": 3 }' "https://d11e7f38-02a3-4308-b40d-f52248069905_vp1-api.blockchain.ibm.com:443/chaincode"
The response body should look as follows:
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "a1a12b12-1a12-1ab1-ab12-a1234a12ab1a"
},
"id": 3
}Links
To get the Postman collection for Blockchain, click here.