Added comments and some minor improvements

Author: rampatra

src/main/java/com/rampatra/blockchain/Blockchain.java

@@ -40,6 +40,15 @@ public void addBlock(Block block) {
         blocks.add(block);
     }
 
+    /**
+     * Mine, create a new block with the {@code data}, and finally, add it to the blockchain.
+     * <p>
+     * Mining is nothing but the process of calculating a hash of a {@link Block} with {@code data} such
+     * that the hash starts with a specific number of zeros equal to the difficulty of the blockchain.
+     *
+     * @param data
+     * @return
+     */
     public Block mine(String data) {
         Block previousBlock = getLatestBlock();
         Block nextBlock = getNextBlock(previousBlock, data);
@@ -52,6 +61,11 @@ public Block mine(String data) {
         }
     }
 
+    /**
+     * Executes the {@link Blockchain#isValidNextBlock(Block, Block)} on the entire blockchain.
+     *
+     * @return {@code false} if at least one block in the blockchain is invalid, {@code true} otherwise.
+     */
     public boolean isValidChain() {
         ListIterator<Block> listIterator = blocks.listIterator();
         listIterator.next();
@@ -63,6 +77,11 @@ public boolean isValidChain() {
         return true;
     }
 
+    /**
+     * Creates the Genesis Block for the blockchain. The Genesis Block is the first block in the blockchain.
+     *
+     * @return the genesis block
+     */
     private Block getGenesisBlock() {
         final long timestamp = new Date().getTime();
         int nonce = 0;
@@ -105,6 +124,13 @@ private boolean isValidNextBlock(Block previousBlock, Block nextBlock) {
         }
     }
 
+    /**
+     * Checks if the hash respects the difficulty of the blockchain, i.e, if the hash
+     * begins with a number of zeros equal to the difficulty of the blockchain.
+     *
+     * @param hash the SHA256 hash of the block.
+     * @return {@code true} if hash obeys difficulty, {@code false} otherwise.
+     */
     private boolean isValidHashDifficulty(String hash) {
         for (int i = 0; i < difficulty; i++) {
             if (hash.charAt(i) != '0') {
@@ -114,6 +140,16 @@ private boolean isValidHashDifficulty(String hash) {
         return true;
     }
 
+    /**
+     * Calculates the SHA256 hash of the block.
+     *
+     * @param index
+     * @param previousHash
+     * @param timestamp
+     * @param data
+     * @param nonce
+     * @return the SHA256 hash of the block.
+     */
     private String calculateHashForBlock(final int index, final String previousHash, final long timestamp,
                                          final String data, final int nonce) {
         try {

src/main/java/com/rampatra/blockchain/MessageHandler.java

@@ -12,9 +12,9 @@
  */
 public class MessageHandler implements Runnable {
 
-    ObjectInputStream in;
-    ObjectOutputStream out;
-    Peer peer;
+    private ObjectInputStream in;
+    private ObjectOutputStream out;
+    private Peer peer;
 
     MessageHandler(Socket client, Peer peer) {
         try {
@@ -42,6 +42,11 @@ public void run() {
         }
     }
 
+    /**
+     * Handle messages accordingly.
+     *
+     * @param message is the message object from the peer.
+     */
     private void handleMessage(Message message) {
         Message.MessageType type = message.getMessageType();
         switch (type) {
@@ -78,6 +83,14 @@ private void sendMessage(Message message) {
         }
     }
 
+    /**
+     * If the latest block received from the peer has {@code previousHash} equal to the hash of the
+     * latest block in the current user's blockchain then add the latest block received to the 
+     * current user's blockchain, or else, if the latest block received has a larger index then 
+     * request the entire blockchain from the peer.
+     *
+     * @param latestBlock the block received from the peer
+     */
     private void handleLatestBlock(Block latestBlock) {
         Block latestBlockWithCurrentPeer = peer.getBlockchain().getLatestBlock();
 
@@ -91,6 +104,12 @@ private void handleLatestBlock(Block latestBlock) {
         }
     }
 
+    /**
+     * If the blockchain received from the peer is valid and longer then replace current user's
+     * blockchain with the received blockchain.
+     *
+     * @param blockchain the entire blockchain received from the peer
+     */
     private void handleBlockchain(Blockchain blockchain) {
         if (blockchain.isValidChain() && blockchain.getSize() > peer.getBlockchain().getSize()) {
             peer.setBlockchain(blockchain);

src/main/java/com/rampatra/blockchain/Peer.java

@@ -28,11 +28,15 @@ public class Peer {
         getLatestBlockFromPeers();
     }
 
+    /**
+     * Once a new peer is created, we start the socket server to receive messages from the peers.
+     */
     private void startServer() {
         try {
             executor.submit(() -> {
                 server = new ServerSocket(port);
                 while (true) {
+                    // we create a new thread for each new client thereby supporting multiple client simultaneously
                     new Thread(new MessageHandler(server.accept(), this)).start();
                 }
             });
@@ -41,6 +45,9 @@ private void startServer() {
         }
     }
 
+    /**
+     * Stop the server once a peer is removed from the network.
+     */
     public void stopServer() {
         try {
             if (!server.isClosed()) {
@@ -51,6 +58,10 @@ public void stopServer() {
         }
     }
 
+    /**
+     * Once a new peer is created and added to the network, it requests the latest block from 
+     * all the peers and updates its blockchain if it is outdated.
+     */
     private void getLatestBlockFromPeers() {
         sendMessageToPeers(Message.MessageBuilder
                 .aMessage()
@@ -60,6 +71,7 @@ private void getLatestBlockFromPeers() {
 
     private void sendMessageToPeers(Message message) {
         try {
+            // send to all peers except itself
             List<Peer> peers = P2P.getPeers()
                     .stream()
                     .filter(peer -> !(peer.port == this.port))
@@ -74,6 +86,11 @@ private void sendMessageToPeers(Message message) {
         }
     }
 
+    /**
+     * Mine, create a new block with the {@code data}, and finally, add it to the blockchain.
+     *
+     * @param data
+     */
     public void mine(String data) {
         Block latestBlock = this.blockchain.mine(data);
         sendMessageToPeers(Message.MessageBuilder
@@ -103,6 +120,13 @@ public String toString() {
         return sb.toString();
     }
 
+    /**
+     * The main starting point of the blockchain demo. At first, add some peers (option 1) and mine some data 
+     * by choosing a particular peer (option 2). You would soon see that the newly mined block is broadcast to
+     * all the peers.
+     *
+     * @param args
+     */
     public static void main(String[] args) {
         try {
             int menuChoice;
@@ -129,18 +153,18 @@ public static void main(String[] args) {
                         P2P.showPeersWithBlockchain();
                         break;
                     case 2:
-                        System.out.println("Choose peer: (ex. 1, 2, etc.)");
+                        System.out.println("Choose peer: (a number for ex. 1, 2, etc.)");
                         P2P.showPeers();
                         peerIndex = s.nextInt();
                         Peer p = P2P.getPeer(peerIndex - 1);
-                        System.out.println("Enter data: ");
+                        System.out.println("Enter data: (a string with no spaces)");
                         data = s.next();
                         p.mine(data);
                         System.out.println("Data mined!");
                         P2P.showPeersWithBlockchain();
                         break;
                     case 3:
-                        System.out.println("Choose peer: (ex. 1, 2, etc.)");
+                        System.out.println("Choose peer: (a number for ex. 1, 2, etc.)");
                         P2P.showPeers();
                         peerIndex = s.nextInt();
                         P2P.removePeer(peerIndex - 1);