Hyperledger Fabric Client SDK for Go
This SDK enables Go developers to build solutions that interact with Hyperledger Fabric.
Obtain the client SDK packages for Fabric and Fabric CA.
go get -u github.com/hyperledger/fabric-sdk-go # Optional - populate vendor directory (if needed by your downstream vendoring solution) # cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/ # make populate
You're good to go, happy coding! Check out the examples for usage demonstrations.
- E2E Test: Basic example that uses SDK to query and execute transaction
- Ledger Query Test: Basic example that uses SDK to query a channel's underlying ledger
- Multi Org Test: An example that has multiple organisations involved in transaction
- Dynamic Endorser Selection: An example that uses dynamic endorser selection (based on chaincode policy)
- E2E PKCS11 Test: E2E Test using a PKCS11 crypto suite and configuration
- CLI: An example CLI for Fabric built with the Go SDK.
- More examples needed!
- Discussion is happening in Rocket Chat.
- Issue tracking is handled in Jira.
- Active development occurs in the Gerrit repository.
The SDK's integration tests run against three tagged Fabric versions:
- prev (currently v1.0.6)
- stable (currently v1.1.0)
- prerelease (currently disabled)
Additionally for development purposes integration tests also run against the devstable Fabric version as needed.
The SDK uses the Fabric v1.1 delivery service as the default event mechanism. When using Fabric v1.0, you must override this default by setting the event service type in the config:
client: peer: eventService: type: eventhub
When the 'prev' code level is updated, the last tested fabric-sdk-go commit or tag is listed below.
- fabric v1.0.0 & fabric-ca v1.0.0
- fabric-sdk-go: 79b343ba
Running the test suite
# In the Fabric SDK Go directory cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/ # Optional - Automatically install Go tools used by test suite # make depend-install # Running test suite make # Clean test suite run artifacts make clean
The following Go tags can be supplied to enable additional functionality:
- experimental: includes support for experimental features.
Contributing to the Go SDK
If you want to contribute to the Go SDK, please run the test suite and submit patches to the Gerrit git repostory for review. For general guidelines, please refer to the Fabric project's contribution page.
- Go 1.9
- Docker Compose
Gerrit Git repository
To contribute patches, you will need to clone (or add a remote) from Gerrit with authentication.
Running a portion of the test suite
# In the Fabric SDK Go directory cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/ # Ensure dependencies are installed make depend # Running code checks (license, linting, spelling, etc) make checks # Running all unit tests make unit-test # Running all integration tests make integration-test
Running package unit tests manually
# In a package directory go test
Running integration tests manually
- A working fabric and fabric-ca set up. It is recommended that you use the docker-compose file provided in
test/fixtures/dockerenv. It is also recommended that you use the default .env settings provided in
test/fixtures/dockerenv. See steps below.
- Customized settings in the
test/fixtures/config/config_test.yamlin case your Hyperledger Fabric network is not running on
localhostor is using different ports.
Testing with Fabric Images at Docker Hub
The test suite defaults to the latest compatible tag of fabric images at Docker Hub. The following commands starts Fabric:
# In the Fabric SDK Go directory cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/ # Start fabric (stable tag) make dockerenv-stable-up # Or more generally, start fabric at a different code level (prev, stable, prerelease, devstable) # make dockerenv-[CODELEVEL]-up
Running Integration Tests
Fabric should now be running. In a different shell, run integration tests
# In the Fabric SDK Go directory cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go # Use script to setup parameters for integration tests and execute them # Previously we use to have hostnames like Fabric CA server, orderer and peer pointed to localhost # Now since we removed this now, We will be using a different config file config_test_local.yaml # which has the Fabric CA server, orderer and peers pointed to localhost make -args configFile=config_test_local.yaml integration-tests-local # Or more generally, run integration tests at a different code level (prev, stable, prerelease, devstable) # and fixture target version # FABRIC_CODELEVEL_VER=[VER] FABRIC_CODELEVEL_TAG=[CODELEVEL] make integration-tests-local
# Previously we use to have hostnames like Fabric CA server, orderer and peer pointed to localhost # Now since we removed this now, We will be using a different config file config_test_local.yaml # which has the Fabric CA server, orderer and peers pointed to localhost # It is also possible to run integration tests using go test directly. For example: #cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/test/integration/ #go -args configFile=config_test_local.yaml test #cd $GOPATH/src/github.com/hyperledger/fabric-sdk-go/test/integration/orgs #go -args configFile=config_test_local.yaml test # You should review test/scripts/integration.sh for options and details. # Note: you should generally prefer the scripted version to setup parameters for you.
Testing with Local Build of Fabric (Advanced)
Alternatively you can use a local build of Fabric using the following commands:
# Start fabric (devstable codelevel with latest docker tags) make dockerenv-latest-up
Hyperledger Fabric SDK Go software is licensed under the Apache License Version 2.0.
This document is licensed under a Creative Commons Attribution 4.0 International License.
Package fabricsdk enables Go developers to build solutions that interact with Hyperledger Fabric.
Packages for end developer usage ¶
pkg/fabsdk: The main package of the Fabric SDK. This package enables creation of contexts based on configuration. These contexts are used by the client packages listed below. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/fabsdk
pkg/client/channel: Provides channel transaction capabilities. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/channel
pkg/client/ledger: Enables queries to a channel's underlying ledger. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/ledger
pkg/client/resmgmt: Provides resource management capabilities such as installing chaincode. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/resmgmt
pkg/client/msp: Enables identity management capability. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/msp
- Instantiate a fabsdk instance using a configuration. Note: fabsdk maintains caches so you should minimize instances of fabsdk itself.
- Create a context based on a user and organization, using your fabsdk instance. Note: A channel context additionally requires the channel ID.
- Create a client instance using its New func, passing the context. Note: you create a new client instance for each context you need.
- Use the funcs provided by each client to create your solution!
- Call fabsdk.Close() to release resources and caches.
Package orderer is a generated protocol buffer package.
|Package orderer is a generated protocol buffer package.|
Package channel enables access to a channel on a Fabric network.
|Package channel enables access to a channel on a Fabric network.|
Package invoke provides the handlers for performing chaincode invocations.
|Package invoke provides the handlers for performing chaincode invocations.|
Package verifier provides various verifier (e.g.
|Package verifier provides various verifier (e.g.|
Package ledger enables ability to query ledger in a Fabric network.
|Package ledger enables ability to query ledger in a Fabric network.|
Package resmgmt enables ability to update resources in a Fabric network.
|Package resmgmt enables ability to update resources in a Fabric network.|
Package retry provides retransmission capabilities to fabric-sdk-go
|Package retry provides retransmission capabilities to fabric-sdk-go|
Package status defines metadata for errors returned by fabric-sdk-go.
|Package status defines metadata for errors returned by fabric-sdk-go.|
Package mockcontext is a generated GoMock package.
|Package mockcontext is a generated GoMock package.|
Package mockcore is a generated GoMock package.
|Package mockcore is a generated GoMock package.|
Package mockfab is a generated GoMock package.
|Package mockfab is a generated GoMock package.|
Package mockmsp is a generated GoMock package.
|Package mockmsp is a generated GoMock package.|
Package resource provides access to fabric network resource management, typically using system channel queries.
|Package resource provides access to fabric network resource management, typically using system channel queries.|
Package txn enables creating, endorsing and sending transactions to Fabric peers and orderers.
|Package txn enables creating, endorsing and sending transactions to Fabric peers and orderers.|
Package fabsdk enables client usage of a Hyperledger Fabric network.
|Package fabsdk enables client usage of a Hyperledger Fabric network.|
Package mocksdkapi is a generated GoMock package.
|Package mocksdkapi is a generated GoMock package.|
Package mockmspapi is a generated GoMock package.
|Package mockmspapi is a generated GoMock package.|
Package metadata contains variables used by tests
|Package metadata contains variables used by tests|
Package common is a generated protocol buffer package.
|Package common is a generated protocol buffer package.|
Package rwset is a generated protocol buffer package.
|Package rwset is a generated protocol buffer package.|
Package kvrwset is a generated protocol buffer package.
|Package kvrwset is a generated protocol buffer package.|
Package msp is a generated protocol buffer package.
|Package msp is a generated protocol buffer package.|