doc/book: hashchain: create protcol page && clean up

doc/src/misc/hashchain/architecture.md

@@ -4,63 +4,35 @@
 Tau using Model–view software architecture. All the operations, main data structures, 
 and handling messages from network protocol, happen in the `Model` side. 
 While keeping the `View` independent of the `Model` and focusing on getting update 
-from it continuously, and preserve and apply rules to received data.
+from it continuously.
 
 ## Model
 
 The `Model` consist of chains(`EventNodes`) structured as a tree, each chain has Event-based
-list. To maintain strict order each `Event` dependent on the hash of the previous `Event` 
-in the chain's `Event`s. All the chains will shared a root `Event` to preserve the tree
-structure. 
+list. To maintain strict order in chain, Each `Event` dependent on the hash of the previous `Event`. 
+All the chains share a root `Event` to preserve the tree structure. 
 
 ### Add new Event
 
-On receiving new `Event` from the network protocol, the `Event` will be added to the
-orphans list, then a process of reorganizing the `Event`s in orphans list will
-start, if the `Model` doesn't have the ancestor `Event` it will ask the network
-for the missing `Event`s, otherwise the `Event` will be added to a chain in the
-model according to its ancestor. For example, in the <em> Example1 </em> below, 
-if new `Event` (Event-A2) received, it will be added to the first chain.
+On receiving new `Event` from the network protocol, the `Event` add to the
+orphans list, `Event` from orphans list add to chains according to its ancestor. 
 
+For example, in the <em> Example1 </em> below, An `Event` add to the first chain if
+its previous hash is Event-A1
 
-### Clean the tree 
+### Remove old chains 
 
-Before adding new `Event`, The `Model` must check the tree is clean and 
-removing old forks which no longer needed and update the root accordingly. 
+TODO
 
-#### Remove old forks 
+### Update the root 
 
-Steps:
-- Find the common ancestor between the old fork and the current longest fork
-- Find the depth from the common ancestor to both forks 
-- Apply the condition:   
-	longest_fork_depth - old_fork_depth > `MAX_DEPTH`
-- remove the old fork 
-
-In the <em> Example2 </em> below, assuming the `MAX_DEPTH` equal to 8, 
-then EventNodeA, EventNodeB, and EventNodeE  will be removed from the tree when adding new `EventNode`.
-
-#### Update the root 
-
-Steps:
-- Finding all the leaves
-- Find common ancestors between the leaves and the head of the tree (The last `EventNode` in the longest fork) 
-- Find the highest ancestor in ancestors list 
-- Check if the height of the highest ancestor is greater than `MAX_HEIGHT` 
-- Set the highest ancestor as new root
-- Removing the parents of the new root
-
-In the <em> Example2 </em> below, assuming the `MAX_DEPTH` equal to 4, and  `MAX_HEIGHT` 8
-then EventNodeA, EventNodeB, EventNodeC, and EventNodeE  will be removed from the tree, 
-and Event-D7 will be the new root for the tree
+TODO
 
 ## View
 
-The `View`'s responsibility is to checking the chains in the `Model` and asking for
-new `Event`s, while keeping a list of `Event` ids which have been imported
-previously to prevent importing the same `Event` twice, then order these `Event`s
-according to the timestamp attached to each `Event`, the last step is 
-dispatching these `Event`s to the clients. 
+The `View` asking `Model` for new `Event`s, then dispatching these `Event`s to the clients. 
+
+The `Event`s in `View` are sorted according to the timestamp attached to each `Event`.
 
 
 ![data structure](../../assets/mv_event.png)

doc/src/misc/hashchain/network_protocol.md

@@ -1,4 +1,89 @@
 # Network Protocol
-	TODO
 
