Merge pull request ethereum#8 from jpmorganchase/formatting

Grammar / formatting fixes.

README.md

@@ -1,22 +1,22 @@
 # Quorum
 
-Quorum is an Ethereum-based distributed ledger protocol that has been developed to provide the Financial Services industry with a permissioned implementation of Ethereum that supports transaction and contract privacy.
+Quorum is an Ethereum-based distributed ledger protocol with transaction and contract privacy, developed for the financial services industry.
 
-The key enhancements are:
+Key enhancements:
 
 * __QuorumChain__ - a new consensus model based on majority voting
 * __Constellation__ - a peer-to-peer encrypted message exchange
-* __Peer Security__ - node/peer permissioning using Smart Contracts
+* __Peer Security__ - node/peer permissioning using smart contracts
 
 ## Architecture
 
 ![Quorum privacy architecture](docs/img/architecture.png)
 
-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 pages.
+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.
 
 ## Quickstart
 
-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). Once you have both installed, run the following:
+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):
 
 ```sh
 git clone https://github.com/jpmorganchase/quorum-examples
@@ -28,7 +28,7 @@ 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.
 
-```sh
+```
 # (from within vagrant env, use `vagrant ssh` to enter)
 ubuntu@ubuntu-xenial:~$ cd quorum-examples/7nodes
 

docs/api.md

@@ -3,8 +3,10 @@
 
 Quorum provides an API to inspect the current state of the voting contract.
 
-$ quorum.nodeInfo returns the quorum capabilities of this node.
+### `quorum.nodeInfo` returns the quorum capabilities of this node
+
 Example output for a node that is configured as block maker and voter:
+
 ```
 > quorum.nodeInfo
 {
@@ -21,37 +23,43 @@ Example output for a node that is configured as block maker and voter:
 }
 ```
 
-$ 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` votes for the given hash to be the canonical head on the current height and 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` returns the canonical hash for the given block height (add 1 for the hash that 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` returns whether 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` returns whether 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` 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` (temporary) orders the node to stop creating blocks
+
 ```
 > quorum.pauseBlockMaker()
 null
@@ -70,7 +78,8 @@ null
 }
 ```
 
-$ quorum.resumeBlockMaker instructs the node stop begin creating blocks again when its paused.
+### `quorum.resumeBlockMaker` instructs a paused node to begin creating blocks again
+
 ```
 > quorum.resumeBlockMaker()
 null

docs/design.md

@@ -28,8 +28,8 @@ Quorum supports dual state:
 - 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 payloads (public).
-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.
+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.

docs/privacy.md

@@ -3,22 +3,22 @@
 
 ## Sending Private Transactions
 
-To send a private transaction, a PrivateTransactionManager must be configured. This is the
+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
+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
+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,
+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
+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
+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.)