Repository files navigation

In this pattern, we will take a look at how you can query the world state of a peer within Hyperledger Fabric. Querying the world state is useful for seeing the current state of the assets in the network. For this pattern, we will be using the commercial paper use case from theHyperledger Fabric 1.4 documentation.

In this pattern, you will go through the process of creating indexes for the CouchDB world state database. You will then update the smart contract to include the logic to query the world state utilizing the newly created indexes. After updating and redeploying the smart contract, you will simulate 100 transactions to populate the world state with assets. Lastly, you will run a few queries utilizing the Node.js SDK and view the results that were returned.

In order to understand indexes, let's take a look at what happens when you query the world state. Say, for example, you want to find all assets owned by the user, "Bob". The database will search through each json document in the database one by one and return all documents that match user = "bob". This might not seem like a big deal but consider if you have millions of documents in your database. These queries might take a while to return the results as the database needs to go through each and every document. With indexes you create a reference that contains all the values of a specific field and which document contains that value. What this means is that instead of searching through every document, the database can just search the index for occurrences of the user "bob" and return the documents that are referenced.

It is important to note that every time a document is added to the database the index needs to be updated. Normally in CouchDB this is done when a query is received but in Hyperledger Fabric the indexes are updated every time a new block is committed which allows for faster querying. This is a process known asindex warming.

1. The developer creates the query indexes.
2. The developer adds query logic to the smart contract.
3. The IBM Blockchain extension for VS Code is then used to package, install, and instantiate the smart contract and indexes on the local Hyperledger Fabric network.
4. We simulate 100 transactions on the network to populate the world state with data.
5. The Node.js client application uses the Hyperledger Fabric SDK to send the query to the endorsing nodes to evaluate the query transaction.
6. The query results are returned.

• InstallVSCode version 1.38.0 or greater
• Install theIBM Blockchain platform extension for VSCode
• Node v8.x or v10.x and npm v6.x or greater
• Docker version v17.06.2-ce or greater
• Docker Compose v1.14.0 or greater

As mentioned before, this pattern extends the commercial paper example so we will need to package, install, and instantiate the commercial paper smart contract before we do anything else.

Follow the instructions in theSETUP.md document to get your local environment up and running with the commercial paper smart contract.

In the commercial paper use case, we will be querying by issuer, by owner, and by the current state of each asset.

1. First, create a directory under thecontract directory and name the new directoryMETA-INF.
2. Then, within the new directory, create another directory namedstatedb.
3. After that, create a new directory inside ofstatedb calledcouchdb.
4. Next, you guessed it, create a new directory inside ofcouchdb and name itindexes.

The directory structure should look like the image below.

1. Now we can start creating our index definitions. Create a new file in theindexes directory and name itissuerIndex.json
2. Then, copy the following code into that file:

{"index":{"fields":["issuer"]},"ddoc":"issuerIndexDoc","name":"issuerIndex","type":"json"}

This file states that the index will:

• keep track of theissuer field of each document
• store this index in a design document (ddoc) namedissuerIndexDoc
• is namedissuerIndex
• will be injson format

Now let's create two more index files.

3. Create a new file in theindexes directory and name itownerIndex.json
4. Then, copy the following code into that file:

{"index":{"fields":["owner"]},"ddoc":"ownerIndexDoc","name":"ownerIndex","type":"json"}

This index is very similar to the previous one for theissuer field but instead we are indexing theowner field.

5. Finally, create one last file in theindexes directory and name itcurrentStateIndex.json
6. Then, copy the following code into that file:

{"index":{"fields":["currentState"]},"ddoc":"currentStateIndexDoc","name":"currentStateIndex","type":"json"}

Your directory structure should now look like this:

And that's all it takes to build indexes. These indexes will be deployed the next time the smart contract is installed and instantiated.

Now we need to implement the query logic in the transactions of the smart contract. These transactions will be invoked by the Node.js SDK to execute our queries.

1. Using VSCode, open thepapercontract.js file found in this pattern repo.
2. Replace the contents ofcontract/lib/papercontract.js with the newpapercontract.js.

This updated contract already has the query logic added. Let's take a look at the transactions that were added.

• queryByIssuer, queryByOwner, and queryByCurrentState - These transactions are all similar in that they take one parameter and query the respective fields in the database. If you look at thequeryString for each transaction, you will notice that they are pointing to the design documents that hold the indexes that were created earlier. This query string is then passed toqueryWithQueryString to be executed.

• queryAll - This transaction does what it says. It gets all asset states from the world state database. This query string is then passed toqueryWithQueryString to be executed.

• queryWithQueryString - This function receives a query string as a parameter and is called by other transactions in the contract to do the actual querying. You can also do ad hoc queries with this transaction by passing in your own query strings.

Let's take a closer look at the code involved in making these queries.

Open the newpapercontract.js in VS Code and go to line 182.

