Skip to content

Commit 8de58ed

Browse files
harrisobharrisob
committed
NodeSDK doc changes -- FAB-146
 Changes: modified: docs/Setup/NodeSDK-setup.md modified: docs/index.md new file: docs/nodeSDK/app-developer-env-setup.md new file: docs/nodeSDK/app-overview.md new file: docs/nodeSDK/node-sdk-guide.md new file: docs/nodeSDK/node-sdk-indepth.md new file: docs/nodeSDK/node-sdk-self-contained.md new file: docs/nodeSDK/sample-standalone-app.md new file: docs/nodeSDK/sample-web-app.md new sample file: examples/sdk/node/standalone-app.js new sample file: examples/sdk/node/web-app.js Change-Id: I65f0f470806bc66a28d151780e1f36cf05b509df Signed-off-by: Bret Harrison <[email protected]>
1 parent 9bf95d0 commit 8de58ed

11 files changed

+856
-307
lines changed

‎docs/Setup/NodeSDK-setup.md

100644100755
+5-306
Original file line numberDiff line numberDiff line change
@@ -18,312 +18,11 @@ execute the following command:
1818
npm install -g hfc
1919
```
2020

21-
## Overview
21+
See [Hyperledger fabric Node.js client SDK](../nodeSDK/node-sdk-guide.md) for more information.
2222

23-
The sections in this document are as follows:
2423

25-
* The [Getting Started](#getting-started) section is intended to help you
26-
quickly get a feel for HFC, how to use it, and some of its common capabilities.
27-
This is demonstrated by example.
24+
## Hyperledger fabric network
2825

29-
* The [Getting Set Up](#getting-set-up) section shows you how to set up up your
30-
environment and how to [run the unit tests](#running-unit-tests). Looking at the
31-
implementation of the unit tests will also help you learn more about the APIs by
32-
example, including asset management and confidentiality.
33-
34-
## Getting Started
35-
This purpose of this section is to help you quickly get a feel for HFC and how
36-
you may use it. It is not intended to demonstrate all of its power, but to
37-
demonstrate common use cases by example.
38-
39-
### Some basic terminology
40-
First, there is some basic terminology you should understand. In order to
41-
transact on a hyperledger blockchain, you must first have an identity which has
42-
been both **registered** and **enrolled**.
43-
44-
Think of **registration** as *issuing a user invitation* to join a blockchain.
45-
It consists of adding a new user name (also called an *enrollment ID*) to the
46-
membership service configuration. This can be done programatically with the
47-
`Member.register` method, or by adding the enrollment ID directly to the
48-
[membersrvc.yaml](https://github.com/hyperledger/fabric/blob/master/membersrvc/membersrvc.yaml)
49-
configuration file.
50-
51-
Think of **enrollment** as *accepting a user invitation* to join a blockchain.
52-
This is always done by the entity that will transact on the blockchain. This can
53-
be done programatically via the `Member.enroll` method.
54-
55-
### Learn by example
56-
The best way to quickly learn HFC is by example.
57-
58-
The following example demonstrates a typical web app. The web app authenticates
59-
a user and then transacts on a blockchain on behalf of that user.
60-
61-
```
62-
/**
63-
* This example shows how to do the following in a web app.
64-
* 1) At initialization time, enroll the web app with the block chain.
65-
* The identity must have already been registered.
66-
* 2) At run time, after a user has authenticated with the web app:
67-
* a) register and enroll an identity for the user;
68-
* b) use this identity to deploy, query, and invoke a chaincode.
69-
*/
70-
71-
// To include the package from your hyperledger fabric directory:
72-
// var hfc = require("myFabricDir/sdk/node");
73-
// To include the package from npm:
74-
// var hfc = require('hfc');
75-
var hfc = require('hfc');
76-
77-
// Create a client chain.
78-
// The name can be anything as it is only used internally.
79-
var chain = hfc.newChain("targetChain");
80-
81-
// Configure the KeyValStore which is used to store sensitive keys
82-
// as so it is important to secure this storage.
83-
// The FileKeyValStore is a simple file-based KeyValStore, but you
84-
// can easily implement your own to store whereever you want.
85-
chain.setKeyValStore( hfc.newFileKeyValStore('/tmp/keyValStore') );
86-
87-
// Set the URL for member services
88-
chain.setMemberServicesUrl("grpc://localhost:7054");
89-
90-
// Add a peer's URL
91-
chain.addPeer("grpc://localhost:7051");
92-
93-
// Enroll "WebAppAdmin" which is already registered because it is
94-
// listed in fabric/membersrvc/membersrvc.yaml with its one time password.
95-
// If "WebAppAdmin" has already been registered, this will still succeed
96-
// because it stores the state in the KeyValStore
97-
// (i.e. in '/tmp/keyValStore' in this sample).
98-
chain.enroll("WebAppAdmin", "DJY27pEnl16d", function(err, webAppAdmin) {
99-
if (err) return console.log("ERROR: failed to register %s: %s",err);
100-
// Successfully enrolled WebAppAdmin during initialization.
101-
// Set this user as the chain's registrar which is authorized to register other users.
102-
chain.setRegistrar(webAppAdmin);
103-
// Now begin listening for web app requests
104-
listenForUserRequests();
105-
});
106-
107-
// Main web app function to listen for and handle requests
108-
function listenForUserRequests() {
109-
for (;;) {
110-
// WebApp-specific logic goes here to await the next request.
111-
// ...
112-
// Assume that we received a request from an authenticated user
113-
// 'userName', and determined that we need to invoke the chaincode
114-
// with 'chaincodeID' and function named 'fcn' with arguments 'args'.
115-
handleUserRequest(userName,chaincodeID,fcn,args);
116-
}
117-
}
118-
119-
// Handle a user request
120-
function handleUserRequest(userName, chaincodeID, fcn, args) {
121-
// Register and enroll this user.
122-
// If this user has already been registered and/or enrolled, this will
123-
// still succeed because the state is kept in the KeyValStore
124-
// (i.e. in '/tmp/keyValStore' in this sample).
125-
// The attributes field is optional but can be used for role-based access control.
126-
// See fabric/sdk/node/test/unit/asset-mgmt-with-dynamic-roles.js as an example.
127-
var registrationRequest = {
128-
enrollmentID: userName,
129-
// Customize account & affiliation
130-
account: "bank_a",
131-
affiliation: "00001",
132-
attributes: [
133-
{ name: "bankAccountId", value: "12345-67890" }
134-
]
135-
};
136-
chain.registerAndEnroll( registrationRequest, function(err, user) {
137-
if (err) return console.log("ERROR: %s",err);
138-
// Issue an invoke request
139-
var invokeRequest = {
140-
// Name (hash) required for invoke
141-
chaincodeID: chaincodeID,
142-
// Function to trigger
143-
fcn: fcn,
144-
// Parameters for the invoke function
145-
args: args
146-
};
147-
// Invoke the request from the user object.
148-
var tx = user.invoke(invokeRequest);
149-
// Listen for the 'submitted' event
150-
tx.on('submitted', function(results) {
151-
console.log("submitted invoke: %j",results);
152-
});
153-
// Listen for the 'complete' event.
154-
tx.on('complete', function(results) {
155-
console.log("completed invoke: %j",results);
156-
});
157-
// Listen for the 'error' event.
158-
tx.on('error', function(err) {
159-
console.log("error on invoke: %j",err);
160-
});
161-
});
162-
}
163-
```
164-
165-
## Getting Set Up
166-
167-
First, you'll want to have a running peer node and CA. You can follow the
168-
instructions for setting up a network
169-
[here](https://github.com/hyperledger/fabric/blob/master/docs/Setup/ca-setup.md#Operating-the-CA),
170-
and start a single peer node and CA.
171-
172-
### Chaincode Deployment Directory Structure
173-
174-
To have the chaincode deployment succeed in network mode, you must properly set
175-
up the chaincode project outside of your Hyperledger Fabric source tree. The
176-
following instructions will demonstrate how to properly set up the directory
177-
structure to deploy *chaincode_example02* in network mode.
178-
179-
The chaincode project must be placed under the `$GOPATH/src` directory. For
180-
example, the
181-
[chaincode_example02](https://github.com/hyperledger/fabric/blob/master/examples/chaincode/go/chaincode_example02/chaincode_example02.go)
182-
project should be placed under `$GOPATH/src/` as shown below.
183-
184-
```
185-
mkdir -p $GOPATH/src/github.com/chaincode_example02/
186-
cd $GOPATH/src/github.com/chaincode_example02
187-
curl GET https://raw.githubusercontent.com/hyperledger/fabric/master/examples/chaincode/go/chaincode_example02/chaincode_example02.go > chaincode_example02.go
188-
```
189-
190-
After you have placed your chaincode project under the `$GOPATH/src`, you will need to vendor the dependencies. From the directory containing your chaincode source, run the following commands:
191-
192-
```
193-
go get -u github.com/kardianos/govendor
194-
cd $GOPATH/src/github.com/chaincode_example02
195-
govendor init
196-
govendor fetch github.com/hyperledger/fabric
197-
```
198-
199-
Now, execute `go build` to verify that all of the chaincode dependencies are
200-
present.
201-
202-
```
203-
go build
204-
```
205-
206-
Next, we will switch over to the node sdk directory in the fabric repo to run
207-
the node sdk tests, to make sure you have everything properly set up. Verify
208-
that the
209-
[chain-tests.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/chain-tests.js)
210-
unit test file points to the correct chaincode project path. The default
211-
directory is set to `github.com/chaincode_example02/` as shown below. If you
212-
placed the sample chaincode elsewhere, then you will need to change that.
213-
214-
```
215-
// Path to the local directory containing the chaincode project under $GOPATH
216-
var testChaincodePath = "github.com/chaincode_example02/";
217-
```
218-
219-
**Note:** You will need to run `npm install` the first time you run the sdk
220-
tests, in order to install all of the dependencies. Set the `DEPLOY_MODE`
221-
environment variable to `net` and run the chain-tests as follows:
222-
223-
```
224-
cd $GOPATH/src/github.com/hyperledger/fabric/sdk/node
225-
npm install
226-
export DEPLOY_MODE='net'
227-
node test/unit/chain-tests.js | node_modules/.bin/tap-spec
228-
```
229-
230-
### Enabling TLS
231-
232-
If you wish to configure TLS with the Membership Services server, the following
233-
steps are required:
234-
235-
- Modify `$GOPATH/src/github.com/hyperledger/fabric/membersrvc/membersrvc.yaml` as follows:
236-
237-
```
238-
server:
239-
tls:
240-
cert:
241-
file: "/var/hyperledger/production/.membersrvc/tlsca.cert"
242-
key:
243-
file: "/var/hyperledger/production/.membersrvc/tlsca.priv"
244-
```
245-
246-
To specify to the Membership Services (TLS) Certificate Authority (TLSCA) what
247-
X.509 v3 Certificate (with a corresponding Private Key) to use:
248-
249-
- Modify `$GOPATH/src/github.com/hyperledger/fabric/peer/core.yaml` as follows:
250-
251-
```
252-
peer:
253-
pki:
254-
tls:
255-
enabled: true
256-
rootcert:
257-
file: "/var/hyperledger/production/.membersrvc/tlsca.cert"
258-
```
259-
260-
To configure the peer to connect to the Membership Services server over TLS
261-
(otherwise, the connection will fail).
262-
263-
- Bootstrap your Membership Services and the peer. This is needed in order to
264-
have the file *tlsca.cert* generated by the member services.
265-
266-
- Copy `/var/hyperledger/production/.membersrvc/tlsca.cert` to
267-
`$GOPATH/src/github.com/hyperledger/fabric/sdk/node`.
268-
269-
*Note:* If you cleanup the folder `/var/hyperledger/production` then don't
270-
forget to copy again the *tlsca.cert* file as described above.
271-
272-
## Running Unit Tests
273-
HFC includes a set of unit tests implemented with the
274-
[tape framework](https://github.com/substack/tape). The
275-
[unit test script](https://github.com/hyperledger/fabric/blob/master/sdk/node/bin/run-unit-tests.sh)
276-
builds and runs both the membership service server and the peer node for you,
277-
therefore you do not have to start those manually.
278-
279-
### Running the SDK unit tests
280-
HFC includes a set of unit tests implemented with the
281-
[tape framework](https://github.com/substack/tape). To run the unit tests,
282-
execute the following commands:
283-
284-
cd $GOPATH/src/github.com/hyperledger/fabric
285-
make node-sdk-unit-tests
286-
287-
The following are brief descriptions of each of the unit tests that are being
288-
run.
289-
290-
#### registrar
291-
The [registrar.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/registrar.js)
292-
test case exercises registering users with Membership Services. It also tests
293-
registering a designated registrar user which can then register additional users.
294-
295-
#### chain-tests
296-
The [chain-tests.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/chain-tests.js)
297-
test case exercises the [chaincode_example02.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/chaincode_example02)
298-
chaincode when it has been deployed in both development mode and network mode.
299-
300-
#### asset-mgmt
301-
The [asset-mgmt.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/asset-mgmt.js)
302-
test case exercises the [asset_management.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/asset_management)
303-
chaincode when it has been deployed in both development mode and network mode.
304-
305-
#### asset-mgmt-with-roles
306-
The [asset-mgmt-with-roles.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/asset-mgmt-with-roles.js)
307-
test case exercises the [asset_management_with_roles.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/asset_management_with_roles)
308-
chaincode when it has been deployed in both development mode and network mode.
309-
310-
#### Troublingshooting
311-
If you see errors stating that the client has already been registered/enrolled,
312-
keep in mind that you can perform the enrollment process only once, as the
313-
enrollmentSecret is a one-time-use password. You will see these errors if you
314-
have performed a user registration/enrollment and subsequently deleted the
315-
cryptographic tokens stored on the client side. The next time you try to enroll,
316-
errors similar to the ones below will be seen.
317-
318-
```
319-
Error: identity or token do not match
320-
```
321-
```
322-
Error: user is already registered
323-
```
324-
325-
To address this, remove any stored cryptographic material from the CA server by
326-
following the instructions [here](https://github.com/hyperledger/fabric/blob/master/docs/Setup/Chaincode-setup.md#removing-temporary-files-when-security-is-enabled).
327-
You will also need to remove any of the cryptographic tokens stored on the
328-
client side by deleting the KeyValStore directory. That directory is
329-
configurable and is set to `/tmp/keyValStore` within the unit tests.
26+
First, you'll want to have a running peer node and member services. The
27+
instructions for setting up a network are
28+
[here](Network-setup.md). You may also use the [self contained environment](../nodeSDK/node-sdk-self-contained.md) that provides the network.

‎docs/index.md

100644100755
+1-1
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ relating to Chaincode.
157157
- [APIs - CLI, REST, and Node.js](API/CoreAPI.md)
158158
- [CLI](API/CoreAPI.md#cli): working with the command-line interface.
159159
- [REST](API/CoreAPI.md#rest-api): working with the REST API.
160-
- [Node.js SDK](https://github.com/hyperledger/fabric/blob/master/sdk/node/README.md): working with the Node.js SDK.
160+
- [Node.js SDK](nodeSDK/node-sdk-guide.md): working with the Node.js SDK.
161161

162162
# Operations guide
163163

‎docs/nodeSDK/app-developer-env-setup.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Setting up the Full Hyperledger fabric Developer's Environment
2+
3+
1. See [Setting Up The Development Environment](../dev-setup/devenv.md) to set up your development environment.
4+
5+
2. Issue the following commands to build the Hyperledger fabric client (HFC) Node.js SDK including the API reference documentation
6+
7+
```
8+
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node
9+
make all
10+
```
11+
12+
3. Issue the following command where your Node.js application is located if you wish to use the `require("hfc")`, this will install the HFC locally.
13+
14+
```
15+
npm install /opt/gopath/src/github.com/hyperledger/fabric/sdk/node
16+
```
17+
18+
Or use point directly to the HFC directly by using the following require in your code:
19+
```javascript
20+
require("/opt/gopath/src/github.com/hyperledger/fabric/sdk/node");
21+
```
22+
23+
24+
4. To see the API reference documentation which is built in step 2:
25+
```
26+
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
27+
```
28+
29+
The [Self Contained Node.js Environment](node-sdk-self-contained.md) will have the reference documentation already built and may be accessed by:
30+
```
31+
docker exec -it nodesdk /bin/bash
32+
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
33+
```

0 commit comments

Comments
 (0)