Understanding Blockchain Private Data. A Hands-on Example

Hyperledger Fabric 1.2+ supports a recent feature called Private Data. In this Convector example I want to show how it works.

One of the main concerns the enterprise has around the Blockchain technology is the “public” by default state of most of the frameworks and networks out there.

Private Data is a feature that allows organizations in a network to share both “public” (accessible to all participants) and private data in the same channel.

A channel in Hyperledger Fabric is the actual ledger. It has policies and settings on its own, and is usually the result of multiple organizations connected together.

For example, 10 organizations in a commercial network may want to see every transaction between each of them, but would prefer to keep some specific data hidden from non involved organizations, i.e.: prices.

In that case, data can be stored in different collections. Through collections, data can be segregated according to policies hence some peers may have much more data, while all the peers involved will just store a hash of the related data.

There can be as many collections as needed, and these may contain different data defined in the smart contract.

For example, price may be stored by a collection called fullyPrivateData (accessible just to the directly involved organizations) then delivery details may be stored in a collection called semiPrivateDetails (accessible to the involved parties and the government) and finally in the regular ledger the rest of the details would be stored.

Want to read more about Private Data? https://hyperledger-fabric.readthedocs.io/en/release-1.4/private-data/private-data.html

Data is sent from applications to the peers through an object called transient data. Also, data in stores may have “purge” policies, making it possible to remove data based on regulatory policies (if needed). Immutability and proofs are kept with hashes.

The example

This example takes as a base the official Marbles example and enhances it with Convector.

Collections are defined in a JSON format.

As you can note in the previous JSON, policies includes the organizations that have access to the data as well as unique name and some other settings like blockToLive which defines when (and if) the data should be purged sometime.

The full example resides in here:

worldsibu/convector-example-private-data

That JSON file is passed during instantiation of the smart contract when installing or upgrading the code.

A good practice here is to receive the transient data as a unique model and then split it to store it in multiple collections (if needed). For example:

https://github.com/worldsibu/convector-example-private-data/blob/master/packages/product-cc/src/product.controller.ts

The data is received as transient data on the key marble when it’s gotten through the getTransientValue it will return the JSON version of the data ready to be processed. Convector will automatically parse it to the model type passed through getTransientValue<…>(‘key’, …).

Note that there are no params in the functions, as params in the function are public values accessible to all peers independent from the policies.

Then 2 new models are created here col1Data and col2Data each one of them receive the data they are supposed to store and when we proceed to save it we need to pass a parameter to the .save() function specifying which collection to use { privateCollection: '...' } .

You can see that the models won’t need anything special to be used on private data.

https://github.com/worldsibu/convector-example-private-data/blob/master/packages/product-cc/src/product.model.ts

When you need to retrieve the data from a function you can call the regular .getOne function passing a property privateCollection to tell the controller where to look for the data. In this case the id param is public since it’s no problem that every participant sees this data.

That referenced repo has a unit test to emulate a NodeJS backend making calls to create private data.

https://github.com/worldsibu/convector-example-private-data/blob/master/packages/product-cc/tests/product.e2e.ts

This unit test file passes transient data through .$config(...) . This example also queries data from the WorldState (CouchDB) to demonstrate how collections are stored separately based on policies.

But you could also query through the function we saw before like this:

Test the code example

Be sure to have Node 8.x (you can use NVM to manage multiple versions of Node if needed) and Docker installed.

$ git clone https://github.com/worldsibu/convector-example-private-data.git
$ cd convector-example-private-data
$ npm i

# Start a development blockchain on your computer
$ npm run env:restart

# Install the smart contract
$ npm run cc:start -- product

# Run a test
$ npm run test:e2e

There you go! You have officially created and queries private data in a real blockchain on your computer.

• Join the Convector community here on our Discord chat app.
• Find more about WorldSibu here.

Hyperledger Fabric is one of the most mature Blockchain frameworks out there. Convector Smart Contracts is one of the main smart contracts framework for permissioned blockchain projects.