Take a look at how thequeryString is structured. Theselector property is where you specify which field of the asset state you want to search against. In the case of ourqueryByOwner transaction, we are searching against theowner field and passing in a variable that represents the owner that we want to search for (e.g.MagnetoCorp).

Note: You can look at more examples for selectors inmore_about_selectors.

The next property to note isuse_index which allows you to specify a design document and index to use for the query.

Since we made changes to the smart contract we now need to re-deploy it to the peer.

1. Open upcontract/package.json in VS Code.

2. Change theversion property to0.0.2 and save the file.

3. Press theF1 key to see the different VS code options. ChooseIBM Blockchain Platform: Package Open Project.

If necessary, specify to create the package from thecontract folder.

4. Click theIBM Blockchain Platform extension button on the left. This will show the packaged contracts on top and the blockchain connections on the bottom.

5. The next step is to install this newly packaged smart contract - which is namedpapercontract@0.0.2. Find theFABRIC ENVIRONMENTS section and click on+ Install. Selectpapercontract@0.0.2 when prompted to select the package to install on the peer.

When the process completes, you should seepapercontract@0.0.2 under theInstalled section underFABRIC ENVIRONMENTS.

6. Next, go to theFABRIC ENVIRONMENTS section and find the instantiatedpapercontract@0.0.1. Right click on it and selectUpgrade Smart Contract

7. Select the newly installedpapercontract@0.0.2, when prompted to select the smart contract version to perform an upgrade with.

8. When asked about what function you'd like to call, enterinstantiate.

9. Then when it asks for arguments to pass, just press enter without typing anything.

10. SelectNo when prompted to provide a private data collection configuration file.

11. SelectDefault (single endorser, any org) when prompted to choose a smart contract endorsement policy.

12. If successful, you should now seepapercontract@0.0.2 in theFABRIC ENVIRONMENTS section underInstantiated.

Before we run the query program we need to do a few things first:

• Install dependencies
• Export the connection details and create the wallet
• Populate the world state

1. From the terminal, cd into theapplication directory of this repo.
2. Runnpm install.

1. From the IBM Blockchain Platform extension, go to theFABRIC GATEWAYS section and right click onLocal Fabric.

2. SelectExport Connection Profile.

3. In the dialog that appears, select thequeryPattern folder.

This process will export the connection profile which has the necessary information our application will need to interact with our blockchain network. Next we need to export our wallet.

4. From the IBM Blockchain Platform extension, go to theFABRIC WALLETS section at the bottom leftand right-click theLocal Fabric Wallet. Then selectExport Wallet. In the dialog that appears,choose thequeryPattern folder.

5. Switch back to the Explorer view by clicking on the paper icons at the top left of VS Code. You should now see the newly exportedlocal_fabric_wallet folder.

Your folder structure should look similar to the picture below, with the wallet and admin credentials which include a public and private key.

Right now the world state is empty and there is nothing to query. Let's add some entries to the ledger so that we can see some results when we run the queries.

1. From the terminal and while in theapplication folder, runnode setup.js.

This will run through a variety of transactions to populate the ledger. The process will take about 2-3 minutes. While this is running, take a look at thesetup.js file from within VS Code to see what the transactions are doing.

Now we can finally get around to querying the world state.

1. From the terminal, runnode query.js.

This query will return absolutely everything that is in the world state. While this might be valuable in some situations, in most cases you will want to search based on certain criteria such as by owner or by status.

2. From the terminal, runnode queryByOwner.js.

This query will return all assets that are currently owned by MagnetoCorp. If you take a look at thequeryByOwner.js file in VS Code you can see in line 66 that we are calling thequeryByOwner transaction defined in thepapercontract.js file and that we are passing inMagnetoCorp as the only argument. You can easily changeMagnetoCorp toDigiBank and rerun the query to get all assets owned by DigiBank instead.

3. From the terminal, runnode queryByCurrentState.js.

This query will return all commercial papers that have been bought. If you take a look atqueryByCurrentState.js in VS Code you can see in line 64 that this time we are calling thequeryByCurrentState transaction inpapercontract.js and passing in the status code of 2 as the only parameter. The status codes for the commercial papers are as follows:

• 1 = issued
• 2 = bought
• 3 = redeemed

It's also worth noting that to call the transactions in these query files we are using thecontract.evaluateTransaction() method instead ofcontract.submitTransaction(). This is becauseevaluateTransaction is only evaluated on the endorsing nodes and does not get submitted to the orderer and thus is not ordered into a block or committed. As such this method cannot update the ledger and is only used for querying.

In this section we took a look at how querying works in a Hyperledger Fabric network with CouchDB as the state database. First, we created indexes for commonly used queries. Then, we added the query logic to the smart contract. Finally, we ran some queries and took a look at what the world state contained.

This code pattern is licensed under the Apache License, Version 2. Separate third-party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to theDeveloper Certificate of Origin, Version 1.1 and theApache License, Version 2.

Apache License FAQ