diff --git a/README.md b/README.md index 6fda756f58..52a011c47a 100644 --- a/README.md +++ b/README.md @@ -30,14 +30,14 @@ applications on a development or CI workstation. The asset transfer series provides a series of sample smart contracts and applications to demonstrate how to store and transfer assets using Hyperledger Fabric. Each sample and associated tutorial in the series demonstrates a different core capability in Hyperledger Fabric. The **Basic** sample provides an introduction on how -to write smart contracts and how to interact with a Fabric network using the Fabric SDKs. The **Ledger queries**, **Private data**, and **State-based endorsement** -samples demonstrate these additional capabilities. Finally, the **Secured agreement** sample demonstrates how to bring all the capabilities together to securely +to write smart contracts and how to interact with a Fabric network using the Fabric SDKs. The **Ledger queries** (including asset history), **Private data**, and **State-based endorsement** +samples demonstrate these additional capabilities. 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, 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 | +| [Ledger queries](asset-transfer-ledger-queries) | The ledger queries sample demonstrates range queries, transaction updates using range queries (applicable for both LevelDB and CouchDB state databases), retrieving asset history using GetHistoryForKey, and deploying 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, TypeScript | 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, TypeScript, Java | TypeScript | | [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/main/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 | TypeScript | diff --git a/asset-transfer-ledger-queries/README.md b/asset-transfer-ledger-queries/README.md new file mode 100644 index 0000000000..4a28d8b153 --- /dev/null +++ b/asset-transfer-ledger-queries/README.md @@ -0,0 +1,66 @@ +# Asset transfer ledger queries sample + +The asset transfer ledger queries sample demonstrates the ledger query capabilities of Hyperledger Fabric, including range queries, rich queries (when using CouchDB), and retrieving asset history. + +## About the sample + +This sample includes smart contract and application code in multiple languages. It demonstrates several key features: + +- **Range Queries**: Retrieve a range of assets from the ledger. +- **Transaction Updates with Range Queries**: Safely update assets based on the results of a range query. +- **History Queries**: Use `GetHistoryForKey` to retrieve the entire history of an asset, including all previous owners and deletions. +- **Rich Queries**: Use the state database (CouchDB) to perform complex JSON queries. +- **CouchDB Indexes**: Package indexes with your chaincode to support efficient rich queries and sorting. +- **Pagination**: Handle large result sets using bookmarks and page sizes for both range and rich queries. + +For a detailed walk-through of this sample, refer to the [Using CouchDB as your state database](https://hyperledger-fabric.readthedocs.io/en/latest/couchdb_tutorial.html) tutorial in the Hyperledger Fabric documentation. + +### GetAssetHistory + +The `GetAssetHistory` function in the smart contract uses the `GetHistoryForKey` API to return every change made to an asset since it was first created on the ledger, providing full auditability for asset transfers. + +## Running the sample + +The Fabric test network is used to deploy and run this sample. Follow these steps in order: + +1. Create the test network and a channel (from the `test-network` folder). Use the `-s couchdb` flag to enable rich query support. + + ```shell + ./network.sh up createChannel -c mychannel -ca -s couchdb + ``` + +2. Deploy one of the smart contract implementations (from the `test-network` folder). + + - To deploy the **Go** chaincode implementation: + + ```shell + ./network.sh deployCC -ccn ledger -ccp ../asset-transfer-ledger-queries/chaincode-go/ -ccl go + ``` + + - To deploy the **JavaScript** chaincode implementation: + + ```shell + ./network.sh deployCC -ccn ledger -ccp ../asset-transfer-ledger-queries/chaincode-javascript/ -ccl javascript + ``` + + - To deploy the **TypeScript** chaincode implementation: + + ```shell + ./network.sh deployCC -ccn ledger -ccp ../asset-transfer-ledger-queries/chaincode-typescript/ -ccl typescript + ``` + +3. Run the application (from the `asset-transfer-ledger-queries/application-javascript` folder). + + ```shell + cd application-javascript + npm install + node app.js + ``` + +## Clean up + +When you are finished, you can bring down the test network (from the `test-network` folder). The command will remove all the nodes of the test network, and delete any ledger data that you created. + +```shell +./network.sh down +```