Creating Your First Application

Catalyst Blockchain Platform consists of two components: smart contracts (chaincodes) deployed in the Hyperledger Fabric Service and the custom program portion, which will communicate with the Hyperledger Fabric Service.

Writing Simple “Hello World” Chaincode

Catalyst Blockchain Platform runs chaincodes as external services, meaning that this must be considered during deployment.

A detailed guide on how to write external chaincode can be found in the official Hyperledger Fabric documentation.

Here, we will be using an already created simple “Hello World” chaincode example written in Go to show specific details of how to run smart contracts in Catalyst Blockchain Platform.

The source code of this chaincode can be found following the link.

The key part of this example chaincode is the function where its server starts:

func main() {
ccid := os.Getenv("CHAINCODE_ID")
address := os.Getenv("CHAINCODE_ADDRESS")
server := &shim.ChaincodeServer{
CCID: ccid,
Address: address,
CC: &HelloWorld{},
TLSProps: shim.TLSProperties{
Disabled: true,
},
}
if err := server.Start(); err != nil {
fmt.Printf("Error starting HelloWorld chaincode: %s", err)
}
}

To run chaincode in Catalyst Blockchain Platform, you need to set CCID and Address fields of shim.ChaincodeServer as environment variables CHAINCODE_ID and CHAINCODE_ADDRESS, respectively. These two environment variables will be passed during the creation of the chaincode external service, CHAINCODE_IDmatches chaincode package id after its installation on a peer and CHAINCODE_ADDRESS is the listen address of a chaincode server that was used to build the chaincode server endpoint accessible from peer in connection.json.

Communication with Hyperledger Fabric Service

There are two ways to communicate with the Hyperledger Fabric Service: Hyperledger Fabric SDK and Catalyst Blockchain Platform API.

Hyperledger Fabric SDK

There are many different Hyperledger Fabric resources and guides on configuring the SDK for interaction with Fabric, and these can be utilized as well.

Catalyst Blockchain Platform needs two more steps to complete SDK integration with Hyperledger Fabric Service.

1. Register a client signing identity and TLS identity for the business application on behalf of your Catalyst Blockchain Platform user.

You can do that on Hyperledger Fabric Service UI in the CA tab. Information about how to register an identity can be found here.

2. Enroll the registered identities through SDK CA client from your business application or Hyperledger Fabric CA Client in CLI.

SDK method allows you to fully integrate with Hyperledger Fabric Service and interact with all network components. However, this method is complicated. Instead of using HL Fabric SDK, you can use Catalyst Blockchain Platform API.

Catalyst Blockchain Platform API

For communication between your business application and a chaincode, the Catalyst Blockchain Platform provides you with an API to invoke, query deployed chaincodes, and subscribe for chaincodes’ events.

Note: The Catalyst Blockchain Platform API can be used by the users who have an on-premise installation of the Catalyst Blockchain Platform. The users who use the Catalyst Blockchain Platform as a BaaS will be able to use the API in future releases.

Endpoints and required parameters are listed below.

Invoke endpoint

{domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/invoke [POST]
  • {domain} — the name of the domain, where the Catalyst blockchain platform is deployed.

  • {channelID} — the name of the channel, where the chaincode is committed.

  • {chaincodeID}— the chaincode name.

Content-Type — application/json.

Request body contains fields:

  • function — the name of a chaincode function (type: string).

  • args— an array of function arguments (any type of argument will work).

  • is_init — indicates whether init function call is required, can be set to true only during the first operation with chaincode (type: bool, default value: false).

Example of the request body for invocation of chaincode “Hello World”:

{
"function":"invoke",
"args":["John"],
"is_init": false
}

Query endpoint

{domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/query [POST]
  • {domain} — the name of the domain, where the Catalyst blockchain platform is deployed.

  • {channelID} — the name of the channel, where the chaincode is committed.

  • {chaincodeID}— the chaincode name.

Content-Type — application/json.

The query request body contains the same fields as the invocation request.

Example of the request body for the query of chaincode “Hello World”:

{
"function":"query",
"args":["John"],
"is_init": false
}

Subscribe endpoint

Subscribes for SSE stream of events.

{domain}/channels/{chanID}/cc/{ccID}/subscribe?startFrom={startFromValue}&eventFilter={eventFilterValue} [GET]
  • {domain} — the name of the domain, where the Catalyst blockchain platform is deployed.

  • {channelID} — the name of the channel, where the chaincode is committed.

  • {chaincodeID}— the chaincode name.

  • {startFromValue}— blocknumber, default is 0.

  • {eventFilterValue}— a regexp filter to filter out only needed events.

Content-Type — application/json.

Examples

Catalyst Blockchain Platform supports two authorization types: Basic and OpenID. The user chooses authorization type during the Catalyst Blockchain Platform installation.

Invoke example

The name of the domain, where Catalyst Blockchain Platform is deployed: https://chaincodeinvokeexample.com The channel name: catbp The chancode name: helloworld Auth type: basic auth (login: login, password: passwd)

curl -X POST https://chaincodeinvokeexample.com/api/v1/channels/catbp/cc/helloworld/invoke
-H 'Content-Type: application/json'
-H 'Authorization: Basic bG9naW46cGFzc3dvcmQK'
-d ‘{"function":"invoke","args":["John"],"is_init":false}’
  • wherebG9naW46cGFzc3dvcmQK— base64 authoritation token.

You can generate the token using the following command echo {your_login}:{your_password} | base64

Query example

The name of the domain, where Catalyst Blockchain Platform is deployed: https://chaincodequeryexample.com The channel name: catbp The chancode name: helloworld Auth type: OpenID

curl -X POST https://chaincodequeryexample.com/api/v1/channels/catbp/cc/helloworld/query
-H 'Content-Type: application/json'
-H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo=’
-d ‘{"function":"query","args":["John"],"is_init":false}’
  • where b3BlbmlkOm9wZW5pZAo= is your OpenID token.

Subscribe example

The name of the domain, where Catalyst Blockchain Platform is deployed: https://chaincodesubscriptionexample.com The channel name: catbp The chancode name: helloworld Auth type: OpenID

curl -X GET https://chaincodesubscriptionexample.com/api/v1/channels/catbp/cc/helloworld/subscribe
-H 'Content-Type: application/json'
-H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo=’
  • where b3BlbmlkOm9wZW5pZAo= is your OpenID token.

You can use the already created Docker image of the “Hello World” chaincode intellecteu/fabric-externalcc:latest provided by IntellectEU for testing.