2016-11-01 07:21:55 -07:00
# Quorum
2015-02-05 12:34:47 -08:00
2018-08-03 09:03:46 -07:00
< a href = "https://clh7rniov2.execute-api.us-east-1.amazonaws.com/Express/" target = "_blank" rel = "noopener" > < img title = "Quorum Slack" src = "https://clh7rniov2.execute-api.us-east-1.amazonaws.com/Express/badge.svg" alt = "Quorum Slack" / > < / a >
2017-10-26 03:43:39 -07:00
2017-07-14 19:47:39 -07:00
Quorum is an Ethereum-based distributed ledger protocol with transaction/contract privacy and new consensus mechanisms.
2016-11-14 16:23:29 -08:00
2017-07-14 19:47:39 -07:00
Quorum is a fork of [go-ethereum ](https://github.com/ethereum/go-ethereum ) and is updated in line with go-ethereum releases.
Key enhancements over go-ethereum:
2017-10-31 15:24:11 -07:00
* __Privacy__ - Quorum supports private transactions and private contracts through public/private state separation and utilising [Constellation ](https://github.com/jpmorganchase/constellation ), a peer-to-peer encrypted message exchange for directed transfer of private data to network participants
* __Alternative Consensus Mechanisms__ - with no need for POW/POS in a permissioned network, Quorum instead offers multiple consensus mechanisms that are more appropriate for consortium chains:
2017-07-14 19:47:39 -07:00
* __Raft-based Consensus__ - a consensus model for faster blocktimes, transaction finality, and on-demand block creation
2017-10-31 15:24:11 -07:00
* __Istanbul BFT__ - a PBFT-inspired consensus algorithm with transaction finality, by AMIS.
* __Peer Permissioning__ - node/peer permissioning using smart contracts, ensuring only known parties can join the network
* __Higher Performance__ - Quorum offers significantly higher performance than public geth
2016-11-14 16:23:29 -08:00
2017-10-31 15:24:11 -07:00
Note: The QuorumChain consensus algorithm is not yet supported by this release.
2016-11-14 16:23:29 -08:00
## Architecture
2016-11-17 13:07:02 -08:00
< a href = "https://github.com/jpmorganchase/quorum/wiki/Transaction-Processing#private-transaction-process-flow" > ![Quorum privacy architecture](https://github.com/jpmorganchase/quorum-docs/raw/master/images/QuorumTransactionProcessing.JPG)< / a >
2016-11-14 16:23:29 -08:00
2016-11-16 13:18:19 -08:00
The above diagram is a high-level overview of the privacy architecture used by Quorum. For more in-depth discussion of the components, refer to the [wiki ](https://github.com/jpmorganchase/quorum/wiki/ ) pages.
2016-11-14 16:23:29 -08:00
## Quickstart
2016-11-16 13:18:19 -08:00
The quickest way to get started with Quorum is using [VirtualBox ](https://www.virtualbox.org/wiki/Downloads ) and [Vagrant ](https://www.vagrantup.com/downloads.html ):
2016-11-14 16:23:29 -08:00
```sh
git clone https://github.com/jpmorganchase/quorum-examples
2016-11-18 08:52:54 -08:00
cd quorum-examples
2016-11-14 16:23:29 -08:00
vagrant up
# (should take 5 or so minutes)
vagrant ssh
```
Now that you have a fully-functioning Quorum environment set up, let's run the 7-node cluster example. This will spin up several nodes with a mix of voters, block makers, and unprivileged nodes.
2016-11-17 13:00:39 -08:00
```sh
2016-11-14 16:23:29 -08:00
# (from within vagrant env, use `vagrant ssh` to enter)
2016-11-24 20:15:42 -08:00
ubuntu@ubuntu-xenial:~$ cd quorum-examples/7nodes
2016-11-14 16:23:29 -08:00
2017-10-31 15:24:11 -07:00
$ ./raft-init.sh
2016-11-14 16:23:29 -08:00
# (output condensed for clarity)
[*] Cleaning up temporary data directories
[*] Configuring node 1
[*] Configuring node 2 as block maker and voter
[*] Configuring node 3
[*] Configuring node 4 as voter
[*] Configuring node 5 as voter
[*] Configuring node 6
[*] Configuring node 7
2017-10-31 15:24:11 -07:00
$ ./raft-start.sh
2016-11-14 16:23:29 -08:00
[*] Starting Constellation nodes
2016-11-17 13:00:39 -08:00
[*] Starting bootnode... waiting... done
2016-11-14 16:23:29 -08:00
[*] Starting node 1
[*] Starting node 2
[*] Starting node 3
[*] Starting node 4
[*] Starting node 5
[*] Starting node 6
[*] Starting node 7
[*] Unlocking account and sending first transaction
2016-11-17 13:00:39 -08:00
Contract transaction send: TransactionHash: 0xbfb7bfb97ba9bacbf768e67ac8ef05e4ac6960fc1eeb6ab38247db91448b8ec6 waiting to be mined...
2016-11-14 16:23:29 -08:00
true
2016-07-12 02:51:31 -07:00
```
2016-08-18 09:43:38 -07:00
docker run -d --name ethereum-node -v /Users/alice/ethereum:/root \
-p 8545:8545 -p 30303:30303 \
2018-02-10 02:50:14 -08:00
ethereum/client-go
2016-08-18 09:43:38 -07:00
```
2018-02-10 02:50:14 -08:00
This will start geth in fast-sync mode with a DB memory allowance of 1GB just as the above command does. It will also create a persistent volume in your home directory for saving your blockchain as well as map the default ports. There is also an `alpine` tag available for a slim version of the image.
2016-08-18 09:43:38 -07:00
2017-10-23 23:55:20 -07:00
Do not forget `--rpcaddr 0.0.0.0` , if you want to access RPC from other containers and/or hosts. By default, `geth` binds to the local interface and RPC endpoints is not accessible from the outside.
2016-07-12 02:51:31 -07:00
### Programatically interfacing Geth nodes
2016-11-22 00:21:10 -08:00
We now have a 7-node Quorum cluster with a [private smart contract ](https://github.com/jpmorganchase/quorum-examples/blob/master/examples/7nodes/script1.js ) (SimpleStorage) sent from `node 1` "for" `node 7` (denoted by the public key passed via `privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]` in the `sendTransaction` call).
2016-07-12 02:51:31 -07:00
As a developer, sooner rather than later you'll want to start interacting with Geth and the Ethereum
2018-04-04 06:25:34 -07:00
network via your own programs and not manually through the console. To aid this, Geth has built-in
2016-07-12 02:51:31 -07:00
support for a JSON-RPC based APIs ([standard APIs](https://github.com/ethereum/wiki/wiki/JSON-RPC) and
[Geth specific APIs ](https://github.com/ethereum/go-ethereum/wiki/Management-APIs )). These can be
2017-03-02 08:44:07 -08:00
exposed via HTTP, WebSockets and IPC (unix sockets on unix based platforms, and named pipes on Windows).
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
Connect to any of the nodes and inspect them using the following commands:
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
```sh
2016-11-14 16:26:48 -08:00
$ geth attach ipc:qdata/dd1/geth.ipc
$ geth attach ipc:qdata/dd2/geth.ipc
2016-11-14 16:23:29 -08:00
...
2016-11-14 16:26:48 -08:00
$ geth attach ipc:qdata/dd7/geth.ipc
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
# e.g.
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
$ geth attach ipc:qdata/dd2/geth.ipc
Welcome to the Geth JavaScript console!
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
instance: Geth/v1.5.0-unstable/linux/go1.7.3
coinbase: 0xca843569e3427144cead5e4d5999a3d0ccf92b8e
at block: 679 (Tue, 15 Nov 2016 00:01:05 UTC)
datadir: /home/ubuntu/quorum-examples/7nodes/qdata/dd2
modules: admin:1.0 debug:1.0 eth:1.0 net:1.0 personal:1.0 quorum:1.0 rpc:1.0 txpool:1.0 web3:1.0
2016-07-12 02:51:31 -07:00
2016-11-14 16:26:48 -08:00
# let's look at the private txn created earlier:
2016-11-17 13:00:39 -08:00
> eth.getTransaction("0xbfb7bfb97ba9bacbf768e67ac8ef05e4ac6960fc1eeb6ab38247db91448b8ec6")
2016-11-14 16:26:48 -08:00
{
2016-11-17 13:00:39 -08:00
blockHash: "0xb6aec633ef1f79daddc071bec8a56b7099ab08ac9ff2dc2764ffb34d5a8d15f8",
2016-11-14 16:26:48 -08:00
blockNumber: 1,
from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d",
gas: 300000,
2016-11-17 13:00:39 -08:00
gasPrice: 0,
hash: "0xbfb7bfb97ba9bacbf768e67ac8ef05e4ac6960fc1eeb6ab38247db91448b8ec6",
input: "0x9820c1a5869713757565daede6fcec57f3a6b45d659e59e72c98c531dcba9ed206fd0012c75ce72dc8b48cd079ac08536d3214b1a4043da8cea85be858b39c1d",
2016-11-14 16:26:48 -08:00
nonce: 0,
2016-11-17 13:00:39 -08:00
r: "0x226615349dc143a26852d91d2dff1e57b4259b576f675b06173e9972850089e7",
s: "0x45d74765c5400c5c280dd6285a84032bdcb1de85a846e87b57e9e0cedad6c427",
2016-11-14 16:26:48 -08:00
to: null,
2016-11-17 13:00:39 -08:00
transactionIndex: 1,
v: "0x25",
2016-11-14 16:26:48 -08:00
value: 0
}
2016-07-12 02:51:31 -07:00
```
2018-05-24 04:45:39 -07:00
Note in particular the `v` field value of "0x25" or "0x26" (37 or 38 in decimal) which marks this transaction as having a private payload (input).
2016-11-15 13:55:10 -08:00
2016-11-20 18:35:01 -08:00
## Demonstrating Privacy
2016-11-21 06:30:23 -08:00
Documentation detailing steps to demonstrate the privacy features of Quorum can be found in [quorum-examples/7nodes/README ](https://github.com/jpmorganchase/quorum-examples/tree/master/examples/7nodes/README.md ).
2016-11-20 18:35:01 -08:00
2016-11-14 16:23:29 -08:00
## Further Reading
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
Further documentation can be found in the [docs ](docs/ ) folder and on the [wiki ](https://github.com/jpmorganchase/quorum/wiki/ ).
2016-07-12 02:51:31 -07:00
2016-11-14 16:23:29 -08:00
## See also
2013-12-26 04:29:45 -08:00
2017-03-23 11:41:02 -07:00
* [Quorum ](https://github.com/jpmorganchase/quorum ): this repository
* [Constellation ](https://github.com/jpmorganchase/constellation ): peer-to-peer encrypted message exchange for transaction privacy
* [Raft Consensus Documentation ](raft/doc.md )
2017-11-24 03:37:14 -08:00
* [Istanbul BFT Consensus Documentation ](https://github.com/ethereum/EIPs/issues/650 ): [RPC API ](https://github.com/getamis/go-ethereum/wiki/RPC-API ) and [technical article ](https://medium.com/getamis/istanbul-bft-ibft-c2758b7fe6ff )
2017-10-17 06:37:13 -07:00
* [ZSL ](https://github.com/jpmorganchase/quorum/wiki/ZSL ) wiki page and [documentation ](https://github.com/jpmorganchase/zsl-q/blob/master/README.md )
2017-03-23 11:41:02 -07:00
* [quorum-examples ](https://github.com/jpmorganchase/quorum-examples ): example quorum clusters
2017-11-03 07:32:01 -07:00
* [quorum-tools ](https://github.com/jpmorganchase/quorum-tools ): local cluster orchestration, and integration testing tool
2017-03-23 11:41:02 -07:00
* [Quorum Wiki ](https://github.com/jpmorganchase/quorum/wiki )
2018-08-03 09:03:46 -07:00
* [Quorum Community Slack Inviter ](https://clh7rniov2.execute-api.us-east-1.amazonaws.com/Express/ ): Quorum Slack community entry point
2015-03-02 10:44:29 -08:00
2017-01-25 07:17:38 -08:00
## Third Party Tools/Libraries
The following Quorum-related libraries/applications have been created by Third Parties and as such are not specifically endorsed by J.P. Morgan. A big thanks to the developers for improving the tooling around Quorum!
2018-02-27 00:42:20 -08:00
* [Quorum Blockchain Explorer ](https://github.com/blk-io/blk-explorer-free ) - a Blockchain Explorer for Quorum which supports viewing private transactions
2017-01-25 07:17:38 -08:00
* [Quorum-Genesis ](https://github.com/davebryson/quorum-genesis ) - A simple CL utility for Quorum to help populate the genesis file with voters and makers
2018-06-13 11:53:54 -07:00
* [Quorum Maker ](https://github.com/synechron-finlabs/quorum-maker/ ) - a utility to create Quorum nodes
2017-06-08 12:41:03 -07:00
* [QuorumNetworkManager ](https://github.com/ConsenSys/QuorumNetworkManager ) - makes creating & managing Quorum networks easy
2017-07-14 19:47:39 -07:00
* [ERC20 REST service ](https://github.com/blk-io/erc20-rest-service ) - a Quorum-supported RESTful service for creating and managing ERC-20 tokens
2018-02-27 00:42:20 -08:00
* [Nethereum Quorum ](https://github.com/Nethereum/Nethereum/tree/master/src/Nethereum.Quorum ) - a .NET Quorum adapter
* [web3j-quorum ](https://github.com/web3j/quorum ) - an extension to the web3j Java library providing support for the Quorum API
2017-01-25 07:17:38 -08:00
2016-11-14 16:23:29 -08:00
## Contributing
2015-03-02 10:44:29 -08:00
2016-11-14 16:23:29 -08:00
Thank you for your interest in contributing to Quorum!
2014-02-08 13:16:11 -08:00
2017-10-31 15:24:11 -07:00
Quorum is built on open source and we invite you to contribute enhancements. Upon review you will be required to complete a Contributor License Agreement (CLA) before we are able to merge. If you have any questions about the contribution process, please feel free to send an email to [quorum_info@jpmorgan.com ](mailto:quorum_info@jpmorgan.com ).
2016-04-29 07:40:19 -07:00
## License
2014-01-11 06:27:08 -08:00
2016-04-29 07:40:19 -07:00
The go-ethereum library (i.e. all code outside of the `cmd` directory) is licensed under the
2016-09-26 23:48:55 -07:00
[GNU Lesser General Public License v3.0 ](https://www.gnu.org/licenses/lgpl-3.0.en.html ), also
2016-04-29 07:40:19 -07:00
included in our repository in the `COPYING.LESSER` file.
2014-02-15 02:49:29 -08:00
2016-04-29 07:40:19 -07:00
The go-ethereum binaries (i.e. all code inside of the `cmd` directory) is licensed under the
2016-09-26 23:48:55 -07:00
[GNU General Public License v3.0 ](https://www.gnu.org/licenses/gpl-3.0.en.html ), also included
2016-04-29 07:40:19 -07:00
in our repository in the `COPYING` file.