> For the complete documentation index, see [llms.txt](https://canopy-network.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://canopy-network.gitbook.io/docs/canopy-network/understand-the-protocol/p2p.md). # P2P ## P2P Canopy uses a custom peer-to-peer, or P2P, networking layer to connect nodes across the network. This layer is responsible for moving information between nodes, including transactions, blocks, consensus messages, peer-discovery data, and other protocol messages. The P2P layer uses TCP/IP for transport and adds encrypted connections, multiplexed message streams, peer discovery, liveness checks, reputation tracking, and denial-of-service protections. It supports both direct communication between two peers and gossip-based dissemination across the network. P2P networking is separate from the rules that determine whether a transaction or block is valid. Its role is to deliver messages securely and reliably enough for the state machine and NestBFT consensus protocol to operate. ### How a peer connection works A Canopy node first establishes a TCP connection with another node. Before protocol messages are exchanged, the peers complete an authentication handshake that converts the connection into encrypted transport. The peers then use the established connection to exchange messages over independent topic-based streams. Throughout the connection, the P2P layer applies message-size limits, traffic limits, liveness checks, and reputation rules. It may disconnect or ban peers that fail authentication, violate protocol rules, become unresponsive, or exceed the permitted limits. At a high level, a connection follows this sequence: 1. A node creates or accepts a TCP connection. 2. The peers perform an authenticated key exchange. 3. The peers derive the keys and nonce used for the connection. 4. Messages are encrypted and authenticated with ChaCha20-Poly1305. 5. Messages are assigned to topic-specific streams and serialized with Protobuf. 6. The P2P layer tracks peer behavior, traffic, timeouts, and connection health for the duration of the session. ### Transport Canopy uses TCP/IP as the underlying network transport. TCP provides an ordered, reliable byte stream between peers, while the Canopy P2P protocol defines how peers authenticate, frame, encrypt, classify, and process messages on top of that connection. The P2P layer does not require a separate TCP connection for every type of message. Instead, it multiplexes several logical streams over one authenticated connection. This reduces connection overhead while allowing blocks, transactions, consensus traffic, and discovery messages to be processed independently. ### Authentication handshake When two peers connect, they execute an authentication protocol before exchanging normal P2P messages. The handshake creates a shared secret between the peers and uses that secret to establish encrypted communication. #### Ephemeral key exchange Canopy uses an ephemeral Diffie-Hellman key exchange over the X25519 elliptic curve, also known as X25519 ECDH. Each peer generates temporary key material for the connection and combines its private key material with the other peer’s public key material to produce the same shared secret. The peers do not transmit the final encryption keys across the network. Using ephemeral key material means the keys used for one connection are not intended to be reused as the long-term keys for every future connection. The handshake establishes session-specific material that can be used to protect the traffic on that connection. #### Key derivation After establishing the shared secret, Canopy applies a HMAC-based key-derivation function. The derivation process produces three values used by the connection: | **Output** | **Purpose** | | ------------------ | ----------------------------------------------------------------------- | | Encryption key | Used to protect the confidentiality of messages sent between peers. | | Authentication key | Used to authenticate communication between peers. | | Nonce | A unique initialization value used as part of authenticated encryption. | The derived values allow both peers to encrypt, decrypt, and authenticate messages without exposing the underlying shared secret or transmitting the final session keys directly. #### Message encryption Canopy uses ChaCha20-Poly1305 authenticated encryption with associated data, or AEAD, for subsequent P2P communication. This scheme protects the contents of messages from third parties that cannot decrypt the connection. It also lets the receiving peer verify that a message was produced by the authenticated connection and has not been modified in transit. The encrypted connection provides three important properties: * **Confidentiality.** A third party cannot read the contents of protected P2P messages. * **Authenticity.** A receiving peer can verify that the message belongs to the authenticated connection. * **Integrity.** A receiving peer can detect messages that have been altered, corrupted, or forged. A peer that fails the authentication handshake is automatically banned. This prevents the node from continuing to establish normal protocol communication with a peer that cannot complete the required connection-security process. ### Multiplexing A Canopy connection can carry more than one independent stream of messages. This is called multiplexing. Without multiplexing, a node would need separate connections for blocks, transactions, consensus traffic, peer discovery, and other message types. Instead, Canopy assigns each message to a topic and carries multiple topic-specific streams over the same TCP connection. Each topic has its own stream, message queue, and inbox. A packet header identifies the topic to which the packet belongs, allowing the receiving peer to route it to the correct stream. This separation helps the node manage different kinds of traffic independently. For example, a queue of transaction messages does not need to share the same logical stream as consensus messages. A node can receive peer-discovery information, process a proposed block, and exchange consensus messages over the same authenticated connection while keeping the messages organized by purpose. ### Wire protocol and serialization Canopy uses Protocol Buffers, or Protobuf, to serialize P2P messages. Protobuf is also used by the Canopy storage module. A Protobuf schema defines the structure and fields of a message before that message is transmitted. Nodes serialize the message into a compact wire format, transmit it through the appropriate P2P stream, and deserialize it on receipt. Using a schema-driven format provides several practical benefits. First, it gives the protocol a defined message structure rather than relying on ad hoc payload formats. Second, it supports code generation for different programming languages and implementations. Third, it provides a language-neutral format for nodes that may not share the same application-language environment. Finally, Protobuf is generally more compact than JSON for structured protocol messages, which reduces unnecessary bandwidth and parsing overhead. ### Peer reputation and denial-of-service mitigation A public P2P network must assume that some peers will send malformed messages, consume excessive resources, repeatedly disconnect, or otherwise behave in ways that degrade the network. Canopy’s P2P layer includes multiple controls intended to reduce the impact of this behavior. #### Peer reputation Canopy tracks a reputation score for each peer. A good interaction results in a positive change to the peer’s reputation score. A bad interaction results in a negative change. The P2P layer uses this score to distinguish peers that consistently behave according to the protocol from peers that repeatedly cause problems. If a peer’s reputation score falls below the permitted threshold, the node disconnects from that peer and bans it. This makes reputation a continuing property of a peer relationship rather than a one-time check made only when the connection is created. #### Rate limits and size limits Canopy applies limits at several levels of the connection. Each connection has inbound and outbound traffic limits. These controls limit how much data a peer can send to or receive from the node over time. The protocol also enforces a maximum message size, preventing a peer from submitting arbitrarily large payloads that could consume excessive bandwidth or memory. Nodes also limit the total number of inbound and outbound connections they maintain. This prevents a node from accepting unlimited connection attempts and gives operators control over the networking resources allocated to their node. #### Liveness checks A connected peer is not necessarily a healthy or responsive peer. Canopy uses operation-specific read and write timeouts to detect network operations that do not complete in the expected time. The P2P layer also uses ping and pong heartbeats. A node can periodically send a ping to a connected peer and expect a corresponding pong response. Missing responses help identify peers that are unavailable, disconnected, or no longer functioning correctly. These liveness checks allow nodes to remove stale connections and maintain a more reliable peer set. #### Banning Canopy supports both automatic and manual bans. A node automatically bans a peer that fails the authentication handshake. Operators may also explicitly ban an IP address or a public-key peer ID. This gives node operators a way to remove known abusive or unwanted peers from their local network environment. ### Peer discovery and peer management A node needs a way to find peers, remember useful peers, and remove peers that are no longer reachable. Canopy manages this through validator-aware connections, peer books, peer-book exchange, and peer churn. #### Validator connections The P2P module is aware of the node’s validator status and the active validator list. When a node is an active validator, it attempts to establish direct connections with the other active validators. These direct connections are important for the timely communication required during BFT consensus. This does not mean every node must be a validator. Non-validator nodes can participate in the broader P2P network, while validators receive the additional connectivity behavior needed to exchange consensus messages with the active validator set. #### Peer book Each node maintains a peer book, which is a record of peers that have previously been active or known to the node. The peer book gives a node a starting set of connection candidates when it joins or restarts. It also reduces dependence on a single static list of peers by allowing the node to build knowledge of the network over time. #### Peer-book exchange Connected nodes periodically exchange lists of known peers. This allows a node to learn about peers discovered by other nodes and helps distribute peer information across the network. Peer-book exchange improves the network’s ability to recover when individual peers disappear. A node is not limited to the peers it already knows. It can receive additional candidates from its connected peers and attempt to establish new connections. #### Peer churn The P2P layer periodically crawls the peer book and attempts to connect to recorded peers to determine whether they remain reachable. If a peer repeatedly fails these connection attempts over multiple churn cycles, the node removes that peer from the peer book. This keeps the peer book from becoming a permanent list of obsolete addresses and helps the node prioritize peers that remain available. ### Message dissemination Canopy supports two modes of message dissemination: point-to-point transmission and gossip. The P2P layer selects the appropriate mode based on the purpose of the message. Direct communication is useful when a message has a specific recipient. Gossip is useful when a message should propagate through the wider network. #### Point-to-point transmission Point-to-point transmission sends a message directly to a specified peer. This mode is useful for protocol messages that have a known recipient. For example, a validator can send a consensus vote to the current leader rather than broadcasting that vote to every connected peer. Point-to-point communication supports the linear communication model used by NestBFT. It allows consensus participants to send messages along the paths required by the consensus protocol without creating unnecessary all-to-all traffic. #### Gossip Gossip sends a message to all connected peers except the peer from which the message originated. Excluding the originator prevents the node from immediately returning the same message to the peer that sent it. As peers repeat this behavior, information can spread across the network through multiple paths. Gossip is useful for messages that should become broadly available, such as blocks, transactions, and network information. It helps distribute messages without requiring the original sender to maintain a direct connection to every node in the network. ### Node configuration Node operators can configure the P2P layer to fit their operating environment. These settings allow an operator to control connection limits, prioritize particular peers, block unwanted peers, and define the minimum connectivity required before the node begins normal operation. | Configuration | Description | | ---------------------------- | -------------------------------------------------------------------------------- | | Maximum inbound connections | The maximum number of connections that other peers may initiate with the node. | | Maximum outbound connections | The maximum number of connections that the node may initiate with other peers. | | Dial peers | A list of peers that the node attempts to connect to when it starts. | | Trusted peer IDs | Public-key peer IDs that may bypass normal connection limits. | | Banned peer IDs | Public-key peer IDs that are not permitted to connect. | | Banned IPs | IP addresses that are not permitted to connect. | | Minimum peers to start | The minimum number of peer connections required before the node starts. | | Read and write timeouts | Limits used to identify network operations that are taking too long to complete. | These settings should be chosen with the node’s role in mind. A validator needs dependable connections to the active validator set. A public node may need stricter inbound limits and ban controls. A development or private-network node may use dial peers and trusted peer IDs to create a more controlled connection topology. ### Relationship to consensus and the state machine The P2P layer carries information. It does not decide whether a transaction is valid, whether a block should be committed, or how the ledger state should change. NestBFT uses the P2P layer to exchange the messages needed for leader election, proposals, votes, quorum certificates, recovery, and block propagation. The state machine uses the network-delivered block and transaction data to apply deterministic protocol rules. This separation keeps networking, consensus, and execution distinct. The P2P layer makes communication possible. Consensus determines agreement. The state machine determines the resulting state. Next, learn how Canopy processes transactions and applies deterministic protocol rules in the [State Machine](app://-/state-machine.md).