🏗 Network infrastructure


At its core, Session is built on the Oxen Service Node network, so it's important to understand how the Oxen network functions to support Session's mission of enabling decentralised anonymous communications.

The Oxen network

Many projects have attempted to establish decentralised permission-less networks. These projects have often found themselves struggling with a ‘tragedy of the commons’ of sorts, wherein public servers, required for the operation of the network, are under-resourced and overused. This inadvertently causes the network to provide poor service to users, which discourages further use or expansion of the network.

Conversely, those projects which are able to create large, public permissionless networks find themselves constantly facing questions about the parties that contribute to running that infrastructure. This can be especially damaging when the operation of that infrastructure can adversely affect the privacy, security, or user experience of an application. For example, the Tor network faces constant questions about evidence of Sybil attacks from unknown parties attempting to run large sections of of the public routing network, which could be used to de-anonymise users .

Session seeks to avoid these issues through using a different type of public access network: a staked routing and storage network called the Oxen Service Node network. This network is based on the Oxen blockchain, which itself is based on the CryptoNote protocol. Through the integration of a blockchain network, Session creates a financial precondition for anyone wishing to host a server on the network (and thus participate in Session’s message storage and routing architecture).

Authorisation for a server to operate on the network is attained through the server operator conducting a special staking transaction, which requires that an operator provably lock an amount of Oxen cryptocurrency assigned to their node (previously, this staking requirement was algorithmically adjusted over time; it is now fixed at 15,000 $OXEN).

This staking system provides a defense against Sybil attacks by limiting attackers based on the amount of financial resources they have available. The staking system also achieves two other goals which further reduce the likelihood of a Sybil attack.

Firstly, the need for attackers to buy or control $OXEN to run service nodes creates a feedback loop of increasing price for anyone attempting to run large portions of the network. That is, as the attacker buys or acquires more $OXEN and locks it, removing it from the circulating supply, the supply of Oxen is decreased and the demand from the attacker must be sustained. This causes the price of any remaining Oxen to increase, furthering the feedback loop of increasing prices. Secondly, the staking system binds an attacker to their stake, meaning if they are found to be performing active attacks, the underlying value of their stake can sharply decline as users lose trust in the network, or could be destroyed or locked by the network, in any case increasing the attackers sunken costs.

The other main advantage of a staked blockchain network is that service nodes earn rewards for the work they do. Service nodes are rewarded with a portion of the block reward minted upon the creation of each new block. This system makes Session distinct from altruistic networks like Tor and I2P by providing an incentive linked directly with the performance of a service node. Honest node behaviour and the provision of a minimum standard of operation is ensured through a consensus-based testing suite. Misbehaving nodes face the threat of having their staked capital locked, while the previously-mentioned cryptocurrency rewards function as the positive incentive for nodes to behave honestly and provide at least a minimum standard of service to the network.

Onion requests

The other foundational component of Session is an onion routing protocol, referred to as onion requests, which enables Session clients to obfuscate their IP addresses by creating a 3-hop randomised path through the Oxen Service Node network. Onion requests use a straightforward onion routing protocol which successively encrypts each request for each of the three hops, ensuring the first service node only knows the IP address of the client and the IP address of the middle service node, the middle service node only knows the IP address of the first and last service nodes, and the last service node only knows the IP address of the middle service node and the final destination IP address for the request.

Each Session client establishes a path on start-up, and once established, all requests for messages, attachments and meta information are sent through this path. Session clients establish a path by selecting three random nodes from their service node list (see bootstrapping), which contains each service node’s IP address, storage server port, and X25519 key. Clients use this information to create an onion, with each layer being encrypted with the X25519 key of its respective service node. This onion is sent to the first service node’s storage server; this service node then decrypts its layer of the onion. When a service node unwraps a layer, the destination key for the next node is revealed. The first service node decrypts its layer and initialises a ZMQ connection with the specified downstream node. When the onion reaches the final node in the path, that node sends a path build success message backwards through the path, which indicates a successful path built upon its receipt by the client.

Upon receiving the path build success message, the client will encrypt their messages with the X25519 keys of the final destination, be that a service node, file server, open group server, or client. The client also includes an ephemeral X25519 key in their request. When the destination server or client receives the request, they decrypt it and generate a response. This response is then sent back down the previously-established path, encrypted for the initial sender’s (the client’s) ephemeral key, so that the client can decrypt the response upon receiving it.

Building on foundations

Onion requests provide a straightforward anonymous networking layer, and the Oxen Service Node network provides an incentivised, self-regulating network of remote servers which provide bandwidth and storage space. A number of services have been built on this foundation in order to give Session features commonly expected of modern messaging applications.


Message storage is an essential feature for any chat application aiming to provide a good user experience. When a user sends a message, they expect the recipient to receive that message even if the recipient's device goes offline or is turned off after the message has been sent. Users also expect the user on the other end to receive the message when their device wakes up or reconnects from an offline state. Apps that run on decentralised networks typically cannot provide this experience, because of the lack of incentive structures and, consequently, the ephemeral nature of clients and servers on such a network. Session is able to provide message storage through the incentivised service node network and its usage of swarms.