+The protocol check that `Event`s have properly broadcasted through the
+network before adding `Event`s to the `Model`. 
+
+The read_confirms inside each `Event` indicate how many times the `Event` has 
+been read from other nodes in the network.
+
+The protocol classify the Events by their state:
+
+	| Unread   |  read_confirms < `MAX_CONFIMRS`  | 
+	| Read 	   |  read_confirms >= `MAX_CONFIMRS` | 
+
+## Receiving a new `Event`
+
+The new received `Event` with unread status gets add to the `UnreadMessages` buffer after
+increasing the read_confirms by one. 
+
+The `Event` with read status gets add to the `Model`.
+
+The protocol broadcast the received `Event` to the network again, to ensure every nodes
+in the network get the Event.
+
+## Sending an `Event`
+
+A new created `Event` has unread status with read_confirms equal to 0.
+
+The protocol broadcast the `Event` to the network after adding it to the
+`UnreadMessages`.
+
+## Receiving an `Inv` message
+
+An `Inv` message is a confirmation from a node in the network that the `Event`
+has been read.
+
+Confirmation for an `Event` not exist in the `UnreadMessages` list, 
+A `GetData` message must send back to request the missing `Event`.
+
+The protocol update the `Event` in the `UnreadMessages` list by increasing the
+read_confirms by one.
+
+The state for updated `Event` change to read when the read_confirms exceed
+`MAX_CONFIMRS`, Then the `Event remove from the `UnreadMessages` list and add to the `Model`. 
+
+The protocol rebroadcast the received `Inv` to the network.
+
+## Sending an `Inv` message
+
+On receiving an `Event` with unread status from the network, The protocol send back 
+an `Inv` message to confirm that the `Event` has been read.
+
+## Receiving a `GetData` message
+
+The protocol search in both `Model` and `UnreadMessages` for requested `Event`
+in `GetData` message.
+
+## Add new `Event` to `Model` 
+
+For the `Event` to be successfully add to the `Model`, the protocol check if
+the previous `Event`'s hash inside the `Event` is exist in the `Model`.
+
+In case the check for previous `Event` failed The protocol 
+send a `GetData` message requesting the previous `Event`.
+
+## Add new `Event` to `UnreadMessages` 
+
+To add an `Event` to `UnreadMessages`, the protocol first must check the validity of
+`Event`. 
+
+The `Event` is not valid in the network if it's too far in the future from now,
+or too far in the past from now.
+
+## Updating `UnreadMessages` list
+
+The protocol continually broadcast unread `Event` to the network 
+after a certain period of time(`SEND_UNREAD_EVENTS_INTERVAL`), 
+Until the state of `Event` updated to read.
+
+## Synchronization
+
+To achieve complete synchronization between nodes, the protocol send a
+`SyncEvent` message every 2 seconds to other nodes in the network.
+
+The `SyncEvent` contains the hashes of `Event`s set in the leaves of `Model`'s tree.
+
+On receiving `SyncEvent` message, The leaves in `SyncEvent` should match the 
+leaves in the `Model`'s tree, Otherwise the protocol send `Event`s which are the childern of
+`Event`s in `SyncEvent` 
 

doc/src/misc/hashchain/structures.md

@@ -56,43 +56,27 @@ The `Event` could have many actions according to the underlying data.
 
 ## Inv
 
-On receiving a new `Event`, the node must advertise its knowledge for this `Event` to confirm receipt 
-
 | Description   | Data Type      	   | Comments           		|
 |-------------- | -------------------- | -------------------------- |
 | Invs	  	  	| Vec<`InvItem`> 	   | A list of `InvItem`		|
 
 ## GetData
 
-Sending back `GetData` message contain the missing items, when receiving an `Inv` message. 
-
 | Description   | Data Type      	   | Comments              		|
 |-------------- | -------------------- | -------------------------- |
 | Invs	  	    | Vec<`EventId`> 	   | A list of `EventId`   		|
 
 ## UnreadMessages
 
-Once a `Event` received from the network it will be added to this list unless it has `read_confirms` above the `MAXIMUM CONFIRMATION`. 
-All unread `Event`s are continually sent until receiving confirmations from other nodes.  
-
-All the `Event`s will apply to these filtering rules: 
-- Reject new `Event` too far in the future from now (20 Minutes)
-- Reject old `Event` too far in the past from now (1 Hour)
-- All `Event`s are organized by timestamp. Older `Event`s just gently expired and are then ignored.
-
 | Description | Data Type                   | Comments                                                                             |
 |-------------|---------------------------- | -------------------------------------------------------------------------------------|
 | Messages    | HashMap<`EventId`, `Event`> | Hold all the `Event`s that have broadcasted to other nodes but haven't confirmed yet |
 
-## Sync 
-
-Every 2 seconds each client must broadcast this message which contains 
-the head in the longest chain the client has to ensure the chain remain 
-roughly in sync.
+## SyncEvent 
 
-| Description | Data Type   | Comments					 	|
-|-------------|-------------|------------------------------ |
-| Head	      | `EventId` 	| head id in the longest chain  |
+| Description | Data Type    	| Comments					 	|
+|-------------|---------------- |------------------------------ |
+| Leaves	  | Vec<`EventId`> 	| hash of `Event`s   			|
 
 ## Seen<ObjectId>