diff --git a/README.md b/README.md index 0edf4aeb..2f14bf51 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,21 @@ -[//]: # (SPDX-License-Identifier: CC-BY-4.0) +[//]: # "SPDX-License-Identifier: CC-BY-4.0" # Hyperledger Fabric Samples -You can use Fabric samples to get started working with Hyperledger Fabric, explore important Fabric features, and learn how to build applications that can interact with blockchain networks using the Fabric SDKs. To learn more about Hyperledger Fabric, visit the [Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/latest). +You can use Fabric samples to get started working with Hyperledger Fabric, explore important Fabric features, and learn how to build applications that can interact with blockchain networks using the Fabric SDKs. To learn more about Hyperledger Fabric, visit the [Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.2). + +Note that this branch contains samples for the Fabric v2.2 release. For the latest Fabric version, refer to the [main](https://github.com/hyperledger/fabric-samples) branch. ## Getting started with the Fabric samples -To use the Fabric samples, you need to download the Fabric Docker images and the Fabric CLI tools. First, make sure that you have installed all of the [Fabric prerequisites](https://hyperledger-fabric.readthedocs.io/en/latest/prereqs.html). You can then follow the instructions to [Install the Fabric Samples, Binaries, and Docker Images](https://hyperledger-fabric.readthedocs.io/en/latest/install.html) in the Fabric documentation. In addition to downloading the Fabric images and tool binaries, the Fabric samples will also be cloned to your local machine. +To use the Fabric samples, you need to download the Fabric Docker images and the Fabric CLI tools. First, make sure that you have installed all of the [Fabric prerequisites](https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html). You can then follow the instructions to [Install the Fabric Samples, Binaries, and Docker Images](https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html) in the Fabric documentation. In addition to downloading the Fabric images and tool binaries, the Fabric samples will also be cloned to your local machine. ## Test network The [Fabric test network](test-network) in the samples repository provides a Docker Compose based test network with two Organization peers and an ordering service node. You can use it on your local machine to run the samples listed below. You can also use it to deploy and test your own Fabric chaincodes and applications. To get started, see -the [test network tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html). +the [test network tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/test_network.html). ## Asset transfer samples and tutorials @@ -23,33 +25,31 @@ to write smart contracts and how to interact with a Fabric network using the Fab samples demonstrate these additional capabilities. Finally, the **Secured agreement** sample demonstrates how to bring all the capabilities together to securely transfer an asset in a more realistic transfer scenario. -| **Smart Contract** | **Description** | **Tutorial** | **Smart contract languages** | **Application languages** | -| -----------|------------------------------|----------|---------|---------| -| [Basic](asset-transfer-basic) | The Basic sample smart contract that allows you to create and transfer an asset by putting data on the ledger and retrieving it. This sample is recommended for new Fabric users. | [Writing your first application](https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html) | Go, JavaScript, TypeScript, Java | Go, JavaScript, TypeScript, Java | -| [Ledger queries](asset-transfer-ledger-queries) | The ledger queries sample demonstrates range queries and transaction updates using range queries (applicable for both LevelDB and CouchDB state databases), and how to deploy an index with your chaincode to support JSON queries (applicable for CouchDB state database only). | [Using CouchDB](https://hyperledger-fabric.readthedocs.io/en/latest/couchdb_tutorial.html) | Go, JavaScript | Java, JavaScript | -| [Private data](asset-transfer-private-data) | This sample demonstrates the use of private data collections, how to manage private data collections with the chaincode lifecycle, and how the private data hash can be used to verify private data on the ledger. It also demonstrates how to control asset updates and transfers using client-based ownership and access control. | [Using Private Data](https://hyperledger-fabric.readthedocs.io/en/latest/private_data_tutorial.html) | Go, Java | JavaScript | -| [State-Based Endorsement](asset-transfer-sbe) | This sample demonstrates how to override the chaincode-level endorsement policy to set endorsement policies at the key-level (data/asset level). | [Using State-based endorsement](https://github.com/hyperledger/fabric-samples/tree/master/asset-transfer-sbe) | Java, TypeScript | JavaScript | -| [Secured agreement](asset-transfer-secured-agreement) | Smart contract that uses implicit private data collections, state-based endorsement, and organization-based ownership and access control to keep data private and securely transfer an asset with the consent of both the current owner and buyer. | [Secured asset transfer](https://hyperledger-fabric.readthedocs.io/en/latest/secured_asset_transfer/secured_private_asset_transfer_tutorial.html) | Go | JavaScript | -| [Events](asset-transfer-events) | The events sample demonstrates how smart contracts can emit events that are read by the applications interacting with the network. | [README](asset-transfer-events/README.md) | JavaScript, Java | JavaScript | -| [Attribute-based access control](asset-transfer-abac) | Demonstrates the use of attribute and identity based access control using a simple asset transfer scenario | [README](asset-transfer-abac/README.md) | Go | None | - - +| **Smart Contract** | **Description** | **Tutorial** | **Smart contract languages** | **Application languages** | +| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | -------------------------------- | +| [Basic](asset-transfer-basic) | The Basic sample smart contract that allows you to create and transfer an asset by putting data on the ledger and retrieving it. This sample is recommended for new Fabric users. | [Writing your first application](https://hyperledger-fabric.readthedocs.io/en/release-2.2/write_first_app.html) | Go, JavaScript, TypeScript, Java | Go, JavaScript, TypeScript, Java | +| [Ledger queries](asset-transfer-ledger-queries) | The ledger queries sample demonstrates range queries and transaction updates using range queries (applicable for both LevelDB and CouchDB state databases), and how to deploy an index with your chaincode to support JSON queries (applicable for CouchDB state database only). | [Using CouchDB](https://hyperledger-fabric.readthedocs.io/en/release-2.2/couchdb_tutorial.html) | Go, JavaScript | Java, JavaScript | +| [Private data](asset-transfer-private-data) | This sample demonstrates the use of private data collections, how to manage private data collections with the chaincode lifecycle, and how the private data hash can be used to verify private data on the ledger. It also demonstrates how to control asset updates and transfers using client-based ownership and access control. | [Using Private Data](https://hyperledger-fabric.readthedocs.io/en/release-2.2/private_data_tutorial.html) | Go, Java | JavaScript | +| [State-Based Endorsement](asset-transfer-sbe) | This sample demonstrates how to override the chaincode-level endorsement policy to set endorsement policies at the key-level (data/asset level). | [Using State-based endorsement](https://github.com/hyperledger/fabric-samples/tree/master/asset-transfer-sbe) | Java, TypeScript | JavaScript | +| [Secured agreement](asset-transfer-secured-agreement) | Smart contract that uses implicit private data collections, state-based endorsement, and organization-based ownership and access control to keep data private and securely transfer an asset with the consent of both the current owner and buyer. | [Secured asset transfer](https://hyperledger-fabric.readthedocs.io/en/release-2.2/secured_asset_transfer/secured_private_asset_transfer_tutorial.html) | Go | JavaScript | +| [Events](asset-transfer-events) | The events sample demonstrates how smart contracts can emit events that are read by the applications interacting with the network. | [README](asset-transfer-events/README.md) | JavaScript, Java | JavaScript | +| [Attribute-based access control](asset-transfer-abac) | Demonstrates the use of attribute and identity based access control using a simple asset transfer scenario | [README](asset-transfer-abac/README.md) | Go | None | ## Additional samples Additional samples demonstrate various Fabric use cases and application patterns. -| **Sample** | **Description** | **Documentation** | -| -------------|------------------------------|------------------| -| [Commercial paper](commercial-paper) | Explore a use case and detailed application development tutorial in which two organizations use a blockchain network to trade commercial paper. | [Commercial paper tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html) | -| [Off chain data](off_chain_data) | Learn how to use the Peer channel-based event services to build an off-chain database for reporting and analytics. | [Peer channel-based event services](https://hyperledger-fabric.readthedocs.io/en/latest/peer_event_services.html) | -| [Token ERC-20](token-erc-20) | Smart contract demonstrating how to create and transfer fungible tokens using an account-based model. | [README](token-erc-20/README.md) | -| [Token UTXO](token-utxo) | Smart contract demonstrating how to create and transfer fungible tokens using a UTXO (unspent transaction output) model. | [README](token-utxo/README.md) | -| [High throughput](high-throughput) | Learn how you can design your smart contract to avoid transaction collisions in high volume environments. | [README](high-throughput/README.md) | -| [Auction](auction) | Run an auction where bids are kept private until the auction is closed, after which users can reveal their bid | [README](auction/README.md) | -| [Chaincode](chaincode) | A set of other sample smart contracts, many of which were used in tutorials prior to the asset transfer sample series. | | -| [Interest rate swaps](interest_rate_swaps) | **Deprecated in favor of state based endorsement asset transfer sample** | | -| [Fabcar](fabcar) | **Deprecated in favor of basic asset transfer sample** | | +| **Sample** | **Description** | **Documentation** | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| [Commercial paper](commercial-paper) | Explore a use case and detailed application development tutorial in which two organizations use a blockchain network to trade commercial paper. | [Commercial paper tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/tutorial/commercial_paper.html) | +| [Off chain data](off_chain_data) | Learn how to use the Peer channel-based event services to build an off-chain database for reporting and analytics. | [Peer channel-based event services](https://hyperledger-fabric.readthedocs.io/en/release-2.2/peer_event_services.html) | +| [Token ERC-20](token-erc-20) | Smart contract demonstrating how to create and transfer fungible tokens using an account-based model. | [README](token-erc-20/README.md) | +| [Token UTXO](token-utxo) | Smart contract demonstrating how to create and transfer fungible tokens using a UTXO (unspent transaction output) model. | [README](token-utxo/README.md) | +| [High throughput](high-throughput) | Learn how you can design your smart contract to avoid transaction collisions in high volume environments. | [README](high-throughput/README.md) | +| [Auction](auction) | Run an auction where bids are kept private until the auction is closed, after which users can reveal their bid | [README](auction/README.md) | +| [Chaincode](chaincode) | A set of other sample smart contracts, many of which were used in tutorials prior to the asset transfer sample series. | | +| [Interest rate swaps](interest_rate_swaps) | **Deprecated in favor of state based endorsement asset transfer sample** | | +| [Fabcar](fabcar) | **Deprecated in favor of basic asset transfer sample** | | ## License diff --git a/asset-transfer-basic/chaincode-external/README.md b/asset-transfer-basic/chaincode-external/README.md index 1b4a294e..f0032412 100755 --- a/asset-transfer-basic/chaincode-external/README.md +++ b/asset-transfer-basic/chaincode-external/README.md @@ -1,6 +1,6 @@ # Asset-Transfer-Basic as an external service -This sample provides an introduction to how to use external builder and launcher scripts to run chaincode as an external service to your peer. For more information, see the [Chaincode as an external service](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html) topic in the Fabric documentation. +This sample provides an introduction to how to use external builder and launcher scripts to run chaincode as an external service to your peer. For more information, see the [Chaincode as an external service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/cc_launcher.html) topic in the Fabric documentation. **Note:** each organization in a real network would need to setup and host their own instance of the external service. For simplification purpose, in this sample we use the same instance for both organizations. @@ -8,14 +8,16 @@ This sample provides an introduction to how to use external builder and launcher External Builders and Launchers is an advanced feature that typically requires custom packaging of the peer image so that it contains all the tools your builder and launcher require. For this sample we use very simple (and crude) shell scripts that can be run directly within the default Fabric peer images. -Open the `config/core.yaml` file at the top of the `fabric-samples` hierarchy. Note that this file comes along with the Fabric binaries, so if you don't have it, follow the [Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/latest/install.html) instructions in the Hyperledger Fabric documentation to download the binaries and config files. +Open the `config/core.yaml` file at the top of the `fabric-samples` hierarchy. Note that this file comes along with the Fabric binaries, so if you don't have it, follow the [Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html) instructions in the Hyperledger Fabric documentation to download the binaries and config files. Modify the field `externalBuilders` as the following: + ``` externalBuilders: - path: /opt/gopath/src/github.com/hyperledger/fabric-samples/asset-transfer-basic/chaincode-external/sampleBuilder name: external-sample-builder ``` + This configuration sets the name of the external builder as `external-sample-builder`, and the path of the builder to the scripts provided in this sample. Note that this is the path within the peer container, not your local machine. To set the path within the peer container, you will need to modify the container compose file to mount a couple of additional volumes. @@ -108,7 +110,6 @@ setGlobals 1 Edit the `chaincode.env` file in the `fabric-samples/asset-transfer-basic/chaincode-external` directory as necessary to set the `CHAINCODE_ID` variable to the chaincode package-id obtained above. - ## Running the Asset-Transfer-Basic external service To run the service in a container, from a different terminal, build an Asset-Transfer-Basic docker image, using the supplied `Dockerfile`, using the following command in the `fabric-samples/asset-transfer-basic/chaincode-external` directory: diff --git a/asset-transfer-events/README.md b/asset-transfer-events/README.md index 34e90bdd..1d938da0 100644 --- a/asset-transfer-events/README.md +++ b/asset-transfer-events/README.md @@ -8,64 +8,71 @@ a block is committed to the ledger, containing all the transaction details within that block. For more information about event services on per-channel basis, visit the -[Channel-based event service](https://hyperledger-fabric.readthedocs.io/en/latest/peer_event_services.html) +[Channel-based event service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/peer_event_services.html) page in the Fabric documentation. - ## About the Sample -This sample includes chaincodes and application code in multiple languages. +This sample includes chaincodes and application code in multiple languages. In a use-case similar to basic asset transfer ( see `../asset-transfer-basic` folder) -this sample shows sending and receiving of events during create/update/delete of an asset +this sample shows sending and receiving of events during create/update/delete of an asset and during transfer of an asset to a new owner. ### Application + The application demonstrates this, using two types of listeners in subsequent sections of `main` function: + 1. Contract Listener: listen for events in a specific Contract + - How to register a contract listener in an application, for chaincode events - How to get the chaincode event name and value from the chaincode event - How to retrieve the transaction and block information from the chaincode event 2. Block Listener: listen for block level events and parse private-data events + - How to register a block listener for full block events - How to retrieve the transaction and block information from the block event - How to register to receive private data associated with transactions, when registering a block listener - How to retrieve the private data collection details from the full block event - This section also shows how to connect to a Gateway with listener that will not listen for commit events. This may be useful when the application does not want to wait for the peer to commit blocks and notify the application. - Follow the comments in `application-javascript/app.js` file, and corresponding output on running this application. -Pay attention to the sequence of +Pay attention to the sequence of + - smart contract calls (console output like `--> Submit Transaction or --> Evaluate`) -- the events received at application end (console output like `<-- Contract Event Received: or <-- Block Event Received`) +- the events received at application end (console output like `<-- Contract Event Received: or <-- Block Event Received`) The listener will be notified of an event asynchronously. Notice that events will -be posted by the listener after the application code sends the transaction (or after the +be posted by the listener after the application code sends the transaction (or after the change is committed to the ledger), but during other application activity unrelated to the event. ### Smart Contract + The smart contract implements (in folder `chaincode-xyz`) following functions to support the application: + - CreateAsset - ReadAsset - UpdateAsset - DeleteAsset - TransferAsset -Note that the asset transfer implemented by the smart contract is a simplified scenario, without ownership validation, meant only to +Note that the asset transfer implemented by the smart contract is a simplified scenario, without ownership validation, meant only to demonstrate the use of sending and receiving events. - ## Running the sample Like other samples, we will use the Fabric test network to deploy and run ths sample. Follow these step in order. + - Create the test network and a channel -``` + +``` cd test-network ./network.sh up createChannel -c mychannel -ca ``` - Deploy the chaincode (smart contract) -``` + +``` # to deploy javascript version ./network.sh deployCC -ccs 1 -ccv 1 -ccep "OR('Org1MSP.peer','Org2MSP.peer')" -ccl javascript -ccp ./../asset-transfer-events/chaincode-javascript/ -ccn asset-transfer-events-javascript @@ -74,6 +81,7 @@ cd test-network ``` - Run the application + ``` cd application-javascript npm install @@ -82,8 +90,8 @@ npm install node app.js ``` - ## Clean up + When you are finished, you can bring down the test network. The command will remove all the nodes of the test network, and delete any ledger data that you created: ``` diff --git a/asset-transfer-events/application-javascript/app.js b/asset-transfer-events/application-javascript/app.js index 4a8a1c2f..037eda55 100644 --- a/asset-transfer-events/application-javascript/app.js +++ b/asset-transfer-events/application-javascript/app.js @@ -27,7 +27,7 @@ * before executing this application. * export HFC_LOGGING='{"debug":"console"}' * See the following on how the SDK is working with the Peer's Event Services - * https://hyperledger-fabric.readthedocs.io/en/latest/peer_event_services.html + * https://hyperledger-fabric.readthedocs.io/en/release-2.2/peer_event_services.html * * See the following for more details on using the Node SDK * https://hyperledger.github.io/fabric-sdk-node/release-2.2/module-fabric-network.html diff --git a/asset-transfer-private-data/chaincode-go/README.md b/asset-transfer-private-data/chaincode-go/README.md index f87a95c6..daf13039 100644 --- a/asset-transfer-private-data/chaincode-go/README.md +++ b/asset-transfer-private-data/chaincode-go/README.md @@ -1 +1 @@ -[Using Private Data tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/private_data_tutorial.html) +[Using Private Data tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/private_data_tutorial.html) diff --git a/asset-transfer-private-data/chaincode-java/src/main/java/org/hyperledger/fabric/samples/privatedata/AssetTransfer.java b/asset-transfer-private-data/chaincode-java/src/main/java/org/hyperledger/fabric/samples/privatedata/AssetTransfer.java index f95a234d..75018d35 100644 --- a/asset-transfer-private-data/chaincode-java/src/main/java/org/hyperledger/fabric/samples/privatedata/AssetTransfer.java +++ b/asset-transfer-private-data/chaincode-java/src/main/java/org/hyperledger/fabric/samples/privatedata/AssetTransfer.java @@ -40,7 +40,7 @@ import java.util.Map; * cd fabric-samples/test-network * ./network.sh up createChannel -ca -s couchdb * To deploy this chaincode to test-network, use the collection config as described in - * See * Change both -ccs sequence & -ccv version args for iterative deployment * ./network.sh deployCC -ccn private -ccp ../asset-transfer-private-data/chaincode-java/ -ccl java -ccep "OR('Org1MSP.peer','Org2MSP.peer')" -cccg ../asset-transfer-private-data/chaincode-go/collections_config.json -ccs 1 -ccv 1 */ diff --git a/asset-transfer-secured-agreement/chaincode-go/README.md b/asset-transfer-secured-agreement/chaincode-go/README.md index f65f09b6..e27ae43c 100644 --- a/asset-transfer-secured-agreement/chaincode-go/README.md +++ b/asset-transfer-secured-agreement/chaincode-go/README.md @@ -1 +1 @@ -[Secured asset transfer in Fabric Tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/secured_asset_transfer/secured_private_asset_transfer_tutorial.html) +[Secured asset transfer in Fabric Tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/secured_asset_transfer/secured_private_asset_transfer_tutorial.html) diff --git a/chaincode/fabcar/java/README.md b/chaincode/fabcar/java/README.md index 581c0a4c..2e2cedb2 100644 --- a/chaincode/fabcar/java/README.md +++ b/chaincode/fabcar/java/README.md @@ -1,7 +1,7 @@ # Java FabCar contract sample The directions for using this sample are documented in the Hyperledger Fabric -[Writing Your First Application](https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html) tutorial. +[Writing Your First Application](https://hyperledger-fabric.readthedocs.io/en/release-2.2/write_first_app.html) tutorial. The tutorial is based on JavaScript, however the same concepts are applicable when using Java. @@ -11,4 +11,4 @@ To install and instantiate the Java version of `FabCar`, use the following comma ./startFabric.sh javascript ``` -*NOTE:* After navigating to the documentation, choose the documentation version that matches your version of Fabric +_NOTE:_ After navigating to the documentation, choose the documentation version that matches your version of Fabric diff --git a/commercial-paper/README.md b/commercial-paper/README.md index 779dc6d9..e6576464 100644 --- a/commercial-paper/README.md +++ b/commercial-paper/README.md @@ -4,19 +4,17 @@ ## Introduction -This folder contains a structured set of smart contracts and application clients (ie. in a choice of languages, eg Node.js, Java, Go etc) relating to *Commercial Paper*, a finance 'instrument' (in Global Finance). At present, the Node.js sample contract in particular has further added functionality: an optional two-step authority check (see diagram below), when redeeming a commercial paper instance - and a range of sample ledger queries, to help consolidate your learning; both can be explored using the Node.js application client. +This folder contains a structured set of smart contracts and application clients (ie. in a choice of languages, eg Node.js, Java, Go etc) relating to _Commercial Paper_, a finance 'instrument' (in Global Finance). At present, the Node.js sample contract in particular has further added functionality: an optional two-step authority check (see diagram below), when redeeming a commercial paper instance - and a range of sample ledger queries, to help consolidate your learning; both can be explored using the Node.js application client. -While a more detailed 'explainer' of the Commercial Paper scenario (including use case analysis, code walkthrough & practices, logical/physical representation of ledger data etc) can be found in the [Hyperledger Fabric Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html), you don't have to read through this, just to try out this sample. There's also a [Wikipedia page](https://en.wikipedia.org/wiki/Commercial_paper) +While a more detailed 'explainer' of the Commercial Paper scenario (including use case analysis, code walkthrough & practices, logical/physical representation of ledger data etc) can be found in the [Hyperledger Fabric Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/tutorial/commercial_paper.html), you don't have to read through this, just to try out this sample. There's also a [Wikipedia page](https://en.wikipedia.org/wiki/Commercial_paper)
Key Objectives - * see a Commercial Paper use case in action - - * explore the key 'takeaways': understand differences between asset _state_ changes ('e.g. 'lifecycle') and transaction _inputs_* (e.g. 'inputs' during lifecycle) - - * try out a number of different query types: asset history, asset state, ownership, partial key, named query (criteria-based), ad-hoc queries (you supply a query string) - presently available in the Node.js sample only. +- see a Commercial Paper use case in action +- explore the key 'takeaways': understand differences between asset _state_ changes ('e.g. 'lifecycle') and transaction _inputs_\* (e.g. 'inputs' during lifecycle) +- try out a number of different query types: asset history, asset state, ownership, partial key, named query (criteria-based), ad-hoc queries (you supply a query string) - presently available in the Node.js sample only. - \* the smart contract uses these (along with business logic) to decide outcomes; some inputs change the asset _state_ (like 'ownership') ; some don't. + \* the smart contract uses these (along with business logic) to decide outcomes; some inputs change the asset _state_ (like 'ownership') ; some don't.

@@ -35,9 +33,8 @@ While a more detailed 'explainer' of the Commercial Paper scenario (including us

- - Expand the twisty below to see an overview diagram of a 'sample' Commercial paper marketplace - transactions, queries being executed by different organisations (we'll focus on two of these organisations) +Expand the twisty below to see an overview diagram of a 'sample' Commercial paper marketplace - transactions, queries being executed by different organisations (we'll focus on two of these organisations)
PaperNet Overview diagram - The sample commercial paper marketplace @@ -48,8 +45,7 @@ While a more detailed 'explainer' of the Commercial Paper scenario (including us But first, it might useful to explain Commercial Paper, an unsecured promissory note issued to obtain capital, and operates in global financial markets. A Commercial Paper instance is represented as an asset with a lifecycle, recorded on the blockchain - transactions change its _state_ (over time) and those transactions, naturally - have _inputs_. - -#### Explainers +#### Explainers
Commercial Paper - what is it briefly? @@ -73,42 +69,41 @@ I mentioned marketplace: even during the typical 6-9 month period, a commercial ## Scenario Overview -![](https://hyperledger-fabric.readthedocs.io/en/latest/_images/commercial_paper.diagram.1.png) +![](https://hyperledger-fabric.readthedocs.io/en/release-2.2/_images/commercial_paper.diagram.1.png) -In this tutorial two organizations, MagnetoCorp and DigiBank, trade commercial paper with each other on 'PaperNet', the marketplace represented by a Hyperledger Fabric blockchain network. Note that there are two alternative transaction flows - one which mirrors the [Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html) as described in Fabric documentation, and one which requires the authorised owner of the paper to complete a transfer following a request to buy the commercial paper - the latter example features an authorization check in the smart contract that ensures the transactor is from the organization that currently owns the commercial paper - they approve and complete the buy request. These are the commercial paper transaction lifecycles you can try out: +In this tutorial two organizations, MagnetoCorp and DigiBank, trade commercial paper with each other on 'PaperNet', the marketplace represented by a Hyperledger Fabric blockchain network. Note that there are two alternative transaction flows - one which mirrors the [Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/tutorial/commercial_paper.html) as described in Fabric documentation, and one which requires the authorised owner of the paper to complete a transfer following a request to buy the commercial paper - the latter example features an authorization check in the smart contract that ensures the transactor is from the organization that currently owns the commercial paper - they approve and complete the buy request. These are the commercial paper transaction lifecycles you can try out: ![Transaction Flow alternatives](img/transaction-flow.png) The tutorial exercises the commercial paper asset lifecycle: _issue_, _buy_ ( 1 to _n_ ) (or _buy_request_ / _transfer_ alternative), and _redeem_ transactions: the key 'takeaways' from the scenario are: -- understanding the _changes in state_ in the commercial paper asset (reflected in the ledger world state) which reaches maturity after 6 months. -- understanding the _transaction inputs_ for each transaction (some inputs change the asset _state_ - eg. ownership) and some _don't_ (e.g. purchase price) and not part of the asset - but importantly, the _inputs_ for a given transaction are recorded on the blockchain). -- understanding the importance of _queries_ such as: asset history, rich queries (criteria matching etc), transaction history (where the inputs are recorded) +- understanding the _changes in state_ in the commercial paper asset (reflected in the ledger world state) which reaches maturity after 6 months. +- understanding the _transaction inputs_ for each transaction (some inputs change the asset _state_ - eg. ownership) and some _don't_ (e.g. purchase price) and not part of the asset - but importantly, the _inputs_ for a given transaction are recorded on the blockchain). +- understanding the importance of _queries_ such as: asset history, rich queries (criteria matching etc), transaction history (where the inputs are recorded) -Client applications (CLI based) are used: +Client applications (CLI based) are used: - to perform the transactions - run queries (Node.js sample only) - examine the transaction inputs (as opposed to _states_) that are written to the ledger after you perform a transaction (using the Node.js listener). -This sample uses the `test-network` . You’ll act as Isabella, an employee of MagnetoCorp (Org2), who will issue a commercial paper on its behalf. You’ll then 'switch hats' to take the role of Balaji, an employee of DigiBank (Org1), who will buy this commercial paper, hold it for a period of time, and then redeem it with MagnetoCorp for a small profit or yield. Note that the smart contract sample doesn't enforce the actual hold period ; the user can, in fact, redeem the paper immediately. - +This sample uses the `test-network` . You’ll act as Isabella, an employee of MagnetoCorp (Org2), who will issue a commercial paper on its behalf. You’ll then 'switch hats' to take the role of Balaji, an employee of DigiBank (Org1), who will buy this commercial paper, hold it for a period of time, and then redeem it with MagnetoCorp for a small profit or yield. Note that the smart contract sample doesn't enforce the actual hold period ; the user can, in fact, redeem the paper immediately. ## Quick Start -Below are the quick start instructions for running the tutorial. As mentioned, if you're interested in a 'deeper dive' analysis and importance of the concepts, design, structure and implementation of the smart contract, they can be found in the [Hyperledger Fabric Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html). Suffice to say, you DON'T have to have read this, to do this tutorial. +Below are the quick start instructions for running the tutorial. As mentioned, if you're interested in a 'deeper dive' analysis and importance of the concepts, design, structure and implementation of the smart contract, they can be found in the [Hyperledger Fabric Commercial Paper Tutorial](https://hyperledger-fabric.readthedocs.io/en/release-2.2/tutorial/commercial_paper.html). Suffice to say, you DON'T have to have read this, to do this tutorial. This `README.md` file is in the `commercial-paper` directory, the source code for client applications and the contracts is in the `organization` directory. ### High-Level Overview of Steps -1) Install Binaries, Start the Hyperledger Fabric infrastructure +1. Install Binaries, Start the Hyperledger Fabric infrastructure - The Fabric 'test-network' will be used - this has two organizations 'Org1' and 'Org2' DigiBank will be Org1, and MagnetoCorp will be Org2. + The Fabric 'test-network' will be used - this has two organizations 'Org1' and 'Org2' DigiBank will be Org1, and MagnetoCorp will be Org2. -2) Install and Instantiate the Contracts +2. Install and Instantiate the Contracts -3) Run client applications in the roles of MagnetoCorp and DigiBank to trade the commercial paper +3. Run client applications in the roles of MagnetoCorp and DigiBank to trade the commercial paper - Issue the Paper as Magnetocorp (org2) - Buy the paper as DigiBank (org1) @@ -127,22 +122,21 @@ You will need a machine with the following - Java v8 if you want to run Java client applications - Maven to build the Java applications -You will need to install the `peer` cli binaries and cloned the `fabric-samples` repository. For more information see -[Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/latest/install.html) in the Hyperledger Fabric documentation. Once you have installed the cli binaries, ensure you have added the `bin` directory (for your `peer` commands used by scripts below) to your exported `PATH` variable in your `.bashrc` or `.profile` directory (per below). This is important as you will be opening a number of windows which will need PATH set. Finally, check that it finds the `peer` command in your PATH using the `which` command eg. +You will need to install the `peer` cli binaries and cloned the `fabric-samples` repository. For more information see +[Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html) in the Hyperledger Fabric documentation. Once you have installed the cli binaries, ensure you have added the `bin` directory (for your `peer` commands used by scripts below) to your exported `PATH` variable in your `.bashrc` or `.profile` directory (per below). This is important as you will be opening a number of windows which will need PATH set. Finally, check that it finds the `peer` command in your PATH using the `which` command eg. ``` export PATH=:$PATH which peer ``` +It is advised to have 3 terminal windows (consoles) open; -It is advised to have 3 terminal windows (consoles) open; +- one to monitor the infrastructure +- one for MagnetoCorp +- one for DigiBank. -* one to monitor the infrastructure -* one for MagnetoCorp -* one for DigiBank. - -Once you've cloned the `fabric-samples` - change to the `commercial-paper` directory in each window. +Once you've cloned the `fabric-samples` - change to the `commercial-paper` directory in each window. ``` git clone https://github.com/hyperledger/fabric-samples.git @@ -168,7 +162,7 @@ You can re-use this console window if you wish, but it is recommended to run a d ### Setup the Organizations' environments -The contract code is available as either JavaScript, Java or Go. You can use either one, and the choice of contract language does not affect the choice of client language. With the v2.0 Fabric chaincode lifecycle, this requires operations for both MagnetoCorp and Digibank admin. Open two windows in the fabric-samples/commercial paper directory, one for each organization. +The contract code is available as either JavaScript, Java or Go. You can use either one, and the choice of contract language does not affect the choice of client language. With the v2.0 Fabric chaincode lifecycle, this requires operations for both MagnetoCorp and Digibank admin. Open two windows in the fabric-samples/commercial paper directory, one for each organization. In your 'MagnetoCorp' window run the following commands, to set the shell environment variables needed to act as that organization. The leading '.' in the command sequence sets in your current environment - if you do not run this, you will not be able to package the chaincode. @@ -192,17 +186,14 @@ cd fabric-samples/commercial-paper/organization/digibank [_back to top_](#top) - ### Deploy the smart contract to the channel -You need to perform similar operations for _both_ organizations and for your language choice from the instructions below. For the different contract languages, the steps are very similar - the full set of steps are actually shown in the JavaScript section (see twisty). However, you will perform one or two different initial steps for Java or Go before completing the remaining common steps as instructed in those language sections. +You need to perform similar operations for _both_ organizations and for your language choice from the instructions below. For the different contract languages, the steps are very similar - the full set of steps are actually shown in the JavaScript section (see twisty). However, you will perform one or two different initial steps for Java or Go before completing the remaining common steps as instructed in those language sections. Note that the commands below make use of the `jq` utility for parsing output - download and install it from [the jq download page](https://stedolan.github.io/jq/download/). - **
For a JavaScript Contract** - Running in MagnetoCorp directory: ``` @@ -225,7 +216,7 @@ peer lifecycle chaincode approveformyorg --orderer localhost:7050 --ordererTLSH --sequence 1 \ --tls \ --cafile $ORDERER_CA - + peer lifecycle chaincode checkcommitreadiness --channelID mychannel --name papercontract -v 0 --sequence 1 ``` @@ -265,7 +256,7 @@ peer lifecycle chaincode commit -o localhost:7050 \ --ordererTLSHostnameOverride orderer.example.com \ --channelID mychannel --name papercontract -v 0 \ --sequence 1 \ - --tls --cafile $ORDERER_CA --waitForEvent + --tls --cafile $ORDERER_CA --waitForEvent ``` @@ -287,13 +278,12 @@ peer chaincode query -o localhost:7050 --ordererTLSHostnameOverride orderer.exa --peerAddresses localhost:9051 --tlsRootCertFiles ${PEER0_ORG2_CA} \ --tls --cafile $ORDERER_CA | jq '.' -C | more ``` +

- **
For a Java Contract:** - Before the `peer lifecycle chaincode package` command below, you will first need to change into each organization's `contract-java` directory and issue ``` @@ -302,7 +292,6 @@ Before the `peer lifecycle chaincode package` command below, you will first need Then complete the steps below. - Running in MagnetoCorp contract directory: ``` @@ -325,7 +314,7 @@ peer lifecycle chaincode approveformyorg --orderer localhost:7050 --ordererTLSH --sequence 1 \ --tls \ --cafile $ORDERER_CA - + peer lifecycle chaincode checkcommitreadiness --channelID mychannel --name papercontract -v 0 --sequence 1 ``` @@ -365,7 +354,7 @@ peer lifecycle chaincode commit -o localhost:7050 \ --ordererTLSHostnameOverride orderer.example.com \ --channelID mychannel --name papercontract -v 0 \ --sequence 1 \ - --tls --cafile $ORDERER_CA --waitForEvent + --tls --cafile $ORDERER_CA --waitForEvent ``` @@ -393,15 +382,13 @@ peer chaincode query -o localhost:7050 --ordererTLSHostnameOverride orderer.exa **
For a Go Contract** - Before the `peer lifecycle chaincode package` command step, you will need to change into each organization's `contract-go` directory and issue ``` go mod vendor ``` -Then complete the steps below. - +Then complete the steps below. Running in MagnetoCorp contract directory: @@ -425,7 +412,7 @@ peer lifecycle chaincode approveformyorg --orderer localhost:7050 --ordererTLSH --sequence 1 \ --tls \ --cafile $ORDERER_CA - + peer lifecycle chaincode checkcommitreadiness --channelID mychannel --name papercontract -v 0 --sequence 1 ``` @@ -465,7 +452,7 @@ peer lifecycle chaincode commit -o localhost:7050 \ --ordererTLSHostnameOverride orderer.example.com \ --channelID mychannel --name papercontract -v 0 \ --sequence 1 \ - --tls --cafile $ORDERER_CA --waitForEvent + --tls --cafile $ORDERER_CA --waitForEvent ``` @@ -488,15 +475,11 @@ peer chaincode query -o localhost:7050 --ordererTLSHostnameOverride orderer.exa --tls --cafile $ORDERER_CA | jq '.' -C | more ``` - -

- [_back to top_](#top) - ## Client Applications Note for Java applications, you will need to compile the Java Code using `maven`. Use this command in each application-java directory @@ -510,13 +493,14 @@ Note for JavaScript applications, you will need to install the dependencies firs ``` npm install ``` -> Note that there is NO dependency between the language of any one client application and any contract. Mix and match as you wish! + +> Note that there is NO dependency between the language of any one client application and any contract. Mix and match as you wish! The docker containers don't contain the node or Java runtimes; so it is best to exit the docker containers - but keep the windows open and run the applications locally. -As mentioned earlier in the Sample introduction section, transaction _inputs_ are recorded on the ledger, as well as any asset _state_ changes. Just *before* you run the _issue_ application script below - you need to launch a block 'listener' application that will show you these _inputs_, as you complete each transaction in the commercial paper lifecycle (eg. Paper Number: 00001, 00002 etc) . +As mentioned earlier in the Sample introduction section, transaction _inputs_ are recorded on the ledger, as well as any asset _state_ changes. Just _before_ you run the _issue_ application script below - you need to launch a block 'listener' application that will show you these _inputs_, as you complete each transaction in the commercial paper lifecycle (eg. Paper Number: 00001, 00002 etc) . -For the listener, its best to open a *new* terminal for this in the `commercial-paper/organization/magnetocorp/application` directory (javascript). Next, run the `addToWallet` step in the `issue` transaction below, to add Isabella's identity to the wallet - the listener will use this wallet. Once the listener is launched, it will show the inputs for transactions you will perform and which are committed to blocks (ie part of the ledger). Note: initially, the listener may show a spurious message, and then go into a _listening_ or 'wait' state. As transactions complete below, messages will be displayed by the listener - so keep an eye out. *After* adding Isabella's wallet, you can then launch the listener as follows: +For the listener, its best to open a _new_ terminal for this in the `commercial-paper/organization/magnetocorp/application` directory (javascript). Next, run the `addToWallet` step in the `issue` transaction below, to add Isabella's identity to the wallet - the listener will use this wallet. Once the listener is launched, it will show the inputs for transactions you will perform and which are committed to blocks (ie part of the ledger). Note: initially, the listener may show a spurious message, and then go into a _listening_ or 'wait' state. As transactions complete below, messages will be displayed by the listener - so keep an eye out. _After_ adding Isabella's wallet, you can then launch the listener as follows: ``` node cpListener.js @@ -524,12 +508,12 @@ node cpListener.js **
Issue the commercial paper** -The paper is issued by *MagnetoCorp* +The paper is issued by _MagnetoCorp_ -You can now run the applications to issue the commercial paper. Change to either the -`commercial-paper/organization/magnetocorp/application` directory (javascript) or `commercial-paper/organization/magnetocorp/application-java` directory (java) +You can now run the applications to issue the commercial paper. Change to either the +`commercial-paper/organization/magnetocorp/application` directory (javascript) or `commercial-paper/organization/magnetocorp/application-java` directory (java) -*Add the Identity to be used to the wallet* +_Add the Identity to be used to the wallet_ ``` node addToWallet.js @@ -537,7 +521,7 @@ node addToWallet.js java -cp target/commercial-paper-0.0.1-SNAPSHOT.jar org.magnetocorp.AddToWallet ``` -*Issue the Commercial Paper* +_Issue the Commercial Paper_ ``` node issue.js @@ -550,15 +534,14 @@ Don't forget to check the application listener for messages above!

- **
Buy the commercial paper** -_Buy_ is performed as *Digibank*; +_Buy_ is performed as _Digibank_; You can now run the applications to buy the paper. Change to either the -`commercial-paper/organization/digibank/application` directory or `commercial-paper/organization/digibank/application-java` +`commercial-paper/organization/digibank/application` directory or `commercial-paper/organization/digibank/application-java` -*Add the Identity to be used* +_Add the Identity to be used_ ``` node addToWallet.js @@ -566,7 +549,7 @@ node addToWallet.js java -cp target/commercial-paper-0.0.1-SNAPSHOT.jar org.digibank.AddToWallet ``` -*Buy the paper* +_Buy the paper_ ``` node buy.js @@ -576,7 +559,7 @@ java -cp target/commercial-paper-0.0.1-SNAPSHOT.jar org.digibank.Buy If you have just executed a `buy` transaction above - jump to the `redeem` transaction below - otherwise execute the _buy_/_transfer_ sequence as described earlier. -*Alternative: Request to Buy the paper (buy/transfer)* +_Alternative: Request to Buy the paper (buy/transfer)_ ``` node buy_request.js @@ -595,13 +578,12 @@ node transfer.js **
Redeem the commercial paper** -_Redeem_ is performed as *Digibank* - the current owner (buyer) in the lifecycle. +_Redeem_ is performed as _Digibank_ - the current owner (buyer) in the lifecycle. You can now run the applications to redeem the paper. Change to either the -`commercial-paper/organization/digibank/application` directory or `commercial-paper/organization/digibank/application-java` +`commercial-paper/organization/digibank/application` directory or `commercial-paper/organization/digibank/application-java` - -*Redeem* +_Redeem_ ``` node redeem.js @@ -612,35 +594,35 @@ java -cp target/commercial-paper-0.0.1-SNAPSHOT.jar org.digibank.Redeem

- **
Perform Queries: Ownership, Asset History etc (Node.js sample only) ** - - Having completed the full commercial paper lifecycle for one paper (paper number: 00001) some queries below won't show a lot of data - as an optional exercise, you can change the scripts above (paper number: 00002) to create another paper lifecycle and run the `queryapp` application below (change query 1 to the new CP number FYI), with more data available. As indicated, the query transactions mentioned are presently only available in the Node.js sample. - - Execute the Node.js application client script, which will run the following 5 queries, in order: - - - History of Commercial Paper (Note: the paper state is shown more descriptively eg. 'ISSUED', 'TRADING' and based on currentState values on ledger) - - Ownership of Commercial Papers - - Partial Key query, for Commercial papers in org.papernet.papers namespace belonging to MagnetoCorp - - Named Query: all redeemed papers in a state of 'redeemed' (currentState = 4) - - Named Query: all commercial papers with a face value > $4m - - From the `digibank/application` subdirectory run: - - ``` - node queryapp.js - ``` - + +Having completed the full commercial paper lifecycle for one paper (paper number: 00001) some queries below won't show a lot of data - as an optional exercise, you can change the scripts above (paper number: 00002) to create another paper lifecycle and run the `queryapp` application below (change query 1 to the new CP number FYI), with more data available. As indicated, the query transactions mentioned are presently only available in the Node.js sample. + +Execute the Node.js application client script, which will run the following 5 queries, in order: + +- History of Commercial Paper (Note: the paper state is shown more descriptively eg. 'ISSUED', 'TRADING' and based on currentState values on ledger) +- Ownership of Commercial Papers +- Partial Key query, for Commercial papers in org.papernet.papers namespace belonging to MagnetoCorp +- Named Query: all redeemed papers in a state of 'redeemed' (currentState = 4) +- Named Query: all commercial papers with a face value > $4m + +From the `digibank/application` subdirectory run: + +``` +node queryapp.js +``` +

When you're done with this section, return to the terminal where your Node.js _listener_ application is running, and terminate the process. ## Clean up + When you are finished using the Fabric test network and the commercial paper smart contract and applications, you can use the following command to clean up the network: ``` -./network-clean.sh +./network-clean.sh ``` [_back to top_](#top) diff --git a/test-network/README.md b/test-network/README.md index 418e467e..1f1de995 100644 --- a/test-network/README.md +++ b/test-network/README.md @@ -1,5 +1,5 @@ ## Running the test network -You can use the `./network.sh` script to stand up a simple Fabric test network. The test network has two peer organizations with one peer each and a single node raft ordering service. You can also use the `./network.sh` script to create channels and deploy chaincode. For more information, see [Using the Fabric test network](https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html). The test network is being introduced in Fabric v2.0 as the long term replacement for the `first-network` sample. +You can use the `./network.sh` script to stand up a simple Fabric test network. The test network has two peer organizations with one peer each and a single node raft ordering service. You can also use the `./network.sh` script to create channels and deploy chaincode. For more information, see [Using the Fabric test network](https://hyperledger-fabric.readthedocs.io/en/release-2.2/test_network.html). The test network is being introduced in Fabric v2.0 as the long term replacement for the `first-network` sample. -Before you can deploy the test network, you need to follow the instructions to [Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/latest/install.html) in the Hyperledger Fabric documentation. +Before you can deploy the test network, you need to follow the instructions to [Install the Samples, Binaries and Docker Images](https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html) in the Hyperledger Fabric documentation. diff --git a/test-network/addOrg3/addOrg3.sh b/test-network/addOrg3/addOrg3.sh index b56b92d1..b13a8fa2 100755 --- a/test-network/addOrg3/addOrg3.sh +++ b/test-network/addOrg3/addOrg3.sh @@ -81,7 +81,7 @@ function generateOrg3() { echo "ERROR! fabric-ca-client binary not found.." echo echo "Follow the instructions in the Fabric docs to install the Fabric Binaries:" - echo "https://hyperledger-fabric.readthedocs.io/en/latest/install.html" + echo "https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html" exit 1 fi diff --git a/test-network/network.sh b/test-network/network.sh index 66fe0493..5d0a4562 100755 --- a/test-network/network.sh +++ b/test-network/network.sh @@ -56,7 +56,7 @@ function checkPrereqs() { errorln "Peer binary and configuration files not found.." errorln errorln "Follow the instructions in the Fabric docs to install the Fabric Binaries:" - errorln "https://hyperledger-fabric.readthedocs.io/en/latest/install.html" + errorln "https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html" exit 1 fi # use the fabric tools container to see if the samples and binaries match your @@ -91,7 +91,7 @@ function checkPrereqs() { errorln "fabric-ca-client binary not found.." errorln errorln "Follow the instructions in the Fabric docs to install the Fabric Binaries:" - errorln "https://hyperledger-fabric.readthedocs.io/en/latest/install.html" + errorln "https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html" exit 1 fi CA_LOCAL_VERSION=$(fabric-ca-client version | sed -ne 's/ Version: //p')