quorum hero developers

Product Guides

Getting Started with ConsenSys Quorum

This product guide will walk through the deployment of the ConsenSys Quorum quickstart.

Let’s get started

This is a 6 part guide that will walk through the deployment of the ConsenSys Quorum quickstart. 

  • Part 1: Download all necessary dependencies required of your system to run the ConsenSys Quorum quickstart
  • Part 2: Download and start the ConsenSys Quorum quickstart
  • Part 3: Set up MetaMask and import a private key from the README
  • Part 4: Deploy a decentralized application to the private network
  • Part 5: Use the monitoring tools used in the quickstart
  • Part 6: Deploy a second smart contract to the network and send a private transaction

We will walk you through every step of the process, helping you get setup and providing helpful resources in case you get stuck. We will go into more detail than the documentation, where appropriate, to give you a deeper understanding of ConsenSys Quorum.

We will be referring to the documentation found here throughout this article and linking to other useful documentation if you would like to do deeper into any particular topic.

 

Introduction

What is ConsenSys Quorum?

ConsenSys Quorum is private/permissioned Ethereum with mainnet compatibility. It is the open-source protocol layer that delivers all the perks from Ethereum and addresses enterprise requirements. Bundled in a suite of Ethereum protocol clients (Hyperledger Besu and GoQuorum), private key managers, consensus mechanisms, transaction managers, APIs, plugins, libraries, deployment tools, etc.— with ConsenSys Quorum, you and your business have plenty of ways to customize your solution in production.

 

What is Ethereum? 

Ethereum is a public blockchain protocol for running smart contracts and building decentralized and/or distributed applications. For those just now hearing about Ethereum, it’s not just a cryptocurrency (Ether) — instead it’s an exciting open source software for building decentralized applications (DApps) and a general platform for smart contract development. This is a mindblowing decentralized global system that is not controlled by any single entity, prevents censorship, ensures transparency, is trustless, and removes any single points of failure that we currently have with a centralized client-server model.

It opens the door to a global financial system where an internet connection is all you need to access applications, products and services that operate in a trustless manner. Anyone can interact with the Ethereum network and participate in this digital economy, without the need for third parties.

 

Why Private/Permissioned Networks?

Inside an enterprise environment where parties (nodes) are exchanging large amounts of data, there is a demand for privacy, speed of transactions, and volume of transactions —in addition to leveraging public Ethereum’s smart contract features.

Existing enterprise systems can find use-cases for ConsenSys Quorum in supply chain, financial services, and healthcare. Multi-party and multi-organizational decision making via multi-signature contracts, real-time auditing, operational transparency, and data integrity use-cases are also possible. 

In the spirit of open source—any developer can go right to the Github, clone Hyperledger Besu, or GoQuorum, and start playing with ConsenSys Quorum. We also have a CLA (Contributor License Agreement) if you would like to contribute to the project. If you want to skip ahead, feel free to go through our developer docs!

 

Part 1: Install Dependencies

This section will walk you through the installation of dependencies. This is written for new developers or those unfamiliar with the technology used by Hyperledger Besu. Feel free to move at a pace that meets your needs.

MacOS users will start by installing NodeJS.

  • Open up the terminal. If this is the first that you are hearing the term terminal or directory, check out this guide to understanding how the shell, terminal, and directories on a computer will work. This will be important to understand how to navigate to the appropriate location on your computer.
    • Type in node –version to see if node is already installed on your computer.
    • If it is, you will get the version returned, for example:

GSwCQ Image 1

  • If node is not installed, you will see command not found: node.  Click on this link to go to the Nodejs website and download the MacOS installer (the file name will end in .pkg). Open it up and follow the instructions.
    • Once completed, restart your terminal. Then type node –version into the terminal again to confirm Node has properly installed.
    • If you are having problems with installation of node, you can access the help from the Node community via the “help” section of their GitHub, which includes links to their Slack channel.

