How P2PD works
===============

Addresses
----------

You may already be familiar with IPv4 and IPv6 addresses. These addresses allow
for data to reach nodes on
the Internet. Practically, we can say these addresses are assigned to routers. They work  well for regular servers but in a peer-to-peer context more information is needed to
describe a peer's network. Here is what a peer's address looks like in P2PD.

``0,1-[1,0,8.8.8.8,192.168.21.21,58959,3,2,0]-0-zmUGXPOFxUBuToh-easdasd``

As you can see there are already pieces of information you may recognize.
There is a private LAN IP that belongs to the NIC
interface and its associated external IP. But what is the other information?
Well, the address format includes the following details.

-   **Signaling offsets.** MQTT server offsets (for signaling messages.)
-   **Netiface offset.** An index of the interface in absolute terms on the machine.
-   **Interface offset.** Peers include a list of interfaces to listen on. 
    The offset is relative to that list.
-   **External IP.** The WAN IP associated with an interface route.
-   **Internal IP.** The private address associated with a route. 
-   **Listen port.** The port used to listen on by the peer's node server.
-   **NAT type.** The main type of NAT for the router.
-   **Delta type.** Information on a NAT's port mapping algorithm.
-   **Delta value.** Information on any patterns found in a NAT's port mappings.
-   **Node ID.** ECDSA public key. Also subscribed for MQTT signaling.
-   **Machine ID.** Generated by the OS to uniquely identify a machine.

The address format can describe multiple interfaces and address families.
The maximum interface number is currently limited to 3 per address family.
The importance of these addresses is they are what's used to open direct
connections to a peer. See :doc:`../p2p/nicknames` for a guide
to using names to avoid sharing addresses directly.

----

Signaling
-----------

P2PD uses MQTT for signaling. Signaling refers to the protocol P2PD uses to coordinate P2P connections. Some
examples include:

-   **P2P_DIRECT** = Tell a peer to connect back to an address.
-   **P2P_PUNCH** = Exchange port mappings for TCP hole punching.

Signaling messages are integral to how P2PD functions. By relying on
public MQTT servers -- messages are able to reach peers easily.
The way this occurs is through the use of random IDs (pub keys) as topic subscriptions.
A peer subscribes to a random ID and includes this ID in its address information.
Messages can then reach that peer via an MQTT server.
Such an approach is scalable and already backed by many public servers.

P2PD's message format is intentionally simple. It's based on a series of classes in Python
that use JSON for input and output. There's a main message class that
includes sections for addressing (for the sender and destination.) Unique
protocol messages inherit this class and add what they need. The resulting
protocol code is incredibly short -- around 300~ lines.

See p2p_defs.py and p2p_protocol.py for how it looks.

.. NOTE::
    P2PD does not use MQTT servers as 'proxies.' Only as a way to exchange
    initial messages needed to setup direct connections between peers. 
    Connectivity is fully peer-to-peer.

----

Methodology
-------------

Please see :doc:`../p2p/connect` for strategies P2PD uses for direct connections.