Merge pull request #129 from s-matthew-english/readability_improvements

docs, raft, core: general readability improvements

core/quorum/README.md

@@ -53,7 +53,7 @@ null
   voteAccount: "0x7bd175a388c7a5f33fb81bbb3b7e97cbfabb3600"
 }
 
-$ quorum.resumeBlockMaker instructs the node stop begin creating blocks again when its paused.
+$ quorum.resumeBlockMaker instructs the node to begin creating blocks again when its paused.
 > quorum.resumeBlockMaker()
 null
 > quorum.nodeInfo

core/quorum/block_maker.go

@@ -74,7 +74,7 @@ func (ps *pendingState) applyTransactions(txs *types.TransactionsByPriorityAndNo
 			break
 		}
 		// Error may be ignored here. The error has already been checked
-		// during transaction acceptance is the transaction pool.
+		// during transaction acceptance in the transaction pool.
 		from, _ := tx.From()
 
 		// Start executing the transaction

core/quorum/block_voting.go

@@ -74,7 +74,7 @@ type Vote struct {
 
 // CreateBlock is posted to the event mux when the BlockVoting instance
 // is ordered to create a new block. Either the hash of the created
-// block is returned is hash or an error.
+// block or an error is returned.
 type CreateBlock struct {
 	Hash chan common.Hash
 	Err  chan error

core/quorum/block_voting.sol

@@ -12,7 +12,7 @@ contract BlockVoting {
     event Vote(address indexed sender, uint blockNumber, bytes32 blockHash);
     // Raised when a new address is allowed to vote.
     event AddVoter(address);
-    // Raised when an address is not alloed to make votes anymore.
+    // Raised when an address is not allowed to make votes anymore.
 	event RemovedVoter(address);
 	// Raised when a new address is allowed to create new blocks.
 	event AddBlockMaker(address);
@@ -32,7 +32,7 @@ contract BlockVoting {
     // Collection of vote rounds.
 	Period[] periods;
 
-    // canonical hash must have as least voteThreshold votes before its considered valid
+    // Canonical hash must have at least voteThreshold votes before its considered valid.
 	uint public voteThreshold;
 
     // Number of addresses that are allowed to make votes.
@@ -41,7 +41,7 @@ contract BlockVoting {
     // Collection of addresses that are allowed to vote.
     mapping(address => bool) public canVote;
 
-    // Number of addresses that are alloed to create blocks.
+    // Number of addresses that are allowed to create blocks.
     uint public blockMakerCount;
 
     // Collection of addresses that are allowed to create blocks.
@@ -112,7 +112,7 @@ contract BlockVoting {
 		return best;
 	}
 
-	// Add an party that is allowed to make a vote.
+	// Add a party that is allowed to make a vote.
 	// Only current voters are allowed to add a new voter.
 	function addVoter(address addr) mustBeVoter {
 		if (!canVote[addr]) {
@@ -123,9 +123,9 @@ contract BlockVoting {
 	}
 
 	// Remove a party that is allowed to vote.
-	// Note, a voter can remove it self as a voter!
+	// Note, a voter can remove itself as a voter!
 	function removeVoter(address addr) mustBeVoter {
-	    // don't let the last voter remove it self
+	    // don't let the last voter remove itself
 	    // which can cause the algorithm to stall.
 	    if (voterCount == 1) throw;
 
@@ -151,7 +151,7 @@ contract BlockVoting {
         }
 	}
 
-	// removeBlocksMaker deletes the given address of the collection of
+	// removeBlocksMaker deletes the given address from the collection of
 	// addresses that are allowed to create blocks.
 	function removeBlockMaker(address addr) mustBeBlockMaker {
 	    if (blockMakerCount == 1) throw;
@@ -178,4 +178,4 @@ contract BlockVoting {
 		Period period = periods[height-1];
 		return period.indices[n];
 	}
-}
+}

core/quorum/block_voting_test.go

@@ -66,85 +66,3 @@ func genesisBlock(voteThreshold int) string {
 		voteThreshold,
 	)
 }
-
-func TestBlockVotingBlockMaker(t *testing.T) {
-	//var (
-	//	db, _       = ethdb.NewMemDatabase()
-	//	mux         event.TypeMux
-	//	chainConfig = core.MakeChainConfig()
-	//	bv          *quorum.BlockVoting
-	//
-	//	err error
-	//)
-	//
-	//genesis, err := core.WriteGenesisBlock(db, strings.NewReader(genesisBlock(2)))
-	//if err != nil {
-	//	t.Fatal(err)
-	//}
-	//
-	//blockchain, _ := core.NewBlockChain(db, chainConfig, core.FakePow{}, &mux, false)
-	//
-	//txpool := core.NewTxPool(chainConfig, &mux, func() (*state.StateDB, error) {
-	//	_, state := bv.Pending()
-	//	return state, nil
-	//}, func() *big.Int { return big.NewInt(1000000) })
-	//
-	//// func NewBlockVoting(client *rpc.Client, bc *core.BlockChain, chainConfig *core.ChainConfig, txpool *core.TxPool, mux *event.TypeMux, db ethdb.Database, blockMakerKey, voteKey *ecdsa.PrivateKey, isSynchronised bool) *BlockVoting {
-	//bv, err = quorum.NewBlockVoting(nil, blockchain, chainConfig, txpool, &mux, db, blockMakerKey1, voteKey1, true)
-	//if err != nil {
-	//	t.Fatal(err)
-	//}
-	//
-	//pBlock, _ := bv.Pending()
-	//if pBlock.NumberU64() != 1 {
-	//	t.Fatalf("Expected pending block to have block number 1, got %d", pBlock.NumberU64())
-	//}
-	//
-	//createBlockReq := quorum.CreateBlock{
-	//	Hash: make(chan common.Hash),
-	//	Err:  make(chan error),
-	//}
-	//
-	//mux.Post(createBlockReq)
-	//
-	//select {
-	//case <-createBlockReq.Hash:
-	//	t.Fatalf("Block was create while vote threshold was not met")
-	//case <-createBlockReq.Err:
-	//	break
-	//}
-	//
-	//// send in 2 votes and creating a block should work
-	//vote := quorum.Vote{
-	//	Hash:   genesis.Hash(),
-	//	Number: genesis.Number(),
-	//	TxHash: make(chan common.Hash),
-	//	Err:    make(chan error),
-	//}
-	//mux.Post(vote)
-	//
-	//select {
-	//case err := <-vote.Err:
-	//	t.Fatalf("Unable to vote: %s", err)
-	//case <-vote.TxHash:
-	//	break
-	//}
-	//
-	//mux.Post(vote)
-	//
-	//select {
-	//case err := <-vote.Err:
-	//	t.Fatalf("Unable to vote: %s", err)
-	//case <-vote.TxHash:
-	//	break
-	//}
-	//
-	//mux.Post(createBlockReq)
-	//
-	//select {
-	//case hash := <-createBlockReq.Hash:
-	//	t.Logf("Created block %s", hash.Hex())
-	//case err := <-createBlockReq.Err:
-	//	t.Fatalf("Block should be created but got error: %s", err)
-	//}
-}

core/quorum/vote_strategy.go

@@ -35,7 +35,7 @@ type BlockMakerStrategy interface {
 
 // randomDeadlineStrategy asks the block voter to generate blocks
 // after a deadline is passed without importing a new head. This
-// deadline is chosen random between 2 limits.
+// deadline is chosen at random between 2 limits.
 type randomDeadlineStrategy struct {
 	mux           *event.TypeMux
 	min, max      int // min and max deadline

docs/api.md

@@ -18,9 +18,9 @@ Sends a transaction to the network.
   - `to`: `String` - (optional) The destination address of the message, left undefined for a contract-creation transaction.
   - `value`: `Number|String|BigNumber` - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction.
   - `gas`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
-  - <strike>`gasPrice`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price.</strike>
+  - <strike>`gasPrice`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The price of gas for this transaction in Wei, defaults to the mean network gas price.</strike>
   - `data`: `String` - (optional) Either a [byte string](https://github.com/ethereum/wiki/wiki/Solidity,-Docs-and-ABI) containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code.
-  - `nonce`: `Number`  - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
+  - `nonce`: `Number`  - (optional) Integer of a nonce. This allows you to overwrite your own pending transactions that use the same nonce.
   - `privateFrom`: `String`  - (optional) When sending a private transaction, the sending party's base64-encoded public key to use. If not present *and* passing `privateFor`, use the default key as configured in the `TransactionManager`.
   - `privateFor`: `List<String>`  - (optional) When sending a private transaction, an array of the recipients' base64-encoded public keys.
 2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details.

docs/design.md

@@ -27,7 +27,7 @@ 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 payloads (public).
+The difference is made through the use of transactions with encrypted (private) and non-encrypted (public) payloads.
 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.
 
@@ -48,7 +48,7 @@ S: sender, (X): private, X: public, ->: direction, []: read only mode
 2. S -> (A) -> (B)
 3. S -> (A) -> [B -> C]
 ```
-The following transaction are unsupported:
+The following transactions are unsupported:
 
 ```
 1. (S) -> A

docs/running.md

@@ -106,6 +106,7 @@ From the above example, the `<256 bit aligned key value>` is the ethereum accoun
 The `genesis.json` file can be found in the `7nodes` folder in the `quorum-examples` repository.
 
 ### Setup Bootnode
+
 Optionally you can set up a bootnode that all the other nodes will first connect to in order to find other peers in the network. You will first need to generate a bootnode key: 
 
 1-	To generate the key for the first time:

raft/backend.go

@@ -20,7 +20,7 @@ import (
 
 type RaftService struct {
 	blockchain     *core.BlockChain
-	chainDb        ethdb.Database // Block chain database
+	chainDb        ethdb.Database // Blockchain database
 	txMu           sync.Mutex
 	txPool         *core.TxPool
 	accountManager *accounts.Manager

raft/doc.md

@@ -27,7 +27,7 @@ verifier | follower
 
 The main reasons we co-locate the leader and minter are (1) convenience, in that Raft ensures there is only one leader at a time, and (2) to avoid a network hop from a node minting blocks to the leader, through which all Raft writes must flow. Our implementation watches Raft leadership changes -- if a node becomes a leader it will start minting, and if a node loses its leadership, it will stop minting.
 
-An observant reader might note that during raft leadership transitions, there could be a small period of time where more than one node might assume that it has minting duties; we detail how correctness is preserved in more detail later in this document.
+An observant reader might note that during raft leadership transitions, there could be a small period of time where more than one node might assume that it has minting duties; we describe how correctness is preserved in more detail later in this document.
 
 We use the existing Ethereum p2p transport layer to communicate transactions between nodes, but we communicate blocks only through the Raft transport layer. They are created by the minter and flow from there to the rest of the cluster, always in the same order, via Raft.
 
@@ -94,7 +94,7 @@ Where `0xbeda` is the ID of new block, and `0xaa` is the ID of its parent. Here,
   v                              [ 0x8b37 Parent: 0x8b37 ]
 ```
 
-Once the partition heals, at the Raft layer node1 will resubmit `0x2c52`, and the resulting serialized log might look as follows:
+Once the partition heals, at the Raft layer node 1 will resubmit `0x2c52`, and the resulting serialized log might look as follows:
 
 ```
 [ 0xbeda Parent: 0xacaa - Extends! ]  (due to node 1)
@@ -144,7 +144,7 @@ There is currently no limit to the length of these speculative chains, but we pl
 
 ## The Raft transport layer
 
-We communicate blocks over the HTTP transport layer built in to etcd Raft. It's also (at least theoretically) possible to use p2p protocol built-in to Ethereum as a transport for Raft. In our testing we found the default etcd HTTP transport to be more reliable than the p2p (at least as implemented in geth) under high load.
+We communicate blocks over the HTTP transport layer built in to etcd Raft. It's also (at least theoretically) possible to use the p2p protocol built-in to Ethereum as a transport for Raft. In our testing we found the default etcd HTTP transport to be more reliable than the p2p (at least as implemented in geth) under high load.
 
 ## FAQ
 

raft/speculative_chain.go

@@ -77,7 +77,7 @@ func (chain *speculativeChain) accept(acceptedBlock *types.Block) {
 // Remove all blocks in the chain from the specified one until the end
 func (chain *speculativeChain) unwindFrom(invalidHash common.Hash, headBlock *types.Block) {
 
-	// check our "guard" to see if this is a (descendant) block we're
+	// check our "guard" to see if this is a (descendant) block we
 	// expected to be ruled invalid. if we find it, remove from the guard
 	if chain.expectedInvalidBlockHashes.Has(invalidHash) {
 		glog.V(logger.Warn).Infof("Removing expected-invalid block %x from guard.\n", invalidHash)
@@ -102,7 +102,7 @@ func (chain *speculativeChain) unwindFrom(invalidHash common.Hash, headBlock *ty
 
 		glog.V(logger.Info).Infof("Popped block %x from queue RHS.\n", currBlock.Hash())
 
-		// Maintain invariant: the parent always points the last speculative block or the head of the blockchain
+		// Maintain invariant: the parent always points to the last speculative block or the head of the blockchain
 		// if there are not speculative blocks.
 		if speculativeParentI := chain.unappliedBlocks.Last(); nil != speculativeParentI {
 			chain.head = speculativeParentI.(*types.Block)
@@ -138,7 +138,7 @@ func (chain *speculativeChain) recordProposedTransactions(txes types.Transaction
 // Removes txes in block from our "blacklist" of "proposed tx" hashes. When we
 // create a new block and use txes from the tx pool, we ignore those that we
 // have already used ("proposed"), but that haven't yet officially made it into
-// the chain yet.
+// the chain.
 //
 // It's important to remove hashes from this blacklist (once we know we don't
 // need them in there anymore) so that it doesn't grow endlessly.