IPv8 documentation


This book is made to explain the protocol behind the IPv8 application and protocol. This protocol aims to fulfill a few key goals, namely:

  • Unordered and connection oriented, but reliable transmission
  • Message authenticity
  • Message encryption
  • Low hop count
  • Protection against falsified node ID's
  • Self repairing in case of node failure
  • Almost guaranteed message delivery
  • Protection against malicious nodes
  • Offline message delivery
  • Route locality
  • Low redundant messages being send out
  • Rate limiting/flood protection for (D)DOS protection


This system is designed to be secure. It uses a DHT routing system under the hood, which historically has a lot of issues. There are a few key points of security this is trying to solve. These will be discussed in this page.


The system uses symmetric encryption to ensure confidentiality of the messages passed trough the network. The key for this is shared during a handshake, if either of the two wants to set up a secured connetion. This ensures complete confidentiality between two nodes. More information about the implementation can be found on the security layer.


This ensures that the data has not been manipulated. It is guaranteed by the verification layer. This page will go into more detail of the exact implementation, but the more important


This was the hardest problem to solve, as there is no sure way to verify if a packet is intentionally dropped, or that the node is not online.

A few of the implemented defenses:

  • Difficult hashing of the public key to reduce the amount of new public keys.
  • Periodic proof-of-work requests to limit the number of clients per node.
  • Dropping of nodes with a high packet loss rate.

While these defenses don't prevent all attacks on the availability of the network, it should reduce the amount and scale of most attacks. You can find more information on the implementation on the routing page.


Trust in a distributed network has been proven to be a difficult challenge. structured p2p networks like DHT's use a high level of trust, making them vulnerable to a range of attacks. Distnet tries to defend against these attacks by using a routing algorithm derrived from SPROUT and Pastry. It uses a web of trust defined by the overlay to create a routing table for that overlay. While there is a global network spanning all nodes which can be used as a fallback, the routing table for that overlay is used till the node cannot forward the message any better. When that happens the global network takes care of the last mile using tratitional Pastery.

In this network trust is defined by a number between -1 and 1 (inclusive). Every node starts of with a neutral trust of 0. An overlay can use it's own algorithm to register a new trust value for a node. For example a social network can use the trust value to indicate the relationship between two identities. If two identities have a close relation the overlay might set the trust to 0.9, but if they barely know each other it might give a rating of 0.2. A negative rating is also possible, if this is given the node tries to avoid this node, and never connects to it directly.

Building the trust graph

The trust of a node is stored in the Trustchain, of which the starting node has a local copy of from the last time it connected to the network. It will use this to build the trust graphs of all of the overlays as well as an aggregated one, which combines all the overlays into one. This aggregated one is used when creating the globally linked network.

When building the trust graph for a overlay it first reads out all ratings given to nodes. Negative ratings are ignored here. If the rating is higher than a treshhold (let's say 0.6), then the process is repeated but for that node. So it reads out the trustchain for that node, and get's the trust. That trust is multiplied by the trust of the origional node, giving the relative trust of the new node. This is then added to the list of nodes.

A quick example:

Node A tries to connect to the network.
It finds node B in it's trust graph, with a trust rating of `0.7`.
Node A explores the Trustchain of node B, finding a new node C with a rating of 0.4.
The ratings of node B and C are multiplied, giving the relative rating of 0.28 for C from A.
If node C already existed in the graph of node A then the trusts are added together.
So if node A had a trust of 0.3 for node C, then the new trust will be 0.58.

To build the aggregated graph it simply combines all graphs, with adding the different trusts together. If a collision occures the trust values are added together, giving that node a higher incentive to be connected to.

Building the routing table

When a node starts up it will connect to a boostrap node and do the boostrapping procedure as notmal with Pastery. In the procedure it tries to connect to a few of the most trusted nodes as defined in the trust graph. This is used to build the routing table. While the is going on it tries to swap out any random nodes with nodes with a higher trust rating. This would create


The protocol is set up in a layered fasion, where every layer should be independent of the other. This is done to simplify the model and create a seperation of concerns. A simplified table is displayed below:

| 5 | Community       |
| 4 | Security        |
| 3 | Routing         |
| 2 | Verification    |
| 1 | Transmission    |

Every part will be explained separately in different chapters from low to high.

Transmission layer

This layer is responsible for the connection between two directly connected nodes. It has no knowledge of the global state and lives directly above the choosen transport layer. It deals with the different types of packets.

Permanent type receiver

Packet types

There are a few different types of packets, to make sure it arrives at the right spot.

  • Send
  • Ack

The send packet is used to transmit a packet directly between two nodes. The ack packet is used to acknowledge the receiving of the packed, identified by the sequence ID. If the ack packet is not received after a certain timeout the sender should resend the packet. If after x amount of tries it still does not respond the node should be marked as failed. The packet should be rerouted trough a different node if possible, if not drop the packet. A higher layer will do a retransmittion of the packet starting from the source.

Packet format

This section describes the format of packets to be send over the network. It does not specify the format of the content of the packets, but the metadata of the packets. This metadata is used in routing the packets around.

It contains the following parts:

  • magic byte (4 byte, 0x20f57c03)
  • sequence ID (2 bit)
  • reserved (3 bit)
  • data length (2 byte)
  • data (x byte)
  • signature (8 byte, ED25519)


| 4 bytes    | 4 bits  | 4 bits |
| Magic byte | Flags   | TTL    |

Magic byte

This magic byte is four bytes long, always set to 0x20f57c03. Any packet which don't start with this magic byte can safely be ignored, as this would be a different protocol. It is added to makes sure you are dealing with an IPv8 packet, instead of something else (non-malicious).


The first meaningfull part of a packet are the flags. Flags are a single bit datatype where 1 equals true and 0 equals false. These flags help with parsing the packet, as not all packet have the same format. In total there are 4 flags, but not all of them are in use. Flags are processed as they come in, so the left most flag is flag 0.

| Flag ID | Name                    |
| ------- | ----------------------- |
| 0       | Real time               |
| 1       | Reserved for futher use |
| 2       | Reserved for futher use |
| 3       | Reserved for futher use |

Real time

If the packet is real time

Underlying transport

While UDP is recommended for this network, it is not limited to it. If you want you can also use other transport protocols like TCP, TLS, WS and any other type of socket connection.


The verification layer is to make sure the message is send from where


Signed Lamport clock?


The routing layer is the first layer which is aware of nodes not directly attached. It makes use of the Pastry routing protocol, as defined in this page. This page defines the way the pastry routing is applied


Store-and-forward Permanent messages Expiration Route table rotation


Routing is done by the pastry. The paper for this is located here.

The rest of this page is to be done.


This layer makes it able to encrypt any traffic above this layer.



This layer is specific to the communities. It will route the communities and the messages.


communityid (2 byte) messageid (1 byte) Authenticated communities?

System community

This is the community responsibe for the general housekeeping of the network. It is responsible for the introduction requests and route discovery.