2018-02-16 11:32:47 -08:00
|
|
|
|
[![Silk crate](https://img.shields.io/crates/v/silk.svg)](https://crates.io/crates/silk)
|
|
|
|
|
[![Silk documentation](https://docs.rs/silk/badge.svg)](https://docs.rs/silk)
|
2018-02-16 10:49:21 -08:00
|
|
|
|
[![Build Status](https://travis-ci.org/loomprotocol/silk.svg?branch=master)](https://travis-ci.org/loomprotocol/silk)
|
|
|
|
|
[![codecov](https://codecov.io/gh/loomprotocol/silk/branch/master/graph/badge.svg)](https://codecov.io/gh/loomprotocol/silk)
|
2018-02-14 14:25:49 -08:00
|
|
|
|
|
2018-02-16 11:44:00 -08:00
|
|
|
|
# Silk, a silky smooth implementation of the Loom specification
|
2018-02-15 12:59:33 -08:00
|
|
|
|
|
2018-02-16 10:30:36 -08:00
|
|
|
|
Loom is a new achitecture for a high performance blockchain. Its whitepaper boasts a theoretical
|
2018-02-16 11:51:57 -08:00
|
|
|
|
throughput of 710k transactions per second on a 1 gbps network. The specification is implemented
|
|
|
|
|
in two git repositories. Reserach is performed in the loom repository. That work drives the
|
|
|
|
|
Loom specification forward. This repository, on the other hand, aims to implement the specification
|
|
|
|
|
as-is. We care a great deal about quality, clarity and short learning curve. We avoid the use
|
2018-02-16 11:53:44 -08:00
|
|
|
|
of `unsafe` Rust and write tests for *everything*. Optimizations are only added when
|
2018-02-16 11:51:57 -08:00
|
|
|
|
corresponding benchmarks are also added that demonstrate real performance boots. We expect the
|
|
|
|
|
feature set here will always be a ways behind the loom repo, but that this is an implementation
|
|
|
|
|
you can take to the bank, literally.
|
2018-02-15 15:09:11 -08:00
|
|
|
|
|
2018-02-19 08:19:26 -08:00
|
|
|
|
# Usage
|
|
|
|
|
|
2018-02-19 11:12:45 -08:00
|
|
|
|
Add the latest [silk package](https://crates.io/crates/silk) to the `[dependencies]` section
|
2018-02-19 08:19:26 -08:00
|
|
|
|
of your Cargo.toml.
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```rust
|
2018-02-19 11:00:56 -08:00
|
|
|
|
extern crate silk;
|
2018-02-19 08:19:26 -08:00
|
|
|
|
|
2018-02-19 11:00:56 -08:00
|
|
|
|
use silk::historian::Historian;
|
2018-02-19 15:48:29 -08:00
|
|
|
|
use silk::log::{verify_slice, Entry, Event, Sha256Hash};
|
2018-02-19 11:00:56 -08:00
|
|
|
|
use std::{thread, time};
|
2018-02-19 11:25:57 -08:00
|
|
|
|
use std::sync::mpsc::SendError;
|
2018-02-19 08:19:26 -08:00
|
|
|
|
|
2018-02-19 11:25:57 -08:00
|
|
|
|
fn create_log(hist: &Historian) -> Result<(), SendError<Event>> {
|
|
|
|
|
hist.sender.send(Event::Tick)?;
|
2018-02-19 11:00:56 -08:00
|
|
|
|
thread::sleep(time::Duration::new(0, 100_000));
|
2018-02-20 12:07:54 -08:00
|
|
|
|
hist.sender.send(Event::UserDataKey(Sha256Hash::default()))?;
|
2018-02-19 11:00:56 -08:00
|
|
|
|
thread::sleep(time::Duration::new(0, 100_000));
|
2018-02-19 11:25:57 -08:00
|
|
|
|
hist.sender.send(Event::Tick)?;
|
|
|
|
|
Ok(())
|
2018-02-19 11:00:56 -08:00
|
|
|
|
}
|
2018-02-19 08:19:26 -08:00
|
|
|
|
|
2018-02-19 11:00:56 -08:00
|
|
|
|
fn main() {
|
2018-02-19 15:48:29 -08:00
|
|
|
|
let seed = Sha256Hash::default();
|
|
|
|
|
let hist = Historian::new(&seed);
|
2018-02-19 11:25:57 -08:00
|
|
|
|
create_log(&hist).expect("send error");
|
|
|
|
|
drop(hist.sender);
|
|
|
|
|
let entries: Vec<Entry> = hist.receiver.iter().collect();
|
2018-02-19 11:00:56 -08:00
|
|
|
|
for entry in &entries {
|
|
|
|
|
println!("{:?}", entry);
|
|
|
|
|
}
|
2018-02-20 12:07:54 -08:00
|
|
|
|
|
|
|
|
|
// Proof-of-History: Verify the historian learned about the events
|
|
|
|
|
// in the same order they appear in the vector.
|
2018-02-19 15:48:29 -08:00
|
|
|
|
assert!(verify_slice(&entries, &seed));
|
2018-02-19 08:19:26 -08:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2018-02-19 11:00:56 -08:00
|
|
|
|
Running the program should produce a log similar to:
|
|
|
|
|
|
2018-02-19 15:48:29 -08:00
|
|
|
|
```rust
|
2018-02-19 15:53:58 -08:00
|
|
|
|
Entry { num_hashes: 0, end_hash: [0, ...], event: Tick }
|
|
|
|
|
Entry { num_hashes: 6, end_hash: [67, ...], event: UserDataKey(3735928559) }
|
|
|
|
|
Entry { num_hashes: 5, end_hash: [123, ...], event: Tick }
|
2018-02-19 11:00:56 -08:00
|
|
|
|
```
|
|
|
|
|
|
2018-02-20 12:07:54 -08:00
|
|
|
|
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 `end_hash` is the result of applying a sha256 hash to the previous `end_hash`
|
|
|
|
|
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.
|
2018-02-19 11:00:56 -08:00
|
|
|
|
|
2018-02-15 15:09:11 -08:00
|
|
|
|
# Developing
|
|
|
|
|
|
2018-02-16 09:38:12 -08:00
|
|
|
|
Building
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
Install rustc, cargo and rustfmt:
|
2018-02-15 15:09:11 -08:00
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ curl https://sh.rustup.rs -sSf | sh
|
2018-02-16 09:38:12 -08:00
|
|
|
|
$ source $HOME/.cargo/env
|
|
|
|
|
$ rustup component add rustfmt-preview
|
2018-02-15 15:09:11 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Download the source code:
|
|
|
|
|
|
|
|
|
|
```bash
|
2018-02-16 10:49:21 -08:00
|
|
|
|
$ git clone https://github.com/loomprotocol/silk.git
|
|
|
|
|
$ cd silk
|
2018-02-15 15:09:11 -08:00
|
|
|
|
```
|
|
|
|
|
|
2018-02-16 09:38:12 -08:00
|
|
|
|
Testing
|
|
|
|
|
---
|
|
|
|
|
|
2018-02-15 15:09:11 -08:00
|
|
|
|
Run the test suite:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cargo test
|
|
|
|
|
```
|
2018-02-16 09:38:12 -08:00
|
|
|
|
|
|
|
|
|
Benchmarking
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
First install the nightly build of rustc. `cargo bench` requires unstable features:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ rustup install nightly
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Run the benchmarks:
|
|
|
|
|
|
|
|
|
|
```bash
|
2018-02-19 15:51:32 -08:00
|
|
|
|
$ cargo +nightly bench --features="asm,unstable"
|
2018-02-16 09:38:12 -08:00
|
|
|
|
```
|