Skip to content

Commit

Permalink
FAB-13271 Commercial Paper Updates
Browse files Browse the repository at this point in the history 
Change-Id: I82cb88af9837a1725e45489d9b6db2e61efb2bc1
Signed-off-by: Anthony O'Dowd <a_o-dowd@uk.ibm.com>
(cherry picked from commit 5c887e5)
  • Loading branch information
@ODOWDAIBM @denyeart
ODOWDAIBM authored and denyeart committed Dec 18, 2018
1 parent a467c65 commit ecb8e48
Show file tree
Hide file tree
Showing 3 changed files with 332 additions and 238 deletions.
217 changes: 123 additions & 94 deletions docs/source/developapps/application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,77 +2,98 @@

**Audience**: Architects, Application and smart contract developers

In our scenario, organizations access PaperNet using applications which invoke
**issue**, **sell** and **redeem** transactions defined in a commercial paper
smart contract. MagnetoCorp's application starts straightforwardly -- it just
needs to issue a commercial paper.

Let's walk through the commercial paper sample application provided with
Hyperledger Fabric. You can [download the sample](../install.html) and play with
it locally. It is written in JavaScript, but the logic is quite language
independent, so you'll be easily able to see what's going on! (The sample will
become available for Java and GOLANG as well.)

## Fabric SDK

Applications interact with PaperNet using the Fabric SDK. Here's a simplified
diagram of how an application invokes a smart contract:
An application can interact with a blockhain network by submitting transactions
to a ledger or querying ledger content. This topic covers the mechanics of how
an application does this; in our scenario, organizations access PaperNet using
applications which invoke **issue**, **sell** and **redeem** transactions
defined in a commercial paper smart contract. Even though MagnetoCorp's
application to issue a commercial paper is basic, it covers all the major points
of understanding.

In this topic, we're going to cover:

* [The application flow to invoke a smart contract](#basic-flow)
* [How an application uses a wallet and identity](#wallet)
* [How an application connects using a gateway](#gateway)
* [How to access a particular network](#network-channel)
* [How to construct a transaction request](#construct-request)
* [How to submit a transaction](#submit-transaction)
* [How to process a transaction response](#process-response)

To help your understanding, we'll make reference to the commercial paper sample
application provided with Hyperledger Fabric. You can [download
it](../install.html) and [run it locally](../tutorial/commercial_paper.html). It
is written in JavaScript, but the logic is quite language independent, so you'll
be easily able to see what's going on! (The sample will become available for
Java and GOLANG as well.)

## Basic Flow

An application interacts with a blockchain network using the Fabric SDK. Here's
a simplified diagram of how an application invokes a commercial paper smart
contract:

![develop.application](./develop.diagram.3.png) *A PaperNet application invokes
the commercial paper smart contract to submit the issue transaction*
the commercial paper smart contract to submit an issue transaction request.*

An application has to follow six basic steps to submit a transaction:

You're going to see how a typical application uses APIs provided by the Fabric
SDK to interact with a Fabric network. The SDK takes care of all the low-level
details, making it really easy for an application to submit a transaction
without worrying about the underlying network topology.
* Select an identity from a wallet
* Connect to a gateway
* Access the desired network
* Construct a transaction request for a smart contract
* Submit the transaction to the network
* Process the response

You'll find the application code in `application.js` --
[view it with your browser](https://github.com/hyperledger/fabric-samples), or
open it in your favourite editor if you've downloaded it. Spend a few moments
looking at the overall structure of the application; even with comments and
spacing, it's only 50 lines of code!
You're going to see how a typical application performs these six steps using the
Fabric SDK. You'll find the application code in the `issue.js` file. [View
it](https://github.com/hyperledger/fabric-samples/blob/master/commercial-paper/organization/magnetocorp/application/issue.js)
in your browser, or open it in your favourite editor if you've downloaded it.
Spend a few moments looking at the overall structure of the application; even
with comments and spacing, it's only 100 lines of code!

## Application wallet
## Wallet

Towards the top of `application.js`, you'll see two Fabric classes are brought
Towards the top of `issue.js`, you'll see two Fabric classes are brought
into scope:

```JavaScript
const { FileSystemWallet, Gateway } = require('fabric-network');
```

You can read about these classes in the
[node.js SDK on-line documentation](https://fabric-sdk-node.github.io/), but for
You can read about the `fabric-network` classes in the
[node SDK documentation](https://fabric-sdk-node.github.io/master/module-fabric-network.html), but for
now, let's see how they are used to connect MagnetoCorp's application to
PaperNet. The application uses the Fabric **Wallet** class as follows:

```JavaScript
const wallet = new FileSystemWallet('./wallet');
const wallet = new FileSystemWallet('../identity/user/isabella/wallet');
```

A Fabric wallet holds the digital equivalents of a government ID, driving
license or ATM card that you might find in your own wallet. Nowadays, wallets
hold mostly identity information rather than cash, and
[Fabric wallets](./wallet.html) are similar; they hold the digital certificates
that associate an application with a organization, thereby entitling them to
rights in a network channel.
See how `wallet` locates a [wallet](./wallet.html) in the local filesystem. The
identity retrieved from the wallet is clearly for a user called Isabella, who is
using the `issue` application. The wallet holds a set of identities -- X.509
digital certificates -- which can be used to access PaperNet or any other Fabric
network. If you run the tutorial, and look in this directory, you'll see the
identity credentials for Isabella.

See how `wallet` locates a filesystem wallet for `application.js`. The
`./wallet` directory holds a set of identities -- X.509 digital certificates --
which can be used to access a PaperNet or any other Fabric network. Look in this
directory and examine its contents.
Think of a [wallet](./wallet.html) holding the digital equivalents of your
government ID, driving license or ATM card. The X.509 digital certificates
within it will associate the holder with a organization, thereby entitling them
to rights in a network channel. For example, `Isabella` might be an
administrator in MagnetoCorp, and this could give her more privileges than a
different user -- `Balaji` from DigiBank. Moreover, a smart contract can
retrieve this identity during smart contract processing using the [transaction
context](./transactioncontext.html).

In PaperNet, the certificate provided by MagnetoCorp application user will
determine which operations they can perform, according to their role. Moreover,
the digital certificate can be retrieved during smart contract processing using
the [transaction context](./transactioncontext.md).
Note also that wallets don't hold any form of cash or tokens -- they hold
identities.

## Peer gateway
## Gateway

The second key class is a Fabric **Gateway**. Most importantly, a
[gateway](./gateway.html) identifies one or more peers that provide access to a
network -- in our case, PaperNet. See how `application.js` connects to its
gateway:
network -- in our case, PaperNet. See how `issue.js` connects to its gateway:

```JavaScript
await gateway.connect(connectionProfile, connectionOptions);
Expand All @@ -84,18 +105,34 @@ await gateway.connect(connectionProfile, connectionOptions);
[connection profile](./connectionprofile.html) that identifies
a set of peers as a gateway to PaperNet

* **connectionOptions**: a set of options used to control how `application.js`
* **connectionOptions**: a set of options used to control how `issue.js`
interacts with PaperNet

Spend a few moments examining the connection profile
`./gateway/connectionProfile.yaml`
[YAML](http://yaml.org/spec/1.2/spec.html#Preview) file.

Right now, we're only interested in the `channels:` and `peers:` sections:
See how the client application uses a gateway to insulate itself from the
network topology, which might change. The gateway takes care of sending the
transaction proposal to the right peer nodes in the network using the
[connection profile](./connectionprofile.html) and [connection
options](./connectionoptions.html).

Spend a few moments examining the connection
[profile](https://github.com/hyperledger/fabric-samples/blob/master/commercial-paper/organization/magnetocorp/gateway/networkConnection.yaml)
`./gateway/connectionProfile.yaml`. It uses
[YAML](http://yaml.org/spec/1.2/spec.html#Preview), making it easy to read.

It was loaded and converted into a JSON object:

```JavaScript
let connectionProfile = yaml.safeLoad(file.readFileSync('./gateway/connectionProfile.yaml', 'utf8'));
```

Right now, we're only interested in the `channels:` and `peers:` sections of the
profile: (We've modified the details slightly to better explain what's
happening.)

```YAML
channels:
PaperNet:
papernet:
peers:
peer1.magnetocorp.com:
endorsingPeer: true
Expand Down Expand Up @@ -132,35 +169,25 @@ The connection profile contains a lot of information -- not just peers -- but
network channels, network orderers, organizations, and CAs, so don't worry if
you don't understand all of it!

See how the connection profile is loaded and converted into a JSON object:

```JavaScript
connectionProfile = yaml.safeLoad(file.readFileSync('./gateway/connectionProfile.yaml', 'utf8'));
```

Let's now look at the `connectionOptions` object:
Let's now turn our attention to the `connectionOptions` object:

```JavaScript
let connectionOptions = {
identity: 'isabella.the.issuer@magnetocorp.com',
identity: userName,
wallet: wallet
}
```

See how it specifies that identity, `isabella.the.issuer@magnetocorp.com`, and
wallet, `wallet`, should be used to connect to a gateway.

Under the covers, the SDK will use the `connectionOptions` and `gateway` details
to send the transaction proposal to the right peers in the network. See how the
client application need not be concerned with this any more, the SDK will take
care of it all!
See how it specifies that identity, `userName`, and wallet, `wallet`, should be
used to connect to a gateway. These were assigned values earlier in the code.

There are other [connection options](./gateway.html) which enable the SDK to
act intelligently on behalf of an application. For example:
There are other [connection options](./connectionoptions.html) which an
application could use to instruct the SDK to act intelligently on its behalf.
For example:

```JavaScript
let connectionOptions = {
identity: 'isabella.the.issuer@magnetocorp.com',
identity: userName,
wallet: wallet,
eventHandlerOptions: {
commitTimeout: 100,
Expand All @@ -176,14 +203,14 @@ application after a single MagnetoCorp peer has confirmed the transaction, in
contrast to `strategy: EventStrategies.NETWORK_SCOPE_ALLFORTX` which requires
that all peers from MagnetoCorp and DigiBank to confirm the transaction.

If you'd like to, [read more](./gateway.html) about how connection options allow
applications to specify goal-oriented behaviour without having to worry about
how it is achieved.
If you'd like to, [read more](./connectionoptions.html) about how connection
options allow applications to specify goal-oriented behaviour without having to
worry about how it is achieved.

## Access network channel
## Network channel

The peers defined in the gateway `connectionProfile.yaml` provide
`application.js` with access to PaperNet. Because these peers can be joined to
`issue.js` with access to PaperNet. Because these peers can be joined to
multiple network channels, the gateway actually provides the application with
access to multiple network channels!

Expand Down Expand Up @@ -225,8 +252,8 @@ namespace of a contract: `org.papernet.commercialpaper`! We see how a
[namespace](./namespace.html) picks out a particular contract from a chaincode
file such as `papercontract.js` that contains many contracts. In PaperNet,
`papercontract.js` was installed and instantiated with the name `papercontract`,
and if you're interested, read how to install and instantiate a chaincode
containing multiple smart contracts [here](../chaincode4noah.html).
and if you're interested, [read how](../chaincode4noah.html) to install and
instantiate a chaincode containing multiple smart contracts.

If our application simultaneously required access to another contract in
PaperNet or BondNet this would be easy:
Expand All @@ -238,7 +265,7 @@ const bondContract = await network2.getContract('BondContract');
```

In these examples, note how we didn't use a qualifying namespace -- we assumed
only one contract per file.
only one smart contract per file.

Recall the transaction MagnetoCorp uses to issue its first commercial paper:

Expand All @@ -258,45 +285,47 @@ Let's now submit this transaction to PaperNet!
Submitting a transaction is a single method call to the SDK:

```JavaScript
const response = await contract.submitTransaction('issue', 'MagnetoCorp', '00001', '2020-05-31', '2020-11-30', '5000000');
const issueResponse = await contract.submitTransaction('issue', 'MagnetoCorp', '00001', '2020-05-31', '2020-11-30', '5000000');
```

See how the `submitTransaction()` parameters match those of the transaction
request. It's these values that will be passed to the `issue()` method in the
smart contract, and used to create a new commercial paper. Recall its signature
and basic structure:
smart contract, and used to create a new commercial paper. Recall its
signature:

```JavaScript
async issue(ctx, issuer, paperNumber, issueDateTime, maturityDateTime, faceValue) {...}
```

It might appear that a smart contract receives control shortly after the
application issues `submitTransaction()`, but that's not the case. Under the
covers, the SDK uses the `connectionOptions` and `gateway` details to send the
transaction proposal to the right peers in the network, where it can get the
required endorsements. But the application doesn't need to worry about any of
this -- it just issues `submitTransaction` and the SDK takes care of it all!
covers, the SDK uses the `connectionOptions` and `connectionProfile` details to
send the transaction proposal to the right peers in the network, where it can
get the required endorsements. But the application doesn't need to worry about
any of this -- it just issues `submitTransaction` and the SDK takes care of it
all!

Let's now turn our attention to how the application handles the response!

## Process response

See how the **issue** transaction returns a commercial paper response:
Recall from `papercontract.js` how the **issue** transaction returns a
commercial paper response:

```JavaScript
return cp.serialize();
return paper.toBuffer();
```

You'll notice a slight quirk -- the new commercial paper `cp` needs to be
returned as buffer using `serialize()` to be returned to the application. Notice
how `application.js` uses the class method `deserialize()` to rehydrate the
response buffer as a commercial paper:
You'll notice a slight quirk -- the new `paper` needs to be converted to a
buffer before it is returned to the application. Notice how `issue.js` uses the
class method `CommercialPaper.fromBuffer()` to rehydrate the response buffer as
a commercial paper:

```JavaScript
let paper = CommercialPaper.deserialize(response);
let paper = CommercialPaper.fromBuffer(issueResponse);
```

allowing `paper` to be used in a natural way in a descriptive completion
This allows `paper` to be used in a natural way in a descriptive completion
message:

```JavaScript
Expand Down
18 changes: 12 additions & 6 deletions docs/source/developapps/developing_applications.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,16 @@ Developing Applications
apis.md
designelements

This topic covers how to develop a client application and smart contract to solve a
business requirement using Hyperledger Fabric. Using a real world **Commercial
Paper** application, you'll learn about all the concepts and tasks required to
accomplish this goal. We assume that the blockchain network is already available.
This topic covers how to develop a client application and smart contract to
solve a business problem using Hyperledger Fabric. In a real world **Commercial
Paper** scenario, involving multiple organizations, you'll learn about all the
concepts and tasks required to accomplish this goal. We assume that the
blockchain network is already available.

The topic is designed for multiple audiences:

* Solution and application architect
* Client application developer
* Solution and application architect
* Client application developer
* Smart contract developer
* Business professional

Expand All @@ -35,5 +36,10 @@ business requirements, and then covers all the major technical activities
required to develop an application and smart contract to meet these
requirements.

If you'd prefer, you can try out the commercial paper scenario immediately,
following an abbreviated explanation, by running the commercial paper `tutorial
<../tutorial/commercial_paper.html>`_. You can return to this topic when you
need fuller explanations of the concepts introduced in the tutorial.

.. Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/

0 comments on commit ecb8e48

Please sign in to comment.