## 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](https://github.com/algorand/go-algorand/blob/df0613a04432494d0f437433dd1efd02481db838/network/wsPeer.go#L177).

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:

| TAG | DESCRIPTION |
| --- | --- |
| "AV" | Agreement Vote (a protocol vote, see [normative section](https://specs.algorand.co/abft/abft-messages-votes)). |
| "MI" | Message of Interest. |
| "MS" | Message Digest Skip. A request by a PeerPeer to avoid sending messages with a specific hash. |
| "NP" | Network Priority Response. |
| "NI" | Network ID Verification. |
| "PP" | Proposal Payload (see [normative section](https://specs.algorand.co/abft/abft-messages-proposals)). |
| "SP" | State Proof Signature (see [normative section](https://specs.algorand.co/crypto/crypto-state-proofs)). |
| "TS" | Topic Message Response. |
| "TX" | Transaction (see [normative section](https://specs.algorand.co/ledger/ledger-transactions)). |
| "UE" | Unicast Catchup Request. Messages used to request blocks by a PeerPeer when serving blocks for the catchup service |
| "VB" | Vote Bundle (a protocol bundle, see [normative section](https://specs.algorand.co/abft/abft-messages-bundles)). |
| "pi" | Ping.[1](https://specs.algorand.co/network/non-normative/network-nn-notation#footnote-1) |
| "pj" | Ping Reply.[1](https://specs.algorand.co/network/non-normative/network-nn-notation#footnote-1) |

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](https://github.com/algorand/go-algorand/blob/ce9b2b0870043ef9d89be9ccf5cda0c42e3af70c/network/gossipNode.go#L140C6-L140C21).

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

> Important  
> **IMPLEMENTATION:**  
> High priority queue [reference implementation](https://github.com/algorand/go-algorand/blob/ce9b2b0870043ef9d89be9ccf5cda0c42e3af70c/network/wsNetwork.go#L388).

Every tagtag has a corresponding set of handlers, described in detail in the [Message Handlers section](https://specs.algorand.co/network/non-normative/network-nn-notation#message-handlers).

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](https://specs.algorand.co/network/non-normative/network-nn-notation#protocol-tags)), 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](https://specs.algorand.co/network/non-normative/network-nn-parameters) for details on size constraints,

- `network`, the type of network from which the message originated ([Relay Network](https://specs.algorand.co/network/non-normative/network-nn-definitions-ws) or [P2P Network](https://specs.algorand.co/network/non-normative/network-nn-definitions-p2p)),

- `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](https://specs.algorand.co/network/non-normative/network-nn-notation#protocol-tags)). 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`.
> 
> ```go
> 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.