README

Hyperledger Fabric Client SDK for Go

Release License GoDoc

Build Status codecov Go Report Card

This SDK enables Go developers to build solutions that interact with Hyperledger Fabric.

Getting started

Obtain the client SDK packages for Fabric and Fabric CA.

go get github.com/hyperledger/fabric-sdk-go

You're good to go, happy coding! Check out the examples for usage demonstrations.

Documentation

SDK documentation can be viewed at GoDoc.

The packages intended for end developer usage are within the pkg/client folder along with the main SDK package (pkg/fabsdk).

Examples
  • 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!
Community
  • Discussion is happening in Rocket Chat.
  • Issue tracking is handled in Jira.

Client SDK

Current Compatibility

The SDK's integration tests run against three tagged Fabric versions:

  • prev (currently v1.3.0)
  • stable (currently v1.4.2)
  • prerelease (currently disabled)

Additionally for development purposes integration tests also run against the devstable Fabric version as needed.

Retired versions

When the 'prev' code level is updated, the last tested fabric-sdk-go commit or tag is listed below.

  • fabric v1.2: 5e291d3
  • fabric v1.1: f7ae259
  • fabric v1.0: 5ac5226
Auth Token payload compatibility between Fabric CA v1.4 and earlier releases

Fabric CA v1.4 introduced a more secure Auth Token payload signing which requires a non compatible update. In order to maintain compatibility with Fabric CA v1.3, the CA client queries the server to fetch the version and determine if compatibility with pre v1.4 is required.

Once v1.3 is retired, the above client code logic will need to be removed as well. No change is required from the Go SDK users.

Running the test suite

Obtain the client SDK packages for Fabric and Fabric CA.

git clone https://github.com/hyperledger/fabric-sdk-go.git
# In the Fabric SDK Go directory
cd fabric-sdk-go/

# Optional - Automatically install Go tools used by test suite
# make depend

# Running test suite
make

# Clean test suite run artifacts
make clean
Go Tags

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 for review. For general guidelines, please refer to the Fabric project's contribution page.

You need:

  • Go 1.13
  • Make
  • Docker
  • Docker Compose
  • Git
  • gobin (GO111MODULE=off go get -u github.com/myitcv/gobin)
  • libtool

Notes:

Running a portion of the test suite
# In the Fabric SDK Go directory
cd fabric-sdk-go/

# Optional - Automatically install Go tools used by test suite
# make depend

# Optional - Running only code checks (linters, license, spelling, etc)
# make checks

# Running all unit tests and checks
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

You need:

  • 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.yaml in case your Hyperledger Fabric network is not running on localhost or 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 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 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 configuration
make 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 fabric-sdk-go/test/integration/
#go test -args testLocal=true

#cd fabric-sdk-go/test/integration/orgs
#go test -args testLocal=true 

# 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

License

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.

Expand ▾ Collapse ▴

Documentation

Overview

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/event: Provides channel event capabilities. Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/event

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

Basic workflow

1) Instantiate a fabsdk instance using a configuration.
   Note: fabsdk maintains caches so you should minimize instances of fabsdk itself.
2) Create a context based on a user and organization, using your fabsdk instance.
   Note: A channel context additionally requires the channel ID.
3) Create a client instance using its New func, passing the context.
   Note: you create a new client instance for each context you need.
4) Use the funcs provided by each client to create your solution!
5) Call fabsdk.Close() to release resources and caches.

Source Files

Directories

