Hyperledger Fabric Client SDK for Node.js

Branch	Build status
main
release-2.2
release-1.4

The Hyperledger Fabric Client SDK makes it possible to use APIs to interact with a Hyperledger Fabric blockchain. This readme is directed towards a current or future contributor to this project, and gives an overview of setting up the project locally and running tests. For more information on the SDK, including features and an API reference, please visit the SDK documentation.

This project publishes the following npm packages:

• fabric-ca-client - client for the optional component in Hyperledger Fabric, fabric-ca. The fabric-ca component allows applications to enroll Peers and application users to establish trusted identities on the blockchain network. It also provides support for pseudonymous transaction submissions with Transaction Certificates. If the target blockchain network is configured with standard Certificate Authorities for trust anchors, the application does not need to use this package.
• fabric-common - encapsulates the common code used by all fabric-sdk-node packages supporting fine grain interactions with the Fabric network to send transaction invocations
• fabric-network - This package encapsulates the APIs to connect to a Fabric network, submit transactions and perform queries against the ledger at a higher level of abstraction than through the fabric-common.
• fabric-protos - This package encapsulates the protobuffers that are used to communicate over gRPC

Note: When developing applications for Hyperledger Fabric v2.4 and later, you are strongly encouraged to use the new Fabric Gateway client API.

Build and Test

To build and test, the following pre-requisites must be installed first:

• Node.js, version 10 is supported from 10.15.3 and higher
• Node.js, version 12 is supported from 12.13.1 and higher
• npm tool version 6 or higher
• docker (only required for running integration tests, see below)

Run unit tests

Clone the project and launch the following commands to install the dependencies and perform various tasks.

In the project root folder:

• Install all dependencies via npm install
• Optionally, to generate API docs via npm run docs
• To generate the required crypto material used by the tests, use the npm task npm run installAndGenerateCerts
• To run the unit tests that do not require any additional set up, use npm run testHeadless

Run Integration Tests

Integration tests run on the main branch require the most recent stable Fabric images, which are hosted on Artifactory. A utility script is provided to retrieve non-published docker images, which may be run using the command npm run pullFabricImages

Now you are ready to run the integration tests. It is advisable to clear out any previous key value stores that may have cached user enrollment certificates using the command (rm -rf /tmp/hfc-*, rm -rf ~/.hfc-key-store) prior to testing in isolation.

We have functional and scenario based tests that may be run via the following commands:

• end to end (tape) tests may be run via npm run tapeIntegration
• scenario (cucumber) tests may be run via npm run cucumberScenario
• You may run both integration test styles using npm run tapeAndCucumber
• All tests (unit and integration) may be run using the command npm test or npm run testNoHSM when not using a HSM or HSM simulator

Special Tests for Hardware Security Module support via PKCS #11 interface

The SDK has support for Hardware Security Module (HSM) via PKCS #11 interface. See the test README for details of how to run HSM tests locally.

Pluggability

HFC defines the following abstract classes for application developers to supply extensions or alternative implementations. For each abstract class, a built-in implementation is included with the ability to load alternative implementations via designated environment variables:

1. To replace FileKeyValueStore with a different implementation, such as one that saves data to a database, specify "KEY_VALUE_STORE" and provide the full require() path to an alternative implementation of the api.KeyValueStore abstract class.

2. The cryptography suite used by the default implementation uses ECDSA for asymmetric keys cryptography, AES for encryption and SHA2/3 for secure hashes. A different suite can be plugged in with "CRYPTO_SUITE" environment variable specifying full require() path to the alternative implementation of the api.CrytoSuite abstract class.

3. If the user application uses an alternative membership service than the one provided by the component fabric-ca, the client code will likely need to use an alternative client to fabric-ca-client to interact with that membership service.

Continuous Integration

Our Continuous Integration is run using Azure Pipelines. Builds are automatically triggered on opening pull requests.

Release notes

Check the ./release_notes directory for the release notes of the specified release.

Contributing

Check the documentation on how to contribute to this project for the full details.

This work is licensed under a Creative Commons Attribution 4.0 International License.