Update readme

doc/historian.md

@@ -0,0 +1,65 @@
+The Historian
+===
+
+Create a *Historian* and send it *events* to generate an *event log*, where each log *entry*
+is tagged with the historian's latest *hash*. Then ensure the order of events was not tampered
+with by verifying each entry's hash can be generated from the hash in the previous entry:
+
+![historian](https://user-images.githubusercontent.com/55449/36950845-459bdb58-1fb9-11e8-850e-894586f3729b.png)
+
+```rust
+extern crate silk;
+
+use silk::historian::Historian;
+use silk::log::{verify_slice, Entry, Sha256Hash};
+use silk::event::{generate_keypair, get_pubkey, sign_claim_data, Event};
+use std::thread::sleep;
+use std::time::Duration;
+use std::sync::mpsc::SendError;
+
+fn create_log(hist: &Historian<Sha256Hash>) -> Result<(), SendError<Event<Sha256Hash>>> {
+    sleep(Duration::from_millis(15));
+    let data = Sha256Hash::default();
+    let keypair = generate_keypair();
+    let event0 = Event::new_claim(get_pubkey(&keypair), data, sign_claim_data(&data, &keypair));
+    hist.sender.send(event0)?;
+    sleep(Duration::from_millis(10));
+    Ok(())
+}
+
+fn main() {
+    let seed = Sha256Hash::default();
+    let hist = Historian::new(&seed, Some(10));
+    create_log(&hist).expect("send error");
+    drop(hist.sender);
+    let entries: Vec<Entry<Sha256Hash>> = hist.receiver.iter().collect();
+    for entry in &entries {
+        println!("{:?}", entry);
+    }
+    // Proof-of-History: Verify the historian learned about the events
+    // in the same order they appear in the vector.
+    assert!(verify_slice(&entries, &seed));
+}
+```
+
+Running the program should produce a log similar to:
+
+```rust
+Entry { num_hashes: 0, id: [0, ...], event: Tick }
+Entry { num_hashes: 3, id: [67, ...], event: Transaction { data: [37, ...] } }
+Entry { num_hashes: 3, id: [123, ...], event: Tick }
+```
+
+Proof-of-History
+---
+
+Take note of the last line:
+
+```rust
+assert!(verify_slice(&entries, &seed));
+```
+
+[It's a proof!](https://en.wikipedia.org/wiki/Curry–Howard_correspondence) For each entry returned by the
+historian, we can verify that `id` is the result of applying a sha256 hash to the previous `id`
+exactly `num_hashes` times, and then hashing then event data on top of that. Because the event data is
+included in the hash, the events cannot be reordered without regenerating all the hashes.

doc/historian.msc

@@ -0,0 +1,18 @@
+msc {
+  client,historian,logger;
+
+  logger=>historian [ label = "e0 = Entry{id: h0, n: 0, event: Tick}" ] ;
+  logger=>logger [ label = "h1 = hash(h0)" ] ;
+  logger=>logger [ label = "h2 = hash(h1)" ] ;
+  client=>historian [ label = "Transaction(d0)" ] ;
+  historian=>logger [ label = "Transaction(d0)" ] ;
+  logger=>logger [ label = "h3 = hash(h2 + d0)" ] ;
+  logger=>historian [ label = "e1 = Entry{id: hash(h3), n: 3, event: Transaction(d0)}" ] ;
+  logger=>logger [ label = "h4 = hash(h3)" ] ;
+  logger=>logger [ label = "h5 = hash(h4)" ] ;
+  logger=>logger [ label = "h6 = hash(h5)" ] ;
+  logger=>historian [ label = "e2 = Entry{id: h6, n: 3, event: Tick}" ] ;
+  client=>historian [ label = "collect()" ] ;
+  historian=>client [ label = "entries = [e0, e1, e2]" ] ;
+  client=>client [ label = "verify_slice(entries, h0)" ] ;
+}