MacOS users will now move onto installing Docker and Docker Compose

  • Open up the terminal
    • Type in docker –version to see if Docker is already installed on your computer.
    • If it is, you will get the version returned, for example:

GSwCQ Image 2

  • If Docker is not installed, you will see command not found: docker. Click on this link to go to Docker website and download Docker Desktop, which will include Docker and Docker Compose. Click the button for the appropriate chip within your Mac (The Apple chip was released in late 2020, if you have a Mac from before then it’s most likely an Intel chip)

GSwCQ Image 3

  • Follow along with the rest of the instructions in the link provided. For a tutorial on Docker itself, you can find that here, along with another Getting Started Guide here. If you run into issues, access the troubleshooting guide for Docker here
  • Open up Docker on your desktop, and you should see the following:

GSwCQ Image 4

  • Click on the Gear icon in the upper right corner

GSwCQ Image 6

  • Navigate to resources and ensure under the “Advanced” tab there is at least 6 GB of memory allocated to allow us to run all the examples in this Getting Started guide

GSwCQ Image 7

 

Linux users will need first need to install Docker Engine and then can follow the steps contained within the Docker Compose documentation.

After installing Docker, Linux users MUST follow the post-installation steps. Specifically, you need to add the user to the `docker` group, this step is often overlooked and every docker command will fail if this is not done.

 

Part 2: Install and Start the ConsenSys Quorum Quickstart

Open up the terminal and type in npx quorum-dev-quickstart and press enter (npx, as opposed to the command npm, will cut down on pollution on your computer by not installing dependencies)

GSwCQ Image 8

The quickstart will download and we will get the following prompt. For the purposes of this guide, we will use the Hyperledger Besu option, the first option.

GSwCQ Image 9

We are not trying out Codefi Orchestrate in this demo, so hit N for the prompt: Do you want to try out Codefi Orchestrate? Note: choosing yes will direct you to a login/registration page. [Y/n]

N

We do want to enable support for private transactions, so choose Y for the following prompt

Y

Do you wish to enable support for private transactions? [Y/n]

Y

Do you wish to enable support for logging with ELK (Elasticsearch, Logstash & Kibana)? [y/N]

This will look like:

GSwCQ image 10

The default directory that will be created to store these files will be named quorum-test-network, but you can rename the network on this next line:

Where should we create the config files for this network? Please choose either an empty directory, or a path to a new directory that does not yet exist. Default: ./quorum-test-network

For example, if I wanted to name the directory besu-test-network, I would enter ./besu-test-network and this would create a new directory called besu-test-network. The name of the new directory has to be a directory that does not exist, or else we will get an error.

  • The Quorum Quickstart will be installed on your computer in the directory named quorum-test-network
  • In the terminal, change directory to the quorum-test-network folder with the command cd quorum-test-network and the list out the sub-directories and files within this folder by typing the command ls to list the contents of quorum-test-network.

GSwCQ Image 11

  • Type in the command less README.md to see the instructions for the quickstart. Hit q to exit out of this view. Alternatively, you can see the READ.ME within the Quorum Dev Quickstart by viewing it within the ConsenSys Quorum GitHub Repository.

We are now going to start a private network that will run using Hyperledger Besu as the Ethereum client. This private network will run locally on our computer.

How will we know if we have successfully launched the network?

You should see the following (it may take a few minutes for this to load):

GSwCQ Image 12

Congratulations! You’ve spun up a private Ethereum network on your local computer using Hyperledger Besu.

 

Issues you may encounter and how to resolve them

If you have use Docker and Docker compose previously, particularly with a previous version of this quickstart, it is likely that you could run into an error upon start up::

ERROR: Pool overlaps with other one on this address space

If you get this error, it means that even though the docker containers are down, the networks may still exist. A longer thread explaining this issue can be found here.

A helpful resolution is to open up the command line and run the following command:

docker network prune

If that does not work, run the following combination of commands

docker-compose down

docker network prune

This will restart the Docker service, and hopefully resolve any overlap conflicts.

