Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Last update: July 20, 2021

Quorum Developer Quickstart tutorial

The Quorum Developer Quickstart uses the Hyperledger Besu Docker image to run a private IBFT 2.0 network of Besu nodes managed by Docker Compose.

Warning

This tutorial runs a private network suitable for education or demonstration purposes and is not intended for running production networks.

Prerequisites

  • One of the following operating systems is required:
    • Linux on x86_64 architecture
    • macOS on an Intel processor (M1 processor not supported yet)
    • Windows 64-bit edition, with:
      • Windows Subsystem for Linux 2.
      • Docker desktop configured to use the WSL2-based engine.
  • Docker and Docker-compose.
  • Node.js v6+ LTS installed and ready to use. The best way to install this tool it to use NVM the Node Version Manager.
  • Truffle development framework installed.
  • cURL command line.
  • A Web browser with MetaMask installed. MetaMask is currently available for Chrome, Firefox, Opera, and Brave.

Important

Allow Docker up to 4G of memory or 6G if running the privacy examples. Refer to the Resources section in Docker for Mac and Docker Desktop for details.

Generate the tutorial blockchain configuration files

To create the tutorial docker-compose files and artifacts, run:

npx quorum-dev-quickstart

Follow the prompts displayed to run Hyperledger Besu and logging with ELK. Enter n for Codefi Orchestrate and private transactions.

Start the network

To start the network, go to the installation directory (quorum-test-network if you used the default value) and run:

./run.sh

The script builds the Docker images, and runs the Docker containers.

Four Besu IBFT 2.0 validator nodes and a non-validator node are created to simulate a base network.

When execution is successfully finished, the process lists the available services:

Services list

*************************************
Quorum Dev Quickstart
*************************************
----------------------------------
List endpoints and services
----------------------------------
JSON-RPC HTTP service endpoint      : http://localhost:8545
JSON-RPC WebSocket service endpoint : ws://localhost:8546
Web block explorer address          : http://localhost:25000/
Prometheus address                  : http://localhost:9090/graph
Grafana address                     : http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All
Kibana logs address                 : http://localhost:5601/app/kibana#/discover

For more information on the endpoints and services, refer to README.md in the installation directory.
****************************************************************

To display the list of endpoints again, run:

./list.sh

Block explorer

This tutorial uses a modified version of the Alethio Ethereum Lite Explorer.

Access the explorer at http://localhost:25000 as displayed when starting the private network.

The block explorer displays a summary of the private network, indicating four peers.

Click the block number to the right of Best Block to display the block details:

Block Details

You can explore blocks by clicking on the blocks under Bk on the left-hand side.

You can search for a specific block, transaction hash, or address by clicking the 🔍 in the top left-hand corner.

Explorer Search

Monitor nodes with Prometheus and Grafana

The sample network also includes Prometheus and Grafana monitoring tools to let you visualize node health and usage. You can directly access these tools from your browser at the addresses displayed in the endpoint list.

For more details on how to configure and use these tools for your own nodes, see our performances monitoring documentation, the Prometheus documentation and Grafana documentation.

Grafana

Run JSON-RPC requests

You can run JSON-RPC requests on:

  • HTTP with http://localhost:8545.
  • WebSockets with ws://localhost:8546.

Run with cURL

This tutorial uses cURL to send JSON-RPC requests over HTTP.

Run with Postman

You can also run all the requests with the Besu Postman collection.

Besu JSON-RPC APIs documentation in Postman format

Postman documentation

View the Besu JSON-RPC APIs documentation in the Postman format and obtain example requests in multiple coding languages.

Run in Postman

Click the following button to fork the collection and run requests directly on your local network.

Run in Postman.

Download collection

Alternatively you can download the JSON collection file.

Request the node version

Run the following command from the host shell:

curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://localhost:8545

The result displays the client version of the running node:

{
"jsonrpc" : "2.0",
"id" : 1,
"result" : "besu/v21.1.2/linux-x86_64/oracle_openjdk-java-11"
}
  • "jsonrpc" : "2.0" indicates that the JSON-RPC 2.0 spec format is used.
  • "id" : 1 is the request identifier used to match the request and the response. This tutorial always uses 1.
  • "result" contains the running Besu information:
    • v21.1.2 is the running Besu version number. This may be different when you run this tutorial.
    • linux-x86_64 is the architecture used to build this version.
    • oracle_openjdk-java-11 is the JVM type and version used to build this version. This may be different when you run this tutorial.

Successfully calling this method shows that you can connect to the nodes using JSON-RPC over HTTP.

From here, you can walk through more interesting requests demonstrated in the rest of this section, or skip ahead to Create a transaction using MetaMask.

Count the peers

Peers are the other nodes connected to the node receiving the JSON-RPC request.

Poll the peer count using net_peerCount:

curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' http://localhost:8545

The result indicates that there are four peers (our validators):

{
  "jsonrpc" : "2.0",
  "id" : 1,
  "result" : "0x4"
}

Request the most recent block number

Call eth_blockNumber to retrieve the number of the most recently synchronized block:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8545

The result indicates the highest block number synchronized on this node.

{
  "jsonrpc" : "2.0",
  "id" : 1,
  "result" : "0x2a"
}

Here the hexadecimal value 0x2a translates to decimal as 42, the number of blocks received by the node so far, about 2 minutes after the new network started.

Create a transaction using MetaMask

You can use MetaMask to send a transaction on your private network.

Security warning

Do not use the test accounts on Ethereum mainnet or any production network.

The following accounts are test accounts and their private keys are publicly visible in this documentation and in publicly available source code.

They are not secure and everyone can use them.

Using test accounts on Ethereum mainnet and production networks can lead to loss of funds and identity fraud.

In this documentation, we only provide test accounts for ease of testing and learning purposes; never use them for other purposes.

Always secure your Ethereum mainnet and any production account properly.

See for instance MyCrypto “Protecting Yourself and Your Funds” guide.

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)

Note

Besu doesn’t incorporate account management. To create your own account, you have to use a third-party tool, such as MetaMask.

After importing an existing test account, create another test account from scratch to use as the recipient for a test Ether transaction.

In MetaMask, select the new test account and copy its address.

In the Block Explorer, search for the new test account by clicking on the 🔍 and pasting the test account address into the search box.

The new test account displays with a zero balance.

Send test Ether from the first test account (containing test Ether) to the new test account (which has a zero balance).

Tip

You can use a zero gas price here as this private test network is a free gas network but the maximum amount of gas that can be used (the gas limit) for a value transaction must be at least 21000.

Refresh the Block Explorer page in your browser displaying the target test account.

The updated balance reflects the transaction completed using MetaMask.

Smart contract and dapp usage

You can use a demo dapp called Pet Shop, provided by Truffle.

The dapp runs a local website using Docker, and uses smart contracts deployed on the network.

The directory created by quorum-dev-quickstart includes a dapps directory with a pet-shop subdirectory, which contains the source code for the dapp, including the smart contracts, website, and configurations to run this tutorial.

With the blockchain running and MetaMask connected to Localhost 8545 via the browser, run the following command to start the Pet Shop dapp:

cd dapps/pet-shop
./run_dapp.sh

The script will:

  1. Install the dapp Node dependencies (you may see some warnings here, but it will not prevent the dapp from running).
  2. Compile the contracts.
  3. Deploy the contracts to the blockchain.
  4. Run tests.
  5. Build and run a Docker image to serve the dapp website.

./run_dapp.sh example output

Compiling your contracts...
===========================
> Compiling ./contracts/Adoption.sol
> Compiling ./contracts/Migrations.sol
> Artifacts written to /Users/demo/quorum-test-network/dapps/pet-shop/pet-shop-box/build/contracts
> Compiled successfully using:
    - solc: 0.5.16+commit.9c3226ce.Emscripten.clang

