Add more comments for client code

client/client.go

@@ -9,40 +9,45 @@ import (
 	"sync"
 )
 
-// A client represent a entity/user which send transactions and receive responses from the harmony network
+// A client represent a node (e.g. wallet) which  sends transactions and receive responses from the harmony network
 type Client struct {
-	PendingCrossTxs      map[[32]byte]*blockchain.Transaction // map of TxId to pending cross shard txs
-	PendingCrossTxsMutex sync.Mutex
-	leaders              *[]p2p.Peer
-
-	UpdateBlocks func([]*blockchain.Block) // func used to sync blocks with the leader
+	PendingCrossTxs      map[[32]byte]*blockchain.Transaction // Map of TxId to pending cross shard txs. Pending means the proof-of-accept/rejects are not complete
+	PendingCrossTxsMutex sync.Mutex                           // Mutex for the pending txs list
+	leaders              *[]p2p.Peer                          // All the leaders for each shard
+	UpdateBlocks         func([]*blockchain.Block)            // Closure function used to sync new block with the leader. Once the leader finishes the consensus on a new block, it will send it to the clients. Clients use this method to update their blockchain
 
 	log log.Logger // Log utility
 }
 
+// The message handler for CLIENT/TRANSACTION messages.
 func (client *Client) TransactionMessageHandler(msgPayload []byte) {
 	messageType := TransactionMessageType(msgPayload[0])
 	switch messageType {
 	case PROOF_OF_LOCK:
+		// Decode the list of blockchain.CrossShardTxProof
 		txDecoder := gob.NewDecoder(bytes.NewReader(msgPayload[1:])) // skip the PROOF_OF_LOCK messge type
-
 		proofList := new([]blockchain.CrossShardTxProof)
 		err := txDecoder.Decode(&proofList)
+
 		if err != nil {
 			client.log.Error("Failed deserializing cross transaction proof list")
 		}
 
 		txsToSend := []blockchain.Transaction{}
-		client.PendingCrossTxsMutex.Lock()
 
+		// Loop through the newly received list of proofs
+		client.PendingCrossTxsMutex.Lock()
 		for _, proof := range *proofList {
 
+			// Find the corresponding pending cross tx
 			txAndProofs, ok := client.PendingCrossTxs[proof.TxID]
 
-			readyToUnlock := true
+			readyToUnlock := true // A flag used to mark whether whether this pending cross tx have all the proofs for its utxo input
 			if ok {
+				// Add the new proof to the cross tx's proof list
 				txAndProofs.Proofs = append(txAndProofs.Proofs, proof)
 
+				// Check whether this pending cross tx have all the proofs for its utxo input
 				txInputs := make(map[blockchain.TXInput]bool)
 				for _, curProof := range txAndProofs.Proofs {
 					for _, txInput := range curProof.TxInput {
@@ -58,30 +63,30 @@ func (client *Client) TransactionMessageHandler(msgPayload []byte) {
 			} else {
 				readyToUnlock = false
 			}
+
 			if readyToUnlock {
 				txsToSend = append(txsToSend, *txAndProofs)
 			}
 		}
+
+		// Delete all the transactions with full proofs from the pending cross txs
 		for _, txToSend := range txsToSend {
 			delete(client.PendingCrossTxs, txToSend.ID)
 		}
 		client.PendingCrossTxsMutex.Unlock()
 
+		// Broadcast the cross txs with full proofs for unlock-to-commit/abort
 		if len(txsToSend) != 0 {
-			client.sendCrossShardTxUnlockMessage(&txsToSend)
-			tempList := []*blockchain.Transaction{}
-			for i, _ := range txsToSend {
-				tempList = append(tempList, &txsToSend[i])
-			}
+			client.broadcastCrossShardTxUnlockMessage(&txsToSend)
 		}
 	}
 }
 
-func (client *Client) sendCrossShardTxUnlockMessage(txsToSend *[]blockchain.Transaction) {
+func (client *Client) broadcastCrossShardTxUnlockMessage(txsToSend *[]blockchain.Transaction) {
 	p2p.BroadcastMessage(*client.leaders, ConstructUnlockToCommitOrAbortMessage(*txsToSend))
 }
 
-// Create a new Node
+// Create a new Cient
 func NewClient(leaders *[]p2p.Peer) *Client {
 	client := Client{}
 	client.PendingCrossTxs = make(map[[32]byte]*blockchain.Transaction)

client/message.go

@@ -19,7 +19,7 @@ const (
 type TransactionMessageType int
 
 const (
-	PROOF_OF_LOCK TransactionMessageType = iota // The proof of accept or reject returned by the leader to the cross shard transaction client.
+	PROOF_OF_LOCK TransactionMessageType = iota // The proof of accept or reject returned by the leader to the client tnat issued cross shard transactions.
 )
 
 // [leader] Constructs the proof of accept or reject message that will be sent to client