You can also run

run docker ps

to check for any overlapping registered containers. Once those are identified, use

docker rm

to remove the containers that are overlapping.

 

Part 3: Set up MetaMask

Now that we have the network up and running, we are going to set up our MetaMask wallet. If you already have MetaMask installed, you can skip this step. If not, follow the links below.

First, download the MetaMask browser extension. If you want to explore the features of MetaMask, this article can help you walk through how to send your first transaction using MetaMask.

Follow the instructions to set up your MetaMask account. For the purposes of this guide, the accounts we will be using will not have mainnet Ether. Still get in the habit of the following:

  • Copy down your seed phrase and store it in a secure location.
  • Do not share your seed phrase with anyone
  • Ensure that you can use your seed phrase to recover your account

MetaMask is a self-custodial wallet, so if you lose the seed phrase associated with it, you have lost access to that Ethereum account. If you give that seed phrase to someone, they now have control over that account. 

Open up your MetaMask account and navigate to the top of the browser extension click on the Ethereum Mainnet pill, which will look like this:

GSwCQ Image 13

From the drop-down select Localhost 8545. This is where the blockchain that we spun up with the quickstart is running. 

GSwCQ Image 14

If you want to learn more about connecting to different networks, this documentation from MetaMask will give you more insight on how it works.

MetaMask will allow us to send transactions between Ethereum accounts on our network, which we will call Externally Owned Accounts (EOA). When we ran the quickstart, the private blockchain network that we created was initialized with three accounts pre-loaded with test Ether. 

Looking into the quorum-test-network folder, you will see a structure within the config -> besu folder that shows the three member folders. In each folder is a keys folder, which has a file called key, which is the private key and key.pub, which is the public key. 

GSwCQ Image 15

We will open the file named “key” in member1 to see what is inside

GSwCQ Image 16

Here we see the private key, without the 0x prefix. The private key for this address would be

0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63

To import this address into our MetaMask, we will click the circle in the upper right corner of the MetaMask extension. This circle is called a favicon by the MetaMask team:

GSwCQ Image 17

We will hit the Import Account button:

GSwCQ Image 18

And will copy paste the private key, repeated below:

0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63 

Into the following field:

GSwCQ Image 19

This will create our account, which is pre-loaded with 200 test Ether:

GSwCQ Image 20

Below you can find information about the pre-loaded accounts in the event you want to import them:

Test Account 1 (address 0xfe3b557e8fb62b89f4916b721be55ceb828dbd73)

Private key to copy : 0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63

Initial balance : 200 Eth (200000000000000000000 Wei)

Test Account 2 (address 0x627306090abaB3A6e1400e9345bC60c78a8BEf57)

Private key to copy : 0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3

Initial balance : 90000 Eth (90000000000000000000000 Wei) 

Test Account 3 (address 0xf17f52151EbEF6C7334FAD080c5704D77216b732)

Private key to copy : 0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f

Initial balance : 90000 Eth (90000000000000000000000 Wei)

If we import these accounts and send 7 ETH from Test Account 1 to Test Account 2:

GSwCQ Image 21

