Build Status

Blockchain for maintaining Digital Assets

NOTE: This developer pattern creates a blockchain network on IBM Blockchain Platform version 2.5 using the Hyperledger Fabric version 1.4.

In this code pattern, we will be building a digital asset management application by creating and deploying a smart contract on a Hyperledger Fabric Network created on IBM Blockchain Platform. We will then interact with this application via a user interface created using VueJS.

Digital Asset Management Systems ensure that operations are only performed on a digital asset by individuals (or organizations) that have the right access rights and permissions for the asset. The digital asset is defined as the content (an image, a music file, a document, a video file, etc.) and its metadata. The metadata could be as simple as the name of the asset, the name of the owner of the asset and the date of creation of the asset, or it could be something more complex, such as extracted speech from a video (subtitles). In any Digital Asset Management system, there can be any number of users and these users can have the ability to perform various actions on the asset in the system based on the permissions they have. Examples of such actions that are being covered in this developer pattern are:

  1. User registration and user login.
  2. Viewing all existing assets in the system.
  3. Viewing assets owned by the user that is currently logged in.
  4. Uploading a new asset.
  5. Deleting an existing asset.
  6. Suggesting edits to an existing asset.
  7. Viewing suggested edits for an asset that is owned by the user that is currently logged in.
  8. Approving or denying suggeested edits for an asset that is owned by the user that is currently logged in.
  9. Allowing other users the permission to update an asset owned by the user that is currently logged in.
  10. Assigning another user as the owner of an asset that is owned by the user that is currently logged in.
  11. Downloading assets.

The large number of users (participants) in this use case, as well as the different kinds of actions (transactions) that can be executed indicate that this is a good use case for Blockchain. Blockchain will also allow for the history of the transactions to be maintained in the ledger, thereby ensuring that there is always a chain of record for any changes that have been made to any asset.

We will start by packaging the Node.js smart contract using the IBM Blockchain Platform Extension for VS Code. Next, we will create a Hyperledger Fabric Network on IBM Blockchain Platform where we will install and instantiate the smart contract. We will also set up an IBM Cloud Object Storage instance, where we can retain the digital assets uploaded to the Digital Asset Management application, and a fake SMTP testing server using Mailtrap.io to test the email notifications sent by the application. Finally, the VueJS web application, which makes use of the Hyperledger Fabric SDK, can be used to interact with the network.

When you have completed this code pattern, you will understand how to:

  • Package a blockchain smart contract using the IBM Blockchain Platform Extension for VS Code.
  • Set up a Hyperledger Fabric network on IBM Blockchain Platform.
  • Install and instantiate a smart contract package through IBM Blockchain Platform.
  • Set up an instance of the IBM Cloud Object Storage service and connect it with the Node.js application.
  • Test the blockchain network by executing a Node.js application with the Hyperledger Fabric SDK to interact with the deployed network by issuing transactions.

Architecture flow

  1. The Blockchain Operator sets up the IBM Blockchain Platform service.
  2. The IBM Blockchain Platform service creates a Hyperledger Fabric network on an IBM Cloud Kubernetes Service, and the Blockchain Operator installs and instantiates the smart contract on the network.
  3. The Node.js application server uses the Fabric SDK to interact with the deployed network on IBM Blockchain Platform, IBM Cloud Object Storage instance and the Mailtrap Server (fake SMTP testing server) and creates APIs for a web client.
  4. The Vue.js client uses the Node.js application API to interact with the network.
  5. The User interacts with the Vue.js web interface to interact with the digital asset management application.

Included components

  • IBM Blockchain Platform gives you total control of your blockchain network with a user interface that can simplify and accelerate your journey to deploy and manage blockchain components on the IBM Cloud Kubernetes Service.
  • IBM Cloud Kubernetes Service creates a cluster of compute hosts and deploys highly available containers. A Kubernetes cluster lets you securely manage the resources that you need to quickly deploy, update, and scale applications.
  • IBM Blockchain Platform Extension for VS Code is designed to assist users in developing, testing, and deploying smart contracts - including connecting to Hyperledger Fabric environments.
  • IBM Cloud Object Storage is a highly scalable cloud storage service, designed for high durability, resiliency and security.
  • Mailtrap.io is a test mail server solution that allows testing email notifications without sending them to the real users of your application.

