rlp, trie, contracts, compression, consensus: improve comments (ethereum#14580)

Author: S. Matthew English

compression/rle/read_write_test.go

@@ -33,102 +33,18 @@ func (s *CompressionRleSuite) TestDecompressSimple(c *checker.C) {
 	res, err := Decompress([]byte{token, 0xfd})
 	c.Assert(err, checker.IsNil)
 	c.Assert(res, checker.DeepEquals, exp)
-	// if bytes.Compare(res, exp) != 0 {
-	// 	t.Error("empty sha3", res)
-	// }
 
 	exp = []byte{0x56, 0xe8, 0x1f, 0x17, 0x1b, 0xcc, 0x55, 0xa6, 0xff, 0x83, 0x45, 0xe6, 0x92, 0xc0, 0xf8, 0x6e, 0x5b, 0x48, 0xe0, 0x1b, 0x99, 0x6c, 0xad, 0xc0, 0x1, 0x62, 0x2f, 0xb5, 0xe3, 0x63, 0xb4, 0x21}
 	res, err = Decompress([]byte{token, 0xfe})
 	c.Assert(err, checker.IsNil)
 	c.Assert(res, checker.DeepEquals, exp)
-	// if bytes.Compare(res, exp) != 0 {
-	// 	t.Error("0x80 sha3", res)
-	// }
 
 	res, err = Decompress([]byte{token, 0xff})
 	c.Assert(err, checker.IsNil)
 	c.Assert(res, checker.DeepEquals, []byte{token})
-	// if bytes.Compare(res, []byte{token}) != 0 {
-	// 	t.Error("token", res)
-	// }
 
 	res, err = Decompress([]byte{token, 12})
 	c.Assert(err, checker.IsNil)
 	c.Assert(res, checker.DeepEquals, make([]byte, 10))
-	// if bytes.Compare(res, make([]byte, 10)) != 0 {
-	// 	t.Error("10 * zero", res)
-	// }
-}
-
-// func TestDecompressMulti(t *testing.T) {
-// 	res, err := Decompress([]byte{token, 0xfd, token, 0xfe, token, 12})
-// 	if err != nil {
-// 		t.Error(err)
-// 	}
-
-// 	var exp []byte
-// 	exp = append(exp, crypto.Keccak256([]byte(""))...)
-// 	exp = append(exp, crypto.Keccak256([]byte{0x80})...)
-// 	exp = append(exp, make([]byte, 10)...)
-
-// 	if bytes.Compare(res, res) != 0 {
-// 		t.Error("Expected", exp, "result", res)
-// 	}
-// }
-
-// func TestCompressSimple(t *testing.T) {
-// 	res := Compress([]byte{0, 0, 0, 0, 0})
-// 	if bytes.Compare(res, []byte{token, 7}) != 0 {
-// 		t.Error("5 * zero", res)
-// 	}
-
-// 	res = Compress(crypto.Keccak256([]byte("")))
-// 	if bytes.Compare(res, []byte{token, emptyShaToken}) != 0 {
-// 		t.Error("empty sha", res)
-// 	}
-
-// 	res = Compress(crypto.Keccak256([]byte{0x80}))
-// 	if bytes.Compare(res, []byte{token, emptyListShaToken}) != 0 {
-// 		t.Error("empty list sha", res)
-// 	}
 
-// 	res = Compress([]byte{token})
-// 	if bytes.Compare(res, []byte{token, tokenToken}) != 0 {
-// 		t.Error("token", res)
-// 	}
-// }
-
-// func TestCompressMulti(t *testing.T) {
-// 	in := []byte{0, 0, 0, 0, 0}
-// 	in = append(in, crypto.Keccak256([]byte(""))...)
-// 	in = append(in, crypto.Keccak256([]byte{0x80})...)
-// 	in = append(in, token)
-// 	res := Compress(in)
-
-// 	exp := []byte{token, 7, token, emptyShaToken, token, emptyListShaToken, token, tokenToken}
-// 	if bytes.Compare(res, exp) != 0 {
-// 		t.Error("expected", exp, "got", res)
-// 	}
-// }
-
-// func TestCompressDecompress(t *testing.T) {
-// 	var in []byte
-
-// 	for i := 0; i < 20; i++ {
-// 		in = append(in, []byte{0, 0, 0, 0, 0}...)
-// 		in = append(in, crypto.Keccak256([]byte(""))...)
-// 		in = append(in, crypto.Keccak256([]byte{0x80})...)
-// 		in = append(in, []byte{123, 2, 19, 89, 245, 254, 255, token, 98, 233}...)
-// 		in = append(in, token)
-// 	}
-
-// 	c := Compress(in)
-// 	d, err := Decompress(c)
-// 	if err != nil {
-// 		t.Error(err)
-// 	}
-
-// 	if bytes.Compare(d, in) != 0 {
-// 		t.Error("multi failed\n", d, "\n", in)
-// 	}
-// }
+}

