doc/book: add hashchain page

doc/src/SUMMARY.md

@@ -22,10 +22,11 @@
 - [Miscellaneous tools](misc/misc.md)
   - [vanityaddr](misc/vanityaddr.md)
   - [ircd](misc/ircd.md)
-  - [tau](misc/tau/tau.md)
-  	- [Architecture](misc/tau/architecture.md)
-  	- [Specification](misc/tau/specification.md)
-  	- [Network Protocol](misc/tau/network_protocol.md)
+  - [tau](misc/tau.md)
+  - [HashChain](misc/hashchain/hashchain.md)
+  	- [Architecture](misc/hashchain/architecture.md)
+  	- [Network Protocol](misc/hashchain/network_protocol.md)
+  	- [Structures](misc/hashchain/structures.md)
   - [darkwiki](misc/darkwiki.md)
   - [dnetview](misc/dnetview.md)
 - [Learn](learn/learn.md)

doc/src/misc/hashchain/architecture.md

@@ -0,0 +1,75 @@
+
+# Architecture 
+
+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.
+
+## 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. 
+
+### 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.
+
+
+### Clean the tree 
+
+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. 
+
+#### Remove old forks 
+
+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
+
+## 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. 
+
+
+![data structure](../../assets/mv_event.png)
+
+Example1
+
+![data structure](../../assets/mv_event_tree.png)
+
+Example2
+
+
+

doc/src/misc/hashchain/hashchain.md

@@ -0,0 +1,2 @@
+# HashChain
+

doc/src/misc/hashchain/structures.md

@@ -0,0 +1,136 @@
+# Structures 
+
+## EventId
+
+Hash of all the metadata in the `Event` 
+
+	type EventId = [u8; 32];	
+
+## EventAction 
+
+The `Event` could have many actions according to the underlying data.
+
+	enum EventAction { ... };	
+
+## Event
+
+| Description            | Data Type      | Comments                    |
+|----------------------- | -------------- | --------------------------- |
+| previous_event_hash    | `EventId` 	  | Hash of the previous `Event`|
+| Action     			 | `EventAction`  | `Event`'s action 			|
+| Timestamp     		 | u64  		  | `Event`'s timestamp 		|
+| read_confirms			 | u8	 		  | A confirmation counter 	    |
+
+## EventNode
+
+| Description    | Data Type      		  | Comments                    			 			  |
+|--------------- | ---------------------- | ----------------------------------------------------- |
+| parent    	 | Option<`EventNode`> 	  | Only current root has this set to None   			  |
+| Event     	 | `Event`  			  | The `Event` itself 					       			  |
+| Children     	 | Vec<`EventNode`>  	  | The `Event`s which has parent as this `Event` hash    |
+
+## Model 
+
+| Description   | Data Type      		  		   | Comments                      |
+|-------------- | -------------------------------- | ----------------------------- |
+| current_root  | `EventId` 	  		  		   | The root `Event` for the tree |
+| orphans       | Vec<`Event`>  		  		   | Recently added `Event`s 	   |
+| event_map     | HashMap<`EventId`, `EventNode`>  | The actual tree  		 	   |
+
+## View 
+
+| Description   | Data Type      	   | Comments                    					|
+|-------------- | -------------------- | ---------------------------------------------- |
+| seen  		| HashSet<`EventId`>   | A list of `Event`s have imported from Model	|
+
+
+## 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<`InvItem`, `Event`> | Hold all the `Event`s that have broadcasted to other nodes but haven't confirmed yet |
+
+## InvItem
+
+Unique generated integer
+
+	type InvItem = u32;	
+
+## 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
+
+On receiving an `Inv` message if the client doesn't have the `InvItem`s, 
+Sending back `GetData` message contain the missing `InvItem`s
+
+| Description | Data Type   		| Comments				|
+|-------------|--------------------	|---------------------- |
+| Invs	  	  | Vec<`InvItem`> 		| A list of `EventId`   |
+
+## 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.
+
+| Description | Data Type   | Comments					 	|
+|-------------|-------------|------------------------------ |
+| Head	      | `EventId` 	| head id in the longest chain  |
+
+## Events  
+
+This used in response to `Sync` message, sending all the children 
+in the node correspond to `EventId` in `Sync` message 
+
+| Description | Data Type    | Comments							|
+|-------------|------------- |--------------------------------- |
+| Events	  | Vec<`Event`> | A list of `Event`  			  	|
+| Head  	  | `EventId`	 | The head in the `Sync` message 	|
+
+
+## SeenEventIds
+
+Every `Event` received its id will be add to this list to prevent receiving duplicate `Event`s.
+The list will contains only 2^16 ids.
+
+| Description | Data Type      | Comments			  		   |
+|-------------|--------------- |------------------------------ |
+| Ids		  | Vec<`EventId`> | Contains all the `Event`s ids |
+
+## SeenInvIds
+
+Every `InvItem` received its id will be add to this list to prevent receiving duplicate `InvItem`.
+The list will contains only 2^16 ids.
+
+| Description | Data Type      | Comments			  		     |
+|-------------|--------------- |------------------------------   |
+| Ids		  | Vec<`InvItem`> | Contains all the `InvItem`s ids |
+
+
+## Actions types
+
+### Privmsg 
+
+| Description 	| Data Type   	| Comments																	|
+|-------------- |-------------- | ------------------------------------------------------------------------- |
+| nickname    	| String		| The nickname for the sender (must be less than 32 chars) 					|
+| target      	| String		| The target for the `Privmsg` (recipient) 				 					|
+| message     	| String		| The `Privmsg`'s content 				 									|
+
+
+
+

