Hyperledger Fabric chaincode kit (CCKit)

Source code moved to https://github.com/hyperledger-labs/cckit

We're pleased to announce that ССKit has officially joined https://github.com/hyperledger-labs.

CCKit development continues here https://github.com/hyperledger-labs/cckit

Build

Overview

A smart contract is code, invoked by a client application external to the blockchain network – that manages access and modifications to a set of key-value pairs in the World State. In Hyperledger Fabric, smart contracts are referred to as chaincode.

CCKit is a programming toolkit for developing and testing Hyperledger Fabric golang chaincodes. It enhances the development experience while providing developers components for creating more readable and secure smart contracts.

Chaincode examples

There are several chaincode "official" examples available:

Commercial paper from official Hyperledger Fabric documentation
Blockchain insurance application (testing tutorial: how to write tests for "insurance" chaincode)

and others

Main problems with existing examples are:

Working with chaincode state at very low level
Lots of code duplication (JSON marshalling / unmarshalling, validation, access control, etc)
Chaincode methods routing appeared only in HLF 1.4 and only in Node.Js chaincode
Uncompleted testing tools (MockStub)

CCKit features

Chaincode method router with invocation handlers and middleware capabilities
Chaincode state modeling using protocol buffers / golang struct to json marshalling, with private data support
Designing chaincode in gRPC service notation with code generation of chaincode SDK, gRPC and REST-API
MockStub testing, allowing to immediately receive test results
Data encryption on application level
Chaincode method access control

Publications with usage examples

Examples based on CCKit

Cars - car registration chaincode, simplest example
Commercial paper, service-oriented approach - recommended way to start new application. Code generation radically simplifies building on-chain and off-chain applications.
Commercial paper - faithful reimplementation of the official example
Commercial paper extended example - with protobuf chaincode state schema and other features
ERC-20 - tokens smart contract, implementing ERC-20 interface
Cars private - car registration chaincode with private data
Payment - a few examples of chaincodes with encrypted state

Installation

CCKit requires Go 1.11+ with modules support

Standalone

git clone git@github.com:s7techlab/cckit.git

go mod vendor

As dependency

go get -u github.com/s7techlab/cckit

Example - Commercial Paper chaincode

Scenario

Commercial paper scenario from official documentation describes a Hyperledger Fabric network, aimed to issue, buy and redeem commercial paper.

commercial paper network

5 steps to develop chaincode

Chaincode is a domain specific program which relates to specific business process. The job of a smart contract developer is to take an existing business process and express it as a smart contract in a programming language. Steps of chaincode development:

Define chaincode model - schema for state entries, transaction payload and events
Define chaincode interface
Implement chaincode instantiate method
Implement chaincode methods with business logic
Create tests

Define chaincode model

With protocol buffers, you write a .proto description of the data structure you wish to store. From that, the protocol buffer compiler creates a golang struct that implements automatic encoding and parsing of the protocol buffer data with an efficient binary format (or json).

Code generation can be simplified with a short Makefile:

.: generate

generate:
	@echo "schema"
	@protoc -I=./ --go_out=./ ./*.proto

Chaincode state

The following file shows how to define the world state schema using protobuf.

examples/cpaper_extended/schema/state.proto

syntax = "proto3";

package cckit.examples.cpaper_extended.schema;
option go_package = "schema";

import "google/protobuf/timestamp.proto";

// Commercial Paper state entry
message CommercialPaper {

    enum State {
        ISSUED = 0;
        TRADING = 1;
        REDEEMED = 2;
    }

    // Issuer and Paper number comprises composite primary key of Commercial paper entry
    string issuer = 1;
    string paper_number = 2;

    string owner = 3;
    google.protobuf.Timestamp issue_date = 4;
    google.protobuf.Timestamp maturity_date = 5;
    int32 face_value = 6;
    State state = 7;

    // Additional unique field for entry
    string external_id = 8;
}

// CommercialPaperId identifier part
message CommercialPaperId {
    string issuer = 1;
    string paper_number = 2;
}

// Container for returning multiple entities
message CommercialPaperList {
    repeated CommercialPaper items = 1;
}

Chaincode transaction and events payload

This file defines the data payload used in business logic methods. In this example transaction and event payloads are exactly the same for the sake of brevity, but you could create a different schema for each type of payload.

examples/cpaper_extended/schema/payload.proto

// IssueCommercialPaper event
syntax = "proto3";

package cckit.examples.cpaper_extended.schema;
option go_package = "schema";

import "google/protobuf/timestamp.proto";
import "github.com/mwitkow/go-proto-validators/validator.proto";

// IssueCommercialPaper event
message IssueCommercialPaper {
    string issuer = 1;
    string paper_number = 2;
    google.protobuf.Timestamp issue_date = 3;
    google.protobuf.Timestamp maturity_date = 4;
    int32 face_value = 5;

    // external_id - another unique constraint
    string external_id = 6;
}

// BuyCommercialPaper event
message BuyCommercialPaper {
    string issuer = 1;
    string paper_number = 2;
    string current_owner = 3;
    string new_owner = 4;
    int32 price = 5;
    google.protobuf.Timestamp purchase_date = 6;
}

// RedeemCommercialPaper event
message RedeemCommercialPaper {
    string issuer = 1;
    string paper_number = 2;
    string redeeming_owner = 3;
    google.protobuf.Timestamp redeem_date = 4;
}

Define chaincode interface

In examples/cpaper_extended/chaincode.go file we will define the mappings, chaincode initialization method and business logic in the transaction methods. For brevity, we will only display snippets of the code here, please refer to the original file for full example.

Firstly we define mapping rules. These specify the struct used to hold a specific chaincode state, it's primary key, list mapping, unique keys, etc. Then we define the schemas used for emitting events.

var (
	// State mappings
	StateMappings = m.StateMappings{}.
		// Create mapping for Commercial Paper entity
		Add(&schema.CommercialPaper{},
			// Key namespace will be <"CommercialPaper", Issuer, PaperNumber>
			m.PKeySchema(&schema.CommercialPaperId{}),
			// Structure of result for List method
			m.List(&schema.CommercialPaperList{}),
			// External Id is unique
			m.UniqKey("ExternalId"),
		)

	// EventMappings
	EventMappings = m.EventMappings{}.
		// Event name will be "IssueCommercialPaper", payload - same as issue payload
		Add(&schema.IssueCommercialPaper{}).
		// Event name will be "BuyCommercialPaper"
		Add(&schema.BuyCommercialPaper{}).
		// Event name will be "RedeemCommercialPaper"
		Add(&schema.RedeemCommercialPaper{})
)

CCKit uses router to define rules about how to map chainco

Cckit

Install / Use

README