P2P Network Basics đ
The P2PNet
library provides the core functionality for building and managing a peer-to-peer network. It includes classes and methods for peer discovery, connection management, data exchange, and network routines. This document provides a broad overview of the peer network basics.
Overview
General broad overview of the peer network structure.
Initialization
The PeerNetwork
class is the main entry point for initializing and managing the peer-to-peer network. It sets up the necessary configurations and services required for network operations.
- Configuration: The peer network hosts several configuration fields which can be used to fine tune control over the network operations. Some of these fields include subclasses that can be explored under
TrustPolicies
. Other aspects of configuration are in design such as the usage of queues and events, or the use of delegates for handling certain scenarios. - Logging: Logging is handled using the
ConsoleDebugger
package. Logging can be toggled between being directed to either console output or the log file, or optionally both. By default logging is omitted. To toggle logging on, setPeerNetwork.Logging.EmitConsoleMessages
to true for console output and/orPeerNetwork.Logging.LogToFile
for logging to file. TheConsoleDebugger
package is a lightweight package that is easy to configure and managed by the same team that made the P2PNet (the package was actually made as a result of P2PNet development). - Network Configuration: The application scans all network interface devices and collects essential information needed for the peer network, such as public IP addresses and LAN IP addresses.
Operation
The PeerNetwork
class operates by providing several key functionalities:
Peer Discovery and Connection:The library supports both LAN and WAN peer discovery. It uses broadcasting, multicasting, and designated ports to discover peers and establishes connections using TCP.
- LAN Discovery: Broadcasts are used for peer discovery within the local network.
- WAN Discovery: Specific WAN components and designated ports facilitate the discovery of peers over a wide area.
Peer Management: A list of known peers and active peer channels is maintained. This supports functions such as adding or removing peers and managing connection permissions.
- Known Peers: Stores details of all discovered peers.
- Active Peer Channels: Manages active communication channels and leverages the
PeerChannel
class to encapsulate connection logic.
Data Exchange and Network Packets: Data exchange between peers is accomplished via network packets formatted to ensure data consistency and integrity.
- Network Packets: These packets encapsulate various types of information for transmission between peers. Types include identity packets, disconnect packets, data transmission packets, pure message packets, and more. The packets are wrapped using the
DistributionProtocol
so that each packet is tagged properly, making it easier for the receiver to determine the payload type. All network packet types derive from theNetworkPacket
base class. - DistributionHandler: This static class is responsible for handling outgoing and incoming data packets. It wraps raw data into packets and distributes them to trusted peers. In addition, the handler supports unwrapping payloads to extract raw data before processing.
- NetworkTaskHandler: In parallel with data handling, the
NetworkTaskHandler
manages network tasks defined as actions such as blocking a peer, sending messages, or synchronizing data. Tasks are enqueued and processed asynchronously to maintain smooth operations across the network.
- Network Packets: These packets encapsulate various types of information for transmission between peers. Types include identity packets, disconnect packets, data transmission packets, pure message packets, and more. The packets are wrapped using the
Peer Channels: Each communication channel between peers is represented by an instance of the
PeerChannel
class. This class manages the relay of data packets, conducts connection retries, and enforces trust policies by invoking predefined delegates from thePacketHandleProtocol
.
File Management via IFileManager
The DistributionHandler
uses its static NetworkFileManager
propertyâtyped as IFileManager
âto handle all fileâbased payloads (DataPayloadFormat.File
). On receipt, each file packet is passed to
NetworkFileManager.InboundDatapacketToFile(packet);
and outgoing file data is written via the same interface.
By default two implementations are provided:
- MemoryMappedFileManager Uses memoryâmapped files for fast, lowâoverhead read/write operations in RAM. Ideal when working with large files or highâthroughput scenarios.
- VirtualImageFileManager Creates a VHD image formatted with FAT and stores files inside it. Useful when you need a selfâcontained disk image or want FAT semantics on top of a virtual filesystem.
To swap in a custom manager, assign before distribution starts:
DistributionHandler.NetworkFileManager = new YourCustomFileManager(...);
Your implementation must handle GetFile(string|int)
, WriteToFile(...)
and InboundDatapacketToFile(...)
to integrate smoothly with the distribution pipeline.
Routines
The NetworkRoutines
class provides a mechanism for managing network routines. Routines are tasks that run at specified intervals to perform various network-related operations.
- Routine Management: The
NetworkRoutines
class manages a dictionary of routines and provides methods for adding, starting, stopping, and setting the interval of routines.- Default Routines: The application has default routines. These default routines do not automatically startup, but are automatically added in to the routines list.
- Custom Routines: Users can add custom routines to perform specific tasks.
Routines are accessed using their RoutineName
property. This is automatically handled when they are added as network routines.
Trust Policies
The PeerNetwork
class employs a multi-pronged trust model to ensure secure and robust peer interactions. These policies determine how incoming connections are verified, how bootstrap nodes are treated, and how the local network identifier is managed.
Incoming Peer Trust Policy This policy governs the verification and handling of peers attempting to connect to the network. It includes several configurable settings:
- AllowDefaultCommunication:
Enables basic communicationâsuch as exchanging
PureMessagePackets
andDisconnectPackets
âwithout full verification. Example use case: In a trusted LAN environment, you might allow default communication to quickly establish a connection before a deeper security check. - AllowEnhancedPacketExchange:
When enabled, permits the exchange of complex packets (e.g.,
DataTransmissionPackets
) that may carry critical data. Example use case: For networks where peers are pre-validated, you might allow enhanced packet exchange immediately to boost performance. - RunDefaultTrustProtocol:
Initiates the systemâs built-in handshake mechanism (which you can replace with a custom
PeerTrustHandshake
delegate) that verifies a peerâs authenticity before granting them full network access. - Incoming Peer Placement: Supports both queue-based and event-based models. Queue-based placement helps throttle connections when there are many incoming requests, while event-based placement provides immediate notification for further processing.
- AllowDefaultCommunication:
Enables basic communicationâsuch as exchanging
Bootstrap Trust Policy This policy handles the initial secure connection phase with bootstrap nodes that help a new node join the network. Key settings include:
- AllowBootstrapTrustlessConnection: Permits bootstrap connections without pre-established credentials, often useful for open networks needing quick scalability.
- AllowBootstrapAuthorityConnection: Allow bootstrap nodes to validate their credentials via key issuance, ensuring a tighter security model.
- MustBeAuthority: Prohibits connecting to bootstrap nodes that are not operating in authority mode. Example use case: In a decentralized network, you may require that only nodes with verified authority can bootstrap, ensuring that malicious nodes cannot easily infiltrate the system.
- FirstSingleLockingAuthority: Enforce strict measures so that the first trusted authority connection can be locked inâpreventing further authority connections that might threaten network integrity.
PeerNetworkTrustPolicyControls how the local network identifier is set and maintained, and how the public IPv4 address is retrieved.
- LocalIdentifierSetPolicy: Defines policies like
StrictLocalOnly
,Local
,LocalAndRemote
,RemoteOnly
, orStrictRemoteOnly
to ensure that the identifier is assigned only under secure, predefined conditions. - PublicIPv4GetPolicy: Determines the method used to retrieve the public IPv4 address. Options include:
- SingleStaticURL: Fetches the IP address from one static URL.
- StaticURLAndFailover: Tries a primary static URL and falls back to others if necessary.
- URLListConsensus: Utilizes multiple URLs and selects the most frequently returned IP address as the public IP.
- PublicIPv4Sources: A list of URLs that are queried to fetch the public-facing IPv4 address, based on the defined retrieval policy. URLs should point directly to an API endpoint serving a plain text response.
- SetIdentifier: Gets or sets the delegate responsible for generating and assigning the peerâs network identifier. The default
SetIdentifier
handler concatenates the systemâs MAC address with the current timestamp, computes an MD5 hash, appends the chosen public IP (IPv6 if available, otherwise IPv4), and computes a second MD5 hash. Override this delegate to supply custom identifier logic that fits your network requirements. - NetworkTaskTrustSettings: An instance of
NetworkTaskTrustConfiguration
namedNetworkTaskTrustSettings
defines trust parameters for executing network tasks. It maps specific task types (such as bootstrap initialization, blocking, and messaging) to required trust parameters, such as requiring a signed hash or authority verification. This configuration ensures that tasks are only executed when the originating peer meets the necessary trust criteria. For example, tasks likeTaskType.AssignIdentifierToPeer
require that the sender provides a valid signed hash and is recognized as an authority bootstrap server. However, by creating a new instance ofNetworkTaskTrustConfiguration
we can set it to block any tasks that attempt to assign an identifier to a peer thereby nullifying the action all together. This allows for finer control over network behavior.
- LocalIdentifierSetPolicy: Defines policies like
These trust policies work in tandem to balance flexibility and security. You can adjust the settings to suit various network scenariosâfrom enterprise-level internal networks that rely on rapid, low-security handshakes, to public peer-to-peer systems that demand strict, authority-based validations.