orderer

Orderer

The Orderer module implements the actual ordering of Batches, i.e., committing new Entries to the Log. The Orderer listens to the Manager for new Segments. Whenever the Manager issues a new Segment, the Orderer creates a new instance of the ordering protocol that proposes and agrees on Request Batches - one Batch for each SN that is part of the Segment. When a Batch has been agreed upon for a particular SN, the Orderer announces the (SN, Batch) pair as an Entry, indicating that it can be committed to the Log. We now describe the interface of an Orderer in terms of its behavior.

Execution of the Orderer

The Orderer module starts executing when its Start method is called by the system. The implementation of the Start method must:

• Read Segments from the attached Manager (see below on initializing the Orderer).
• For each obtained Segment, order the Segment (possibly in parallel with ordering other Segments).

We define ordering a Segment segment as calling announcer.Announce(logEntry) exactly once for each sequence number returned by segment.SNs. The logEntry parameter is of type *log.Entry and represents an Entry. It must contain one of the sequence numbers returned by segment.SNs along with a Batch of Requests.

Ordering a segment is subject to the following restrictions:

• The set of logEntry arguments passed to invocations of announcer.Announce must be the same across all correct peers. (The order in which those Log Entries are announced, however, need not be the same.)
• All Entries must contain Batches exclusively from the Segment's Bucket.
  • The leader of the protocol obtains a Batch using the segment.bucket.CutBatch method.
• The leader must not call segment.bucket.CutBatch before a particular sequence number has been committed. This sequence number is defined by the Segment and accessible through the segment.StartsAfter method.
  • The log package provides a convenience method log.WaitForEntry that blocks until a specific Entry is committed.

Implementing an Orderer

To implement an Orderer, one must implement the orderer.Orderer interface. The Init, HandleMessage, and Start methods serve for integration with the rest of the system and their signature is described in the comments in orderer.go. Here we describe how these methods need to be implemented for obtaining a working Orderer.

For an example implementation of a dummy Orderer that can be used as a skeleton for real Orderer implementations, see orderer/dummyorderer.go.

Initializing the Orderer

Initialization needs to be implemented in the Init method. In addition to initializing whatever internal data structures the particular Orderer implementation needs, the Orderer must subscribe to Segments the provided Manager issues (the Manager is provided as an argument to Init). Subscribing to Segments will most likely be a one-liner calling the Manager's SubscribeOrderer method. This method returns a channel that the Orderer needs to save in its local state. When started, the Orderer will read Segments from the channel and order these Segments.

The Init method must be called before the Orderer is started (using Start). After Init returns, the Orderer must be ready to process incoming messages (even if the handler blocks on the first one), while not producing any outgoing messages. (Outgoing messages can be produced only after Start is called.) This is crucial, as the program that uses the Orderer firs initializes it and then starts the messaging subsystem (the Messenger). The Messenger needs an initialized Orderer for the messages the Messenger delivers. However, it is only after the Messenger starts, when it is safe for the Orderer to produce outgoing messages.

Protocol messages

As the Orderer is supposed to implement an ordering protocol, it will need to exchange messages. Each message used by the Orderer is wrapped in a protocol message of type *pb.OrdererMsg, defined in protobufs/messenger.proto. A *pb.OrdererMsg only has one field (called Msg) of the protocol buffers "oneof" type, containing the actual message of the ordering protocol. The Orderer implementation must define its own message types (e.g. PrePrepare, Prepare, Commit, etc. for PBFT) to be used in this field and add these message types as possible values of the msg field in the definition of OrdererMsg in protobufs/messenger.proto.

Sending messages

To send a message m to a peer with ID id, the Orderer implementation only needs to call the messenger.EnqueueMessage(m, id). The message m needs to be of type *pb.ProtocolMessage with senderId set to the own ID (accessible through membership.OwnID) and Msg containing a (properly wrapped) message of type *pb.OrdererMsg. The OrdererMsg, in turn, contains the (properly wrapped) actual message in its own (nested) Msg field.

For example, the DummyOrderer defines a DummyOrdererMsg, an instance of which is created as follows.

m := &pb.ProtocolMessage{
    SenderId: membership.OwnID,
    Msg: &pb.ProtocolMessage_Orderer{Orderer: &pb.OrdererMsg{
        Msg: &pb.OrdererMsg_Dummy{Dummy:&pb.DummyOrdererMsg{
            ProtocolSpedificField1: protocolSpecificValue1
            ProtocolSpedificField2: protocolSpecificValue2
            //...
        }},
    }},
}

Handling messages

To handle incoming messages, the HandleMessage method of the Orderer must be implemented. This method is called by the Messenger whenever the peer receives a message that belongs to the ordering protocol. Note that HandleMessage will potentially be called by multiple goroutines concurrently and its implementation needs to deal with it.

In addition to the received message, HandleMessage receives he ID of the sending peer as an additional argument. Depending on the implementation of Messenger, thes messages might or might not be authenticated.