doc/src/misc/tau/architecture.md

@@ -1,43 +0,0 @@
-
-# Architecture 
-
-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.
-
-## 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 events. All the chains will shared a root event to preserve the tree
-structure. <em> check the diagram bellow  </em>
-
-On receiving new event from the network protocol, the event will be added to the
-orphans list, then a process of reorganizing the events in orphans list will
-start, if the Model doesn't have the ancestor event it will ask the network
-for the missing events, otherwise the event will be added to a chain in the
-model according to its ancestor. For example, in the diagram below, 
-if new event (Event-A2) received, it will be added to the first chain.
-
-## Find head event 
-	TODO
-
-## Find common ancestors
-	TODO
-
-## View
-
-The view's responsibility is to checking the chains in the Model and asking for
-new events, while keeping a list of event ids which have been imported
-previously to prevent importing the same event twice, then order these events
-according to the timestamp attached to each event, the last step is 
-dispatching these events to the clients. 
-<em> check the diagram bellow  </em>
-
-
-![data structure](../../assets/mv_event.png)
-
-
-
-

doc/src/misc/tau/specification.md

@@ -1,46 +0,0 @@
-# Specification
-
-## EventId
-
-Hash of all the metadata in the event
-
-	type EventId = [u8; 32];	
-
-## EventAction 
-
-The event could have many actions according to the underlying data.
-
-	enum EventAction { ... };	
-
-## Event
-
-| Description            | Data Type      | Comments                    |
-|----------------------- | -------------- | --------------------------- |
-| previous_event_hash    | `EventId` 	  | Hash of the previous event  |
-| Action     			 | `EventAction`  | event's action 				|
-| Timestamp     		 | u64  		  | event's timestamp 			|
-
-## EventNode
-
-| Description    | Data Type      		  | Comments                    			 |
-|--------------- | ---------------------- | ---------------------------------------- |
-| parent    	 | Option<`EventNode`> 	  | Only current root has this set to None   |
-| Event     	 | `Event`  			  | The event itself 					     |
-| Children     	 | Vec<`EventNode`>  	  | The events followed this event  		 |
-
-## Model 
-
-| Description   | Data Type      		  		   | Comments                    |
-|-------------- | -------------------------------- | --------------------------- |
-| current_root  | `EventId` 	  		  		   | The root event for the tree |
-| orphans       | Vec<`Event`>  		  		   | Recently added events 		 |
-| event_map     | HashMap<`EventId`, `EventNode`>  | The actual tree  		 	 |
-
-## View 
-
-| Description   | Data Type      	   | Comments                    				|
-|-------------- | -------------------- | ------------------------------------------ |
-| seen  		| HashSet<`EventId`>   | A list of events have imported from Model	|
-
-
-