Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

• Auto
• Light
• Dark

Algorand Specifications

We define a PeerPeer as a generic network actor.

This construct provides a way to refer to nodes indistinctly and keep track of all neighbors with inbound or outbound connections that may relay or broadcast messages.

Each of PeerPeer represents a fully operational Algorand node with a working network layer.

A specific PeertPeert, with t∈{WS,P2P,HYB} is a PeerPeer whose network layer implements a specific type of network.

A PeerPeer has all the necessary contents to communicate with the node it represents (the HTTP client, the URL representing the node, and extra metadata necessary to maintain an active connection).

Important
IMPLEMENTATION:
Peer struct reference implementation.

A protocol tagtag is a short 2-byte string that marks a message type.

A tagtag should not contain a comma, as lists of tags are modeled by comma-separated tag handles.

Protocol tags play a key role in routing messages to appropriate handlers and incorporating priority notions.

Conceptually, a tagtag determines the purpose of an incoming data packet inside the overarching protocol.

Possible values for the tagtag type are:

Agreement Vote ("AV") and Proposal Payload ("PP") are the only ones considered of “high priority”. This means they impact internal ordering in the broadcast queue, as a priority function discriminates against them.

Important
IMPLEMENTATION:
High priority tags reference implementation.

Messages tagged with AV or PP get pushed into a separate high-priority queue.

Important
IMPLEMENTATION:
High priority queue reference implementation.

Every tagtag has a corresponding set of handlers, described in detail in the Message Handlers section.

Algorand nodes communicate inside a network layer exchanging messages.

A message is a data structure with a payload (a set of bytes) and metadata that serves to authenticate, route, and interpret messages received or sent out.

We define a deserializable object incoming message ∗M, as an object representing a message from some PeerPeer in the same network layer.

An incoming message ∗M provides the following fields:

• sender, an identified PeerPeer indicating the sending party,

• protocolTag, a tag (see above), used to identify univocally the message type and route it to the correct message handler to produce an outgoing message,

• payload, an array of bytes representing the content of the message. See the parameters section for details on size constraints,

• network, the type of network from which the message originated (Relay Network or P2P Network),

• received, a 64-bit integer representing the reception time of this message (expressed in nanoseconds since the epoch).

When an incoming message ∗M is received, and the appropriate message handler has processed it, an outgoing message is produced.

We define a deserializable object outgoing message M∗, as an object representing a message from some PeerPeer in the network.

An outgoing message M∗ provides the following fields:

• protocolTag, a tag (see above). Similarly to incoming messages, it marks how the receiving PeerPeer should interpret and handle the produced message,

• topics, a list of key-value pairs (of the form string -> bytes[]) for topics this message serves, used in certain specific scenarios (mainly for the catch-up service). The possible topic keys are:

  • General purpose:
    • "RequestHash", responding to requests for specific topics,
    • "Error", passing an error message on a specific topic request.
  • Block service:
    • "roundKey", the block round-number topic-key in the request,
    • "requestDataType", the data-type topic-key in the request (e.g., block, cert, blockAndCert),
    • "blockData", serving block data,
    • "certData", serving block certificate data,
    • "blockAndCert", requesting block and certificate data,
    • "latest", serving the latest round.

• disconnectReason, only when the Action calls for a Disconnect as a ForwardingPolicy (see below). An enumeration of the reasons to disconnect from a given PeerPeer (message sender) may be found right below.

A ForwardingPolicy is an enumeration, indicating what action should be taken for a given outgoing message M∗. It may take any of the following values:

• Ignore, to discard the message (don’t forward),

• Disconnect, to disconnect from the PeerPeer that sent the message M∗ which returned this response,

• Broadcast, to forward this message to everyone (except the original sender PeerPeer),

• Respond, to reply to the sender PeerPeer directly,

• Accept, to accept the message for further processing after successful validation.

When an incoming message ∗M is received, a handler function is called according to its type. The message handler processes the message according to the protocolTag, and produces an outbound message M∗ with information on how to proceed further.

We define a message handler MHt(∗M) as a function that takes an incoming message as input and transforms it into an outgoing message.

MHt(∗M)=M∗

where tt denotes a tagtag-specific handler function (according to the input inbound message protocolTag).

We define a message validator handler MVh(∗M) as a function that performs synchronous validation of a message before processing it with the MHt(∗M) functions.

The prototype of message validator handlers is similar to regular handlers.

Important
IMPLEMENTATION:
The reference implementation defines a helper function, Propagate(msg IncomingMessage), representing the prevalent case of a message handler re-propagating an incoming message ∗M. Internally, it creates an outgoing message M∗, with the same data as the received message and the action to Broadcast.

func Propagate(msg IncomingMessage) OutgoingMessage {
 return OutgoingMessage{Action: Broadcast, Tag: msg.Tag, Payload: msg.Data, Topics: nil}
}

1. Removed in go-algorand 3.2.1., included for completeness.