70448724e8
Fix SetPrivate and validation |
||
---|---|---|
.github | ||
_data | ||
accounts | ||
build | ||
cmd | ||
common | ||
compression/rle | ||
console | ||
containers | ||
contracts | ||
core | ||
crypto | ||
errs | ||
eth | ||
ethclient | ||
ethdb | ||
event | ||
generators | ||
internal | ||
light | ||
logger | ||
metrics | ||
node | ||
p2p | ||
params | ||
pow | ||
private | ||
rlp | ||
rpc | ||
swarm | ||
tests | ||
trie | ||
vendor | ||
whisper | ||
.gitattributes | ||
.gitignore | ||
.mailmap | ||
.travis.yml | ||
AUTHORS | ||
COPYING | ||
COPYING.LESSER | ||
Makefile | ||
README.md | ||
VERSION | ||
appveyor.yml | ||
circle.yml | ||
interfaces.go | ||
vendor.conf |
README.md
Quorum
Quorum is a blockchain with properties that make it suitable as a consortium or private chain. One of its core features is the ability to keep certain state private and only accessible by granted parties.
Consensus algorithm
Quorum is a majority voting protocol where a subset of nodes within the network are given the voting
role.
The voting role allows a node to vote which block should be the canonical head on a particular height.
The block with the most votes will win and is considered the canonical head of the chain.
Block creation is only allowed by nodes with the block maker
role.
A node with this role can create a block, sign the block and put the signature within in ExtraData
field of the block.
On block import nodes can verify if the block was signed by one of the nodes that have the block maker
role.
Nodes can be given no role, one of the roles or both roles through command line arguments. The collection of addresses with special roles is tracked within the Quorum smart contract.
Quorum is implemented in a smart contract pre-deployed on address 0x0000000000000000000000000000000000000020
and can be found here.
Voters and block makers can be added or removed and the minimum number of votes before a block is selected as winner can be configured.
State
Quorum supports dual state:
- public state, accessible by all nodes within the network
- private state, only accessible by nodes with the correct permissions
The difference is made through the use of transactions with encrypted (private) and non-encrypted payload (public) transactions. Nodes can determine if a transaction is private by looking at the V value of the signature. Public transactions have a V value of 27 or 28, private transactions have a value of 37 or 38.
If the transaction is private and the node has the ability to decrypt the payload it can execute the transaction. Nodes who are not involved in the transaction cannot decrypt the payload and process the transaction. As a result all nodes share a common public state which is created through public transactions and have a local unique private state.
This model imposes a restriction in the ability to modify state in private transactions. Since its a common use case that a (private) contract reads data from a public contract the virtual machine has the ability to jump into read only mode. For each call from a private contract to a public contract the virtual machine will change to read only mode. If the virtual machine is in read only mode and the code tries to make a stage change the virtual machine stops execution and throws an exception.
The following transactions are allowed:
S: sender, (X): private, X: public, ->: direction, []: read only mode
1. S -> A -> B
2. S -> (A) -> (B)
3. S -> (A) -> [B -> C]
The following transaction are unsupported:
1. (S) -> A
2. (S) -> (A)
State verification
To determine if nodes are in sync the public state root hash is included in the block.
Since private transactions can only be processed by nodes that are involved its impossible to get global consensus on the private state.
To overcome this issue the RPC method eth_storageRoot(address[, blockNumber]) -> hash
can be used.
It returns the storage root for the given address at an (optional) block number.
If the optional block number is not given the latest block number is used.
The storage root hash can be on or off chain compared by the parties involved.
Building Quorum
Clone the repository and build the source:
git clone https://github.com/jpmorganchase/quorum.git
cd quorum
make all
Binaries are placed within $REPO_ROOT/build/bin
.
Run the tests:
make test
Running Quorum
Describing all command line arguments it out of the scope of this document. They can be viewed with: geth --help
.
Initialize chain
The first step is to generate the genesis block.
geth init genesis.json
The genesis block should include the Quorum voting contract address 0x0000000000000000000000000000000000000020
.
The code can be generated with browser solidity (note, use the runtime code) or using the solidity compiler solc --optimize --bin-runtime block_voting.sol
.
The 7nodes
directory in the quorum-examples
repository contains several keys (using an empty password) that are used in the example genesis file:
key1 vote key 1
key2 vote key 2
key3 vote key 3
key4 block maker 1
key5 block maker 2
Example genesis file:
{
"alloc": {
"0x0000000000000000000000000000000000000020": {
"code": "606060405236156100c45760e060020a60003504631290948581146100c9578063284d163c146100f957806342169e4814610130578063488099a6146101395780634fe437d514610154578063559c390c1461015d57806368bb8bb61461025d57806372a571fc146102c857806386c1ff681461036957806398ba676d146103a0578063a7771ee31461040b578063adfaa72e14610433578063cf5289851461044e578063de8fa43114610457578063e814d1c71461046d578063f4ab9adf14610494575b610002565b610548600435600160a060020a03331660009081526003602052604090205460ff16156100c45760018190555b50565b610548600435600160a060020a03331660009081526005602052604090205460ff16156100c4576004546001141561055e57610002565b61045b60025481565b61054a60043560056020526000908152604090205460ff1681565b61045b60015481565b61045b60043560006000600060006000600050600186038154811015610002579080526002027f290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e5630192505b60018301548110156105d75760018301805484916000918490811015610002576000918252602080832090910154835282810193909352604091820181205485825292869052205410801561023257506001805490840180548591600091859081101561000257906000526020600020900160005054815260208101919091526040016000205410155b156102555760018301805482908110156100025760009182526020909120015491505b6001016101a8565b610548600435602435600160a060020a03331660009081526003602052604081205460ff16156100c4578054839010156105e45780548084038101808355908290829080158290116105df576002028160020283600052602060002091820191016105df919061066b565b610548600435600160a060020a03331660009081526005602052604090205460ff16156100c457600160a060020a0381166000908152604090205460ff1615156100f65760406000819020805460ff191660019081179091556004805490910190558051600160a060020a038316815290517f1a4ce6942f7aa91856332e618fc90159f13a340611a308f5d7327ba0707e56859181900360200190a16100f6565b610548600435600160a060020a03331660009081526003602052604090205460ff16156100c4576002546001141561071457610002565b61045b600435602435600060006000600050600185038154811015610002579080526002027f290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e5630181509050806001016000508381548110156100025750825250602090200154919050565b61054a600435600160a060020a03811660009081526003602052604090205460ff165b919050565b61054a60043560036020526000908152604090205460ff1681565b61045b60045481565b6000545b60408051918252519081900360200190f35b61054a600435600160a060020a03811660009081526005602052604090205460ff1661042e565b610548600435600160a060020a03331660009081526003602052604090205460ff16156100c457600160a060020a03811660009081526003602052604090205460ff1615156100f65760406000818120600160a060020a0384169182905260036020908152815460ff1916600190811790925560028054909201909155825191825291517f0ad2eca75347acd5160276fe4b5dad46987e4ff4af9e574195e3e9bc15d7e0ff929181900390910190a16100f6565b005b604080519115158252519081900360200190f35b600160a060020a03811660009081526005602052604090205460ff16156100f65760406000819020805460ff19169055600480546000190190558051600160a060020a038316815290517f8cee3054364d6799f1c8962580ad61273d9d38ca1ff26516bd1ad23c099a60229181900360200190a16100f6565b509392505050565b505050505b60008054600019850190811015610002578382526002027f290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563016020819052604082205490925014156106b8578060010160005080548060010182818154818355818115116106a5578183600052602060002091820191016106a5919061068d565b50506002015b808211156106a157600181018054600080835591825260208220610665918101905b808211156106a1576000815560010161068d565b5090565b5050506000928352506020909120018290555b600082815260208281526040918290208054600101905581514381529081018490528151600160a060020a033316927f3d03ba7f4b5227cdb385f2610906e5bcee147171603ec40005b30915ad20e258928290030190a2505050565b600160a060020a03811660009081526003602052604090205460ff16156100f65760406000819020805460ff19169055600280546000190190558051600160a060020a038316815290517f183393fc5cffbfc7d03d623966b85f76b9430f42d3aada2ac3f3deabc78899e89181900360200190a16100f656",
"storage": {
"0x0000000000000000000000000000000000000000000000000000000000000001": "0x02",
"0x0000000000000000000000000000000000000000000000000000000000000002": "0x04",
"0x29ecdbdf95c7f6ceec92d6150c697aa14abeb0f8595dd58d808842ea237d8494": "0x01",
"0x6aa118c6537572d8b515a9f9154be55a3377a8de7991cd23bf6e5ceb368688e3": "0x01",
"0x50793743212c6f01d326957d7069005b912f8215f10c7536be6b10782c6c44cd": "0x01",
"0x38f6c908c5cc7ca668cec2f476abe61b4dbb1df20f0ad8e07ef5dbf6a2f1ffd4": "0x01",
"0x0000000000000000000000000000000000000000000000000000000000000004": "0x02",
"0xaca3b76ed4968740c3180dd7fa37f4aa229a2c758a848f53920e9ccb4c4bb74e": "0x01",
"0xd188ba2dc293670542c1befaf7678b0859e5354a0727d1188b2afb6f47fe24d1": "0x01"
}
},
"0xed9d02e382b34818e88b88a309c7fe71e65f419d": {
"balance": "1000000000000000000000000000"
},
"0xca843569e3427144cead5e4d5999a3d0ccf92b8e": {
"balance": "1000000000000000000000000000"
},
"0x0fbdc686b912d7722dc86510934589e0aaf3b55a": {
"balance": "1000000000000000000000000000"
},
"0x9186eb3d20cbd1f5f992a950d808c4495153abd5": {
"balance": "1000000000000000000000000000"
},
"0xed9d02e382b34818e88b88a309c7fe71e65f419d": {
"balance": "1000000000000000000000000000"
},
"0x0638e1574728b6d862dd5d3a3e0942c3be47d996": {
"balance": "1000000000000000000000000000"
}
},
"coinbase": "0x0000000000000000000000000000000000000000",
"config": {
"homesteadBlock": 0
},
"difficulty": "0x0",
"extraData": "0x",
"gasLimit": "0x2FEFD800",
"mixhash": "0x00000000000000000000000000000000000000647572616c65787365646c6578",
"nonce": "0x0",
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp": "0x00"
}
The storage key for voters and block makers is calculated with web3.sha3(<256 bit aligned key value> + <256 bit variable index>)
.
The console can be used to calculate the storage key, in this case for vote key 1:
> key = "000000000000000000000000ed9d02e382b34818e88b88a309c7fe71e65f419d" + "0000000000000000000000000000000000000000000000000000000000000003"
"000000000000000000000000ed9d02e382b34818e88b88a309c7fe71e65f419d0000000000000000000000000000000000000000000000000000000000000003"
> web3.sha3(key, {"encoding": "hex"})
"0x29ecdbdf95c7f6ceec92d6150c697aa14abeb0f8595dd58d808842ea237d8494"
The genesis.json
file can be found in the 7nodes
folder in the quorum-examples
repository.
Start node
Starting a node is as simple as geth
. This will start the node without any of the roles and makes the node a spectator.
Voting role
Start a node with the voting role:
geth --voteaccount 0xed9d02e382b34818e88b88a309c7fe71e65f419d
Optionally the --votepassword
can be used to unlock the account.
If this flag is omitted the node will prompt for the password.
Block maker role
Start a node with the block maker role:
geth --blockmakeraccount 0x9186eb3d20cbd1f5f992a950d808c4495153abd5
Created blocks will be signed with this account.
Optionally the --blockmakerpassword
can be used to unlock the account.
If this flag is omitted the node will prompt for the password.
Setup multi-node network
Quorum comes with several scripts to setup a private test network with 7 nodes:
- node 1, has no special roles
- node 2, has the block maker role
- node 3, has no special roles
- node 4, has the voting role
- node 5, has the voting role
- node 6, has no special roles
All scripts can be found in the 7nodes
folder in the quorum-examples
repository.
- Step 1, run
init.sh
and initialize data directories (change variables accordingly) - Step 2, start nodes with
start.sh
(change variables accordingly) - Step 3, stop network with
stop.sh
API
Quorum provides an API to inspect the current state of the voting contract.
$ quorum.nodeInfo returns the quorum capabilities of this node. Example output for a node that is configured as block maker and voter:
> quorum.nodeInfo
{
blockMakerAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d",
blockmakestrategy: {
maxblocktime: 6,
minblocktime: 3,
status: "active",
type: "deadline"
},
canCreateBlocks: true,
canVote: true,
voteAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"
}
$ quorum.vote accepts a block hash and votes for this hash to be the canonical head on the current height. It returns the tx hash.
> quorum.vote(eth.getBlock("latest").hash)
"0x16c69b9bdf9f10c64e65dbfe50bc997d2bc1ed321c6041db602908b7f6cab2a9"
$ quorum.canonicalHash accepts a block height and returns the canonical hash for that height (+1 will return the hash where the current pending block will be based on top of).
> quorum.canonicalHash(eth.blockNumber+1)
"0xf2c8a36d0c54c7013246fddebfc29bc881f6f10f74f761d511b5ebfaa103adfa"
$ quorum.isVoter accepts an address and returns an indication if the given address is allowed to vote for new blocks
> quorum.isVoter("0xed9d02e382b34818e88b88a309c7fe71e65f419d")
true
$ quorum.isBlockMaker accepts an address and returns an indication if the given address is allowed to make blocks
> quorum.isBlockMaker("0xed9d02e382b34818e88b88a309c7fe71e65f419d")
true
$ quorum.makeBlock() orders the node to create a block bypassing block maker strategy.
> quorum.makeBlock()
"0x3a07e82a48ab3c19a3d09d247e189e3a3041d1d9eafd2e1515b4ddd5b016bfd9"
$ quorum.pauseBlockMaker (temporary) orders the node to stop creating blocks
> quorum.pauseBlockMaker()
null
> quorum.nodeInfo
{
blockMakerAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d",
blockmakestrategy: {
maxblocktime: 6,
minblocktime: 3,
status: "paused",
type: "deadline"
},
canCreateBlocks: true,
canVote: true,
voteAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"
}
$ quorum.resumeBlockMaker instructs the node stop begin creating blocks again when its paused.
> quorum.resumeBlockMaker()
null
> quorum.nodeInfo
{
blockMakerAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d",
blockmakestrategy: {
maxblocktime: 6,
minblocktime: 3,
status: "active",
type: "deadline"
},
canCreateBlocks: true,
canVote: true,
voteAccount: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"
}
Sending Private Transactions
To send a private transaction, a PrivateTransactionManager must be configured. This is the service which transfers private payloads to their intended recipients, performing encryption and related operations in the process.
Currently, constellation
is supported out of the box via the PRIVATE_CONFIG environment
variable (please note that this integration method will change in the near future.) See the
7nodes
folder in the quorum-examples
repository for a complete example of how to use it.
The transaction sent in script1.js
is private for node 7's PrivateTransactionManager
public key.
Once constellation
is launched and PRIVATE_CONFIG points to a valid configuration file,
a SendTransaction
call can be made private by specifying the privateFor
argument.
privateFor
is a list of public keys of the intended recipients. (Note that in the case of
constellation
, this public key is distinct from Ethereum account keys.) When a transaction
is private, the transaction contents will be sent to the PrivateTransactionManager and the
identifier returned will be placed in the transaction instead. When other Quorum nodes
receive a private transaction, they will query their PrivateTransactionManager for the
identifier and replace the transaction contents with the result (if any; nodes which are
not party to a transaction will not be able to retrieve the original contents.)
Command line flags
QUORUM OPTIONS:
--voteaccount value Address that is used to vote for blocks
--votepassword value Password to unlock the voting address
--blockmakeraccount value Address that is used to create blocks
--blockmakerpassword value Password to unlock the block maker address
--singleblockmaker Indicate this node is the only node that can create blocks
--minblocktime value Set minimum block time (default: 3)
--maxblocktime value Set max block time (default: 10)
License
The go-ethereum library (i.e. all code outside of the cmd
directory) is licensed under the
GNU Lesser General Public License v3.0, also
included in our repository in the COPYING.LESSER
file.
The go-ethereum binaries (i.e. all code inside of the cmd
directory) is licensed under the
GNU General Public License v3.0, also included
in our repository in the COPYING
file.