Featured technologies

  • Hyperledger Fabric v1.4 is a platform for distributed ledger solutions, underpinned by a modular architecture that delivers high degrees of confidentiality, resiliency, flexibility, and scalability.
  • Node.js is an open source, cross-platform JavaScript run-time environment that executes server-side JavaScript code.
  • Vue.js 2.6.10 is an open-source JavaScript framework for building user interfaces and single-page applications.

Prerequisites

Watch the video - Introduction and Demo

Note: Click on the image below to view the video on YouTube. For Google Chrome, press the Ctrl key + the left mouse button and say Open link.

Running the application

Follow these steps to set up and run this code pattern. The steps are described in detail below.

Steps

  1. Clone the repo
  2. Package the smart contract
  3. Create the Mailtrap server
  4. Create IBM Cloud services
  5. Build a network
  6. Deploy Blockchain for maintaining Digital Assets Smart Contract on the network
  7. Connect application to the network
  8. Run the application

1. Clone the repo

Clone this repository in a folder your choice:

git clone https://github.com/IBM/Blockchain-for-maintaining-Digital-Assets.git

2. Package the smart contract

We will use the IBM Blockchain Platform extension on VS Code to package the smart contract.

  • Open Visual Studio code and open the contract folder from Blockchain-for-maintaining-Digital-Assets repository that was cloned earlier. It is important that you are opening the contract folder and not the entire Blockchain-for-maintaining-Digital-Assets directory; otherwise you will see an error that states that it doesn't understand what programming language you are using.

  • Press the F1 key to see the different VS code options. Choose IBM Blockchain Platform: Package Open Project.

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

  • Next, right click on the packaged contract (in this case, select blockchain-for-maintaining-digital-assets@0.0.1) to export it and choose Export Package.

  • Choose a location on your machine and save the .cds file. We will use this packaged smart contract later to deploy on the IBM Blockchain Platform service.

Now, we will start setting up the different services required for configuring our Hyperledger Fabric network on the IBM Cloud and for running our application using this network.

3. Create the Mailtrap server

  • Create the Mailtrap server. You can sign up using your Google or Github account or using your email address. Once the account has been created and you have logged in, create a new inbox by typing in an inbox name and clicking on Create Inbox.

4. Create IBM Cloud services

  • Create the IBM Cloud Kubernetes Service. You can find the service in the Catalog. For this code pattern, we can use the Free cluster, and give it a name. Note, that the IBM Cloud allows one instance of a free cluster which expires after 30 days. Note: it could take 20 minutes for the IBM Cloud Kubernetes Service setup to complete.


  • Create the IBM Cloud Object Storage service on the IBM Cloud. You can find the service in the Catalog, and give it a name.


  • Create the IBM Blockchain Platform service on the IBM Cloud. You can find the service in the Catalog, and give it a name.


  • After your kubernetes cluster is up and running, you can deploy your IBM Blockchain Platform on the cluster. Again - wait for the IBM Cloud Kubernetes service to indicate it was deployed. The IBM Blockchain Platform service walks through few steps and finds your cluster on the IBM Cloud to deploy the service on.


  • Once the Blockchain Platform is deployed on the Kubernetes cluster, you can launch the console to start configuring your blockchain network.

5. Build a network

We will build a network as provided by the IBM Blockchain Platform documentation. This will include creating a channel with a single peer organization with its own MSP and CA (Certificate Authority), and an orderer organization with its own MSP and CA. We will create the respective identities to deploy peers and operate nodes.

Create your peer organization CA

  • Navigate to the Nodes tab in the left navigation and click Add Certificate Authority +.
  • Click Create a Certificate Authority + and click Next.
  • Give it a CA display name of Org1 CA, a CA administrator enroll ID of admin and a CA administrator enroll secret of adminpw, then click Next.
  • Review the summary and click Add Certificate Authority.


Associate the peer organization CA admin identity

  • In the Nodes tab, select the Org1 CA once it is running (indicated by the green box in the tile).
  • Click Associate identity on the CA overview panel.
  • On the side panel, select the Enroll ID tab.
  • Provide an Enroll ID of admin and an Enroll secret of adminpw. Use the default value of Org1 CA Admin for the Identity display name.
  • Click Associate identity to associate the admin identity with the Org1 CA.