consensus/clique/clique.go

@@ -76,15 +76,15 @@ var (
 	errUnknownBlock = errors.New("unknown block")
 
 	// errInvalidCheckpointBeneficiary is returned if a checkpoint/epoch transition
-	// block has a beneficiary set to non zeroes.
+	// block has a beneficiary set to non-zeroes.
 	errInvalidCheckpointBeneficiary = errors.New("beneficiary in checkpoint block non-zero")
 
 	// errInvalidVote is returned if a nonce value is something else that the two
 	// allowed constants of 0x00..0 or 0xff..f.
 	errInvalidVote = errors.New("vote nonce not 0x00..0 or 0xff..f")
 
 	// errInvalidCheckpointVote is returned if a checkpoint/epoch transition block
-	// has a vote nonce set to non zeroes.
+	// has a vote nonce set to non-zeroes.
 	errInvalidCheckpointVote = errors.New("vote nonce in checkpoint block non-zero")
 
 	// errMissingVanity is returned if a block's extra-data section is shorter than
@@ -104,7 +104,7 @@ var (
 	// ones).
 	drrInvalidCheckpointSigners = errors.New("invalid signer list on checkpoint block")
 
-	// errInvalidMixDigest is returned if a block's mix digest is non zero.
+	// errInvalidMixDigest is returned if a block's mix digest is non-zero.
 	errInvalidMixDigest = errors.New("non-zero mix digest")
 
 	// errInvalidUncleHash is returned if a block contains an non-empty uncle list.
@@ -122,7 +122,7 @@ var (
 	// be modified via out-of-range or non-contiguous headers.
 	errInvalidVotingChain = errors.New("invalid voting chain")
 
-	// errUnauthorized is returned if a header is signed by a non authorized entity.
+	// errUnauthorized is returned if a header is signed by a non-authorized entity.
 	errUnauthorized = errors.New("unauthorized")
 )
 
@@ -499,7 +499,7 @@ func (c *Clique) verifySeal(chain consensus.ChainReader, header *types.Header, p
 // Prepare implements consensus.Engine, preparing all the consensus fields of the
 // header for running the transactions on top.
 func (c *Clique) Prepare(chain consensus.ChainReader, header *types.Header) error {
-	// If the block isn't a checkpoint, cast a random vote (good enough fror now)
+	// If the block isn't a checkpoint, cast a random vote (good enough for now)
 	header.Coinbase = common.Address{}
 	header.Nonce = types.BlockNonce{}
 
@@ -601,7 +601,7 @@ func (c *Clique) Seal(chain consensus.ChainReader, block *types.Block, stop <-ch
 	if _, authorized := snap.Signers[signer]; !authorized {
 		return nil, errUnauthorized
 	}
-	// If we're amongs the recent signers, wait for the next block
+	// If we're amongst the recent signers, wait for the next block
 	for seen, recent := range snap.Recents {
 		if recent == signer {
 			// Signer is among recents, only wait if the current block doens't shift it out

consensus/clique/snapshot.go

@@ -39,7 +39,7 @@ type Vote struct {
 // Tally is a simple vote tally to keep the current score of votes. Votes that
 // go against the proposal aren't counted since it's equivalent to not voting.
 type Tally struct {
-	Authorize bool `json:"authorize"` // Whether the vote it about authorizing or kicking someone
+	Authorize bool `json:"authorize"` // Whether the vote is about authorizing or kicking someone
 	Votes     int  `json:"votes"`     // Number of votes until now wanting to pass the proposal
 }
 
@@ -56,7 +56,7 @@ type Snapshot struct {
 	Tally   map[common.Address]Tally    `json:"tally"`   // Current vote tally to avoid recalculating
 }
 
-// newSnapshot create a new snapshot with the specified startup parameters. This
+// newSnapshot creates a new snapshot with the specified startup parameters. This
 // method does not initialize the set of recent signers, so only ever use if for
 // the genesis block.
 func newSnapshot(config *params.CliqueConfig, sigcache *lru.ARCCache, number uint64, hash common.Hash, signers []common.Address) *Snapshot {

consensus/clique/snapshot_test.go

@@ -243,7 +243,7 @@ func TestVoting(t *testing.T) {
 			},
 			results: []string{"A", "B"},
 		}, {
-			// Cascading changes are not allowed, only the the account being voted on may change
+			// Cascading changes are not allowed, only the account being voted on may change
 			signers: []string{"A", "B", "C", "D"},
 			votes: []testerVote{
 				{signer: "A", voted: "C", auth: false},
@@ -293,7 +293,7 @@ func TestVoting(t *testing.T) {
 			results: []string{"A", "B", "C"},
 		}, {
 			// Ensure that pending votes don't survive authorization status changes. This
-			// corner case can only appear if a signer is quickly added, remove and then
+			// corner case can only appear if a signer is quickly added, removed and then
 			// readded (or the inverse), while one of the original voters dropped. If a
 			// past vote is left cached in the system somewhere, this will interfere with
 			// the final signer outcome.

consensus/consensus.go

@@ -79,8 +79,7 @@ type Engine interface {
 
 	// Finalize runs any post-transaction state modifications (e.g. block rewards)
 	// and assembles the final block.
-	//
-	// Note, the block header and state database might be updated to reflect any
+	// Note: The block header and state database might be updated to reflect any
 	// consensus rules that happen at finalization (e.g. block rewards).
 	Finalize(chain ChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction,
 		uncles []*types.Header, receipts []*types.Receipt) (*types.Block, error)

consensus/ethash/algorithm.go

@@ -53,7 +53,6 @@ type hasher func(dest []byte, data []byte)
 
 // makeHasher creates a repetitive hasher, allowing the same hash data structures
 // to be reused between hash runs instead of requiring new ones to be created.
-//
 // The returned function is not thread safe!
 func makeHasher(h hash.Hash) hasher {
 	return func(dest []byte, data []byte) {
@@ -82,7 +81,6 @@ func seedHash(block uint64) []byte {
 // memory, then performing two passes of Sergio Demian Lerner's RandMemoHash
 // algorithm from Strict Memory Hard Hashing Functions (2014). The output is a
 // set of 524288 64-byte values.
-//
 // This method places the result into dest in machine byte order.
 func generateCache(dest []uint32, epoch uint64, seed []byte) {
 	// Print some debug logs to allow analysis on low end devices
@@ -220,7 +218,6 @@ func generateDatasetItem(cache []uint32, index uint32, keccak512 hasher) []byte
 }
 
 // generateDataset generates the entire ethash dataset for mining.
-//
 // This method places the result into dest in machine byte order.
 func generateDataset(dest []uint32, epoch uint64, cache []uint32) {
 	// Print some debug logs to allow analysis on low end devices

consensus/ethash/algorithm_go1.8_test.go

@@ -20,7 +20,7 @@ package ethash
 
 import "testing"
 
-// Tests whether the dataset size calculator work correctly by cross checking the
+// Tests whether the dataset size calculator works correctly by cross checking the
 // hard coded lookup table with the value generated by it.
 func TestSizeCalculations(t *testing.T) {
 	var tests []uint64

consensus/ethash/consensus.go

@@ -218,7 +218,6 @@ func (ethash *Ethash) VerifyUncles(chain consensus.ChainReader, block *types.Blo
 
 // verifyHeader checks whether a header conforms to the consensus rules of the
 // stock Ethereum ethash engine.
-//
 // See YP section 4.3.4. "Block Header Validity"
 func (ethash *Ethash) verifyHeader(chain consensus.ChainReader, header, parent *types.Header, uncle bool, seal bool) error {
 	// Ensure that the header's extra-data section is of a reasonable size
@@ -286,7 +285,6 @@ func (ethash *Ethash) verifyHeader(chain consensus.ChainReader, header, parent *
 // CalcDifficulty is the difficulty adjustment algorithm. It returns
 // the difficulty that a new block should have when created at time
 // given the parent block's time and difficulty.
-//
 // TODO (karalabe): Move the chain maker into this package and make this private!
 func CalcDifficulty(config *params.ChainConfig, time uint64, parent *types.Header) *big.Int {
 	next := new(big.Int).Add(parent.Number, common.Big1)
@@ -462,7 +460,6 @@ var (
 // AccumulateRewards credits the coinbase of the given block with the mining
 // reward. The total reward consists of the static block reward and rewards for
 // included uncles. The coinbase of each uncle block is also rewarded.
-//
 // TODO (karalabe): Move the chain maker into this package and make this private!
 func AccumulateRewards(state *state.StateDB, header *types.Header, uncles []*types.Header) {
 	reward := new(big.Int).Set(blockReward)

consensus/ethash/ethash.go

@@ -355,7 +355,7 @@ type Ethash struct {
 // New creates a full sized ethash PoW scheme.
 func New(cachedir string, cachesinmem, cachesondisk int, dagdir string, dagsinmem, dagsondisk int) *Ethash {
 	if cachesinmem <= 0 {
-		log.Warn("One ethash cache must alwast be in memory", "requested", cachesinmem)
+		log.Warn("One ethash cache must always be in memory", "requested", cachesinmem)
 		cachesinmem = 1
 	}
 	if cachedir != "" && cachesondisk > 0 {
@@ -412,7 +412,7 @@ func NewFakeDelayer(delay time.Duration) *Ethash {
 	return &Ethash{fakeMode: true, fakeDelay: delay}
 }
 
-// NewFullFaker creates a ethash consensus engine with a full fake scheme that
+// NewFullFaker creates an ethash consensus engine with a full fake scheme that
 // accepts all blocks as valid, without checking any consensus rules whatsoever.
 func NewFullFaker() *Ethash {
 	return &Ethash{fakeMode: true, fakeFull: true}

consensus/misc/dao.go

@@ -54,7 +54,7 @@ func VerifyDAOHeaderExtraData(config *params.ChainConfig, header *types.Header)
 	if header.Number.Cmp(config.DAOForkBlock) < 0 || header.Number.Cmp(limit) >= 0 {
 		return nil
 	}
-	// Depending whether we support or oppose the fork, validate the extra-data contents
+	// Depending on whether we support or oppose the fork, validate the extra-data contents
 	if config.DAOForkSupport {
 		if !bytes.Equal(header.Extra, params.DAOForkBlockExtra) {
 			return ErrBadProDAOExtra

contracts/chequebook/cheque.go

@@ -49,7 +49,7 @@ import (
 // TODO(zelig): watch peer solvency and notify of bouncing cheques
 // TODO(zelig): enable paying with cheque by signing off
 
-// Some functionality require interacting with the blockchain:
+// Some functionality requires interacting with the blockchain:
 // * setting current balance on peer's chequebook
 // * sending the transaction to cash the cheque
 // * depositing ether to the chequebook
@@ -100,13 +100,13 @@ type Chequebook struct {
 	// persisted fields
 	balance      *big.Int                    // not synced with blockchain
 	contractAddr common.Address              // contract address
-	sent         map[common.Address]*big.Int //tallies for beneficiarys
+	sent         map[common.Address]*big.Int //tallies for beneficiaries
 
 	txhash    string   // tx hash of last deposit tx
 	threshold *big.Int // threshold that triggers autodeposit if not nil
 	buffer    *big.Int // buffer to keep on top of balance for fork protection
 
-	log log.Logger // contextual logger with the contrac address embedded
+	log log.Logger // contextual logger with the contract address embedded
 }
 
 func (self *Chequebook) String() string {
@@ -442,7 +442,7 @@ type Inbox struct {
 	maxUncashed *big.Int                    // threshold that triggers autocashing
 	cashed      *big.Int                    // cumulative amount cashed
 	cheque      *Cheque                     // last cheque, nil if none yet received
-	log         log.Logger                  // contextual logger with the contrac address embedded
+	log         log.Logger                  // contextual logger with the contract address embedded
 }
 
 // NewInbox creates an Inbox. An Inboxes is not persisted, the cumulative sum is updated
@@ -509,9 +509,8 @@ func (self *Inbox) AutoCash(cashInterval time.Duration, maxUncashed *big.Int) {
 	self.autoCash(cashInterval)
 }
 
-// autoCash starts a loop that periodically clears the last check
+// autoCash starts a loop that periodically clears the last cheque
 // if the peer is trusted. Clearing period could be 24h or a week.
-//
 // The caller must hold self.lock.
 func (self *Inbox) autoCash(cashInterval time.Duration) {
 	if self.quit != nil {
@@ -557,10 +556,10 @@ func (self *Inbox) Receive(promise swap.Promise) (*big.Int, error) {
 
 	var sum *big.Int
 	if self.cheque == nil {
-		// the sum is checked against the blockchain once a check is received
+		// the sum is checked against the blockchain once a cheque is received
 		tally, err := self.session.Sent(self.beneficiary)
 		if err != nil {
-			return nil, fmt.Errorf("inbox: error 	calling backend to set amount: %v", err)
+			return nil, fmt.Errorf("inbox: error calling backend to set amount: %v", err)
 		}
 		sum = tally
 	} else {