Starting migrations...
======================
> Network name:    'quickstartWallet'
> Network id:      1337
> Block gas limit: 16234336 (0xf7b760)

1_initial_migration.js
======================

    Deploying 'Migrations'
    ----------------------
    > transaction hash:    0xdd27f5bc5b0c4a42bb4f4d9ba00b4d33742de10ba8f03484cbf095ee824ba11a
    > Blocks: 0            Seconds: 0
    > contract address:    0xFB88dE099e13c3ED21F80a7a1E49f8CAEcF10df6
    > block number:        2747
    > block timestamp:     1618000437
    > account:             0x627306090abaB3A6e1400e9345bC60c78a8BEf57
    > balance:             89999.97435026
    > gas used:            221555 (0x36173)
    > gas price:           20 gwei
    > value sent:          0 ETH
    > total cost:          0.0044311 ETH


    > Saving migration to chain.
    > Saving artifacts
       -------------------------------------
    > Total cost:           0.0044311 ETH

2_deploy_contracts.js
=====================

    Deploying 'Adoption'
    --------------------
    > transaction hash:    0xd6f5b11807a0727a92b6063c95b9101769d310592b0d3cf35d6df233d05d50e6
    > Blocks: 0            Seconds: 0
    > contract address:    0xf204a4Ef082f5c04bB89F7D5E6568B796096735a
    > block number:        2749
    > block timestamp:     1618000441
    > account:             0x627306090abaB3A6e1400e9345bC60c78a8BEf57
    > balance:             89999.968712
    > gas used:            239915 (0x3a92b)
    > gas price:           20 gwei
    > value sent:          0 ETH
    > total cost:          0.0047983 ETH


    > Saving migration to chain.
    > Saving artifacts
       -------------------------------------
    > Total cost:           0.0047983 ETH

Summary
=======
> Total deployments:   2
> Final cost:          0.0092294 ETH


Using network 'quickstartWallet'.

Compiling your contracts...
===========================
> Compiling ./test/TestAdoption.sol

TestAdoption
✓ testUserCanAdoptPet (2071ms)
✓ testGetAdopterAddressByPetId (6070ms)
✓ testGetAdopterAddressByPetIdInArray (6077ms)

3 passing (37s)

After these tests are successful, the script builds a container for the Pet Shop dapp and deploys it, binding it to port 3001 on your system.

Sending build context to Docker daemon  489.4MB
Step 1/5 : FROM node:12.14.1-stretch-slim
---> 2f7e25ad14ea
Step 2/5 : EXPOSE 3001
---> Using cache
---> 2ef0665a040a
Step 3/5 : WORKDIR /app
---> Using cache
---> e8e97cedb575
Step 4/5 : COPY . /app
---> f70e4265e598
Step 5/5 : CMD npm run dev
---> Running in 3c6e8bdb3f3b
Removing intermediate container 3c6e8bdb3f3b
---> ce2588e47ab0
Successfully built ce2588e47ab0
Successfully tagged quorum-dev-quickstart_pet_shop:latest
b1615ab765656bc027f63fc60019dba1ca572305766c820f41eaf113b7e14cf8

In the browser where you have MetaMask enabled and one of the test accounts loaded, open a new tab and navigate to the Pet Shop dapp where you can adopt lovely pets (sorry, not for real, it’s a demo).

When you click on ‘Adopt’, a MetaMask window will pop up and request your permissions to continue with the transaction.

After the transaction is complete and successful, the status of the pet you adopted will show ‘Success’.

Dapp UI

You can also search for the transaction and view its details in the Block Explorer.

Dapp UI

The MetMask UI also keeps a record of the transaction.

Dapp UI

Stop and restart the private network without removing containers

To shut down the private network without deleting the containers:

./stop.sh

This command stops the containers related to the services specified in the docker-compose.yml file.

To restart the private network:

./resume.sh

Stop the private network and remove containers

To shut down the private network and delete all containers and images created from running the sample network and the Pet Shop dapp:

./remove.sh
Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list besu@lists.hyperledger.org