Use peer organization CA to register the peer and org1 admin identities

  • Select the Org1 CA Certificate Authority and ensure the admin identity that was created for the CA is visible in the table.
  • The next step is to register an admin for the organization "Org1". Click on the Register User + button. Give an Enroll ID of org1admin and an Enroll secret of org1adminpw. Set the Type for this identity as admin. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next.
  • Skip the section to add attributes to this user and click Register user.
  • Repeat the process to create an identity of the peer. Click on the Register User + button. Give an Enroll ID of peer1 and an Enroll secret of peer1pw. Set the Type for this identity as peer. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next.
  • Skip the section to add attributes to this user and click Register user.


Create the peer organization MSP definition

  • Navigate to the Organizations tab in the left navigation and click Create MSP definition +.
  • Enter the MSP display name as Org1MSP and the MSP ID as Org1MSP. Click Next.
  • Specify Org1 CA as the Root Certificate Authority. Click Next.
  • Select the New identity tab. Give the Enroll ID and Enroll secret for your organization admin, i.e. org1admin and org1adminpw respectively. Then, give the Identity name as Org1 Admin.
  • Click the Generate button to enroll this identity as the admin of your organization and add the identity to the wallet. Click Export to export the admin certificates to your file system. Click Next.
  • Review all the information and click Create MSP definition.


Create a peer

  • Navigate to the Nodes tab in the left navigation and click Add peer +.
  • Click Create a peer + and then click Next.
  • Give the Peer display name as Peer Org1 and click Next.
  • On the next screen, select Org1 CA as the Certificate Authority. Then, give the Peer enroll ID and Peer enroll secret as peer1 and peer1pw respectively. Select the Organization MSP as Org1MSP. Leave the TLS CSR hostname blank and select 1.4.7-0 in the drop-down for Fabric version. Click Next.
  • Provide Org1 Admin as the Peer administrator identity and click Next.
  • Review the summary and click Add peer.


Create your orderer organization CA

  • Navigate to the Nodes tab in the left navigation and click Add Certificate Authority +.
  • Click Create a Certificate Authority + and click Next.
  • Give it a CA display name of Orderer CA, a CA administrator enroll ID of admin and a CA administrator enroll secret of adminpw, then click Next.
  • Review the summary and click Add Certificate Authority.


Associate the orderer organization CA admin identity

  • In the Nodes tab, select the Orderer CA once it is running (indicated by the green box in the tile).
  • Click Associate identity on the CA overview panel.
  • On the side panel, select the Enroll ID tab.
  • Provide an Enroll ID of admin and an Enroll secret of adminpw. Use the default value of Orderer CA Admin for the Identity display name.
  • Click Associate identity to associate the admin identity with the Orderer CA.


Use orderer organization CA to register orderer and orderer admin identities

  • Select the Orderer CA Certificate Authority and ensure the admin identity that was created for the CA is visible in the table.
  • The next step is to register an admin for the organization "Orderer". Click on the Register User + button. Give an Enroll ID of ordereradmin and an Enroll secret of ordereradminpw. Set the Type for this identity as admin. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next.
  • Skip the section to add attributes to this user and click Register user.
  • Repeat the process to create an identity of the orderer. Click on the Register User + button. Give an Enroll ID of orderer and an Enroll secret of ordererpw. Set the Type for this identity as orderer. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next.
  • Skip the section to add attributes to this user and click Register user.


Create the orderer organization MSP definition

  • Navigate to the Organizations tab in the left navigation and click Create MSP definition +.
  • Enter the MSP display name as OrdererMSP and the MSP ID as OrdererMSP. Click Next.
  • Specify Orderer CA as the Root Certificate Authority. Click Next.
  • Select the New identity tab. Give the Enroll ID and Enroll secret for your organization admin, i.e. ordereradmin and ordereradminpw respectively. Then, give the Identity name as Orderer Admin.
  • Click the Generate button to enroll this identity as the admin of your organization and add the identity to the wallet. Click Export to export the admin certificates to your file system. Click Next.
  • Review all the information and click Create MSP definition.


Create an orderer

  • Navigate to the Nodes tab in the left navigation and click Add ordering service +.
  • Click Create an ordering service + and then click Next.
  • Give the Ordering service display name as Orderer and click Next.
  • On the next screen, select Orderer CA as the Certificate Authority. Then, give the Ordering service enroll ID and Ordering service enroll secret as orderer and ordererpw respectively. Select the Organization MSP as OrdererMSP. Leave the TLS CSR hostname blank and select 1.4.7-0 in the drop-down for Fabric version. Click Next.
  • Provide Orderer Admin as the Orderer administrator identity and click Next.
  • Review the summary and click Add ordering service.