Although the Oxen blockchain incentivises correct service node behaviour through rewards and punishments, these incentive models cannot prevent nodes going offline unexpectedly due to operator choice, software bugs, or data centre outages. Therefore, for redundancy, a secondary logical data storage layer must be built on top of the service node network to ensure reliable message storage and retrieval.

This secondary logical layer is created by replicating stored messages across small groupings of service nodes called swarms. The swarm a service node initially joins is determined at the time of that service node’s registration, with the service node having minimal influence over which swarm it joins. This protects against swarms being entirely made up of malicious or non-performant nodes, which is important to maintain the network’s self-regulating properties.

Composition of each swarm inevitably changes as the networks evolves: some nodes leave the network and the newly registered nodes take their place. If a swarm loses a large number of nodes it may additionally "steal" a node from some other, larger swarm. In the unlikely event that the network has no swarms to steal from (i.e., every swarm is at Nmin=5 nodes), the ‘starving’ swarm (a swarm with fewer than Nmin nodes) will be dissolved and its nodes will be redistributed among the remaining swarms. Conversely, when a large number of nodes enter the network that would oversaturate existing swarms (i.e., every swarm is already at max capacity Nmax=10), a new swarm is created from a random selection of Ntarget=7 excess nodes. Note that Nmin < Ntarget < Nmax to ensure that a newly generated swarm doesn’t get dissolved shortly after and that there is still room for growth.

The outcome of this algorithm is the creation and, when necessary, rebalancing of swarms of around Nmin⁠–Nmax service nodes which store and serve Session clients’ messages. The goal of the swarm algorithm is to ensure that no swarm is controlled by a single entity and that the network is resilient enough to handle both small and large scale events where service nodes are no longer contactable, ensuring data integrity and privacy in both cases.

The following set of simple rules ensure that service nodes within swarms remain synchronised as the composition of swarms changes:

When a node joins a new swarm, existing swarm members recognise this and push the swarm’s data records to the new member. When a node leaves a swarm, its existing records can be safely erased, with the exception of when the node is migrating from a dissolving swarm. In this case, the migrating node determines the swarms responsible for its records and distributes them accordingly.

Identity and long-term keys

The majority of popular messaging applications require the user to register with an email or phone number in order to use the service. This provides some advantages, including account verification, for purposes of spam protection, and social network discoverability. However, such requirements also create some major privacy and security issues for users.

The use of a phone number as the basis for ownership of an identity key/long-term key pair weakens security against user accounts being compromised, such as in the cases of popular applications like Signal and WhatsApp. This weakness primarily stems from the fact that phone numbers are managed by centralised service providers (i.e. telecommunications service providers) who can circumvent user control, allowing these providers to assume direct control of specific users’ numbers. Widespread legislation already exists to compel service providers to take this kind of action. Additionally, methods such as SIM swapping attacks, service provider hacking, and phone number recycling can all be exploited by lower-level actors .

Signal and Whatsapp put forward varying degrees of protection against these types of attacks. Signal and WhatsApp both send a 'Safety numbers have changed' warning to a user's contacts if identity keys are changed. In practice, however, users rarely verify these details out-of-band .

Both Signal and WhatsApp also allow users to set a "registration PIN lock" . This protection means that an attacker (including a service provider or state-level actor) needs access to both the phone number and the registration PIN code to modify identity keys. However, this feature is off by default, difficult to find in the settings menu, and automatically disabled after periods of user inactivity. These factors all significantly reduce the efficacy of registration PIN locks as a protective measure against the security risks of phone number-linked accounts.

Using phone numbers as the basis for account registration also greatly weakens the privacy achievable by an average user. In most countries, users must provide personally identifiable information such as a passport, drivers' license or identity card to obtain a phone number — permanently mapping users’ identities to their phone numbers. These identity mappings are kept in private databases that can be queried by governments or the service providers that own them. There are also a number of web scrapers and indexers that automatically scrape phone numbers associated with individuals. These scrapers may target sources such as leaked databases, public social media profiles, and business phone numbers to link people to their phone numbers. Since the only method of initiating contact with a user in Signal, WhatsApp, or similar application is to know the user’s phone number, this immediately strips away user anonymity — a significant concern for whistleblowers, activists, protestors and other such users.

Account systems based on phone numbers also limit the potential for the establishment of multiple identities by a single user. These systems also prevent high-risk users without access to a phone number from accessing these services.

Session does not use email addresses or phone numbers as the basis of its account system. Instead, user identity is established through the generation of X25519 public-private key pairs. These key pairs are not required to be linked with any other identifier, and new key pairs can be generated on-device in seconds. This means that each key pair (and thus, each account) is pseudonymous, unless intentionally linked with an individual identity by the user through out-of-band activity.


Because Session does not have a central server to keep records of user identities, the commonly expected user experience of being able to recover or log back into an account using a username and password is not possible. Instead, users are prompted to write down their long-term private key (represented as a mnemonic seed, referred to within Session as a recovery phrase) upon account generation. A user can use this backup key to recover their account if their device is lost or destroyed, and the user's contacts will be able to continue contacting that same user account, rather than having to re-initiate contact with a new key.