We can see within the block explorer (accessible in our browser at http://localhost:25000/), Account 1 will decrement by 7 ETH:

GSwCQ Image 22

And that Account 2 will increase by just under 7 ETH

GSwCQ Image 23

Why didn’t Account 2 increase by 7 ETH? In this specific example, we have paid a transaction cost to send the Ether from one account to another. The transaction cost is called the gas, and is sometimes also called the gas fee. It is paid in increments of Ether called Wei, which is a fractional amount of ETH (1 Wei is 10^-18 ETH). There is a 21000 wei cost we pay to send Ether, and that is deducted from the transaction, which was the gas limit (the upper amount of gas we are willing to pay) stipulated for this transaction on MetaMask.

The private network we have created is a gas-less network, so there is no need to pay that fee, and we could reduce the gas limit to 0 and the transaction would go through. Understanding gas is critical for understanding how mainnet Ethereum works, as well as how it may be useful in other private networks we create, but for now, you can read a brief overview about gas here to better understand this concept.

How were these accounts created?

When we ran ./run.sh in our terminal, this script told docker-compose to run a .yml file, which contained information about the accounts, keys, and initialization information for our network in a genesis file. This genesis file – which is a .json file, provided our blockchain with information about the accounts, including the address and the amount of Ether they held. To see a genesis file in the quickstart, you can open and look at cliqueGenesis.json, which is in the quorum-test-network -> config -> besu directory. It looks like the following:

GSwCQ Extra 1

Within this file, I have highlighted the accounts that were created and the balances they were created with (the balances are in wei, not Ether. Remember 1 wei is 10 x -18 Ether). The quickstart and the scripts we run take care of creating these accounts, but we are able to create our own network where we can initialize accounts and configure our network to be customized to our particular use case.

 

Part 4: Deploy a Dapp to a Private Network

We are now going to deploy the pet shop decentralized application within the dapps folder of the quorum-test-network directory.

From your terminal, change directory to the folder dapps, and then into pet-shop cd dapps/pet-shop/

Within this directory, you will find a file called custom_config and a script called run_dapp.sh

GSwCQ Image 24

run_dapp.sh looks like the following:

GSwCQ Extra 2

This script is going to download from GitHub a Truffle box, which are pre-built dapps or templates for building your own dapp. In this case, the pet-shop dapp contains a smart contract called Adoption.sol, a front-end for this dapp written in react, which is a javascript library specifically for building front-ends and user interfaces, and the necessary dependencies needed to deploy the smart contract to an Ethereum network. The script is going to install truffle which is required in order to run commands using truffle, like truffle migrate. Truffle migrate is a command which specifically compiles our smart contract (Adoption.sol) into EVM bytecode and deploys it to the private network we have created. The script also downloads hdwallet-provider, which is used to create Ethereum accounts that we can use to interact with our decentralized application, and to send transactions on the private network we have created. The Ethereum accounts we have created will be imported into MetaMask. 

If you want to familiarize yourself with Truffle, you can walk through a tutorial here. For our current tutorial, we are using the private network created by the quorum quickstart as our local test blockchain network.

Within the folder custom_config, we have our Smart Contract – Adoption.sol

GSwCQ Image 25

Adoption.sol is a simple smart contract written in solidity. It looks like this:

GSwCQ Extra 3

A detailed description of this smart contract, along with a tutorial to build it can be found on the Truffle website. We are going to give you a quick overview of the contract in order to contextualize what happens once it is deployed to our private blockchain.

Let us take a look at the smart contract to better understand what it does:

pragma solidity ^0.5.0;

This first line of code tells us the smart contract is written for Solidity version 0.5.0 or higher and will be compatible with 0.5.0 and higher.

contract Adoption {

  address[16] public adopters;

These two lines of code do the following:

contract Adoption { declares an object of type contract. If you want to learn more about this object type, the Solidity documentation has a nice explanation of a Contract object. In this example, anything after the { (the brackets) will define the contract object – what it can do and what it can store on the blockchain.

address[16] public adopters; instantiates 16 addresses in an array which we have given the variable name “adopters”. These addresses are public, which means they can be accessed from outside of this contract as well as inside the contract. 

GSwCQ Extra 4

The first line is a comment, which will not be compiled but gives us information that the following function is for adopting a pet. The function, adopt, takes in a unsigned integer called petID, and checks if it is between 0 and 15. If it is, then the address at the location of the the petID within the adopters array is assigned to the account that called the adopt function (adopters[petID] = msg.sender is the specific code). Then the petID is returned.

The second function:

GSwCQ Extra 5

returns the array of addresses of the adopters. 

Now that we understand the smart contract,we run the command ./run_dapp.sh in the terminal within the pet-shop folder (which we should have already navigated into if you have been following along with each step). This is going to download all the dependencies, as well as compile and migrate our smart contract to the private network we have created using the Quorum quickstart, and spin up a front end that will allow us to “adopt” some group of 16 pets.

When you run it, there will be many downloads. You know that the script has successfully run when you reach the following:

GSwCQ Image 26

GSwCQ Image 27

Here we can see that Truffle has deployed the Migrationsmart contract and has now deployed it to the Hyperledger Besu based blockchain network we have spun up. If we take the contract address (0x345cA3e014Aaf5dcA488057592ee47305D9B3e10) that is listed here and navigate in a web browser to the block explorer (go to your browser and type in: http://localhost:25000/, then paste in the contract address: 0x345cA3e014Aaf5dcA488057592ee47305D9B3e10

We will see the following information about our deployed smart contract: 

GSwCQ Image 28

We can also use the block explorer to look up other information, like the externally owned account (in the >account field, which for our specific example is: 0x627306090abaB3A6e1400e9345bC60c78a8BEf57)

GSwCQ Image 29

We are able to see the ETH balance for that account. The ETH used in this example is not mainnet ETH, and it is only used for testing purposes. 

From this step, we hope that you can see how you can use the quickstart to deploy a decentralized application. Thus, the quickstart provides you with a template of being able to test a decentralized application of your own that you build. Let’s look at the dapp by going to our browser and typing in http://localhost:3001. We will arrive at the following screen, and MetaMask, which we installed in Part 3, will pop up for us and ask which account we want to connect to the application.

GSwCQ Image 30

Hitting adopt will prompt MetaMask to pop-up and adopt the pet:

GSwCQ Image 31

Since this is a gasless network, there is no fee associated with adopting a pet.

 

Issues you may encounter and how to solve them

When you run /.run_dapp.sh you may get the following error:

GSwCQ Image 32

The Error: ***Deployment Failed ***

Migrations –Wrong chainId means that within the deployment.js file, the chainID (which chain you are deploying to) was incorrectly specified. 

If that is the case, you should run the npx quorum-dev-quickstart again, as this means you are on an older version of the quickstart that does not have the most up to date versions of truffle and hd-wallet provider. Specifically, you need to be on 1.4.0 and above of hd-wallet provider. Versions 1.3.0 and 1.3.1 will not work work with the quickstart (though users will see that version 1.2.6 will still work with the quickstart). Make sure you are on version 0.0.21 of the quickstart or higher to avoid this issue.

If there is no UI that appears at localhost:3001 after running the script ./run_dapp.sh, navigate to the pet-shop-box folder:

cd pet-shop-box

and use the command

npm run dev

to start up the front end in our browser. If this runs successfully, we will get the following output in the terminal:

GSwCQ Image 33

Then you can navigate to the URLs listed in the output to see your application.

 

Part 5: Use Quickstart Monitoring Tools

There are monitoring tools included in the quickstart, which allow us to learn about how our private blockchain network is working. In part 4, we use the block explorer to look at the contract address of the deployed smart contract and the externally owned account that was responsible for deploying the smart contract to our network. Now we are going to explore two additional tools we can use to monitor our private network.

The first is Prometheus, an open-source monitoring tool that pulls data from the services that it is connected to – like nodes, databases, validators, servers, etc – and allows for that data from these services to be used in alerts and notifications. For example, if the memory usage of a certain node on your network exceeds a defined threshold, Prometheus is able to track this and alert you so you can take the appropriate action to ensure your network continues to run properly. In the case of a failure, Prometheus provides the data from the various services to allow for troubleshooting the issue. Prometheus pulls the data and stores it in a database, and then allows you or a data visualization tool to query that data.

When you install and run the quickstart, you will get access to Prometheus at http://localhost:9090/graph. If you enter this address into a web browser, you will see the following:

What exactly is Prometheus monitoring? To see the details, you can navigate to the config folder within your quorum-test-network directory. Opening the prometheus folder will reveal a prometheus.yml file. If you open that with a text editor (like Visual Studio Code or Vim) you will see that Prometheus is configured by the quickstart to scrape data from each validator, the rpcnode, and each member of the network every 15 seconds, and to store that data in the /metrics pathway, so that you can query it. Below is a screenshot of the first 28 of the total 129 lines of the prometheus.yml file.

GSwCQ Image 34 P5

The metrics we have access to can be seen by navigating and clicking on the curricular icon next to the Execute button in the right upper side of the screen.

GSwCQ Image 35

This will reveal the list of metrics that you can query Promtheus to return data for:

GSwCQ Image 36

If we choose ethereum_peer_count, it will return the number of peers on the network, which for this example is seven:

GSwCQ Image 37

If we type in the following query into the search bar (the part of the user interface with “Expression (press Shift+Enter for newlines)

besu_blockchain_difficulty_total

We will get back the following result of our query that will look similar to the below screenshot:

GSwCQ Image 38

This query is asking Prometheus to return data on the total difficulty for each participant node in our network. 

Prometheus has an integration with Granfana – an observability platform that takes in data – in this case from our private blockchain via Prometheus – and displays the outputs as visualizations. This allows us to make sense of what is occurring in our private network over time. The quickstart manages the connection of the data from Prometheus to pre-built dashboards in Grafana. If you navigate to http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All, the metrics from Prometheus will be displayed in a Grafana dashboard, providing us with the metrics in tabular and graphical format.

GSwCQ Image 39

This format makes exploring the data retrieved from Prometheus easier, and allows us to explore many metrics simultaneously.

Logs are available via Elasticsearch, Logstash, and Kibana (ELK).  ELK allows us to take in process, search, transform, and display data. In the Quickstart, this is configured specifically to ingest the Besu logs. As a reminder, navigating to the terminal and running the script

./list.sh

This script will show the various endpoints and services available in the quickstart:

GSwCQ Extra 6

Navigating to the Collated logs using Kibana endpoint using your browser

http://localhost:5601/app/kibana#/discover

This will pull up a Kibana dashboard:

GSwCQ Image 40

The logs are pulled automatically by the setup of the Quickstart. For more information about configuring Kibana on your own, you can see an overview within the documentation.

 

Part 6: Deploy a Smart Contract and Send a Private Transaction

Now we are going to take another smart contract and deploy it to our network. This will be a simple smart contract, and the goal of deploying it is to demonstrate the use of private transactions in the network.. This smart contract is already installed as part of the quickstart, and you can find it in the folder smart_contracts. 

Navigate to the smart_contracts folder using the command cd smart_contracts and you can look at that smart contract EventEmitter.sol:

GSwCQ Extra 7

Run the commands

npm install

node scripts/deploy.js

which will deploy the EventEmitter.sol smart contract that is in the contracts folder and send a private transaction from Member1 to Member3 of the network. The private transaction, in this example, is the sending of a value from Member1 to Member3. If we look inside the deploy.js script, we will see that the value being sent from Member1 to Member3 is 47 (see line 89 within the deploy.js file)

GSwCQ Image 41

Alt Text: Private Transaction example output

Looking at this output in the terminal, the following has occurred. The smart contract EventEmitter.sol was migrated and deployed to our network. This is confirmed by the following outputs:

GSwCQ Extra 8

Once the EventEmitter.sol contract was deployed, Member1 sent a private transaction to Member3. Member1 and Member3 can see the value within the transaction, which has been hashed, as

GSwCQ Extra 9

Member2, which was not included in the private transaction, is unable to see that value and gets a returned value of 0x. 

GSwCQ 10

What has been demonstrated here is that two Members can send transactions between each other, and other members cannot observe the contents of the transaction.

Congratulations! You have successfully run through many of the features of Hyperledger Besu.

For more information, please see the Documentation. In our next product guide, we will cover the quickstart using GoQuorum.

Need some help? Contact ConsenSys Quorum Support