Add organization as Consortium Member on the orderer to transact

  • Navigate to the Nodes tab, and click on the Orderer that was created.
  • Under Consortium Members, click Add organization +.
  • Select the Existing MSP ID tab. From the drop-down list, select Org1MSP (Org1MSP), as this is the MSP that represents the peer's organization "Org1".
  • Click Add organization.


Create the channel

  • Navigate to the Channels tab in the left navigation and click Create channel +.
  • Click Next.
  • Give the Channel name as mychannel. Select Orderer from the Ordering service drop-down list. Click Next.
  • Under Organizations, select Org1MSP (Org1MSP) from the drop-down list to add the organization "Org1" as a member of this channel. Click the Add button. Set the permissions for this member as Operator. Click Next.
  • Leave the Policy as the default value i.e. 1 out of 1. Click Next.
  • Select the Channel creator MSP as Org1MSP (Org1MSP) and the Identity as Org1 Admin. Click Next.
  • Review the summary and click Create channel.


Join your peer to the channel

  • Click on the newly created channel mychannel.
  • In the side panel that opens, under Choose from available peers, select Peer Org1. Once the peer is selected, a check mark will be displayed next to it. Ensure that Make anchor peer(s) is marked as Yes. Click Join channel.


6. Deploy Blockchain for maintaining Digital Assets Smart Contract on the network

Install a smart contract

  • Navigate to the Smart contracts tab in the left navigation and click Install smart contract +.
  • Click on Add file.
  • Browse to the location of the Blockchain for maintaining Digital Assets smart contract package file (it is probably named blockchain-for-maintaining-digital-assets@0.0.1.cds), which we packaged earlier using the IBM Blockchain Platform extension for Visual Studio code.
  • Once the contract is uploaded, click Install smart contract.


Instantiate smart contract

  • Under Installed smart contracts, find the smart contract from the list (Note: ours is called blockchain-for-maintaining-digital-assets) installed on our peer and click Instantiate from the overflow menu on the right side of the row.
  • On the side panel that opens, select the channel, mychannel on which to instantiate the smart contract. Click Next.
  • Select Org1MSP as the organization member to be included in the endorsement policy. Click Next.
  • Skip the Setup private data collection step and simply click Next.
  • Leave the Function name and Arguments blank.
  • Click Instantiate smart contract.


7. Connect application to the network

Connect with sdk through connection profile

  • Navigate to the Organizations tab in the left navigation, and click on Org1MSP.
  • Click on Download Connection Profile.
  • In the side panel that opens up, select Yes as the response for Include Org1 CA for user registration and enrollment?. Under Select peers to include, select Peer Org1. Then click Download connection profile. This will download the connection json which we will use to establish a connection between the Node.js web application and the Blockchain Network.


Create an application admin

  • Navigate to the Nodes tab in the left navigation, and under Certificate Authorities, choose Org1 CA.
  • Click on the Register User + button. Give an Enroll ID of app-admin and an Enroll secret of app-adminpw. Set the Type for this identity as client. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next.
  • Click on Add attribute +. Enter the attribute name as hf.Registrar.Roles and the attribute value as *. Click Register user.


Update application connection profile

  • Copy the connection profile you downloaded into the config folder.
  • Update the config.json file with:
    • The connection json file name you downloaded.
    • The enroll id and enroll secret for your app admin, which we earlier provided as app-admin and app-adminpw respectively.
    • The orgMSP ID, which we provided as Org1MSP.
    • The caName, which can be found in your connection json file under "organizations" -> "Org1MSP" -> certificateAuthorities". This would be like an IP address and a port.
    • The peerName, which can be found in your connection json file under "organizations" -> "Org1MSP" -> peers". This would be like an IP address and a port.
    • Update gateway discovery to { enabled: true, asLocalhost: false } to connect to IBM Blockchain Platform.
    • Go to your inbox on mailtrap.io and choose Nodemailer in the dropdown under Integrations. Obtain the host, port, auth.user and auth.pass values and specify them as smtpHost, smtpPort, smtpUserName and smtpPassword values in the config.json file.


    • Go to your IBM Cloud Object Storage instance and go to Buckets in the left hand navigation pane and click on Create bucket. Choose Standard under Predefined buckets. Provide a Unique bucket name as per the naming rules specified. Skip the Upload files step and click Next. Skip the Test bucket out step and click Next. Once the bucket is successfully created, obtain the following information from the webpage:
      • Under Bucket details, obtain the bucket name and specify it as cos_bucketName in the config.json.
      • Under Service Credentials, obtain the apikey and resource_instance_id values and specify them as the cos_apiKeyId and cos_serviceInstanceId respectively in the config.json.
      • Under Endpoints, obtain the Public endpoint and specify this value as the cos_endpoint in the config.json file


