2018-08-30 01:22:56 -07:00
|
|
|
//! # Binary Agreement
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! The Binary Agreement protocol allows each node to input one binary (`bool`) value, and will
|
|
|
|
//! output a binary value. The output is guaranteed to have been input by at least one correct
|
|
|
|
//! node, and all correct nodes will have the same output.
|
|
|
|
//!
|
|
|
|
//! ## How it works
|
|
|
|
//!
|
|
|
|
//! The algorithm proceeds in _epochs_, and the number of epochs it takes until it terminates is
|
|
|
|
//! unbounded in theory but has a finite expected value. Each node keeps track of an _estimate_
|
|
|
|
//! value `e`, which is initialized to the node's own input. Let's call a value `v`
|
|
|
|
//! that has been input by at least one correct node and such that `!v` hasn't been _output_ by any
|
|
|
|
//! correct node yet, a _viable output_. The estimate will always be a viable output.
|
|
|
|
//!
|
|
|
|
//! All messages are annotated with the epoch they belong to, but we omit that here for brevity.
|
|
|
|
//!
|
|
|
|
//! * At the beginning of each epoch, we multicast `BVal(e)`. It translates to: "I know that `e` is
|
2018-07-28 08:31:17 -07:00
|
|
|
//! a viable output."
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * Once we receive `BVal(v)` with the same value from _f + 1_ different validators, we know that
|
|
|
|
//! at least one of them must be correct. So we know that `v` is a viable output. If we haven't
|
|
|
|
//! done so already we multicast `BVal(v)`. (Even if we already multicast `BVal(!v)`).
|
|
|
|
//!
|
|
|
|
//! * Let's say a node _believes in `v`_ if it received `BVal(v)` from _2 f + 1_ validators.
|
2018-07-28 08:31:17 -07:00
|
|
|
//! For the _first_ value `v` we believe in, we multicast `Aux(v)`. It translates to:
|
|
|
|
//! "I know that all correct nodes will eventually know that `v` is a viable output.
|
|
|
|
//! I'm not sure about `!v` yet."
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * Since every node will receive at least _2 f + 1_ `BVal` messages from correct validators,
|
2018-07-28 08:31:17 -07:00
|
|
|
//! there is at least one value `v`, such that every node receives _f + 1_ `BVal(v)` messages.
|
|
|
|
//! As a consequence, every correct validator will multicast `BVal(v)` itself. Hence we are
|
|
|
|
//! guaranteed to receive _2 f + 1_ `BVal(v)` messages.
|
|
|
|
//! In short: If _any_ correct node believes in `v`, _every_ correct node will.
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * Every correct node will eventually send exactly one `Aux`, so we will receive at least
|
2018-07-28 08:31:17 -07:00
|
|
|
//! _N - f_ `Aux` messages with values we believe in. At that point, we define the set `vals`
|
|
|
|
//! of _candidate values_: the set of values we believe in _and_ have received in an `Aux`.
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * Once we have the set of candidate values, we obtain a _coin value_ `s` (see below).
|
|
|
|
//!
|
|
|
|
//! * If there is only a single candidate value `b`, we set our estimate `e = b`. If `s == b`,
|
2018-07-28 08:31:17 -07:00
|
|
|
//! we _output_ and send a `Term(b)` message which is interpreted as `BVal(b)` and `Aux(b)` for
|
|
|
|
//! all future epochs. If `s != b`, we just proceed to the next epoch.
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * If both values are candidates, we set `e = s` and proceed to the next epoch.
|
|
|
|
//!
|
|
|
|
//! In epochs that are 0 modulo 3, the value `s` is `true`. In 1 modulo 3, it is `false`. In the
|
2018-08-14 05:56:32 -07:00
|
|
|
//! case 2 modulo 3, we flip a coin to determine a pseudorandom `s`.
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! An adversary that knows each coin value, controls a few validators and controls network
|
|
|
|
//! scheduling can delay the delivery of `Aux` and `BVal` messages to influence which candidate
|
|
|
|
//! values the nodes will end up with. In some circumstances that allows them to stall the network.
|
|
|
|
//! This is even true if the coin is flipped too early: the adversary must not learn about the coin
|
|
|
|
//! value early enough to delay enough `Aux` messages. That's why in the third case, the value `s`
|
|
|
|
//! is determined as follows:
|
|
|
|
//!
|
|
|
|
//! * We multicast a `Conf` message containing our candidate values.
|
|
|
|
//!
|
|
|
|
//! * Since every good node believes in all values it puts into its `Conf` message, we will
|
2018-07-28 08:31:17 -07:00
|
|
|
//! eventually receive _N - f_ `Conf` messages containing only values we believe in. Then we
|
2018-08-14 05:56:32 -07:00
|
|
|
//! trigger the coin.
|
2018-07-02 06:42:31 -07:00
|
|
|
//!
|
|
|
|
//! * After _f + 1_ nodes have sent us their coin shares, we receive the coin output and assign it
|
|
|
|
//! to `s`.
|
2018-05-01 10:12:05 -07:00
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
mod binary_agreement;
|
2018-08-01 09:51:43 -07:00
|
|
|
mod bool_multimap;
|
2018-07-31 00:38:52 -07:00
|
|
|
pub mod bool_set;
|
2018-08-01 09:51:43 -07:00
|
|
|
mod sbv_broadcast;
|
2018-05-24 10:52:58 -07:00
|
|
|
|
2018-10-24 00:42:59 -07:00
|
|
|
use bincode;
|
2018-10-29 07:36:56 -07:00
|
|
|
use failure::Fail;
|
2018-07-05 09:20:53 -07:00
|
|
|
use rand;
|
2018-10-29 07:36:56 -07:00
|
|
|
use rand_derive::Rand;
|
|
|
|
use serde_derive::{Deserialize, Serialize};
|
2018-05-06 14:39:01 -07:00
|
|
|
|
2018-08-02 11:11:32 -07:00
|
|
|
use self::bool_set::BoolSet;
|
2018-10-23 02:49:19 -07:00
|
|
|
use threshold_sign;
|
2018-05-23 15:00:19 -07:00
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
pub use self::binary_agreement::BinaryAgreement;
|
2018-10-16 10:31:30 -07:00
|
|
|
pub use self::sbv_broadcast::Message as SbvMessage;
|
2018-05-08 09:25:57 -07:00
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
/// An Binary Agreement error.
|
2018-07-25 14:38:33 -07:00
|
|
|
#[derive(Clone, Eq, PartialEq, Debug, Fail)]
|
|
|
|
pub enum Error {
|
2018-10-23 02:49:19 -07:00
|
|
|
#[fail(display = "Error handling threshold sign message: {}", _0)]
|
|
|
|
HandleThresholdSign(threshold_sign::Error),
|
|
|
|
#[fail(display = "Error invoking the common coin: {}", _0)]
|
|
|
|
InvokeCoin(threshold_sign::Error),
|
2018-10-24 00:42:59 -07:00
|
|
|
// Strings because `io` and `bincode` errors lack `Eq` and `Clone`.
|
|
|
|
#[fail(display = "Error writing epoch for nonce: {}", _0)]
|
|
|
|
Io(String),
|
|
|
|
#[fail(display = "Error serializing session ID for nonce: {}", _0)]
|
|
|
|
Serialize(String),
|
|
|
|
}
|
|
|
|
|
|
|
|
impl From<bincode::Error> for Error {
|
|
|
|
fn from(err: bincode::Error) -> Error {
|
|
|
|
Error::Io(format!("{:?}", err))
|
|
|
|
}
|
2018-05-20 04:51:33 -07:00
|
|
|
}
|
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
/// An Binary Agreement result.
|
2018-07-25 14:38:33 -07:00
|
|
|
pub type Result<T> = ::std::result::Result<T, Error>;
|
|
|
|
|
2018-11-07 05:26:14 -08:00
|
|
|
pub type Step<N> = ::Step<Message, bool, N>;
|
2018-08-02 11:11:32 -07:00
|
|
|
|
2018-06-20 01:21:52 -07:00
|
|
|
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
|
2018-08-30 01:22:56 -07:00
|
|
|
pub enum MessageContent {
|
2018-08-01 09:51:43 -07:00
|
|
|
/// Synchronized Binary Value Broadcast message.
|
|
|
|
SbvBroadcast(sbv_broadcast::Message),
|
2018-05-28 03:54:37 -07:00
|
|
|
/// `Conf` message.
|
2018-07-31 00:38:52 -07:00
|
|
|
Conf(BoolSet),
|
2018-06-07 12:06:44 -07:00
|
|
|
/// `Term` message.
|
|
|
|
Term(bool),
|
2018-10-23 02:49:19 -07:00
|
|
|
/// `ThresholdSign` message used for the common coin,
|
|
|
|
Coin(Box<threshold_sign::Message>),
|
2018-06-07 12:06:44 -07:00
|
|
|
}
|
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
impl MessageContent {
|
2018-06-07 12:06:44 -07:00
|
|
|
/// Creates an message with a given epoch number.
|
2018-11-12 03:15:02 -08:00
|
|
|
pub fn with_epoch(self, epoch: u64) -> Message {
|
2018-08-08 06:46:43 -07:00
|
|
|
Message {
|
2018-06-07 12:06:44 -07:00
|
|
|
epoch,
|
|
|
|
content: self,
|
|
|
|
}
|
|
|
|
}
|
2018-07-28 08:31:17 -07:00
|
|
|
|
|
|
|
/// Returns `true` if this message can be ignored if its epoch has already passed.
|
|
|
|
pub fn can_expire(&self) -> bool {
|
|
|
|
match *self {
|
2018-08-30 01:22:56 -07:00
|
|
|
MessageContent::Term(_) => false,
|
2018-07-28 08:31:17 -07:00
|
|
|
_ => true,
|
|
|
|
}
|
|
|
|
}
|
2018-05-23 10:38:33 -07:00
|
|
|
}
|
|
|
|
|
2018-08-30 01:22:56 -07:00
|
|
|
/// Messages sent during the Binary Agreement stage.
|
2018-07-05 09:20:53 -07:00
|
|
|
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Rand)]
|
2018-08-08 06:46:43 -07:00
|
|
|
pub struct Message {
|
2018-11-12 03:15:02 -08:00
|
|
|
pub epoch: u64,
|
2018-08-30 01:22:56 -07:00
|
|
|
pub content: MessageContent,
|
2018-05-23 10:38:33 -07:00
|
|
|
}
|
|
|
|
|
2018-07-05 09:20:53 -07:00
|
|
|
// NOTE: Extending rand_derive to correctly generate random values from boxes would make this
|
|
|
|
// implementation obsolete; however at the time of this writing, `rand::Rand` is already deprecated
|
|
|
|
// with no replacement in sight.
|
2018-08-30 01:22:56 -07:00
|
|
|
impl rand::Rand for MessageContent {
|
2018-07-05 09:20:53 -07:00
|
|
|
fn rand<R: rand::Rng>(rng: &mut R) -> Self {
|
2018-08-01 09:51:43 -07:00
|
|
|
let message_type = *rng.choose(&["sbvb", "conf", "term", "coin"]).unwrap();
|
2018-07-05 09:20:53 -07:00
|
|
|
|
|
|
|
match message_type {
|
2018-10-02 07:24:51 -07:00
|
|
|
"sbvb" => MessageContent::SbvBroadcast(rng.gen()),
|
|
|
|
"conf" => MessageContent::Conf(rng.gen()),
|
|
|
|
"term" => MessageContent::Term(rng.gen()),
|
|
|
|
"coin" => MessageContent::Coin(Box::new(rng.gen())),
|
2018-07-05 09:20:53 -07:00
|
|
|
_ => unreachable!(),
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|