Hyperledger Fabric Client SDK for Node.js
Overview
The Hyperledger Fabric Client SDK (HFC) provides a powerful and easy to use API to interact with a Hyperledger Fabric blockchain from a Node.js application. It provides a set of APIs to register and enroll new network clients, to deploy new chaincodes to the network, and to interact with existing chaincodes through chaincode function invocations and queries.
To view the complete Node.js SDK documentation, additional usage samples, and getting started materials please visit the Hyperledger Fabric SDK documentation page.
Installation
If you are interfacing with a network running the Hyperledger Fabric v0.5-developer-preview branch, you must use the hfc version 0.5.x release and install it with the following command:
npm install hfc@0.5.x
For networks running newer versions of the Hyperledger Fabric, please install the version of hfc that corresponds to the same version of the Fabric code base. For example, for the Fabric v0.6 branch install hfc with the following command:
npm install hfc@0.6.x
Usage
Terminology
In order to transact on a Hyperledger blockchain, you must first have an identity which is both registered and enrolled. Registration means issuing a user invitation to join a blockchain network. Enrollment means accepting a user invitation to join a blockchain network.
In the current Hyperleger Fabric implementation, the administative user admin is already registered on the network by the virtue of the fact that their user ID and password pair are already added to the membership services server confiruation file, membersrvc.yaml. Therefore, the admin user must only enroll to be able to transact on the network. After enrollment, the administrative user is then able to register and enroll new users, in the role of a registrar. New users are added to the network programmatically, through the HFC chain.registerAndEnroll API.
Example
An example presented in the SDK documentation demonstrated a typical application using the hfc.
The application sets up a target for the membership service server and enrolls the admin user. Subsequently, the admin user is set as the registrar user and registers and enrolls a new member, JohnDoe. The new member, JohnDoe, is then able to transact on the blockchain by deploying a chaincode, invoking a chaincode function, and querying chaincode state.
Chaincode Deployment
Chaincode may be deployed in development mode or network mode. Development mode refers to running the chaincode as a stand alone process outside the network peer. This approach is useful while doing chaincode development and testing. The approach is described here. Network mode refers to packaging the chaincode and its dependencies and subsequently deploying the package to an existing network as a Docker container. To have the chaincode deployment with hfc succeed in network mode, you must properly set up the chaincode project and its dependencies. The instructions for doing so can be found in the Chaincode Deployment section of the Node.js SDK documentation page.
Enabling TLS
If you wish to enable TLS connection between the member services, the peers, and the chaincode container, please see the Enabling TLS section within the Node.js SDK documentation.
Objects, Classes, And Interfaces
HFC is written primarily in Typescript and is object-oriented. The source can be found in the fabric/sdk/node directory of the Hyperledger Fabric project. To better understand the object hierarchy, please read the high-level descriptions of the HFC objects (classes and interfaces) in the HFC Objects section within the Node.js SDK documentation. You can also build the complete reference documentation locally by following the instructions here.
Unit Tests
HFC includes a set of unit tests implemented with the tape framework. Currently, the unit tests are designed to run inside the Hyperledger Fabric Vagrant development environment. To run the unit tests, first set up the Hyperledger Fabric Vagrant development environment per the instructions here.
Launch the Vagrant VM and log into the VM by executing the following command:
vagrant ssh
Run the unit tests within the Vagrant environment with the following commands:
cd $GOPATH/src/github.com/hyperledger/fabric
make node-sdk-unit-tests
The following are brief descriptions of each of the unit tests that are being run.
registrar
The registrar.js test case exercises registering users with the membership services server. It also tests registering a designated registrar user which can then register additional users.
chain-tests
The chain-tests.js test case exercises the chaincode_example02.go chaincode when it has been deployed in both development mode and network mode.
asset-mgmt
The asset-mgmt.js test case exercises the asset_management.go chaincode when it has been deployed in both development mode and network mode.
asset-mgmt-with-roles
The asset-mgmt-with-roles.js test case exercises the asset_management_with_roles.go chaincode when it has been deployed in both development mode and network mode.
Basic Troubleshooting
Keep in mind that you can perform the enrollment process with the membership services server only once, as the enrollmentSecret is a one-time-use password. If you have performed a user registration/enrollment with the membership services and subsequently deleted the crypto tokens stored on the client side, the next time you try to enroll, errors similar to the ones below will be seen.
Error: identity or token do not match
Error: user is already registered
To address this, remove any stored crypto material from the CA server by following the instructions here. You will also need to remove any of the crypto tokens stored on the client side by deleting the KeyValStore directory. That directory is configurable and is set to /tmp/keyValStore within the unit tests.
Support
We use Hyperledger Slack for communication regarding the SDK and any potential issues. Please join SDK related channels on Slack such as #fabric-sdk and #nodesdk. If you would like to file a bug report or submit a request for a feature please do so on Jira here.
Contributing
We welcome any contributions to the Hyperledger Fabric Node.js SDK project. If you would like to contribute please read the contribution guidelines here for more information.
License
Contributed to the Hyperledger Project under the Apache Software License 2.0.