Addressing - Algorand Specifications

Algorand Specifications

The following section presents how the two Algorand network layers (WSWS and P2PP2P) resolve peer addressing, to univocally identify themselves amongst PeerPeers, establish two-way connections, and effectively route messages regardless of the underlying architecture.

The Relay Network WSWS relies on an ip:port scheme to let a PeerPeer present itself to and address other peers.

This schema is defined in the NetAddress parameter of the node configuration.

See details in the node configuration non-normative section.

The PublicAddress also can be set in the node configuration to let a PeerPeer differentiate itself from other peers, and to be used in the identity challenges.

Important

IMPLEMENTATION:

The reference implementation checks the scheme of network addresses against this regex:

^[-a-zA-Z0-9.]+:\d+$

Important

IMPLEMENTATION:

Websocket network address reference implementation.

The Peer-to-Peer Network P2PP2P makes use of the underlying libp2p library primitives for PeerPeer addressing, identification, and connection.

This section relies on the libp2p specifications and developer documentation.

In this addressing scheme, each node participating in the P2PP2P network holds a public and private Ed25519 key pair. The private key is kept secret, and the public key is shared with all participants.

The peer identity (PeerID) is a unique reference to a specific PeerPeer within the P2PP2P network, serving as a unique identifier for each PeerPeer. It is linked to the public key of the participant, as it is derived as a hash of said key, encoded in base58.

See libp2p PeerID specification for details on how these are constructed and encoded.

The PeerID are visible and may be incorporated into multiaddresses to route messages.

PeerPeer private keys are used to sign all messages and are kept as secrets by the node.

Important

IMPLEMENTATION:

PeerID are cast-able to str type and are used as plain strings in packages where importing libp2p packages may not be needed.

Important

IMPLEMENTATION:

A GetPrivKey function manages loading and creation of private keys in the P2PP2P network. It prioritizes, in this order:

  1. User supplied path to privKey,
  2. The default path to privKey,
  3. Generating a new privKey.

Important

IMPLEMENTATION:

If a new private key is generated, and should be persisted, its default path is "peerIDPrivKey.key" (inside the root directory). The behavior of this lookup is governed by node configuration values P2PPersistPeerID and P2PPrivateKeyLocation (see the Algorand Infrastructure non-normative section).

A multiaddress is a convention for encoding multiple layers of addressing information into a single “future-proof” path structure. It allows overlay of protocols and interoperation of many peer addressing layers.

When exchanging addresses, peers send a multiaddress containing both their network address and PeerID.

Regular NetAddress (as the scheme presented in the previous section) may be easily converted into a libp2p formatted listen multiaddress.

Given a network address [a]:[b] (where [a] is the IP address and [b] is the open port), the conversion scheme is /ip4/[a]/tcp/[b].

Refer to the libp2p specifications for further detail on this structure.

Important

EXAMPLE:

Here are some examples of syntactically valid multiaddresses:

The hybrid network maintains a single IdentityTracker entity, shared between both network definitions (WSWS and P2PP2P).

Note that a PublicAddress must be set for hybrid nodes to operate properly.

For peer identity deduplication, a signing schema involving both the P2PP2P private key and the WSWS identity challenge is put in place. This is to correlate both PeerPeer definitions and prevent it from existing in both PeerPeer lists.

See the hybrid network identity challenge for further details on this process.