This repository contains setup examples for Quorum.
Current examples include:
- 7nodes: Starts up a fully-functioning Quorum environment consisting of 7 independent nodes. From this example one can test consensus, privacy, and all the expected functionality of an Ethereum platform.
- 5nodesRTGS: [Note: This links to an external repo which you will need to clone, thanks to @rsarres for this contribution!] Starts up a set of 5 nodes that simulates a Real-time Gross Setlement environment with 3 banks, one regulator (typically a central bank) and an observer that cannot access the private data.
The easiest way to get started with running the examples is to use the vagrant environment (see below).
Important note: Any account/encryption keys contained in this repository are for
demonstration and testing purposes only. Before running a real environment, you should
generate new ones using Geth's account
tool and the --generate-keys
option for Constellation (or -keygen
option for Tessera).
The 7nodes example can be run in two ways:
- By running a preconfigured Vagrant environment which comes complete with Quorum, Constellation, Tessera and the 7nodes example (works on any machine).
- By downloading and locally running Quorum, Tessera and the examples (requires an Ubuntu-based/macOS machine; note that Constellation does not support running locally)
-
Install VirtualBox
-
Install Vagrant
-
Download and start the Vagrant instance (note: running
vagrant up
takes approx 5 mins):git clone https://github.com/jpmorganchase/quorum-examples cd quorum-examples vagrant up vagrant ssh
-
To shutdown the Vagrant instance, run
vagrant suspend
. To delete it, runvagrant destroy
. To start from scratch, runvagrant up
after destroying the instance.
- If you are behind a proxy server, please see Consensys/quorum#23.
- If you are using macOS and get an error saying that the ubuntu/xenial64 image doesn't
exist, please run
sudo rm -r /opt/vagrant/embedded/bin/curl
. This is usually due to issues with the version of curl bundled with Vagrant. - If you receive the error
default: cp: cannot open '/path/to/geth.ipc' for reading: Operation not supported
after runningvagrant up
, run./raft-init.sh
within the 7nodes directory on your local machine. This will remove temporary files created after running 7nodes locally and will enablevagrant up
to execute correctly.
-
The Vagrant instance is allocated 6 GB of memory. This is defined in the
Vagrantfile
,v.memory = 6144
. This has been deemed a suitable value to allow the VM and examples to run as expected. The memory allocation can be changed by updating this value and runningvagrant reload
to apply the change. -
If the machine you are using has less than 8 GB memory you will likely encounter system issues such as slow down and unresponsiveness when starting the Vagrant instance as your machine will not have the capacity to run the VM. There are several steps that can be taken to overcome this:
- Shutdown any running processes that are not required
- If running the 7nodes example, reduce the number of nodes started up. See the 7nodes README: Reducing the number of nodes for info on how to do this.
- Set up and run the examples locally. Running locally reduces the load on your memory compared to running in Vagrant.
This is only possible with Tessera. Constellation is not supported when running the examples locally. To use Constellation, the examples must be run in Vagrant.
- Install Golang
- Download and build Quorum:
git clone https://github.com/jpmorganchase/quorum cd quorum make GETHDIR=`pwd`; export PATH=$GETHDIR/build/bin:$PATH cd ..
- Download and build the Tessera jar as detailed in the Tessera README
- Download quorum-examples
git clone https://github.com/jpmorganchase/quorum-examples
Shell scripts are included in the examples to make it simple to configure the network and start submitting transactions.
All logs and temporary data are written to the qdata
folder.
-
Navigate to the 7nodes example, configure the Quorum nodes and initialize accounts & keystores:
cd path/to/7nodes ./raft-init.sh
-
Start the Quorum and privacy manager nodes (Constellation or Tessera):
-
If running in Vagrant:
./raft-start.sh
By default, Constellation will be used as the privacy manager. To use Tessera run the following:
./raft-start.sh tessera
By default,
raft-start.sh
will look in/home/vagrant/tessera/tessera-app/target/tessera-app-{version}-app.jar
for the Tessera jar. -
If running locally with Tessera:
./raft-start.sh tessera --tesseraOptions "--tesseraJar /path/to/tessera-app.jar"
The Tessera jar location can also be specified by setting the environment variable
TESSERA_JAR
.
-
-
You are now ready to start sending private/public transactions between the nodes
To run the example using Istanbul BFT consensus use the corresponding commands:
istanbul-init.sh
istanbul-start.sh
istanbul-start.sh tessera
stop.sh
Some simple transaction contracts are included in quorum-examples to demonstrate the privacy features of Quorum. To learn how to use them see the 7nodes README.