Struct parsec::Parsec

pub struct Parsec<T: NetworkEvent, S: SecretId> { /* fields omitted */ }

The main object which manages creating and receiving gossip about network events from peers, and which provides a sequence of consensused Blocks by applying the PARSEC algorithm. A Block's payload, described by the Observation type, is called an "observation" or a "transaction".

The struct is generic with regards to two type arguments: one that represents a network event, and one that represents a peer ID on the network. This allows the consumer to customise both what constitutes a transaction that can get consensus, and the way peers are identified. The types have to implement NetworkEvent and SecretId traits, respectively.

The Parsec struct exposes two constructors:

• from_genesis, if the owning peer is a part of the genesis group, i.e. the initial group of peers that participate in the network startup
• from_existing, if the owning peer is trying to join an already functioning network

Once the peer becomes a full member of the section, gossip_recipients will start to return potential partners for gossip. In order to initiate gossip exchange with a partner, create_gossip should be called.

Any messages of type Request or Response received by the network layer should be passed to handle_request and handle_response, respectively.

If the owning peer needs to propose something to be consensused, it has to call the vote_for method.

The poll method is used to get the observations in the consensused order.

Most public methods return an error if called after the owning peer has been removed from the section, i.e. a block with payload Observation::Remove(our_id) has been made stable.

For more details, see the descriptions of methods below.

Implementations

impl<T: NetworkEvent, S: SecretId> Parsec<T, S>

pub fn from_genesis(
    our_id: S,
    genesis_group: &BTreeSet<S::PublicId>,
    genesis_related_info: Vec<u8>,
    consensus_mode: ConsensusMode,
    secure_rng: Box<dyn RngCore>
) -> Self

Creates a new Parsec for a peer with the given ID and genesis peer IDs (ours included).

• our_id is the value that will identify the owning peer in the network.
• genesis_group is the set of public IDs of the peers that are present at the network startup.
• genesis_related_info extra arbitrary information attached to the genesis event for use by the client.
• consensus_mode determines how many votes are needed for an observation to become a candidate for consensus. For more details, see ConsensusMode
• secure_rng cryptographically secure RNG to use for DKG key generation.

pub fn from_existing(
    our_id: S,
    genesis_group: &BTreeSet<S::PublicId>,
    section: &BTreeSet<S::PublicId>,
    consensus_mode: ConsensusMode,
    secure_rng: Box<dyn RngCore>
) -> Self

Creates a new Parsec for a peer that is joining an existing section.

• our_id is the value that will identify the owning peer in the network.
• genesis_group is the set of public IDs of the peers that were present at the section startup.
• section is the set of public IDs of the peers that constitute the section at the time of joining. They are the peers this Parsec instance will accept gossip from.
• consensus_mode determines how many votes are needed for an observation to become a candidate for consensus. For more details, see ConsensusMode
• secure_rng cryptographically secure RNG to use for DKG key generation.

pub fn our_pub_id(&self) -> &S::PublicId

Returns our public ID

pub fn vote_for(
    &mut self,
    observation: Observation<T, S::PublicId>
) -> Result<()>

Inserts the owning peer's vote for observation into the gossip graph. The subsequent gossip messages will spread the vote to other peers, eventually making it a candidate for the next consensused block.

Returns an error if the owning peer is not a full member of the section yet, if it has already voted for this observation, or if adding a gossip event containing the vote to the gossip graph failed.

pub fn gossip_recipients(&self) -> impl Iterator<Item = &S::PublicId>

Returns an iterator with the IDs of peers who the owning peer can send gossip messages to. Calling create_gossip with a peer ID returned by this method is guaranteed to succeed (assuming no section mutation happened in between).

pub fn create_gossip(
    &mut self,
    peer_id: &S::PublicId
) -> Result<Request<T, S::PublicId>>

Creates a new message to be gossiped to a peer, containing all gossip events this peer thinks that peer needs. If the given peer is not an active node, an error is returned.

• peer_id: the intended recipient of the gossip message
• returns a Request to be sent to the intended recipient

pub fn handle_request(
    &mut self,
    src: &S::PublicId,
    req: Request<T, S::PublicId>
) -> Result<Response<T, S::PublicId>>

Handles a Request the owning peer received from the src peer. Returns a Response to be sent back to src, or Err if the request was not valid or if src has been removed from the section already.

pub fn handle_response(
    &mut self,
    src: &S::PublicId,
    resp: Response<T, S::PublicId>
) -> Result<()>

Handles a Response the owning peer received from the src peer. Returns Err if the response was not valid or if src has been removed from the section already.

pub fn poll(&mut self) -> Option<Block<T, S::PublicId>>

Returns the next stable block, if any. The method might need to be called more than once for the caller to get all the blocks that have been consensused. A None value means that all the blocks consensused so far have already been returned.

Once the owning peer has been removed from the section (i.e. a block with payload Observation::Remove(our_id) has been made stable), then no further blocks will be enqueued. So, once poll() returns such a block, it will continue to return None forever.

pub fn can_vote(&self) -> bool

Check if the owning peer can vote (that is, it has reached a consensus on itself being a full member of the section).

pub fn have_voted_for(&self, observation: &Observation<T, S::PublicId>) -> bool

Checks if the given observation has already been voted for by the owning peer.

pub fn has_unpolled_observations(&self) -> bool

Check if there are any observations that have been voted for but not yet polled - that is, either they haven't been consensused yet or a block containing that observation hasn't yet been retrieved by calling poll, or a DKG is running.

pub fn our_unpolled_observations(
    &self
) -> impl Iterator<Item = &Observation<T, S::PublicId>>

Returns observations voted for by the owning peer which haven't been returned as a stable block by poll yet. This includes observations that are either not yet consensused or that are already consensused, but not yet popped out of the consensus queue.

The observations are sorted first by the consensus order, then by the vote order.

Trait Implementations

impl<T: NetworkEvent, S: SecretId> Drop for Parsec<T, S>

fn drop(&mut self)

Executes the destructor for this type.