Once all this is done, your config.json should look something like this:

 {
    "channel_name": "mychannel",
    "smart_contract_name": "blockchain-for-maintaining-digital-assets",
    "connection_file": "Org1MSP_profile.json",
    "appAdmin": "app-admin",
    "appAdminSecret": "app-adminpw",
    "orgMSPID": "Org1MSP",
    "caName": "184.172.229.220:31844",
    "peerName": "184.172.229.220:30884",
    "gatewayDiscovery": { "enabled": true, "asLocalhost": false },
    "smtpHost": "smtp.mailtrap.io",
    "smtpPort": 2525,
    "smtpUserName": "cb49e25f8cbe5f",
    "smtpPassword": "3734c09cfdj05f",
    "senderEmail": "no-reply@digitalassetscodepattern.com",
    "cos_endpoint": "s3.us-south.cloud-object-storage.appdomain.cloud",
    "cos_apiKeyId": "QrC2rLBkjEmS755xR88_78seDgD2ai8DIQxVd74G21Je",
    "cos_serviceInstanceId": "crn:v1:bluemix:public:cloud-object-storage:global:a/86ac1b16b6f8b9639124a38d8edbd301:2f8d9627-46ff-46e9-a053-9d3e7121eedf::",
    "cos_bucketName": "blockchain-digital-assets-bucket"
 }

8. Run the application

In a new terminal, navigate to the server directory:

cd Blockchain-for-maintaining-digital-assets/web-app/server/

Build the node dependencies:

npm install

Enroll the admin and add identity to the wallet:

Note: This creates public and private key files for the app-admin in the _idwallet folder inside the config folder. If a folder named "app-admin" exists in the "_idwallet" folder, then the following command will not enroll the app-admin as it already exists in the wallet. Remove the app-admin folder and then run the following command.

node enrollAdmin.js

Start the server:

npm start

In a separate terminal, navigate to the client directory:

cd Blockchain-for-maintaining-digital-assets/web-app/client/

Build the node dependencies:

npm install

Start the client:

npm run serve

Once both the server and client have successfully started, the UI can be accessed at http://localhost:8080/?#/.

Main page of application:


You can have a look at the Introduction and Demo video for examples of actions that can be taken within the application.

Containerize the Application

Here are instructions for containerizing the application. The advantage to containerizing is all of the benefits one gets with kubernetes, to include standing up the front end (client) and backend (server) on a public ip address so anyone can access.

Here are the steps.

Build, tag, and push the image to a container registry:

   docker build -f ./Dockerfile -t commpaper .
   docker tag commpaper us.icr.io/commpaper/commpaper
   docker push us.icr.io/commpaper/commpaper

Ensure you have setup the kubernetes onfigmaps for your server

    cd Blockchain-for-maintaining-digital-assets/web-app/server/config
    kubectl delete configmap configuration
    kubectl create configmap configuration --from-file=./config.json --from-file=./ connection_profile.json   

Ensure you have setup the kubernetes configmaps for your client

    cd Blockchain-for-maintaining-digital-assets/web-app
    kubectl delete configmap images
    kubectl delete configmap assets
    kubectl create configmap assets --from-file=./client/src/assets/logo.png
    kubectl create configmap images --from-file=./client/public/images/favicon.ico   

Deploy your application to kubernetes

     cd Blockchain-for-maintaining-digital-assets/web-app
     kubectl delete -f Kubernetes-deployment.yaml
     kubectl apply -f kubernetes-deployment.yaml

Note: Make sure and edit the kubernetes-deployment.yaml file with the correct information.

Troubleshooting

If you get an error that says Error: Calling register endpoint failed with error [Error: self signed certificate], you can get past this by adding "httpOptions": {"verify": false} to the certificateAuthorities section of the connection profile that was downloaded from IBM Blockchain Platform.





Extending the code pattern

This application can be extended by:

  • Adding additional metadata for the digital assets.
  • Adding enhanced features for registering and logging in users.
  • Adding encryption to the IBM Cloud Object Storage bucket.

Links

License

This code pattern is licensed under the Apache Software 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 the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.

Apache Software License (ASL) FAQ