Path Synopsis
internal/github.com/hyperledger/fabric-ca/api
internal/github.com/hyperledger/fabric-ca/lib
internal/github.com/hyperledger/fabric-ca/lib/attrmgr
internal/github.com/hyperledger/fabric-ca/lib/client/credential
internal/github.com/hyperledger/fabric-ca/lib/client/credential/x509
internal/github.com/hyperledger/fabric-ca/lib/common
internal/github.com/hyperledger/fabric-ca/lib/streamer
internal/github.com/hyperledger/fabric-ca/lib/tls
internal/github.com/hyperledger/fabric-ca/sdkpatch/cryptosuitebridge
internal/github.com/hyperledger/fabric-ca/sdkpatch/logbridge
internal/github.com/hyperledger/fabric-ca/util
internal/github.com/hyperledger/fabric/bccsp
internal/github.com/hyperledger/fabric/bccsp/factory/gm
internal/github.com/hyperledger/fabric/bccsp/factory/plugin
internal/github.com/hyperledger/fabric/bccsp/factory/sw
internal/github.com/hyperledger/fabric/bccsp/gm
internal/github.com/hyperledger/fabric/bccsp/gm/mocks
internal/github.com/hyperledger/fabric/bccsp/pkcs11
internal/github.com/hyperledger/fabric/bccsp/signer
internal/github.com/hyperledger/fabric/bccsp/sw
internal/github.com/hyperledger/fabric/bccsp/utils
internal/github.com/hyperledger/fabric/common/capabilities
internal/github.com/hyperledger/fabric/common/cauthdsl
internal/github.com/hyperledger/fabric/common/channelconfig
internal/github.com/hyperledger/fabric/common/configtx
internal/github.com/hyperledger/fabric/common/crypto
internal/github.com/hyperledger/fabric/common/flogging
internal/github.com/hyperledger/fabric/common/flogging/fabenc
internal/github.com/hyperledger/fabric/common/flogging/floggingtest
internal/github.com/hyperledger/fabric/common/flogging/httpadmin
internal/github.com/hyperledger/fabric/common/flogging/httpadmin/fakes Code generated by counterfeiter.
internal/github.com/hyperledger/fabric/common/flogging/metrics
internal/github.com/hyperledger/fabric/common/flogging/mock Code generated by counterfeiter.
internal/github.com/hyperledger/fabric/common/genesis
internal/github.com/hyperledger/fabric/common/ledger
internal/github.com/hyperledger/fabric/common/metrics
internal/github.com/hyperledger/fabric/common/metrics/disabled
internal/github.com/hyperledger/fabric/common/metrics/internal/namer
internal/github.com/hyperledger/fabric/common/metrics/prometheus
internal/github.com/hyperledger/fabric/common/metrics/statsd
internal/github.com/hyperledger/fabric/common/metrics/statsd/goruntime
internal/github.com/hyperledger/fabric/common/policies
internal/github.com/hyperledger/fabric/common/tools/protolator
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext/commonext
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext/ledger/rwsetext
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext/mspext
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext/ordererext
internal/github.com/hyperledger/fabric/common/tools/protolator/protoext/peerext
internal/github.com/hyperledger/fabric/common/util
internal/github.com/hyperledger/fabric/core/comm
internal/github.com/hyperledger/fabric/core/common/ccprovider
internal/github.com/hyperledger/fabric/core/common/privdata
internal/github.com/hyperledger/fabric/core/ledger
internal/github.com/hyperledger/fabric/core/ledger/kvledger/txmgmt/rwsetutil
internal/github.com/hyperledger/fabric/core/ledger/kvledger/txmgmt/version
internal/github.com/hyperledger/fabric/core/ledger/util
internal/github.com/hyperledger/fabric/core/middleware
internal/github.com/hyperledger/fabric/core/operations
internal/github.com/hyperledger/fabric/discovery/client
internal/github.com/hyperledger/fabric/discovery/protoext
internal/github.com/hyperledger/fabric/gossip/protoext
internal/github.com/hyperledger/fabric/gossip/util
internal/github.com/hyperledger/fabric/msp
internal/github.com/hyperledger/fabric/msp/cache
internal/github.com/hyperledger/fabric/protoutil
internal/github.com/hyperledger/fabric/sdkinternal/configtxgen/encoder
internal/github.com/hyperledger/fabric/sdkinternal/configtxgen/genesisconfig
internal/github.com/hyperledger/fabric/sdkinternal/configtxgen/localconfig
internal/github.com/hyperledger/fabric/sdkinternal/configtxlator/update
internal/github.com/hyperledger/fabric/sdkinternal/pkg/identity
internal/github.com/hyperledger/fabric/sdkpatch/cachebridge
internal/github.com/hyperledger/fabric/sdkpatch/cryptosuitebridge
internal/github.com/hyperledger/fabric/sdkpatch/logbridge
internal/github.com/hyperledger/fabric/sdkpatch/logbridge/httpadmin
internal/github.com/tjfoc/gmsm/sm2 crypto/x509 add sm2 support
internal/github.com/tjfoc/gmsm/sm3
internal/github.com/tjfoc/gmsm/sm4
internal/github.com/tjfoc/gmtls add sm2 support
internal/github.com/tjfoc/gmtls/gmcredentials
internal/github.com/tjfoc/gmtls/gmcredentials/echo Package echo is a generated protocol buffer package.
pkg/client/channel Package channel enables access to a channel on a Fabric network.
pkg/client/channel/invoke Package invoke provides the handlers for performing chaincode invocations.
pkg/client/common/discovery
pkg/client/common/discovery/dynamicdiscovery
pkg/client/common/discovery/greylist
pkg/client/common/discovery/staticdiscovery
pkg/client/common/filter Package filter provides common filters (e.g.
pkg/client/common/mocks
pkg/client/common/random
pkg/client/common/selection/balancer
pkg/client/common/selection/dynamicselection
pkg/client/common/selection/dynamicselection/pgresolver
pkg/client/common/selection/fabricselection
pkg/client/common/selection/options
pkg/client/common/selection/sorter/balancedsorter
pkg/client/common/selection/sorter/blockheightsorter
pkg/client/common/selection/staticselection
pkg/client/common/verifier Package verifier provides various verifier (e.g.
pkg/client/event Package event enables access to a channel events on a Fabric network.
pkg/client/ledger Package ledger enables ledger queries on specified channel on a Fabric network.
pkg/client/msp Package msp enables creation and update of users on a Fabric network.
pkg/client/resmgmt Package resmgmt enables creation and update of resources on a Fabric network.
pkg/common/errors/multi Package multi is an error type that holds multiple errors.
pkg/common/errors/retry Package retry provides retransmission capabilities to fabric-sdk-go.
pkg/common/errors/status Package status defines metadata for errors returned by fabric-sdk-go.
pkg/common/logging Package logging enables setting custom logger implementation.
pkg/common/options
pkg/common/providers/context
pkg/common/providers/core
pkg/common/providers/fab
pkg/common/providers/msp
pkg/common/providers/test/mockcontext Package mockcontext is a generated GoMock package.
pkg/common/providers/test/mockcore Package mockcore is a generated GoMock package.
pkg/common/providers/test/mockfab Package mockfab is a generated GoMock package.
pkg/common/providers/test/mockmsp Package mockmsp is a generated GoMock package.
pkg/context
pkg/core/config
pkg/core/config/comm
pkg/core/config/comm/tls
pkg/core/config/cryptoutil
pkg/core/config/endpoint
pkg/core/config/lookup
pkg/core/cryptosuite
pkg/core/cryptosuite/bccsp/multisuite
pkg/core/cryptosuite/bccsp/pkcs11
pkg/core/cryptosuite/bccsp/sw
pkg/core/cryptosuite/bccsp/wrapper
pkg/core/cryptosuite/common/pkcs11
pkg/core/logging/api
pkg/core/logging/metadata
pkg/core/logging/modlog
pkg/core/mocks
pkg/fab
pkg/fab/ccpackager/gopackager
pkg/fab/ccpackager/javapackager
pkg/fab/ccpackager/nodepackager
pkg/fab/channel
pkg/fab/channel/membership
pkg/fab/chconfig
pkg/fab/comm
pkg/fab/discovery
pkg/fab/discovery/mocks
pkg/fab/events/api
pkg/fab/events/client
pkg/fab/events/client/dispatcher
pkg/fab/events/client/lbp
pkg/fab/events/client/mocks
pkg/fab/events/client/peerresolver
pkg/fab/events/client/peerresolver/balanced
pkg/fab/events/client/peerresolver/minblockheight
pkg/fab/events/client/peerresolver/preferorg
pkg/fab/events/client/peerresolver/preferpeer
pkg/fab/events/deliverclient
pkg/fab/events/deliverclient/connection
pkg/fab/events/deliverclient/dispatcher
pkg/fab/events/deliverclient/mocks
pkg/fab/events/deliverclient/seek
pkg/fab/events/endpoint
pkg/fab/events/mocks
pkg/fab/events/service
pkg/fab/events/service/blockfilter
pkg/fab/events/service/blockfilter/headertypefilter
pkg/fab/events/service/dispatcher
pkg/fab/events/service/mocks
pkg/fab/keyvaluestore
pkg/fab/mocks
pkg/fab/orderer
pkg/fab/peer
pkg/fab/resource Package resource provides access to fabric network resource management, typically using system channel queries.
pkg/fab/resource/genesisconfig
pkg/fab/signingmgr
pkg/fab/txn Package txn enables creating, endorsing and sending transactions to Fabric peers and orderers.
pkg/fabsdk Package fabsdk enables client usage of a Hyperledger Fabric network.
pkg/fabsdk/api
pkg/fabsdk/factory/defcore
pkg/fabsdk/factory/defmsp
pkg/fabsdk/factory/defsvc
pkg/fabsdk/metrics
pkg/fabsdk/metrics/cfg
pkg/fabsdk/provider/chpvdr
pkg/fabsdk/provider/fabpvdr
pkg/fabsdk/provider/msppvdr
pkg/fabsdk/test/mocksdkapi Package mocksdkapi is a generated GoMock package.
pkg/gateway
pkg/msp
pkg/msp/api
pkg/msp/test/mockmsp
pkg/msp/test/mockmspapi Package mockmspapi is a generated GoMock package.
pkg/util/concurrent/futurevalue
pkg/util/concurrent/lazycache
pkg/util/concurrent/lazyref
pkg/util/concurrent/rollingcounter
pkg/util/pathvar
pkg/util/protolator
pkg/util/test
test/metadata Package metadata contains variables used by tests