This is SDK for Hyperledger Fabric written in pure Golang using minimum requirements. This is not official SDK and does not follow official SDK API guidelines provided by Hyperledger team. For the list of official SDK's refer to the official Hyperledger documentation.
It is designed to be easy to use and to be fast as possible. Currently, it outperforms the official Go SDK by far.
We are using it in our production applications, but no guarantees are provided.
This version will be updated and supported, so pull requests and reporting any issues are more than welcome.
Recommended Go version is >=1.9
This SDK is tested for Hyperledger Fabric 1.1.x.
Versions 1.0.x should work, but some features will not be available. We are not planning to support 1.0.x anymore. We are planning to keep backward comparability for versions >=1.1.x
For examples see examples folder.
go get -u golang.org/x/crypto/sha3
go get -u gopkg.in/yaml.v2
go get -u github.com/CognitionFoundry/gohfc
Gohfc provide two high level clients, one for FabricCA and one for Fabric. They work together but user may use them separately.
FabricCAClient is client to work with Fabric certificate authority (CA) and allows you to register, enroll,
revoke certificates, manage affiliations and attributes.
Every operation in Fabric MUST be signed by proper certificate. You can generate this certificates using openssl or other tools, but FabricCA server makes this procedure much more streamline and hides a lot of the complexity.
FabricCAClient can be used to generate complete MSP structure if you do not want to use cryptogen tool for some reason.
FabricClient expose high level API's for working with blockchain, ledger, chaincodes, channels and events.
General flow is like this:
- Start Fabric using docker-compose or any other tool appropriate for you. Running Fabric is not responsibility of gohfc.
- Create one or many channels by sending channels config to orderer. This is done using
gohfc.CreateUpdateChannel - Join one or more peers to one or more channels. This is done using
gohfc.JoinChannel - Install one or many chaincodes in one or many peers. This can be done using
gohfc.InstallChainCode - Instantiate one or more already installed chaincodes. This can be dine using
gohfc.InstantiateChainCode - Query chaincode using
gohfc.Query. This is readonly operation. No changes to blockchain or ledger will be made. - Invoke chaincode using
gohfc.Invoke. This operation may update the blockchain and the ledger. - Listen for events using
gohfc.ListenForFullBlockorgohfc.ListenForFilteredBlock
There are many more methods to get particular block, list channels, get chaincodes etc.
See examples folder.
Both clients can be initialised from yaml file or manually.
FabricCAClient config file:
---
url: http://ca.example.com:7052 # URL for the CA server
skipTLSValidation: true # skip TLS verification in case when you are not providing custom transport
mspId: comp1Msp # this value will be added automatically to any gohfc.Identity returned from this CA
crypto: # cryptographic settings
family: ecdsa
algorithm: P256-SHA256
hash: SHA2-256
FabricCAClient initialization from config file:
caClient, err := gohfc.NewCAClient("./ca.yaml", nil)
if err != nil {
fmt.Println(err)
os.Exit(1)
}
Every peer and orderer in Fabric must have set of cryptographic materials like root CA certificates, intermediate certificates, list of revoked certificates and more. This set of certificates is associated with ID and this ID is called MSP (member service provider). In every operation MSPID must be provided so the peer and orderer know which set of crypto materials to load and to use for verification of the request.
In general MSP define a organization and entities inside organization with there roles. Couple of MSP's are combined to form a consortium so multiple organizations, each one with own set of certificates, can work together.
So when any request to fabric is send this request must be signed by Ecert (user certificate hold in gohfc.Identity)
and MSPID must be provided so Fabric loads MSP by ID, make verification that this request is coming from member of the
organization and that this member has the appropriate access.
Because (in general case) one FabricCa is serving one organization (one MSP) it makes sense to put this ID in config
and to auto populate it when new gohfc.Identity is generated (enroll or reenroll). This is for convenience,
user can always overwrite this value.
FabricClient config file:
---
crypto:
family: ecdsa
algorithm: P256-SHA256
hash: SHA2-256
orderers:
orderer0:
host: orderer0.example.com:7050
useTLS: false
tlsPath: /path/to/tls/server.pem
orderer1:
host: orderer0.example.com:7048
useTLS: false
tlsPath: /path/to/tls/server.pem
peers:
peer01:
host: peer0.example.com:7051
useTLS: false
tlsPath: /path/to/tls/server.pem
peer11:
host: peer1.example.com:8051
useTLS: false
tlsPath: /path/to/tls/server.pem
peer02:
host: peer0.example.com:9051
useTLS: false
tlsPath: /path/to/tls/server.pem
peer12:
host: peer1.example.com:10051
useTLS: false
tlsPath: /path/to/tls/server.pem
eventPeers:
peer0:
host: peer0.example.com:7051
useTLS: false
tlsPath: /path/to/tls/server.pem
FabricClient initialization from config file:
c, err := gohfc.NewFabricClient("./client.yaml")
if err != nil {
fmt.Printf("Error loading file: %v", err)
os.Exit(1)
}
When new chaincode is installed a struct of type gohfc.InstallRequest must be provided:
request := &gohfc.InstallRequest{
ChainCodeType: gohfc.ChaincodeSpec_GOLANG,
ChannelId: "testchannel",
ChainCodeName: "samplechaincode",
ChainCodeVersion: "1.0",
Namespace: "github.com/hyperledger/fabric-samples/chaincode/chaincode_example02/go/",
SrcPath: "/absolute/path/to/folder/containing/chaincode",
Libraries: []gohfc.ChaincodeLibrary{
{
Namespace: "namespace",
SrcPath: "path",
},
},
}
Fabric will support chaincode written in different languages, so language type must be specified using ChainCodeType
Gohfc for now support only Go. Other chaincode languages will be added later when Fabric officially start support them.
ChannelId is the channel name where the chaincode must be installed.
ChainCodeName is the name of the chaincode. This name will be used in future requests (query, invoke, etc..)
to specify which chaincode must be executed. One channel may have multiple chaincodes. name must be unique in context
of a channel.
ChainCodeVersion specify the version.
Gohfc is designed to work without need of Go environment. So when user try to install chaincode he/she must provide
Namespace,SrcPath and optional Libraries
Namespace is the Go namespace where chaincode will be "installed" in Fabric runtime. Like github.com/some/code
SrcPath is the absolute path where source code is located, from where it must be red, packed and prepared for
install.
This separation allows gohfc to run without any external runtime dependencies, also this is very flexible in context of CI,CD systems.
Libraries is a optional list of libraries that will be included in packing of the chaincode. They follow the same
logic of Namespace and SrcPath.
Vendoring the dependencies is an option, but in more complex chaincodes is much better to have some library installed as library and not as vendored dependencies in multiple places.
Many operations require specific peer or orderer to be specified. Gohfc use name alias for this, and names are taken from config file. For example, if you want to query specific peers:
client.Query(*identity, *chaincode, []string{"peer01","peer11"})
In this example "peer01" and "peer11" are names given to peers in config file and query operation will be send to this two peers.
- full block decoding. For now user can take raw block data, but will be much better to provide utility functions to decode block
- specify policy in
InstantiateChainCode. Waiting for official tool from Fabric and decide how to integrate it. - gencrl call for FabricCA
- easy mutual TLS configuration
| Family | Algorithm | Description |
|---|---|---|
| ecdsa | P256-SHA256 | Elliptic curve is P256 and signature uses SHA256 |
| ecdsa | P384-SHA384 | Elliptic curve is P384 and signature uses SHA384 |
| ecdsa | P521-SHA512 | Elliptic curve is P521 and signature uses SHA512 |
| rsa | ---- | RSA is not supported in Fabric |
| Family |
|---|
| SHA2-256 |
| SHA2-384 |
| SHA3-256 |
| SHA3-384 |