Chaincode (or smart contract) is a program that handles business logic agreed by fabric network members and manages the state of shared ledger through transaction submitted by the client application.
Hyperledger fabric chaincode APIs implementation is available in Node.js, Go lang and Java. Whilst Java support was introduced recently, Node.js and Go lang APIs are quite at a mature level. Node.js could be a preferable choice for millions as the learning curve is not as steep as it has been with Go lang. However, I must warn that Node.js is not one of the best tools to design back-end application for the financial industry, especially where numbers are involved. Chaincode programming often deals with math and JavaScript does not fair very well with mathematics. Try these if you are in doubt:
0.1+0.3!=0.4 //true//Math Abel Prize winning professor proven wrong!!(57055*57055*57055)+(339590*339590*339590)==(340126*340126*340126) // true, should be false - Fermat’s Last Theorem
I would be hesitant to use a loosely typed language for serious calculations. Compiler self-made assumptions can cause serious blunders.
Also, the first fully supported chaincode language is Go. All the new features(APIs) are first introduced in Go. Other language developers have to wait. Considering these two and many other reasons, Go lang is my preferred language for writing chaincodes.
Now, writing the first chaincode in Go can be tricky. But believe me, it is just the semantics. Go is easy!!!
Check out this repo for a good example on how to write chaincode ( and unit test using mock APIs)
We will be writing a chaincode(a Go program) with a slight object — orientated approach. Our chaincode would manage the ownership of an asset, let’s say a car. Now in OOP paradigm, I would start with blueprints (classes) for the car and the owner.
class Car {
String modelName;
String color;
String serialNo;
String manufacturer;
Owner owner; //composition
}
class Owner{
String name;
String nationalIdentity;
String gender;
String address;
}Go does not have classes. Instead, it has types and one of those types is structs — a lightweight version of classes. A struct type is a collection of fields and properties. Behaviours (methods) can be added to go types (struct happens to be one of them).
Before we move further, let me mention Go semantics follow a simple rule, write as you speak.
var modelName string // => this should be interpreted as -> a variable modelName of type stringThe Go version would look like this:
type Car struct{
modelName string
color string
serialNo string
manufacturer string
owner Owner //composition
}type Owner struct{
name string
nationalIdentity string
gender string
address string
}
Let’s define a new method changeOwner() on Car.
/** Java Version **/public class Car {
String modelName;
String color;
String serialNo;
String manufacturer;
Owner owner;
void changeOwner(Owner newOwner){
this.owner=newOwner;
}
}
The Go version would be:
type Car struct {
modelName string
color string
serialNo string
manufacturer string
owner Owner
}type Owner struct {
...
}//attached by reference ==> called as pointer receiver
func (c *Car) changeOwner(newOwner Owner) {
c.owner = newOwner
}/** attached by value ==> called as value receiver
func (c Car) changeOwner(newOwner Owner) {
c.owner = newOwner
}
*/
Pointer receiver should be used when changes made to the receiver (c *Car) inside the method (changeOwner) should be visible to the caller (Car struct).
**********************************************************
Let’s take a break here to understand the fabric chaincode APIs. The most important ones are shim APIs.
Shim : a piece of wood or metal that is inserted between two objects to make them fit together better.
Here, a shim is a small library which works as a middleman and transparently intercepts an API, changes the parameters passed, handles the operation itself, or redirects the operation elsewhere.
The chaincode shim APIs has two interfaces:
- Chaincode interface
- ChaincodeStubInterface interface
Chaincode interface:
Fabric enforces that every chaincode must implement Chaincode interface. This interface has two methods:- Init and Invoke. Invoke is called every time a transaction is submitted to the chaincode.
type Chaincode interface {
// Init method accepts stub of type ChaincodeStubInterface as
// argument and returns peer.Response type object
Init(stub ChaincodeStubInterface) peer.Response Invoke(stub ChaincodeStubInterface) peer.Response
}
Now, Go does not have classes to implements interfaces. Instead it has types. Let’s declare a type(of struct) CarChaincode .
type CarChaincode struct{
}Now as mandated by fabric, CarChaincode type has to implement Chaincode interface.
type CarChaincode struct{
}
//Init implemented by CarChaincode
func (t *CarChaincode) Init(stub shim.ChaincodeStubInterface) pb.Response {}//Invoke implemented by CarChaincode
func (t *CarChaincode) Invoke(stub shim.ChaincodeStubInterface) pb.Response {}
ChaincodeStubInterface interface:
This interface has methods (around 36 when writing this article), which are used to access and modify the ledger. This interface is implemented by ChaincodeStub struct. In our chaincode, we will use the default implementation provided by ChaincodeStub struct instead of writing our own implementation.
Now, let’s put together we have discussed so far:
//Define a blueprint for Car
type Car struct {
modelName string
color string
serialNo string
manufacturer string
owner Owner
}//Define a blueprint for owner
type Owner struct{
name string
nationalIdentity string
gender string
address string
}//Define a method for changing ownership
func (c *Car) changeOwner(newOwner Owner) {
c.owner = newOwner
}//Define chaincode CarChaincode reference
type CarChaincode struct{
}//Implements Chaincode interface as mandated by fabric
func (t *CarChaincode) Init(stub shim.ChaincodeStubInterface) pb.Response {}
func (t *CarChaincode) Invoke(stub shim.ChaincodeStubInterface) pb.Response {}
Now, let’s perform some transactions on ledger. Init is called whenever a chaincode is initialized. So this is the good place to declare an asset of Car type and two owners of Owner type and adding them in the ledger.
func (t *CarChaincode) Init(stub shim.ChaincodeStubInterface) pb.Response {//Declare owners from Owner struct
tom := Owner{name: "Tom H", nationaIdentity: "ABCD33457", gender: "M", address: "1, Tumbbad"}
bob := Owner{name: "Bob M", nationaIdentity: "QWER33457", gender: "M", address: "2, Tumbbad"}//Declaree carfrom Car struct
car := Car{modelName: "Land Rover", color: "white", serialNo: "334712531234", manufacturer: "Tata Motors", owner: tom}// convert tom Owner to []byte
tomAsJSONBytes, _ := json.Marshal(tom)
//Add Tom to ledger
err := stub.PutState(tom.nationaIdentity, tomAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + tom.name)
}//Add Bob to ledger
bobAsJSONBytes, _ := json.Marshal(bob)
err = stub.PutState(bob.nationaIdentity, bobAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + bob.name)
}//Add car to ledger
carAsJSONBytes, _ := json.Marshal(car)
err = stub.PutState(car.serialNo, carAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + car.serialNo)
} return shim.Success([]byte("Assets created successfully."))
}
Invoke is called whenever a transaction is submitted to chaincode. Let’s put ownership transfer logic here.
func (c *CarChaincode) Invoke(stub shim.ChaincodeStubInterface) pb.Response { // Read args from the transaction proposal.
// fc=> method to invoke
fc, args := stub.GetFunctionAndParameters()
if fc == "TransferOwnership" {
return c.TransferOwnership(stub, args)
}
return shim.Error("Called function is'nt defined in the chaincode ")
}func (c *CarChaincode) TransferOwnership(stub shim.ChaincodeStubInterface, args []string) pb.Response {
// args[0]=> car serial no
// args[1]==> new owner national identity
// Read existing car asset
carAsBytes, _ := stub.GetState(args[0])
if carAsBytes == nil {
return shim.Error("car asset not found")
}// Construct the struct Car
car := Car{}
_ = json.Unmarshal(carAsBytes, &car)//Read newOwnerDetails
ownerAsBytes, _ := stub.GetState(args[1])
if ownerAsBytes == nil {
return shim.Error("owner asset not found")
}// Construct the struct Owner
newOwner := Owner{}
_ = json.Unmarshal(ownerAsBytes, &newOwner)// Update owner
car.changeOwner(newOwner) carAsJSONBytes, _ := json.Marshal(car)// Update car ownership in the
err := stub.PutState(car.serialNo, carAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + car.serialNo)
}
return shim.Success([]byte("Asset modified."))
}
Now, we need to start the chaincode process so that it can listen for incoming endorsement requests. We will do this in main() method.
func main() {logger.SetLevel(shim.LogInfo)// Start chaincode process
err := shim.Start(new(CarChaincode))
if err != nil {
logger.Error("Error starting PhantomChaincode - ", err.Error()
}
}
Now, putting it all together along with dependencies:
package mainimport (
"encoding/json""github.com/hyperledger/fabric/core/chaincode/shim"
pb "github.com/hyperledger/fabric/protos/peer"
)type Car struct {
modelName string
color string
serialNo string
manufacturer string
owner Owner
}
type Owner struct {
name string
nationaIdentity string
gender string
address string
}func (c *Car) changeOwner(newOwner Owner) {
c.owner = newOwner
}type CarChaincode struct {
}func (c *CarChaincode) Init(stub shim.ChaincodeStubInterface) pb.Response {//Declare owners
tom := Owner{name: "Tom H", nationaIdentity: "ABCD33457", gender: "M", address: "1, Tumbbad"}
bob := Owner{name: "Bob M", nationaIdentity: "QWER33457", gender: "M", address: "2, Tumbbad"}//Decale Car
car := Car{modelName: "Land Rover", color: "white", serialNo: "334712531234", manufacturer: "Tata Motors", owner: tom}// convert tom Owner to []byte
tomAsJSONBytes, _ := json.Marshal(tom)
//Add Tom to ledger
err := stub.PutState(tom.nationaIdentity, tomAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + tom.name)
}//Add Bob to ledger
bobAsJSONBytes, _ := json.Marshal(bob)
err = stub.PutState(bob.nationaIdentity, bobAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + bob.name)
}//Add car to ledger
carAsJSONBytes, _ := json.Marshal(car)
err = stub.PutState(car.serialNo, carAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + car.serialNo)
}
return shim.Success([]byte("Assets created successfully."))
}
func (c *CarChaincode) Invoke(stub shim.ChaincodeStubInterface) pb.Response {// Read args from the transaction proposal.
// fc=> method to invoke
fc, args := stub.GetFunctionAndParameters()
if fc == "TransferOwnership" {
return c.TransferOwnership(stub, args)
}
return shim.Error("Called function is not defined in the chaincode ")
}func (c *CarChaincode) TransferOwnership(stub shim.ChaincodeStubInterface, args []string) pb.Response {
// args[0]=> car serial no
// args[1]==> new owner national identity
// Read car asset
carAsBytes, _ := stub.GetState(args[0])
if carAsBytes == nil {
return shim.Error("car asset not found")
}
car := Car{}
_ = json.Unmarshal(carAsBytes, &car)//Read newOwnerDetails
ownerAsBytes, _ := stub.GetState(args[1])
if ownerAsBytes == nil {
return shim.Error("owner asset not found")
}
newOwner := Owner{}
_ = json.Unmarshal(ownerAsBytes, &newOwner)car.changeOwner(newOwner)
carAsJSONBytes, _ := json.Marshal(car)
err := stub.PutState(car.serialNo, carAsJSONBytes)
if err != nil {
return shim.Error("Failed to create asset " + car.serialNo)
}return shim.Success([]byte("Asset modified."))
}func main() {logger.SetLevel(shim.LogInfo)// Start the chaincode process
err := shim.Start(new(CarChaincode))
if err != nil {
logger.Error("Error starting PhantomChaincode - ", err.Error()
}
}
PS: I have used blank identifier ( _ ) at many places to discards the error value in order to keep this article less verbose; this is terrible practice. Always check error returns; they’re provided for a reason.
Checkout protobuffs for recommended way of serializing the input in a chaincode.
If you liked this article, 👏 to show your support.
….
Vishal
