# Session Messenger Session is a cross-platform, end-to-end encrypted messaging app designed to provide secure, private, and anonymous communication. Session emphasizes user confidentiality and safety by eliminating the need for personal information during account creation and minimizing metadata during app usage. Built on the web3-powered Session Network, Session’s protocol offers advanced privacy features, such as onion-routing by default (protecting IP information), randomized alphanumeric IDs (instead of insecure phone numbers), and decentralized message storage (hardening against data leaks and censorship). In addition to providing privacy and security, Session is also designed to be a full-featured modern messaging app: * Cross platform support (*Android, iOS, Windows, Mac, Linux*) * Localization support in over 70 languages and dialects * User configurable privacy settings, such as disappearing messages and read receipts; * User-first, joy-sparking features, such as emoji reactions * P2P voice and video call * **SOON:** onion-routed voice and video calls using the novel Lokinet protocol * Support for end-to-end encrypted file attachments, including videos, pdfs, and voice recordings * Truly decentralized offline message delivery using swarms in the Session Network * Self-managed keys (generated and stored on-device only), eliminating the trust-on-first-use dilemma * **IN DEV:** [Session Protocol V2](https://getsession.org/blog/session-protocol-v2), adding support for post-quantum cryptography, re-implementing Perfect Forward Secrecy (PFS), and more secure multi-device account management Session is the result of years of open-source development and the dedication of a diverse community of contributors and node operators. ### Get started | [Installing Session](/readme/installing-session) | [Learn about Session Token (SESH)](/session-token-sesh) | | ------------------------------------------------- | ------------------------------------------------------------------ | | [How the Session Network works](/session-network) | [Contributing to Session](/readme/contribute-to-session-messenger) | ### More Resources | [GitHub](https://github.com/session-foundation) | [Whitepaper](https://arxiv.org/pdf/2002.04609) | | -------------------------------------------------- | ------------------------------------------------- | | [Support](https://sessionapp.zendesk.com/hc/en-us) | [Litepaper](https://getsession.org/litepaper/pdf) | # Installing Session You can download Session for free from your app marketplace of choice. Session is completely free to use and available on all major platforms. ### How to install Session on iOS 1. Download Session for free from the [Apple App Store](https://apps.apple.com/us/app/session-private-messenger/id1470168868) 2. Tap the Session app icon in your App Library or Home Screen 3. Read the Terms of Service and Privacy Policy 4. Tap the Create Account on the start-up screen 5. Enter a Display Name and tap Continue 6. Select your preferred notification settings and tap Continue 7. You have successfully installed Session and created your account. Next try messaging a friend, setting your Display Picture, or backing up your Recovery Password! {% hint style="info" %} Want to side-load the app? Use [this page](https://support.apple.com/en-mk/117767) for information about side-loading IPA. {% endhint %} ### How to install Session on Android 1. Download Session for free from the [Google Play Store](https://play.google.com/store/apps/details?id=network.loki.messenger). You may also download the app packages directly from [GitHub](https://github.com/oxen-io/session-android/releases) (see Installing Session using APKs). 2. Tap the Session app icon in your App Drawer or Home Screen 3. Read the Terms of Service and Privacy Policy 4. Tap the Create Account on the start-up screen 5. Enter a Display Name and tap Continue 6. Select your preferred notification settings and tap Continue 7. You have successfully installed Session and created your account. Next try messaging a friend, setting your Display Picture, or backing up your Recovery Password! # Installing on Linux (Debian based distros) Open a terminal and run the following commands 1. Add the Oxen GPG key using ``` sudo curl -so /etc/apt/trusted.gpg.d/oxen.gpg https://deb.oxen.io/pub.gpg ``` 2. Add repository list ``` echo "deb https://deb.oxen.io $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/oxen.list ``` 3. Update repositories ``` sudo apt update ``` 4. Install Session ``` sudo apt install session-desktop ``` ### Updating Session If you want to update Session, you can run the following commands: ``` sudo apt update ``` then, ``` sudo apt upgrade ``` # Installing Session using F-Droid F-Droid is an alternative to the Google Play Store which specializes in free and open-source software. To install Session using F-Droid: 1. Download and install F-Droid using their official website 2. On your device with F-Droid installed, visit Session’s official F-Droid repository, [here](https://fdroid.getsession.org/) 3. Open the F-Droid Settings menu 4. Select Repositories 5. Tap the ‘+’ icon to add the Session repository 6. Paste the Session repository URL * [ https://fdroid.getsession.org/fdroid/repo](< https://fdroid.getsession.org/fdroid/repo>) 7. Paste the fingerprint (available from the repository URL) 8. Add the repository to F-Droid, Session will now appear in your F-Droid Store 9. Install Session using the F-Droid app
# Installing Session using APKs Android app package file (APK or .apk) is a file format used to install applications on Android devices. Session APKs are made publicly available so that users may install the apk file(s) directly to their Android device without the use of an app store (such as the Google Play Store).
1. Open Settings and tap Apps 2. Tap Special access 3. Tap Install unknown apps 4. Tap Chrome (or whichever web browser you are using) 5. Toggle Allow from this source 6. Open Chrome (or your other browser) and navigate to the Session Android releases on [GitHub](https://github.com/session-foundation/session-android/releases) 7. Download and install the relevant APK (the “universal” APK should work for most devices) {% hint style="warning" %} **Warning:** Only download APKs from trusted, official sources. It is not recommended to download or install using unofficial or unverified APKs. Note that when loading your own APK, you will not receive automatic updates. {% endhint %} # Installing beta versions of Session Beta versions of Session allow users to test new versions and features before they are rolled out to all Session users. Public beta versions of Session are available on iOS, Android, and Desktop (Windows, Mac, Linux). ### How to join the Session beta branch on iOS 1. Install TestFlight on your device 2. Opt-in to Testing through the TestFlight beta release[ here](https://testflight.apple.com/join/EB9BcELO) 3. Tap Install or Update Warning: Beta versions are experimental and may be unstable. It is not possible to downgrade versions to an older official version. If you encounter issues with the beta version, you may be required to wait for the next official release or re-install Session and restore using your recovery phrase. Restoring will result in the loss of message contents older than 14 days. ### How to join the Session beta branch on Android 1. Install Session using the [Google Play Store](https://play.google.com/store/apps/details?id=network.loki.messenger\&hl=en_AU\&gl=US\&pli=1) (see How to install Session on Android for further instructions) 2. Navigate under “Join the beta,” tap Join and then follow the prompts You can also join from t[his web page](https://play.google.com/apps/testing/network.loki.messenger) if you are signed into your Google account in your browser. Note: if ‘Join the beta’ section does not appear, try restarting the Play Store app on your device or Download and install any available pre-release APK[ here](https://getsession.org/apk). Warning: Beta versions are experimental and may be unstable. It is not possible to downgrade versions to an older official version. If you encounter issues with the beta version, you may be required to wait for the next official release or re-install Session and restore using your recovery phrase. Restoring will result in the loss of message contents older than 14 days. ### How to join the Session beta branch on Desktop (Windows, Mac, Linux) To join the beta on desktop, simply download the relevant executable file from the pre-release [here](https://github.com/session-foundation/session-desktop/releases) and install as per normal (see [How to install Session on Desktop (Windows, Mac, Linux](/readme/installing-session#how-to-install-session-on-desktop-windows-mac-linux-appimage)) Warning: Beta versions are experimental and may be unstable. It is not possible to downgrade versions to an older official version. If you encounter issues with the beta version, you may be required to wait for the next official release or re-install Session and restore using your recovery phrase. Restoring will result in the loss of message contents older than 14 days. # Advanced Features The Session ecosystem’s advanced features give users access to new and powerful functions. Activating or accessing these features may require the use of Session Token (such as for the Session Name Service), or technical understanding of how to operate a server (to set up a Community). Read more about these planned and implemented advanced features in the pages under this section.
CommunitiesLarge-scale chats that can host hundreds or thousands of users at a time./pages/ebrD5DEd845X50dAvYoC
Session Name Service (SNS)Add contacts and find friends easily using Session Names./pages/jerXGuQWaeMvJNgbtnuO
Session ProA suite of premium features for Session messenger, unlocked with Session Token./pages/prGCuLTIR0UwocbjvgSl
# Communities Communities are large-scale chats that can host hundreds or thousands of users at a time. Each community runs on an individual community-operated server, called a Session Open Group Server (SOGS). By storing messages on specialized SOGS (instead of on the Session Network), Communities are able to efficiently process chats with very large numbers of participants. Communities are commonly used to host conversations relating to specific interests or theme. Although anyone can download and run the SOGS software, some technical expertise and resources are required to run your own server and set-up your own Community.
How to setup a Session Open Group Server (SOGS)/pages/4jPhAGpNnzCNJdZKyxVO
Creating a read-only channel using SOGS/pages/M6U3malJkGt6eW7oyCfp
# How to setup a Session Open Group Server (SOGS) Communities are hosted using[ PySOGS](https://github.com/oxen-io/session-pysogs). Written in Python, PySOGS is the reference implementation of a Session Open Group Server. Below you can find a video guide walking you through the process of setting up a Session open group server, as well as a written guide. Note: Session open group servers provide transit encryption, but open group messages are not encrypted while stored on the server; closed groups (which can be created within Session itself) are a better solution for high-security communications with groups of 100 or less people. Note: .debs for the Session Open Group server are currently available for Ubuntu 20.04 and newer, and for Debian 10 and newer. For other operating systems, you can[ build from source](https://github.com/oxen-io/session-pysogs/blob/dev/install-uwsgi.md) ### Video Guide {% embed url="" %} ### Installation Guide 1. **Find suitable server to run SOGS** Typically, the simplest and cheapest way to host a server is by leasing a Virtual Private Server (VPS). There are hundreds of VPS providers to choose from. You can run a SOGS from home, but consider most consumer internet connections have poor upstream bandwidth, typically don't provide a static IP address, and transient power and network outages are relatively common. For this reason, operating SOGS from home is only recommended for experienced users. Otherwise, these factors may affect the stability of your SOGS and the ability for users to chat in your group. Resource requirements are highly dependent on how many users you plan to support in your open groups and how frequent usage is, however, a good starting point is: * 1 Virtual core * 512 MB of RAM * 20GB HDD space Once you have signed up for a provider you should receive a static IP address, you will need to SSH into your server, you can find instructions on how to do this online. **2. Add Oxen apt repository** Add the Oxen apt repository by running the following commands: ``` sudo curl -so /etc/apt/trusted.gpg.d/oxen.gpg https://deb.oxen.io/pub.gpg echo "deb https://deb.oxen.io $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/oxen.list sudo apt update ``` **3. Install** You have a choice to install either the sogs-standalone package or the sogs-proxied package. **sogs-standalone** This is the simple SOGS package for most setups. It installs a SOGS that listens on a public IP/port for HTTP connections. It does not support HTTPS connections (but since all messages to/from SOGS are separately encrypted, HTTPS is not necessary nor recommended). **sogs-proxied** This package provides a more advanced SOGS configuration where SOGS itself will listen on an internal port and expects to have requests proxied to it from an ngnix or apache2 front-end server that listens on the public IP/port. The package will install basic site configuration files for either nginx or apache2, but extra configuration may be necessary. This package is required if you want your SOGS to be reached over HTTPS: the HTTPS handling is configured on the front-end server (i.e. in nginx or apache) using a tool such as `certbot`. (This package does not auto-configure such HTTPS certificates, but there are many online help pages on setting up such HTTPS support for a front-end web server). If you don't know what any of this means then stick with the `sogs-standalone` package. ``` sudo apt install sogs-standalone ``` or ``` sudo apt install sogs-proxied ``` If installing the standalone version you will see this prompt, asking you to enter a URL or IP address, if you have not set up DNS to point towards the IP address of your VPS then you should enter your VPS Public IP address, which can usually be found on your VPS provider's website.
**4. Add a room** Once finished with installation, you will want to add a room, to add a room run this command: ``` sogs --add-room TOKEN --name "NAME" --description "DESCRIPTION" ``` Replace `TOKEN` with the address to use in the room URL (which must consist of **ONLY** lowercase letters, numbers, underscores, or dashes), replace `NAME` with the room name to display in Session and optionally replace `DESCRIPTION` with a short description of the topic of the room. ``` sogs --add-room fish --name "Fishing" --description "Australian fisheries chat" ``` As an example, setting up a room for discussion of Australian fisheries. **5. Make yourself an administrator** Make yourself a global administrator for all rooms hosted on your SOGS by running the following: ``` sogs --rooms + --add-moderators ACCOUNTID --admin --visible ``` Replace `SESSIONID` with the Account ID you want to be an administrator. For **example**: ``` sogs --rooms + --add-moderators 05d871fc80ca007eed9b2f4df72853e2a2d5465a92fcb1889fb5c84aa2833b3b40 --admin --visible ``` **6. Join your SOGS** Once setup, you should be able to navigate to your VPS's IP address in a web browser, for example[ http://116.203.70.33/](http://116.203.70.33/) Here you should see a list of your rooms, clicking on a room will display a QR code and the link required to join the room, this link can be copied and pasted into a Session client to join a group. ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXco-n7zdlhxDPO05owXM8SngrTlSp88uQmClZFz_SVY2zn0lbwUdliuPnq0CDmAq20oTl5datD10MxjE10d3nzxiZdz9C1asFc-pBTbgnWwkpsjbNv_ei1j0FQp5KVisM289a5uFA?key=xYdGRJlEQzKxaTAE3YIf52CQ) ### Upgrading SOGS SOGS is configured as a Debian package, it will be updated when you update and upgrade other packages on your system, you can trigger this process by running the following commands: ``` sudo apt update sudo apt upgrade ``` ### Having Issues? If you're having trouble setting up your SOGS, we recommend opening an issue on the [Session Open Group Server GitHub repository](https://github.com/session-foundation/session-pysogs). Contributors to the PySOGS software should be able to assist you in getting everything up and running. # Creating a read-only channel using SOGS Some SOGS operators may want to set up a room on their SOGS which features one way style communication; these rooms allow moderators and administrators to update the room with new messages, but disallows unprivileged users to send new messages. These sorts of rooms can be useful for providing updates or information. #### 1. Create a new room ``` sogs --add-room TOKEN --name "NAME" --description "DESCRIPTION" ``` {% hint style="success" %} Skip to step 3 if you already have a room and you are an administrator in that room {% endhint %} Replace `TOKEN` with the address to use in the room URL (which must consist of **ONLY** lowercase letters, numbers, underscores, or dashes), replace `NAME` with the room name to display in Session and optionally replace `DESCRIPTION` with a short description of the topic of the room. #### 2. Ensure you are an administrator of the room ``` sogs --room TOKEN --admin --add-moderator ACCOUNTID ``` Replacing `TOKEN` with the room token you created in step 1, and replacing `ACCOUNTID` with your own Account ID. #### 3. Alter room permissions There are 4 types of permission currently available in rooms * r = Read (ability to read messages) * w = Write (ability to write new messages) * u = Upload (ability to upload attachments, including files, voice notes, images and videos) * a = Access (ability to join the room) When modifying these permissions changes will only apply to non admins/moderators, the default permissions in a room will be "rwua" for all users To create a read only group we want to remove regular users ability to write and upload attachments, we can do this using the following command: ``` sogs --add-perms ra --remove-perms wu --room TOKEN ``` This command will ensure read and access permissions are provided and remove write and upload permissions for regular users. As the permission changes do not affect administrators and moderators, they will still be able to read, write and upload to the group. New Account ID's can be given write/upload access by making those Account ID's moderator or admin, this can be done directly in the Session Desktop client or via the[ CLI](https://github.com/oxen-io/session-pysogs/blob/dev/administration.md). # Session Names and the Session Name Service (SNS) {% hint style="info" %} **Note:** SNS has not yet been deployed in the Session Token ecosystem. {% endhint %} The Session Name Service (SNS) is a distributed, open, and extensible naming system used in the Session Ecosystem. SNS will be used to translate Session Account IDs (long, alphanumeric codes) into human-readable labels, called Session Names. Session Names are one-of-a-kind and easy to share, making it simpler to connect with other people on Session. ### How the Session Name Service (SNS) works The Session Name Service allows users to register records mapping information, such as an Account ID, to a human-readable label. These mappings are stored and maintained on-chain, operated using a series of smart contracts, making SNS a secure and decentralized naming solution for Session. ### Session Name Records When a Session Name is registered, a record containing a name, an Account ID (Session public key) and a wallet address is submitted. For example, a record may contain the following information: | **Name** | `SessionFan` | | ---------------------- | -------------------------------------------------------------------- | | **Session Account ID** | `053b6b764388cd6c4d38ae0b3e7492a8ecf0076e270c013bb5693d973045f45254` | | **Wallet address** | `0x31c319A6621d7e08557391A117B7d0a26C63Fc84` | In the future, these records could also contain other information. ### Session Name Resolvers Because Session Nodes track on-chain registration of Session Names, they are able to act as Resolvers for the Session Name Service (SNS). Session clients are able to query a random set of Session Nodes, which then resolve the queried name to a Session Account ID. In this case, multiple nodes are queried (ensuring they return the same ID) to prevent a single dishonest node compromising name resolution. For example, when sending a new message on Session, entering `SessionFan` prompts the client to query Session Nodes, which then retrieve the corresponding **Account ID**. This allows you to add the recipient using their readable name (`SessionFan`), rather than manually entering their Account ID. # Registering an Oxen Name using the Oxen Name Service {% hint style="info" %} **Note:** Users with Oxen Name records from the Oxen Name Service will be able to claim the corresponding Session Name for a period of time. {% endhint %} The following steps can be used to register and update ONS mappings in the CLI wallet. Note that you can access a detailed description of each command within the app, using “help \”. ### Purchasing an Oxen Name System record Purchasing an ONS record in the CLI wallet uses the `ons_buy_mapping` command. All arguments for the `ons_buy_mapping` command are optional, except for the `` and `` that the name maps to. ``` ons_buy_mapping [index=[,,…]] [] [owner=] [backup_owner=] ``` **Example:** Buy an ONS record that maps ‘KeeJef’ to an Account ID: 053 … 254. The wallet buying is the owner of the record: ``` ons_buy_mapping KeeJef 053b6b764388cd6c4d38ae0b3e7492a8ecf0076e270c013bb5693d973045f45254 ``` **Example:** Buy an ONS record that maps ‘KeeJef’ to an Account ID: 053 … 254. The wallet buying the mapping is the owner of the record, but specifies a backup owner who will also be authorised to update the record: ``` ons_buy_mapping backup_owner=T6U7AaNgN2cARpR7CNHGChGMjsmjq5ffh4hLa4DjUUXtKS3bPy2rKTX614RxmpPPX6KjZzqUSSpAEcoghASTXqvP1qMsJzWch KeeJef 053b6b764388cd6c4d38ae0b3e7492a8ecf0076e270c013bb5693d973045f45254 ``` **Example:** Buy an ONS record that maps ‘KeeJef’ to an Account ID: 053…254. You buy on behalf of another wallet T6UD8...ppir and specify another backup wallet: ``` ons_buy_mapping owner=T6UD8TM1t7mUYmMCHXQ67Kg5jXBwoVxNqGpXctnsLXtGBEFnhq37RQAA8jgqgD9U6QbeNGqAkkVXucXQ5txE6Mrk2aRwpppir backup_owner=T6U7AaNgN2cARpR7CNHGChGMjsmjq5ffh4hLa4DjUUXtKS3bPy2rKTX614RxmpPPX6KjZzqUSSpAEcoghASTXqvP1qMsJzWch KeeJef 053b6b764388cd6c4d38ae0b3e7492a8ecf0076e270c013bb5693d973045f45254 ``` ### Updating an Oxen Name System record: Wallet executing update is owner of record Updating an ONS record in the CLI wallet uses the `ons_update_mapping` command. All arguments for the `ons_update_mapping` command are optional except the name of the record to update, and at least one field of the record to update (`owner`, `backup_owner`, or `value`). The \[`signature`] argument is for deferring updates to the record, and is explained in detail in the next section. ``` ons_update_mapping [owner=] [backup_owner=] [value=] [signature=] ``` **Example:** Updating the owner of the record (essentially transferring ownership — after changing ownership, you will no longer be authorized to update the record): ``` ons_update_mapping owner=T6UC1nSy2289uX8R2jS3ci7y6eNnVdvhSQRoZtckPzmrQgJ3CyUhUtxgxuedusx9TCKVhZZBCuwFkKoJ3joXStWh1QozRsXXo KeeJef ``` {% hint style="info" %} **Note:** At this time you can only update Account ID mappings, you cannot yet add a wallet address mapping to your name — this will require additional changes which will be implemented at a later date. {% endhint %} **Example:** Update all fields of the mapping. ``` ons_update_mapping owner=T6UD8TM1t7mUYmMCHXQ67Kg5jXBwoVxNqGpXctnsLXtGBEFnhq37RQAA8jgqgD9U6QbeNGqAkkVXucXQ5txE6Mrk2aRwpppir backup_owner=T6TEJJRfvhMZbJpRuchJtmQAjuyCUAyYy2yVcc9ySxTHXWgwQkupjUJUQsyCoyYfRGReAY3pgaYxUHwoKEkWNh5o2qe5Btt3x value=0596d2fdc1407490e1bb7cbca3f3674606d3ef9b1d01cf46199ee5c8932d83f40a KeeJef ``` ### Updating an Oxen Name System Record: Wallet executing is not owner of record) In this scenario, you have an ONS record that you wish to update, and you’re able to coordinate with the wallet owning the record. The wallet that owns the record can execute this command to generate a signature. ``` ons_make_update_mapping_signature [owner=] [backup_owner=] [value=] ``` **Example:** User transfers ownership of a record to another person T6TEJ…t3x with the value 058c…c08. The original owner generates a signature. ``` ons_make_update_mapping_signature owner=T6TEJJRfvhMZbJpRuchJtmQAjuyCUAyYy2yVcc9ySxTHXWgwQkupjUJUQsyCoyYfRGReAY3pgaYxUHwoKEkWNh5o2qe5Btt3x value=058c72182ecf25172999414f098f91c07bcf12eae7e0c810659f533e81dc865c08 KeeJef ``` **The generated signature:** ``` 3ede65e0a78eca500549dde612d02d8aeb3f3dd0f3accd767a2f013cab6e3d486582506fbeb7edb1bda209b333fe7f125fd29f6add6c72b20af320de3537788885fee8b6d76f14b4ad253db2f70a518054bb6f512465e1b6cc154c551d3d59b5bf528eef5a678dbee48e2da74a2803c47295acd6967ea5545f6213456a0f5ead ``` On the wallet to execute, the arguments must match the arguments specified in the `ons_make_update_mapping_signature` with the added signature argument: ``` ons_update_mapping owner=T6TEJJRfvhMZbJpRuchJtmQAjuyCUAyYy2yVcc9ySxTHXWgwQkupjUJUQsyCoyYfRGReAY3pgaYxUHwoKEkWNh5o2qe5Btt3x ``` ### Transferring Oxen Names to Session Names Although it is planned for owners of Oxen Names to be able to claim the corresponding Session Name for a period of time, details for transferring Oxen Names to Session Names have not yet been finalized. # Session Pro Session Pro is a service offering advanced features to power users of Session. \ \ A beta version of Pro will be released first as an MVP. The initial feature set for Session Pro Beta is yet to be announced, but will be focused on additional convenience features for users, allowing them to better organize their messages on Session, exceed limits placed on free users and offer more opportunities to customize how they appear to other users in the app. \ \ Planned features for the full version of Session Pro include, but are not limited to: * Increased file transfer limits * Account Profiles * Badges Many of these are intensive features requiring additional storage and computational resources from the Session Network.

A UI mock-up of the Session Pro 'flair'. This is a preliminary mock-up and not indicative of the final product.

Therefore, it would not be sustainable for the network to offer these features for free to all users (seeing as Session does not store, collect, or monetize user data in any way); however, they can be unlocked for a fee. Thus, Pro features are unlocked by paying Session Network Fees. While additional Session Pro features are in discovery, it is important to note that security and privacy features as well as existing Session features will remain freely provided. ### Fees Session Network Fees are paid by burning Session Tokens. These Session Tokens, minus transaction fees, are then re-minted into the Staking Reward Pool, sustaining the network for its work storing and validating information. ### Oracle pricing End users expect Session Pro to have: * A consistent cost * A cost denominated in either their local fiat currency or a major fiat currency To facilitate this, Session Network Fees are dynamically calculated using on-chain oracles. Although Session Network Fees must always be paid in Session Token (SESH), the actual amount of tokens required to unlock Session Pro varies such that the ‘dollar cost’ remains stable. All Session Pro unlocks require Network Fees to be paid in Session Token(s). However, additional third party payment gateways will be available, allowing users to purchase Session Pro with fiat or crypto, which will then be converted to Session Tokens and deposited into the pool on behalf of the user. ### Payment gateways Session Token is always required to unlock Session Pro features. However, other payment options can be offered through use of swapping systems and services. For ease of use, users at point of sale can purchase Session Pro using fiat in-app payment gateways (such as through Google Play and the App Store), or using cryptocurrencies other than Session Token. These will then be swapped into Session Token, which is used natively to pay Session Network Fees and unlock Session Pro. These services will require third-party management of your access to Session Pro, although users may always manage Session Pro using their own Session Tokens, wallet, and Session application. # Contribute to Session Messenger Session is an ecosystem with a diverse group of contributors working on research, development, and education. Whether it is submitting bug reports or writing code, you can help people reclaim their privacy with Session. Your contributions, big or small, will reach millions of users worldwide. The community working on Session is decentralized—just like the Session Network. Find out more about how you can join in.
Contribute to development/pages/QZSnoHZJMMOTlT6s41SO
Contribute to localization/pages/YAW8vY0jEBDbSGZBIgky
# Development All of Session’s code is completely open source and available on GitHub. Several key Session repositories are managed by the Session Technology Foundation as part of its role as steward. You can find these repositories [here](https://github.com/session-foundation). All you need to start contributing is a GitHub account and some development knowledge. ### Contributing to development of Session iOS Session’s iOS client is written using Swift. If you are familiar with Swift, then you can likely contribute to Session on iOS. You can find a list of known issues and feature requests [here](https://github.com/session-foundation/session-ios/issues). Many of these issues contain tags and comments to help you find an issue that suits your skills and experience level. ### Contributing to development Session Android Session’s Android client is predominantly written using Kotlin and to a lesser degree Java. If you are familiar with Kotlin, then you can likely contribute to Session on Android. You can find a list of known issues and feature requests [here](https://github.com/session-foundation/session-android/issues). Many of these issues contain tags and comments to help you find an issue that suits your skills and experience level. ### Contributing to development Session Desktop Session’s Desktop client is predominantly written using TypeScript. If you are familiar with TypeScript, then you can likely contribute to Session on Desktop. You can find a list of known issues and feature requests [here](https://github.com/session-foundation/session-desktop/issues). Many of these issues contain tags and comments to help you find an issue that suits your skills and experience level. ### Contributing development to other parts of the Session ecosystem Other parts of Session’s ecosystem, such as the [docs](https://github.com/session-foundation/session-docs), [websites](https://github.com/session-foundation/session-website), and Node software (which handles Session’s backend) can be accessed and contributed to on GitHub. However, note that the documentation for issues and requests is not rigorous, so it may be difficult to find areas of work in need of contribution. ### Reporting bugs from Session Bugs can be submitted through Session’s helpdesk portal [here](https://sessionapp.zendesk.com/hc/en-us/requests/new) or via the issues section in the relevant GitHub repository ([iOS](https://github.com/session-foundation/session-ios/issues) | [Android](https://github.com/session-foundation/session-android/issues) | [Desktop](https://github.com/session-foundation/session-desktop/issues)). The form will ask for some details about the issue you are encountering, the version of Session you are using, and your device. Additionally, you can attach your logs to give developer contributors more useful information when they investigate the issue. {% hint style="info" %} To export your logs, go to Session’s in-app settings, go to ***Help***, then ***Export Logs***. {% endhint %} {% embed url="" %} # Localization Localization takes place using Crowdin, a community-driven translation platform. You’ll need to [register a free Crowdin](https://accounts.crowdin.com/register) account to participate. After you’ve registered an account, you can [find the Crowdin page for Session here](https://getsession.org/translate). From the dashboard you can search for the language you wish to help translate:
{% hint style="info" %} ***Note:** Because the starting point is a machine translation, Crowdin will display 100% or similar completion for all languages. Many of the strings **will still require review and translation, regardless of whether it is indicated that the translation is complete.*** {% endhint %} Once you’ve located the language you wish to help translate, click on it, then click on the ellipses (…) menu on the right side of the page:
Click on the ‘Editor View’ button at the top right of your screen, then click ‘Comfortable’
On this page you will see the list of all strings and phrases used in Session. At this stage, all of Session's strings are approved, but there is still important work to be done! You can make a big difference to the quality of a localization by reviewing it for errors. In the middle of the screen, you’ll see the Source String at the top. This is the English phrase that is being used in the app.
#### \ \
\ These are used for formatting, making something bold, or adding a line break etc. When you’re translating, just read the sentence as if they’re not there, but please include them in or around the relevant sections of the phrase. In the example above the section mentioning “You” in your translated string should open with `` and close with ``. If you see `
` `
`, please try to include that at the same point in the phrase. #### Curly Brackets { } Anything in curly brackets should not be translated, as these are dynamic strings that will automatically adopt the right contents in the app. In the example above, `{count}` becomes the amount of other users who were invited to join the group. #### Context The Context section provides additional information about how the phrase is being used in the app. In this case, the phrase “You and {count} others were invited to join the group” shows as a control message in group conversations, which displays a user who was invited to join the group at the same time as several others. #### Translating Under the Context section, you’ll see a text box with “Enter translation here” and this is where you’ll write the translation in your chosen language for the English phrase “You and {count} others were invited to join the group.” Once you’ve added that, just hit the save button, and select the next string from the list on the left. # Session Token (SESH) Session Token is an EVM-compatible token utilised in the Session ecosystem to unlock premium features in Session messenger and as a security and incentivization layer for Session Nodes. It is the core of the Session ecosystem, enabling the decentralized network that powers Session messenger. Session Token offers a new model for bootstrapping and growing a communications overlay network which prioritizes user privacy while remaining sustainable. ### What can I do with Session Token (SESH)? As the native cryptocurrency of the Session ecosystem, Session Token can be used to stake to Session Nodes, reward nodes for validating transactions and storage for Session messenger, and unlock, access, or interact with advanced features within Session messenger (such as Session Pro unlocks and Session Names).

Session Token at a glance

*** ### Get started | | | | | | ------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- | | [Session Token FAQs](https://token.getsession.org/faq) | [Session Token Tokenomics](/session-token-sesh/tokenomics) | [Rewards Programs](/session-token-sesh/rewards-programs) | [Get Session Token (SESH)](/session-token-sesh/get-session-token-sesh) | ### Contract Addresses SESH Token Contract on Ethereum and Arbitrum One:\ 0x10Ea9E5303670331Bdddfa66A4cEA47dae4fcF3b Session Node Rewards Contract:\ 0xC2B9fC251aC068763EbDfdecc792E3352E351c00 Reward Rate Pool Contract:\ 0x11f040E89dFAbBA9070FFE6145E914AC68DbFea0 Service Node Contribution Factory Contract:\ 0x8129bE2D5eF7ACd39483C19F28DE86b7EF19DBCA
# Tokenomics The maximum supply of Session Token is 240,000,000. At token genesis, the circulating supply was 79,000,000 Session Tokens. Session Token is a utility token intended to be used within the Session application and for Session Network purposes. This page provides a summary of Session's tokenomic principles. Head to [**Genesis Tokenomics**](/session-token-sesh/tokenomics/genesis-tokenomics) to learn more about the supply, lockups, and overall tokenomics at TGE. ### Token Flow When Session Token is utilized to unlock advanced features ([Session Pro](/readme/advanced-features/session-pro), [Session Names](/readme/advanced-features/session-names-and-the-session-name-service-sns)) or for network security (staking), Session Tokens flow out of circulation. When Session Token is utilised for incentivization (network rewards), Session Tokens flow into circulation. Session Token’s tokenomic system is designed to create flow conditions such that: * Session Token is effective for use in-app by millions of users; * Session Token is viable to stake for node operators and contributors; * Session Token is an effective incentive for good, honest node behaviour.
### Session Network Fees When a user unlocks access to Session Pro, registers a Session Name, or uses other advanced features, they pay Network Fees in Session Tokens (SESH). These dynamic fees are designed to compensate the network for the additional validation and storage required to facilitate these features. Network Fees are burnt and reminted back to the ecosystem. 90% of fees are reminted into the[ Staking Reward Pool](https://docs.getsession.org/staking-reward-pool), directly rewarding Session Nodes in the network for their validation and storage.
The remaining 10% becomes protocol-owned liquidity to ensure market liquidity and scalability.
Initially, this 10% will be deployed to a Uniswap pool. This will continue for a minimum period of 5 years from TGE. This scheme will be reviewed after a 5 year period to ensure its efficacy, in case of emergency (e.g. *Uniswap security breach*), these funds would be able to be removed and/or reallocated to other liquidity provisions. ### Staking Reward Pool The Staking Reward Pool is the ecosystem’s core mechanism for providing incentives to the network (Session Node operators and contributors). Tokens in the pool are time-locked in a smart contract and released at a targeted rate of 14% per year. The tokens released are awarded to active and registered nodes in the Session Network. At TGE, the Staking Reward Pool had 63,177,550 Session Tokens. #### Dynamic rewards As the Staking Reward Pool releases tokens using a percentage rate (rather than an absolute rate), real rewards vary based on the amount of tokens in the pool. If the amount of tokens in the pool increases, the real rewards (in SESH) returned to active network participants also increase. Similarly, if the amount of tokens in the pool decreases, the real rewards (in SESH terms) given to the network also decrease. The network’s reward is equally shared by all registered and active nodes, so the amount of real rewards (in SESH) an individual node receives also depends on the size of the network. The equation for calculating the reward for any node on a given day is as follows: $$ \dfrac{0.151(Staking Reward Pool)}{365 \times Network Size} $$ {% hint style="info" %} For more information about the Staking Reward Pool, check out the [Staking Reward Pool page](/session-network/staking/staking-reward-pool) {% endhint %} # Genesis tokenomics A total of 79,000,000 Session Tokens were circulating at TGE Session Token has a maximum supply of 240,000,000. \ **79 million**** Session Tokens were unlocked at TGE.** * 6 million for Project Treasury * 13 million for the Ecosystem and Community Fund * 60 million from [Session Token Swap Program](https://token.getsession.org/blog/session-token-swap-program) *** The remaining 161,000,000 are subject to varying lockup conditions. #### Lockup Conditions
Lockup A: Staking Enabled Tokens are time-locked using a smart contract for 24 months following TGE. Tokens in this smart contract can be staked for participation in the Session Node Network. Rewards earned through staking are immediately accessible.
Lockup B: Linear Tokens are time-locked using a smart contract for 24 months following TGE. Tokens in this smart contract cannot be staked. 12 months following TGE, a 12 month linear unlock begins at a rate of 8.33% claimable per month.
Lockup C: Unlocked Tokens are distributed at TGE with no associated lockups or restrictions.
Lockup D: Long-term Commit Tokens are time-locked using a smart contract for 3 years following TGE. Tokens in this smart contract cannot be staked. 12 months following TGE, a 24 month linear unlock begins (at a rate of 4.16% claimable per month). When these tokens are allocated to any Session contributor, there are performance and operational requirements which must be met before tokens are received.
Lockup E: Staking Reward Pool Tokens are locked in a smart contract and released at a rate of 14% per year (recalculated per block). The rate of 14% is calculated relative to the total amount of Session Tokens in the Staking Reward Pool, and new Session Tokens may be added to the pool.
Lockup F: Short-term Staking Enabled Tokens are time-locked using a smart contract for 90 days following TGE. Tokens in this smart contract can be staked for participation in the Session Node Network. Rewards earned through staking are immediately accessible.
**The following table describes which tokens (total 240,000,000) are subject to which lockup condition:**
CategorySession TokensLockup ConditionDescription
Oxen Coin Claims30,000,000CTokens reserved for those who participate in the Oxen Coin Claims program.
Service Node Bonus30,000,000CTokens earned by Oxen Service Nodes during the network transition period.
Project Treasury (Session Nodes) 15,000,000AThis allocation is held by the project alongside operational funds. It may only be used for operating up to 10% of the Session Node network. Public disclosure statements must be made if these tokens are used for any other reason. Rewards received from operating nodes do not remain locked.
Project Treasury (Session Contributors)11,000,000DThis allocation is used to reward existing and new Session contributors and demonstrate long-term commitment to the project. In total this is a conditional 3 year lockup term.
Project Treasury (Advisors)1,000,000BLocked for the first 12 months from TGE, then distributed evenly after the 12 month period. This is conditional, based on performance and contributions.
Project Treasury (Operational)33,000,000C: 6,000,000
D: 27,000,000		These tokens are for the operation of the project.
Ecosystem and Community Fund43,000,000B: 30,000,000
C: 13,000,000		These tokens are specifically to be used to strengthen the Session community and bolster the Session ecosystem over time.
Strategic Token Sale12,822,450A: 4,489,700
B: 8,332,750		This amount is reserved for sale before TGE to strategic parties which can help grow Session. Unsold tokens will be put into the Staking Reward Pool, Lockup E.
Staking Reward Pool63,177,550ETo reward Session Nodes for securing and providing services to the Session Network.
Testnet Incentive Program1,000,000FTo reward Testnet Incentive Program participants.
Additional Session Tokens will enter circulation over time as their lockup periods expire. However, Session Tokens will be locked in the [Staking Reward Pool ](/session-network/staking/staking-reward-pool)via mechanisms such as [Session Pro](/readme/advanced-features/session-pro) and removed from circulation via [staking](/session-network/session-nodes/staking-and-collateralization), making it is difficult to predict the future values for circulating supply. # Rewards Programs There have been several rewards programs designed to incentivize and encourage the community contributing to the Session ecosystem. Please remain cautious and vigilant in matters relating to rewards programs. Ensure that your information is sourced from known, reputable channels. Do not connect your wallet(s) to unknown websites or applications, do not send cryptocurrency to unknown addresses. If you are unsure, refer to the [Session Token Twitter/X](https://x.com/session_token) and the [Session Token Discord](https://discord.gg/sessiontoken) for assistance. # Service Node Bonus Program The Service Node Bonus Program rewarded existing Oxen Service Node operators and contributors for their contribution to the network and incentivizing the transition of the Oxen Service Node network to the new Session Network. **30,000,000 Session Tokens** were awarded to participating Oxen Service Nodes upon Session Token’s Token Generation Event (TGE). The Session Tokens available in this program represents 37.5% of the Genesis supply. You can read more about the genesis tokenomics[ here](https://docs.getsession.org/tokenomics/genesis-tokenomics). {% hint style="info" %} Along with the parallel Oxen Coin Claims Program (30,000,000 SESH allocated), these programs represent 75% of the maximum Genesis supply and 25% of the maximum supply of Session Token. {% endhint %} To ensure dedicated community members who have been staking long-term are sufficiently rewarded, snapshots have been captured since the 25th of September 2023. From this point onward, Oxen Service Node operators and contributors can start earning Staking Points. Staking Points are accrued relative to the amount of OXEN staked. Program participants will receive part of the 30,000,000 Session Tokens proportional to their Staking Points. Participation in the Service Node Bonus Program is now closed. You can check still your points via the leaderboard on the[ portal](https://swap.oxen.io/). {% hint style="info" %} Note: You can participate in both the Service Node Bonus Program ***and*** the Oxen Coin Claims Program if you choose to stake and swap OXEN you hold. Read more about the Oxen Coin Claims Program [here](/session-token-sesh/rewards-programs/oxen-coin-claims). {% endhint %} # Oxen Coin Claims The Oxen Coin Claims Program allows users to swap their unstaked Oxen coins for Session Token. **30,000,000 Session Tokens** are available through the Oxen Coin Claims Program. The Session Tokens available in this program represents 37.5% of the Genesis supply. You can read more about the genesis tokenomics[ here](https://docs.getsession.org/tokenomics/genesis-tokenomics). {% hint style="info" %} Along with the parallel Service Node Bonus Program (30,000,000 SESH allocated), these programs represent 75% of the maximum Genesis supply and 25% of the maximum supply of Session Token. {% endhint %} The amount of Session Tokens a user receives in their claim will be directly proportional to the amount circulating supply of Oxen. Oxen’s circulating supply will be snapshotted at Session Token’s TGE. This snapshotted supply will be used to calculate all claims, so claims will not change over time based on new Oxen emissions. The current supply of Oxen is available on the[ block explorer](https://oxen.observer/). For more information, visit the[ Oxen Coin Claims page](https://token.getsession.org/oxen-coin-claims). {% hint style="info" %} **Note:** You can participate in both the Service Node Bonus Program ***and*** the Oxen Coin Claims Program if you choose to stake and swap OXEN you hold. Read more about the Service Node Bonus Program [here](/session-token-sesh/rewards-programs/service-node-bonus-program). {% endhint %} # Testnet Incentive Program The Testnet Incentive Program ran from July 2024-May 2025 to help ensure a successful migration to the new Session Network. Session messenger is a live product with a high number of users, and this testnet phase is vital in identifying and eliminating any issues prior to the network transition. This program was designed to reward active community participation as they battle-test the new Session network ahead of its mainnet launch.\ \ 1M Session Tokens were allocated as rewards to the Testnet Incentive Program. # Get Session Token (SESH) Session Token was generated on May 21, 2025. Its contract address on Ethereum and Arbitrum One is **0x10Ea9E5303670331Bdddfa66A4cEA47dae4fcF3b**. ### Session Token on Exchanges Session Token is now available via Uniswap on [Ethereum](https://app.uniswap.org/explore/tokens/ethereum/0x10Ea9E5303670331Bdddfa66A4cEA47dae4fcF3b) and [Arbitrum One](https://app.uniswap.org/explore/tokens/arbitrum/0x10ea9e5303670331bdddfa66a4cea47dae4fcf3b). Further announcements will be made via trusted channels.
Session Token Discord
Session Token Twitter
### Rewards Programs You may have gained early access to Session Token prior to the Token Generation Event (TGE) by staking Oxen coins to a registered Oxen Service Node to be automatically swapped for Session Tokens at TGE; or by holding Oxen coins and burning them in exchange for Session Tokens after TGE in the Oxen Coin Claims program.
Learn more about Oxen Coin Claims
Learn more about the Service Node Bonus Program
# How to create a crypto wallet A guide for creating crypto wallets for total beginners. ### What are crypto wallets? A crypto wallet is a tool that lets you store and manage your cryptocurrency, like Session Tokens. Just like a real wallet holds your cash, a crypto wallet holds your digital coins. It’s where you can send, receive, and store your tokens safely. A wallet has two important parts: **Public Key:** Think of this like your bank account number. You can share this with people so they can send you crypto. **Private Key:** This is like your password. Only you should know this, as it controls access to your wallet. Crypto wallets also come with a seed phrase, which is a series of words you can use to recover your wallet if you ever lose access to it—similar to your Recovery Password in Session. ### What is an Ethereum wallet? An Ethereum wallet is a type of crypto wallet that works with the popular blockchain called Ethereum. Like many other cryptocurrency tokens, Session Token uses Ethereum. There are several different wallet providers, including MetaMask, Rabby, and Trust Wallet. This guide will illustrate the process with MetaMask, one of the most widely used crypto wallets. \ \ It’s important to note that transactions with Session Token using your Ethereum wallet, while anonymous, are **not private by default.** ### How do I create my crypto wallet? Creating your wallet is easy with MetaMask, one of the most popular wallets. Here’s how to set it up: 1. **Install MetaMask.** Head to the MetaMask website and download the browser extension for Chrome, Firefox, or Brave. 2. **Set a Password.** Choose a strong password to protect your wallet. 3. **Create a Wallet.** After installing, click on the MetaMask icon in your browser. Select “Create a Wallet” and follow the instructions. 4. **Backup Your Seed Phrase.** MetaMask will give you a seed phrase (a series of words, just like your Session recovery password). Write it down and store it in a safe place. Remember, this phrase is the only way to recover your wallet if you lose access! 5. After confirming your seed phrase, your wallet is **ready to use!** You now have a crypto wallet with a unique wallet address, a string of letters and numbers that looks something like this: 0x1A2b3C4d5E6f7G8h9I0jK1L2m3N4O5P6qR7s8T9 This is your public address, which you can share with others to receive tokens. Think of it as your crypto bank account number. ### How do I use my crypto wallet safely? To keep your crypto safe, follow these important security tips: 1. **Keep Your Private Key and Seed Phrase Secure.** Never share your private key or recovery phrase with anyone. These give full access to your wallet. 2. **Use Strong Passwords.** Ensure that the password for your wallet is long and unique. 3. **Enable Two-Factor Authentication (2FA).** If possible, enable 2FA using an authentication app or hardware keys on the services connected to your wallet. 4. **Be Careful with Phishing Scams.** Always double-check website URLs and avoid clicking on suspicious links to prevent phishing attacks that try to steal your credentials.
# How to view SESH in your Wallet Learn how to make SESH show up in your Ethereum wallet. When you receive SESH tokens, you may notice they don’t automatically appear in your Ethereum wallet. This is because wallets don’t automatically display all tokens—they only show tokens you’ve specifically added. To view your test SESH tokens, you’ll need to manually import the token by adding its contract address to your wallet. ### What does it mean to import a contract address? A contract address is a unique identifier for a token on the Ethereum blockchain. It points to the smart contract governing the token's operations—such as transfers, balances, and other functions. When you import a contract address into your wallet, you’re essentially telling the wallet to look for a specific token on the blockchain and display it in your interface. Without this step, your wallet holds the tokens, but it doesn’t know that it should display them. Here are links to step-by-step guides to help you add test SESH to the most popular wallets. [How to import tokens into your MetaMask wallet](https://support.metamask.io/manage-crypto/tokens/how-to-display-tokens-in-metamask/#how-to-add-a-custom-token) [How to import tokens into your Trust Wallet](https://trustwallet.com/blog/web3/how-to-add-a-custom-token-using-trust-wallet) [How to import tokens into your Rabby wallet ](https://support.rabby.io/hc/en-us/articles/11319672399247-List-of-supported-chains-and-tokens) [How to import tokens into your MyEtherWallet](https://help.myetherwallet.com/en/articles/5974186-custom-tokens-on-mew#:~:text=Just%20click%20'Add%20custom%20token,%40myetherwallet.com%20for%20assistance.) You will be prompted to enter the below details:\ **Token Contract Address:** 0x10Ea9E5303670331Bdddfa66A4cEA47dae4fcF3b\ **Token Symbol:** SESH\ **Token Decimal:** 9 You should also make sure you’re on the Arbitrum One network in your wallet before you get started. ### Why don’t tokens show up automatically in my wallet? Ethereum wallets are designed to prioritize simplicity and security. They only display tokens you explicitly add. This ensures that your interface isn’t cluttered with irrelevant or scam tokens and allows you to control which assets appear in your wallet. Adding a token using its contract address is a standard way to make any Ethereum token visible in your wallet.
# How to use Session Token (SESH) Session Token has multiple uses, including staking and accessing advanced features in Session. #### Staking Earn rewards while securing Session by staking your Session Tokens. Staking is fast and simple—all you need is a wallet and some Session Tokens. Every node in the Session Network requires a stake of Session Tokens to activate. Although the full stake amount is fixed, you do not need to deposit a full stake yourself. You can simply delegate your Session Tokens to a single stake—no matter how many tokens you have. Once the full stake is deposited, the node runs its validator software and registers on the network. Nodes are responsible for storing and validating data and transactions for the Session Network. This keeps Session secure for everyone, with stakers being rewarded with Session Tokens. {% hint style="info" %} *Learn more about staking* [*here*](/session-network/staking) {% endhint %} #### Advanced features Session Token can be used to access advanced features in Session, such as Session Names and Session Pro. These features require special validation and processing from the Session Network. To account for this additional work, Session Network Fees must be paid (in Session Token) to access these features.
/pages/jerXGuQWaeMvJNgbtnuO
/pages/prGCuLTIR0UwocbjvgSl
{% hint style="warning" %} *Session Pro and Session Names are still being developed. They are not yet deployed or available.* {% endhint %} # Session Network The heartbeat of the Session Network The Session Network is a decentralized, open-source blockchain network that enables the transmission of encrypted data, specifically for Session messenger. ### Key elements of the Session Network The Session Network is a decentralized physical infrastructure network with thousands of nodes and millions of users. Here are the key elements which enable the Session Network:
* Decentralized: The Session Network is a peer-to-peer network, it is not controlled by any single entity, but by a distributed network of 1,500+ Session Nodes in over 50 countries * Session Nodes: Nodes provide the basic infrastructure for a communication network: message sending, storage, and delivery * Validator software: Validator software enables core functionality of peers in the network, including basic requirements such as message storage and onion-routing protocol(s), as well as more complex logic such as network storage layers * Session Token: Session Token is the native cryptocurrency of the Session Network, used for staking, and paying for transactions and computational services, such as Session’s advanced features. Session Token will be issued on Ethereum, while the incentive layer (staking and rewards) is launching on Arbitrum One * Proof of Stake: The Session Network uses a proof-of-stake (PoS) consensus mechanism, with users depositing Session Token stakes in order to register Session Nodes * Session appchain: To scale with the demands of a modern messaging application and related infrastructure, certain tasks are offloaded to the Session appchain, a sidechain with low-fees * Session Names: The Session Network maintains its own name service (Session Name Service) using a series of smart contracts; this allows users to buy and trade unique Session Names (e.g. for use in Session messenger) ### Session Network use cases The Session Network is primarily utilized as infrastructure for Session messenger. However, there are many other future use cases for the Session Network.
* Private messaging: Session is a decentralized, encrypted, and private messaging application. Free from ads and trackers, Session is already used actively by over 1,000,000 people * Commercial messaging: Session Network and modified Session software can be used to quickly and efficiently deploy commercial messaging solutions * Community hosting: The Session Network combined with Session Community Servers can be utilized to host large-size communities * In-app wallets: Combining Session’s messaging with in-built cryptocurrency wallets, the Session Network can be used to easily transact with your messaging contacts * Session Names: The Session Name Service is an extensible naming system; the system can be used to easily find contacts on Session, create discoverable Communities, or connect to other content (e.g. web links) * Private routing: The Session Network can be used in place of a VPN or other onion-router software, with advantages in speed and scalability. Achievable through integration of the novel [Lokinet](https://lokinet.org/) protocol
# Session Nodes Session Nodes are incentivized full nodes which secures and enables the functionality of the Session Network. Nodes are responsible for validating transactions and data (such as messages) for the Session Network. A full Session Node requires a stake of 25,000 Session Tokens and a minimum level of computational resources (bandwidth, storage, and processing time) to meet its validation responsibilities. This validation provides security and function to the Session Network. In return, Session Nodes receive Session Token rewards from the Staking Reward Pool. # Staking and collateralization Session Nodes lock Session Tokens using a staking smart contract in order to register on the network. The staking transaction contains both the Session Tokens and the information required to stake a node, including the key belonging to the node and the operator fee. For a node to be fully staked, a 25,000 Session Tokens must be deposited to the staking contract. Operators must stake a minimum of 25% of the total stake requirement, or 6250 Session Tokens. If an operator does not contribute the full stake themselves, other contributors must stake the remaining amount (creating a multi-contributor node). In multi-contributor nodes, the operator can set an operator fee to subsidize the time and cost required to successfully run the node. This operator fee is expressed as a % of the node’s reward which will be awarded to the operator. The remaining reward is then awarded among the contributors proportional to their stakes, as per usual. ### Contributors and small staking Up to 10 contributors (including the operator) can combine stakes to meet the requirements for a full Session Node. While the operator must contribute a minimum of 25% of the staking requirement, minimum contributions are calculated dynamically based on the amount of open staking slots for a particular node. To calculate the minimum staking amount for a given contributor: $$ \frac{Total:staking:requirement -Current:stake}{Open:staking:slots} $$ If a contributor stakes less than 25% of the requirement for a full node, they are classified as a small staker. To prevent small stakers holding disproportionate power over the node, small stakers are time-locked for 30 days after their initial staking deposit transaction. ### **Staking Requirements** The current staking requirement for a full node is 25,000 SESH. This means that the minimum staking requirement for a Session Node operator is 6,250 SESH. In the future, if a case arises wherein large portions of the total token supply are locked via Session Nodes and the Staking Reward Pool, it is possible (with the consensus of the Session Network) to reduce the staking requirement (via network consensus) to ensure the network is able to continue growing. # Incentivization Session Token enables the incentivization layer for the Session Network, with registered and active Session Nodes sharing a portion of rewards released from the Staking Reward Pool. Due to the nature of the Staking Reward Pool, incentivization of the network is dynamic. As the amount of tokens in the Staking Reward Pool increases, so too does the amount of Session Token rewards (and vice versa). Session Token rewards incentivize both additional operators/contributors participating in the network as well as promoting good behavior of existing nodes. As the Session Network is self-governing, bad behavior (such as failing to route traffic or store a message) results in lost rewards for the bad node. As all nodes require a time-locked collateral to participate in the network (see [Staking and Collateralization](/session-network/session-nodes/staking-and-collateralization)), bad nodes also risk destabilizing a network they are vested in. # Consensus The state of the Session Network is primarily tracked on the Session Appchain, a minimal L1 blockchain maintained by consensus of Session Nodes. For more information about the Session Appchain, see [here](/session-network/session-nodes/session-appchain). # Swarms Session requires a secondary logical data layer built on top of the Session Node Network to ensure reliable message storage and retrieval. Swarms protect users from message loss if Session Nodes go offline, drop messages, or become otherwise unavailable. Messages are replicated across small groupings of Session Nodes (swarms). Swarm composition is determined by the network design, not individual nodes, keeping network swarms robust and operational even as Session Nodes join and leave the network. The following set of simple rules ensure that Session Nodes within swarms remain synchronized as the composition of swarms changes: * When a node joins a new swarm, existing swarm members recognize the new member 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. # Session Appchain Session Node state is primarily tracked by the Session Appchain, a native L1 which includes rewards calculation logic and voting logic required to deregister or punish nodes on the network. New nodes are permissioned into the Session Node network through staking into the EVM native staking contract. The consensus of Session Nodes can be snapshotted and signed efficiently using BLS signatures and posted back to the native EVM native chain for validation. This is used for node deregistration and is required for any Session Node to claim funds or withdraw their Session Node from the network. {% hint style="info" %} Appchains are specialized, app-specific blockchains built to increase scalability and throughput. The Session appchain logic is based on the original Oxen blockchain. {% endhint %} In this way, the most expensive and frequent operations can occur in an appchain environment (where fees are lower). The appchain state is then snapshotted and returned to the EVM chain for validation and security purposes. The Session Appchain is based on the original Oxen Blockchain, the first blockchain used by Session. # Deregistration The Session Network uses deregistration rules to enforce standards of node performance in a decentralized way. This ensure all operational Session Nodes are up to date and performing adequately to maintain the network. ### Session Node states Session Nodes have four different states: awaiting, active, decommissioned or deregistered. | State | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Awaiting | Session Node is awaiting the required [stake](/session-network/session-nodes/staking-and-collateralization) of Session Tokens. | | Active | Session Node is staked, performing tasks as required, and receiving rewards. | | Decommissioned | Session Node is not performing tasks as required or is not meeting uptime standards, and has been placed into an inactive state. Decommissioned nodes do not earn rewards. | | Deregistered | Session Node has been inactive (decommissioned) for too long, and has been deregistered from the network. | ### **Decommissioned nodes and credits** Session Nodes have "credits" which determine how long a node may remain inactive (decommissioned) before being deregistered from the network. These credits are used during any time period where the Session Node is offline (or otherwise stops meeting network requirements). A new node starts out with `INITIAL_CREDIT`, and then builds up `CREDIT_PER_DAY` for each day the it remains active, up to a maximum of `DECOMMISSION_MAX_CREDIT`. | | | | ------------------------- | ---------------------------------------------- | | `INITIAL_CREDIT` | 60 blocks (\~2 hours) of decommission time. | | `CREDIT_PER_DAY` | 24 blocks (\~0.8 hours) of decommission time. | | `DECOMMISSION_MAX_CREDIT` | 1440 blocks (\~48 hours) of decommission time. | | `MINIMUM` | 60 blocks(\~2 hours) of decommission time. | **Example**: If an Session Node stops sending uptime proofs, a quorum of service nodes will analyze whether the node has built up enough credits (at least `MINIMUM`). If so, instead of submitting a deregistration, the quorum instead submits a decommission, removing the node from the list of active Session Nodes. While decommissioned, the node does not receive rewards or participate in active network duties. If the Session Node node comes back online (i.e. starts sending the required performance proofs again) before its credits run out, a quorum will reinstate the node using a recommission transaction. This transaction adds the Session Node back to the reward list and resets the node's accumulated credits to 0. If the Session Node does not come back online within the required number of blocks (i.e. if the node does not come back online and begin performing as required before its credits are depleted), then a quorum will send a permanent deregistration transaction to the network, locking that node's stake for 30 days. ### Quorums tests | | | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |

Uptime Proofs

| Checks if a node has provided uptime proofs within the last 2 hours. If the node has not provided uptime proofs, but it has at least `MINIMUM` credits, it will be decommissioned. If it does not have at least `MINIMUM` credits, it will be directly deregistered. | | **IP Changes** | Checks if a Session Node has broadcast more than one IP to the network in the last 24 hours. If a service node's IP has changed, it will be forced to the bottom of the reward list. | | **Checkpointing** | Checks if each Session Node within the quorum has provided a hash of a block for a specific block height. If a node within the quorum does not provide a hash, but it has at least `MINIMUM` credits, it will be decommissioned. If it does not have at least `MINIMUM` credits, it will be directly deregistered. | ### **State change transactions** State change transaction change the state of a Session Node. Typically, state change transactions are created when a quorum comes to a consensus about a given node's activities (or lack thereof). The only state change transaction that can be created by any indivdual node is the `Register` transaction, which changes the state of a service node from `awaiting` to `active`. | State\_Change\_Transaction | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Register TX` |

A transaction created from the staking portal registering the Session Node.

State Change: Awaiting -> Active

Note: This is not a quorum transaction.

| | `Decommission TX` |

Node is made inactive; it remains in the service node list, but is removed from the rewards list and from any network duties.

State Change: Active -> Decommissioned

| | `Recommission TX` |

Node is added back to the Session Node list and placed at the bottom of the rewards list.

Stage Change: Decommissioned -> Active

| | `IP Change TX` |

Node is pushed to the bottom of the rewards list as punishment for changing its IP.

Stage Change: N/A (no change)

| | `Deregister TX` |

Node is deregistered from the network.

State Change: Active -> Deregistered / Decommissioned -> Deregistered

| # Session Protocol {% hint style="info" %} [**Session Protocol V2**](https://getsession.org/blog/session-protocol-v2) **is currently in development!** V2 plans to add support for post-quantum cryptography, re-implement Perfect Forward Secrecy (PFS), and bring more secure multi-device account management. {% endhint %} The Session Protocol is an encryption protocol specifically designed for deployment in decentralized networks, optimizing to achieve high levels of security and reliability without requiring strong guarantees of client synchronicity and permanent storage mediums. In the context of one-on-one messaging, the Session Protocol provides a simple stateless end-to-end encryption protocol, and in the context of groups, it provides a protocol that can scale and tolerate faults caused by the constraints of the Session Node network. The Session Protocol is currently utilized by [Session messenger](/). # Onion requests and message routing Session implements a simple onion-routing protocol, called Onion Requests, to protect user IP addresses. {% hint style="info" %} Onion routing is a method of sending internet traffic (like messages) through multiple encrypted layers, like the layers of an onion. Each layer is ‘peeled’ by a different server in the network, hiding the sender's identity. {% endhint %} For the messaging context, this is critical for preventing a node or other party from using metadata to de-anonymize users or deduce conversation participants for a given chat. Onion requests are a relatively simple system, built using TCP. Although this simplicity has its advantages, it also means that onion requests inherit some of TCP's limitations—such as slower connection speeds compared to other protocols. To route a message, the sender first needs to find the Session Nodes in their recipient’s swarm. To do this, the client fetches the swarm mapping for their recipient’s Account ID. Given the swarm mapping, the sender creates a message and prepares the message to be sent to the Session Node network. The sender includes the necessary information for the message to be processed, including: * The Account ID of the recipient * The message timestamp * The message expiry time * The namespace where the message will be stored The sender then sends this message—using an onion request—to a random Session Node within the recipient’s swarm. This Session Node will then propagate the message to the remaining nodes in the swarm, with each node storing the message until the specified expiry time. {% hint style="info" %} By default, chat messages expire after two weeks. However, this can be configured using the Disappearing Messages feature in Session messenger {% endhint %} While functional, Onion Requests are a very limited message-based protocol built on top of TCP. Onion Requests are effective for passing messages across the network, but do not lend themselves well to expanding the network capabilities to large transfers or responsive voice/video communication. In the future, it is intended that the Session client will be able to interface with the network’s more advanced onion-routing overlay network, making key features such as onion-routed voice and video calls possible. # Account IDs and self managed keys Most popular messaging applications require the user to register with an email or mobile phone number in order to use the service. This requirement represents a major privacy and security compromise for users due to the centralized management of phone numbers (i.e. telecommunications service providers), which have the capacity to assume direct control of specific users’ phone numbers. Additionally, methods such as SIM swapping attacks, service provider hacking, and phone number recycling may be exploited by lower-level actors to compromise user security. Using phone numbers as the basis for account registration also greatly weakens privacy, with many countries requiring users to provide personally identifying information such as a passport, driver’s license or identity card to obtain a phone number—permanently mapping users’ identities to their phone numbers. To counter this, Session messenger does not use phone numbers or email addresses as the basis for its account system. User identity is established through the generation of an Ed25519 public-private key pair. This keypair is 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. {% hint style="info" %} Example of an Account ID on Session messenger: *056c3d9682f167135d4c86b0af24e7aca98949380fa825e01455e788fe3df1d05c* {% endhint %} Additionally, because messages are encrypted using the recipient address, Session is able to remove the [trust on first use](https://getsession.org/blog/trust-on-first-use-the-achilles-heel-of-centralised-messengers) problem. # Account restoration Because Session does not have a central server to keep records of users’ accounts, the commonly expected user experience of account recovery using a username and password is not possible. Instead, users are prompted to write down their long-term private key upon account generation. This long-term private key is represented as a mnemonic seed phrase, referred to within Session as a Recovery Password. {% hint style="info" %} Example of a Recovery Password on Session messenger: *virtual rounded dating itself sober fleet adrenalin puzzled wept rural axis fictional fleet* {% endhint %} A user may use their Recovery Password to recover their account if their device is lost or destroyed. This enables the user’s contacts to keep communicating with the same Account ID, instead of needing to establish contact with a new Account ID. {% hint style="danger" %} **Never share your Recovery Password with anyone**. Make sure to store it in a safe and secure place. {% endhint %} # Staking Staking allows users to earn rewards for securing the Session Network. It is simple and fast to begin staking and join Session’s network of over 1,500 nodes. {% hint style="info" %} For Staking guides, check out the [Contribute to the Session Network page](/contribute-to-the-session-network) {% endhint %} Regardless of how many Session Tokens you have, you can contribute to the network’s security and receive rewards. ### Claim rewards anytime 24 hours after you start staking, you start earning SESH rewards for helping secure the network. Your rewards can be claimed whenever it is convenient for you. ### Staking Portal The [Staking Portal](https://stake.getsession.org/) provides a simple, easy-to-use web interface for you to manage your stakes and rewards. All you need is an Ethereum wallet (such as MetaMask) and a browser. Using the Session Staking Portal, you can generally stake within minutes. ### Scaling rewards Rewards for stakers scale based on the amount of tokens in the Staking Reward Pool. A targeted rate of 14% of the total reward pool is awarded to the network each year, calculated daily. As the amount of Session Tokens in the Staking Reward Pool increases, Session Token Rewards also increase (and vice versa). {% hint style="info" %} Click [here ](/session-network/staking/staking-reward-pool)for more information about the Staking Reward Pool {% endhint %} # Staking Reward Pool The Staking Reward Pool is a vital component of the Session ecosystem’s incentivization layer, transforming token utility into rewards for the Session Network. Session Tokens are added to the Staking Reward Pool when Session Tokens are used for advanced features, such as registering a Session Name or unlocking Session Pro, users burn Session Network Fees. These fees are then re-minted into the Staking Reward Pool, increasing network rewards Tokens in the pool are time-locked in a smart contract and released at a targeted rate of 14% per year. These tokens are rewarded to active and registered nodes in the Session Network. These rewards scale based on the amount of tokens in the Staking Reward Pool, so the network's rewards can increase the more Session Token is used (through actions like Session Pro unlocks and SNS registrations). ### Network reward rate Rewards are based on a targeted yearly emission of 14% of the Staking Reward Pool, recalculated every 24 hours (to update for fluctuations in the pool size). To ensure that 14% of the Staking Reward Pool is rewarded to the network in a given year, the percentage used to calculate the daily reward is slightly greater than 14%. To calculate the daily network reward: $$ \dfrac{0.151(Staking:Reward:Pool)}{365}=Daily:Network:Reward $$ Furthermore, to calculate the reward for an individual node, simply divide the Daily Network Reward by the number of active and registered nodes in the Session Network. $$ \dfrac{Daily:Network:Reward}{Nodes:in:network}=Node:Reward $$ Moreover, if you are a contributor to a node, your individual reward can be calculated by multiplying the node reward by your percentage of the full stake, after accounting for operator fees as follows. \ \ Operators can set an operator fee on their multicontributor nodes, which is collected in SESH. This fee helps operators to cover the costs of running a node. The fee is taken as a percentage of the node rewards allocated to the operator. Once the fee is deducted, the remaining rewards are distributed among all contributors (including the operator), proportional to stake amount. {% hint style="info" %} **For example:** If a node earns 1000 Session Tokens and the operator sets a 10% fee, the operator keeps 100 tokens as their fee, and the remaining 900 tokens are split based on stake amounts—so, if the operator staked 50%, they’d get 450 tokens (550 in total), and two contributors with 25% stakes each would get 225 tokens each. {% endhint %} Note that the Staking Reward Pool is dynamic, and it is not possible to effectively predict or account for future tokens added to the pool. For example, if a large amount of Session Tokens were added to the Staking Reward Pool at once, it would make the emission from the previous year period significantly lower than 14%, even though actual rewards would be greater than forecast. ### Claiming rewards To avoid unnecessary transaction fees, rewards are held by the smart contract until they are manually claimed by stakers. Rewards can be claimed once the Session Network validates and authorizes the claim and amount. ### Genesis provision The Staking Reward Pool will have a genesis provision of 40,000,000 Session Tokens. Using the above formula, the network reward for Day 1 can be calculated: $$ \dfrac{0.151(40,000,000)}{365}=16547.95 $$ This amount will be equally divided by the amount of active and registered nodes on Day 1. An additional 23,177,550 SESH tokens have been added to the Staking Reward Pool, bringing the total to 63,177,550 SESH. While this full amount will be in the pool on Day 1, the rewards paid out will initially be calculated based on the original 40,000,000 SESH genesis provision parameter. \ \ Due to a pre-existing security mechanism designed to prevent manipulation, the reward calculation will gradually adjust to reflect the actual 63,177,550 SESH balance over approximately 30 days. This security feature limits how quickly reward rates can increase between blocks, ensuring network stability. # Contribute to the Session Network The best way to participate in the Session Network is by operating or contributing to a Session Node. Nodes are responsible for securing and validating transactions and data (such as messages) for the Session Network. By operating or contributing to a Session Node, you contribute to essential infrastructure for the Session ecosystem—and help protect the security and privacy of the people using Session. All Session Nodes are required to deposit (or ‘stake') a fixed amount of Session Tokens and run validator software to register on the network. ### Single contributor nodes Session Node operators manage the server (such as a VPS or home server) which runs the Session Node validator software. To run the software, the node will need to meet minimum hardware requirements. In a single contributor node, the node operator deposits the full stake required to register on the network. Stakes can be deposited and managed using the [Staking Portal](https://stake.getsession.org/stake). ### Multicontributor nodes If an operator does not have enough Session Tokens for a full stake (or does not wish to provide a full stake for some other reason), they can operate a multicontributor node. Multicontributor nodes allows for multiple to delegate their stake to a single node. Stakes are still managed by the staking smart contract, and funds are not held by the operator. Operators can set an operator fee on their multicontributor nodes, which is collected in SESH. This helps to cover operating costs of running a node. For example, if the operator sets a 10% operator fee, they will earn 10% of the SESH that would have been distributed to contributors. This mirrors how node operator fees will work on mainnet. # Running a Session Node This guide will walk you through the complete process of setting up, staking, and running a Session Node. ## Running a Session Node You can run Session Node software on any device running a supported operating system, but for the purposes of this guide, we'll assume you will be setting up a Session Node on a remote Ubuntu or Debian server. If you're new to Linux or running servers in general, this is the most straightforward approach. If you're more experienced and would prefer to run your Session Node on a different operating system, you'll need to modify the syntax of some commands to suit your system of choice. > **Note:** You'll need Session Tokens (SESH) on the **Arbitrum One network** to be able to stake. If you have purchased SESH on the Ethereum network, you must bridge it to the Arbitrum One network via the [official Arbitrum bridge](https://stake.getsession.org/bridge/arbitrum) first. Please also make sure you have a small amount of ETH on the Arbitrum One network for gas. #### **Requirements** These are the current basic requirements for running a Session Node.
SpecRequirement
Latest Session Node softwareLatest Session Node .deb packages (installed via the steps below) or latest stable branch build from source.
Server operating system*Ubuntu 22.04+ (latest LTS recommended) or Debian 11+ (latest stable recommended)
Storage45GB
RAM4 - 8GB
Connectivity/Bandwidth100Mb or faster
Traffic/Transfer**10 - 20 TB per month or more
PowerRedundant with remote cycling ability, as found in most data centres
> **Note:**\ > \*It is possible for an experienced system administrator to run a Service Node on a server running an operating system other than Ubuntu or Debian. However, this requires additional work to start up and manage the required services, and is beyond the scope of this guide.\ > \ > \*\* While the traffic requirement is 10 TB per month, actual traffic may occasionally exceed this amount. Most VPS providers offer generous or unlimited bandwidth allowances, with any throttling only occurring after a certain level of usage. Even if throttling occurs, it typically doesn't impact node performance. Additionally, many providers only count outgoing traffic toward limits, meaning incoming traffic often isn't counted against your monthly allowance. #### Session Nodes in a nutshell * A Session Node starts as a full node on the Session [appchain](/session-network/session-nodes/session-appchain) that monitors the [Arbitrum One](https://arbitrum.io/) blockchain * The full node becomes a Session Node when the owner locks the required amount of 25,000 SESH and submits a registration transaction to Arbitrum * Once accepted by the network, the Session Node starts performing node operations and becomes eligible to earn rewards in the form of SESH * Multiple participants can stake into one Session Node and can have the reward automatically distributed among them **Session Node functionality** Session Nodes: * Monitor the Arbitrum One network for new registrations and departures. * Provide signatures required to withdraw rewards via Arbitrum * Monitor other Session Nodes and vote on their performance * Produce new blocks for the network via [Pulse PoS](https://docs.oxen.io/oxen-docs/about-the-oxen-blockchain/pulse-pos-on-oxen) * Receive, store, and forward encrypted Session messages * Route [Lokinet](https://lokinet.org/) traffic ## Session Node setup for new users ### **Step 1: Obtaining a server** Choosing where to set up Session Node is the first and most critical decision you will face in setting up and running your node. There are a number of factors to consider. Because you will be locking up SESH as part of operating your Session Node, you will want to ensure, at a minimum, that your server meets the technical requirements given above. Your aim is to provide a stable, reliable server with good network connectivity, so that data can be efficiently routed to and from your node. An underpowered or poorly connected node will have a poor response time and add latency to the network for all users whose traffic passes through it, resulting in a less than optimal experience. If your server goes down while staked, your Session Node could be [deregistered from the network](/session-network/session-nodes/deregistration) and your SESH locked for 30 days (without receiving rewards). The simplest and cheapest way to host a server such as a Session Node is to lease a Virtual Private Server (VPS). There are literally hundreds of options when it comes to VPS providers, but some of the more commonly chosen companies and products are listed below. | Hosting Provider | Product Name | Cost Per Month ($USD) | | ------------------ | ----------------- | --------------------- | | Netcup | VPS 500 G11s | 4.65 | | Evolution Host | BUSINESS | 46.50 | | Scaleway (Dedibox) | Start-2-S-SSD | 5.80 | | Scaleway | DEV1-M (+Storage) | 22.60 | | OVH | VPS-1 | 4.20 | | Feral Hosting | Neon Capability | 17.50 | | Trabia | VDS-4G | 19.80 | | Hetzner | CX33 | 6.60 | > **Note:** Session does not endorse any of these providers. This list is merely a selection of some of the popular options at the time of writing. Of course, this popularity comes at the expense of decentralisation. A useful resource in choosing a less common VPS provider is [ExoticVM](https://www.exoticvm.com/). Another good one is [Server Hunter](https://www.serverhunter.com/). In any case, do not just settle on the first provider you encounter. No two are alike. Do your own research and choose a provider that seems professional, reputable and fits your budget. The better ones will utilise [KVM](https://www.linux-kvm.org/page/Main_Page) [virtualisation technology](https://www.tradingfxvps.com/kvm-vs-vmware-vs-openvz-vs-xen/). In particular, you should steer clear of any VPS which uses OpenVZ. This is an incomplete form of virtualisation that allows VPS capacity to be oversold, and is usually incompatible with the full Session Node software. Virtual machines created with it often lack a `/dev/tun` device, which effectively prevent it from providing the Lokinet service required for a Session Node. A good VPS provider will also allow you to monitor your machine's resource consumption, seamlessly upgrade to a more powerful server at a later date, remotely reboot the host if it becomes unresponsive, and even recover or rebuild the system using out-of-band access if, for example, a bad configuration change results in lost network access. When selecting your VPS’ operating system, please choose the latest Ubuntu LTS release or latest Debian stable release (currently 24.04 and 12, respectively) if you want to be able to follow the steps below verbatim. ### Step 2: Preparing your server Every provider has a slightly different way of issuing you access to your new VPS. Most will send an email with the IP address, root username, and a root password to the VPS. To access your server, you will need an SSH client for your operating system. Because this guide will use Windows to illustrate the setup process, we’ll download [PuTTY](https://www.putty.org/). macOS and Linux users can connect by opening a terminal and typing: ``` ssh root@[your VPS IP address] ``` To connect to your VPS, you'll need to paste the provided IP address into the SSH client’s “Host Name (or IP address)” input box and click the “Open” button. The Port number can usually just be left as `22`. A terminal window will now appear, prompting you for your log-in details, username (`root`) and password, as provided by your VPS provider. When entering your password, characters will not appear in the terminal. This is normal. Hit enter after typing or pasting your password, and you should be logged in to your VPS. *Note: After logging in for the first time, the VPS may prompt you for a new password for the root account. The terminal will require you to enter the new password twice before you can start running commands. If you aren't prompted for a new root password but want to change it anyway, type sudo passwd. Choose something very secure!* #### 2.1: Hot tips for using the console on Windows Consoles don't quite work like the rest of your computer. Here are some basic tips for navigating your way around the command line! * Don't try copying something by using the usual `Ctrl + C` hotkey! If you want to copy something, do so by highlighting text and then right clicking it and selecting Copy. Pasting works by right clicking a blank area in the console and selecting Paste. * If you want to kill a process or stop something from running, press `Ctrl + C`. (This is why you shouldn't try copying something with this hotkey!) * You can always check the directory you are in by typing `pwd`, and you can list its contents by typing `ls`. * You can always return to your home directory by typing `cd` and pressing Enter. * You can move into a given directory by typing `cd ` or move back up one level by typing `cd ..`. * PuTTY allows you to easily duplicate or restart a session by right clicking the top of the window. Handy if you’re trying to do a few things at once. #### 2.2: Server preparation continued Next, update your package lists (the lists that tell your server which software is available for install or upgrade). The following command downloads package lists from their respective package repositories and "updates" them to get information on the newest versions of packages and their dependencies. It will do this for all repositories and PPAs. ``` sudo apt update ``` You'll notice a bunch of package lists were downloaded. Once this is complete run the below command to fetch new versions of any packages that came preinstalled on the system. ``` sudo apt upgrade ``` You'll be prompted to authorise the use of disk space. Type `y` and Enter to authorise. If you are prompted during the upgrade that a new version of any file is available then click the up and down arrows until you are hovering over `install the package maintainer’s version` and click Enter. Alright, good to go. Our server is now set up, up to date, and is not running as root. On to the fun part! #### 2.3: Firewall configuration If you are using a firewall then you should ensure that the following ports are open and reachable: * 22020 (Storage Server to Storage Server, TCP & UDP) * 22021 (Session Client to Storage Server, TCP) * 22022 (Blockchain syncing, TCP) * 22025 (Session Node to Session Node, TCP) * 1090 (Lokinet router data, UDP) * 1190 (Session Router data, UDP) ### Step 3: Initial repository setup You only need to do this step the first time you want to set up the Oxen repository; when you've done it once, the repository will automatically update whenever you fetch new system updates. To add the `apt` repository, run the following commands. This first command downloads the public key used to sign the Session Node packages: ``` sudo curl -so /usr/share/keyrings/session-foundation.gpg https://deb.session.foundation/pub.gpg ``` The second command tells `apt` where to find the packages. {% code overflow="wrap" %} ``` cat < **Note:** If you have a SESH vesting contract, instead, copy this contract address, rather than your wallet address. This will be the operator address for your node. #### 6.2a: Individual Staking To run a Session Node as the sole contributor, you'll need: * A fully synchronized, up-to-date Oxen daemon running on your Session Node * An Arbitrum wallet with at least 25,000 SESH in it (to meet the staking requirement to register your Session Node), and sufficient ETH on the Arbitrum network for gas. #### 6.2b: Multicontributor Staking To run a multicontributor Session Node as the operator, you'll need: * A fully synchronized, up-to-date Oxen daemon running on your Session Node * An Arbitrum wallet with at least 6,250 SESH in it (to meet the operator staking requirement to register your Session Node), and sufficient ETH on the Arbitrum One Network for gas. #### 6.3: Preparing your node for registration Log in (if not already logged in) to the VPS running the Session Node, then run the following command: ``` oxend register [operator ETH address] ``` The daemon will output something which looks similar to: {% code overflow="wrap" %} ``` Submitting L2 staking information to https://stake.getsession.org/register/[Session Node ID] Submitted registration info to the staking website successfully! View your registration at: https://stake.getsession.org/register/[Session Node ID] ``` {% endcode %} *NOTE: This information will be automatically submitted to the Staking Portal to help with creating the transaction on the Arbitrum One blockchain.* #### 6.4a: Registering your single contributor Session Node To register and stake your Session Node, ensure your Arbitrum wallet has a balance of at least 25,000 SESH as well as sufficient ETH on the Arbitrum One network for gas. Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. The node you have prepared registration for will appear in the 'Your Prepared Registrations' list.\ \ View the prepared node’s details and confirm your registration and stake of 25,000 SESH. #### 6.4b: Registering your multicontributor Session Node To register and stake your Session Node, ensure your Arbitrum wallet has a balance of at least 6,250 SESH as well as sufficient ETH on the Arbitrum One network for gas. Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. On the **Register** page, the node you have prepared registration for will appear in the 'Your Prepared Registrations' list. When you view the prepared node's details you can customise your stake amount and operator fee. Change these to whatever you wish, keeping in mind that the minimum Stake Amount for the operator is 6,250 SESH. Once you have confirmed these values, you can proceed to register and stake your node. You node will be listed on the [Staking Portal](https://stake.getsession.org/) as an Available Node, and anyone can stake to it from there. Once your node has reached full 25,000 SESH stake amount, it will automatically be registered on the network. > **Note:** If you are operating a node and staking vesting SESH, note that you cannot set up a multicontributor node with SESH. Instead, you can set up a multicontributor node with non-vesting SESH and stake to it using your vesting SESH. ### Step 7: Session Node status check After you've staked to your Session Node, you can check that Session Node is running, recognised, and eligible to earn SESH rewards on the [My Stakes](https://stake.getsession.org/mystakes) page. This process typically takes 9-12 minutes as the network securely witnesses and finalizes the registration on the chain. ## Operating your node ### Keeping your binaries up to date When a new release is available, upgrading is as simple as syncing with the repository: ``` sudo apt update ``` Then installing updates using: ``` sudo apt upgrade ``` *Note that this will install both updated* `oxend` *packages and any available system updates (this is generally a good thing!)* During the upgrade, all instances of `oxend` will be restarted if they are currently running in order to switch to the updated `oxend`. If for some reason you want to install only Oxen package upgrades but not other system package updates, then instead of the `sudo apt upgrade` you can use: ``` sudo apt install session-service-node ``` ### Monitoring Use the [My Stakes](https://stake.getsession.org/mystakes) page to monitor the status of your staked node. On this page you'll also see the rewards your node is earning, and claim these using the **Claim** button. > **Note:** If you're staking vesting SESH, you'll need to **switch off** Vesting Mode first to be able to see your rewards. You can also verify that the Storage Server is reachable over UDP using [quictest.oxen.io](https://quictest.oxen.io/) once the Session Node is registered onto the network successfully as part of monitoring your node. ### Back-ups You should immediately make a backup of your Session Node's secret keys. This will allow you to migrate your node to a different hardware provider if necessary in the future. **IMPORTANT: These keys should always remain secret and should never be shared with anyone. Sharing these keys can result in the loss of funds or deregistration of your node.** The command to reveal the ed25519 secret keys is: ``` oxen-sn-keys show /var/lib/oxen/key_ed25519 ``` The command to reveal your BLS secret keys is: ``` oxen-sn-keys show /var/lib/oxen/key_bls ``` Alternatively, you can use a tool like *scp* to copy these files off-host for safekeeping. ### Restoration If you backed up your keys and want to restore an unregistered node to use those backed up keys you can use the following commands. The command to restore an ed25519 key into a file is: ``` oxen-sn-keys restore /var/lib/oxen/key_ed25519 ``` The command to restore BLS key into a file is: ``` oxen-sn-keys restore-bls /var/lib/oxen/key_bls ``` Those commands will create a new key file with the correct formatting called “key\_ed25519” and “key\_bls” respectively, if you want to overwrite an existing key file you can pass the “-- overwrite” flag as such: ``` oxen-sn-keys restore --overwrite /var/lib/oxen/key_ed25519 ``` For BLS keys: ``` oxen-sn-keys restore-bls --overwrite /var/lib/oxen/key_bls ``` You can choose either to overwrite your existing key files in the /var/lib/oxen directory using this command or create new key files and swap them out with the existing files, once keys are overwritten or swapped your node can be restarted with the following command: ``` systemctl restart oxen-node ``` IMPORTANT: Never remove or replace keys on an active, registered Session Node! ### Updating L2 Providers and additional node configuration You can reconfigure your Session by modifying the file at `/etc/oxen/oxen.conf` where settings are kept for the current running instance. In `/etc/oxen/oxen.conf` each line denotes a configurable option.\ \ For example, in the following, the Session node is configured to use `http://example.com` as the primary L2 provider and `http://backup.example.com` as a backup if the first provider falls behind. ``` data-dir=/var/lib/oxen log-file=/var/log/oxen.log service-node=1 service-node-public-ip= l2-provider=http://example.com l2-provider=http://backup.example.com ``` Some additional options are available for advanced users to configure how the Session node talks to the L2 provider: * `l2-refresh` Specify the time (in seconds) between refreshes of the Ethereum L2 provider current state (default is 60) * `l2-timeout` Specify the timeout (in seconds) for requests to the L2 provider current state; if multiple providers are configured then after a timeout the next provider will be tried (default is 5) * `l2-max-logs` Specify the maximum number of logs we will request at once in a single request to the L2 provider. If more logs are needed than this at once then multiple requests will be used (default is 1000). * `l2-check-interval` When multiple L2 providers are specified, this specifies how often (in seconds) all of them should be checked to see if they are synced and, if not, switch to a backup provider. Earlier L2 providers will be preferred when all providers are reasonably close (default is 170) * `l2-check-threshold` When multiple L2 providers are specified, this is the threshold (in number of blocks) behind the best provider height before a given provider is considered out of sync (default is 120). An exhaustive list of available options can be found by running `oxend --help`. For more information, see the Oxend L2 tracker tuning page for ensuring that the daemon does not overload the configured L2 provider. After making your changes, you must restart your node for the new settings to apply. Use the following command: ``` systemctl restart oxen-node ``` ### Unlocking your stake Session Nodes will continually earn SESH rewards indefinitely until an exit is requested or the node becomes deregistered. To request an exit to reclaim your SESH stake, simply open the [Staking Portal](https://stake.getsession.org/) and navigate to the [My Stakes](https://stake.getsession.org/mystakes) page. You can then click Request Exit for any stake you wish to initiate an unlock for. Your Session Node will become eligible to exit 15 days after the initial request. When a Session Node has become eligible to exit after 15 days, the node must formally exit the network within 7 days of becoming eligible to exit. Simply click the Exit button on the node in the Staking Portal. After exiting, you can claim your stake by clicking the Claim button on your My Stakes page. If the node is not removed within 7 days becoming eligible to exit (22 days after the initial exit request), the node becomes eligible for liquidation by other users. When a node gets liquidated, a 0.2% penalty is taken from the operator's stake: 0.03% of the operator’s stake is transferred to the liquidator, and 0.17% of the operator’s stake is returned to the Staking Reward Pool.\\ ### Deregistrations Deregistrations can be issued at any point during the active lifecycle of a Session Node, including during the period after requesting an exit. Deregistration removes your Session Node from the network, and your stake(s) become locked and unspendable for 30 days from the block in which the Session Node was deregistered. After this period, operator and contributors can retrieve their stakes by clicking the Claim button in the Staking Portal. Receiving a deregistration **after** the node's participant(s) have already submitted an exit request overrides the 15 day stake unlock time, and sets the unlock time to 30 days. To avoid losing 0.2% of their stake to the liquidation penalty, operators can manually exit their node by clicking the Exit button in the Staking Portal. The stake will still remain locked for 30 days. If the node has not been manually exited within 7 days following deregistration, it is eligible for liquidation. ### Conclusion Well done! Your Session Node is configured, operational, and will now begin receiving SESH rewards. Having trouble? Head to the [Session Token Discord](https://discord.gg/sessiontoken) to access support. # Oxend L2 tracker tuning Learn how to configure options for your Arbitrum RPC provider. One important function that Session Nodes have is to monitor the Arbitrum contracts that define node registrations and rewards.To allow this monitoring, Session Nodes are required to configure an Arbitrum RPC provider. Not all Arbitrum RPC providers are the same, however. Different providers have different tiers often something along the lines of (free, paid, pay more, pay even more), and frequently add arbitrary limitations to the free or cheaper tiers that are designed to get you to move to the paid tiers. The Session Network has been designed so that node operators can opt the free tier of most providers by being more 'relaxed' in its requirements for L2 data. For example, Session appchain blocks include special "L2 event" transactions in response to events on the Arbitrum smart contracts (such as new registrations or unlock requests), but pulse quorums deliberately delay adding these special event transactions into blocks until at least 70 seconds after they first saw them. That slightly delays how long it takes events to be fully confirmed on the appchain, but also allows RPC checks to be reduced to about once a minute without leaving nodes unable to properly confirm these events. At the same time, providers limit their free tiers in different ways, and there is no single setting that works for all providers. Thus, defaults have been selected to have a reasonable chance of working for most providers' free tiers, as well as many 'knobs' to turn that can be tailored to the individual requirements of a particular provider. This guide is designed to explain what these options do, how to configure them, and reasonable values for the different options available. > **Note:** In saying that the Session Network is designed to accommodate the "free tier", this does *not* mean relying on public Arbitrum RPC URLs. While these may be acceptable for use with wallets, they will often rate limit or not be reliable enough for a Session Node. Instead, be sure to sign up with a trusted RPC provider and get URLs for your node to use that are tied to your individual account. Not only is this a more reliable approach, it also provides some useful statistics as to your RPC usage. ### RPC Calls Used As different providers have different costs for different endpoints, it can be useful to know which RPC endpoints are used by `oxend` rate limits to figure out how many requests or "credits" a service node will use. The majority of `oxend` requests are to the `eth_blockNumber` and `eth_getLogs` RPC endpoints: the former is used to query the latest Arbitrum block number, while the latter retrieves any events that have been emitted by the Session contracts since the last successful event fetch. These two calls happen once per minute during normal operation, but several `eth_getLogs` will be issued when oxend restarts to reload any recent events (see the [#l2-max-logs](#l2-max-logs "mention") section below for details). There are also some less frequent invocations of `eth_call`: one approximately every 10 minutes to fetch the latest reward pool balance, and another about one an hour used to fetch all contract service nodes to help ensure that the list of nodes on the contract and on the Session appchain are in sync. If you have configured backup providers then each backup will also have an `eth_blockNumber` call issued approximately every three minutes, used to check that the other nodes are up to date. Backups do not have other RPC requests made *unless* requests to the Primary provider fails, or the primary provider is too far out of sync with the Arbitrum chain. Finally, `oxend` issues a `eth_chainId` request at startup to each provider to ensure that all given providers are on the same chain (to prevent accidentally giving a provider URL for the wrong network, such as Ethereum L1, or Arbitrum testnet). These are one-time requests per provider and are not repeated (until `oxend` restarts). ### L2 Options All of the options discussed below are configured by adding to the `/etc/oxen/oxen.conf` file (or `/etc/oxen/node-NN.conf`, or `/home/USERNAME/.oxen/oxen.conf` depending on how you run oxend), with one option per line, formatted as `option=value`. > **Note:** If you are running your `oxend` binary directly rather than as a system service then you can also pass any of these on the command line, such as `oxend --option=value`, though this is mainly for testing and developer use and it is generally easier to list them in a persistent config file. #### `log-level` This setting does not directly affect the L2 provider functioning, but enabling additional logging around the L2 provider communications can be very useful to see what's happening under the hood while tweaking other options. To enable this logging add a line: ``` log-level=l2_tracker=debug ``` If you want even more verbose information about the individual requests being made, you can also turn on debug logging for the `ethyl` category where the actual HTTP requests are made: ``` log-level=l2_tracker=debug,ethyl=debug ``` Once you are happy with your L2 settings, simply delete (or comment out by adding a `#` at the beginning of the line) to turn disable the debug logging. (Leaving it on won't hurt oxend, but will make it harder to see legitimate errors or warnings from oxend in the future that get lost amid all the debug logging). #### `l2-provider` This is the most important option for most service nodes: it specifies the URL for your Arbitrum RPC provider. Generally, you create an account with the provider, get a unique URL for your node, and use that URL with `oxend`. You can specify this multiple times: the *first* listed provider will be the "primary" provider that oxend will try to use most of the time to obtain the state of the Arbitrum contracts. Any additional providers you give will be backups: these backups (along with the primary) will be periodically checked to see if the primary provider is falling behind, and if it falls too far behind the backups, one of the backups will be used instead until the primary provider catches up again. Listing a second URL, ideally from a different provider network, is generally a good idea just in case the first one goes down, becomes unreachable, or runs out of credits. Without a backup your service node would be unable to participate in creating blocks, which will lead to decommissioning or deregistration if it happens for an extended time. You can list as many backups as you want, but keep in mind that the backups only kick in if the primary fails and so a reliable primary and single reliable backup is probably enough in most cases. Example: ``` l2-provider=http://10.24.0.1/arb l2-provider=https://arbitrum-rpc-provider.qwe907v0972351x.example.com/abc?xyz=42 ``` #### `l2-refresh` This setting controls the frequency (in seconds) with which oxend queries the provider for any new contract events since its last successful query. The default is 60s (unless you are running in "l2-proxy" mode, which we discuss below), and we don't suggest going any higher than this. If you have ample provider request room, you should consider reducing this to 30 or lower: while it uses more requests, in the event of a request failure of both the primary and backup nodes (for instance, due to a momentary internet disconnection) the next request retry will come sooner. #### `l2-max-logs` `oxend`'s main mechanism of scanning the Arbitrum contracts is to use an `eth_getLogs` call, which queries the provider for all events emitted by the contract in a range of blocks. This option controls how large a range of blocks oxend is allowed to request at once. If `oxend` needs events for a larger range than this value then the request is split up into multiple requests, each requesting logs for only `l2-max-logs` blocks at a time. The setting defaults to 1000. For example, if our last successful event retrieval was 9500 blocks ago, and this is set to the default of 1000, we would issue 10 requests for \[9499-8500 ago], \[8499-7500 ago], and so on, until we catch up to the current state. This limit applies most significantly during startup, when `oxend` fetches contract logs for the last 16800 blocks (about 70 minutes) of the Arbitrum chain to ensure that it always has the last hours worth of events (plus a safety margin). At the default setting of 1000 this means 17 `eth_getLogs` requests are issued when `oxend` restarts, but after that there is generally just one per minute. If your providers allow larger range then you should increase this to whatever they allow. For example, many entry level paid tiers allow 10000 here, and increasing this to 10000 will allow oxend to make just two requests on restarts instead of 17. **Lowering this is required for some providers!** Some providers limit the maximum block range for `eth_getLogs.` For example, Infura and Alchemy free tiers limit this endpoint to requesting 500 blocks at a time, and QuickNode's free tier limits it to just 5 (which is only 1.25s of Arbitrum blocks and makes QuickNode's free tier unusable for Session Nodes). If your provider does not allow a range of 1000, you *must* configure this setting to lower it to what your provider supports; otherwise `oxend` will be unable to fetch any logs at all, and will be penalized for missing pulse quorums. Take note that Arbitrum has a 250ms block time (i.e. 4 blocks per second), and so during the normal default 60s update interval there will typically be 240 new blocks that `oxend` needs to fetch logs for. If your provider requires you to drop the `l2-max-logs` value below about 250, then you will end up having to make multiple requests every minute during normal operation just to keep up, which will likely make you run out of credits sooner. It's best to stick to providers that allow a range of at least 500 blocks for the `eth_getLogs` endpoint. #### `l2-update-cooldown` This setting is related to `l2-max-logs`, above: it defines a cooldown period between subsequent `eth_getLogs` request and can be used to avoid request (or credit) per second rate limits imposed by some providers, particularly during the initial burst during startup (see above). For example: `l2-update-cooldown=2` will force `oxend` to delay the next `eth_getLogs` request if it has been less than 2 seconds since the last request. This value defaults to disabled: that is, if oxend needs to send multiple getLogs requests, it will send the next one as soon as it gets the response to the previous one, one after another until it is finished. Some providers may need this to be set. For example, one provider used by one of Session's developers assigns a credit value of 255 credits per `eth_getLogs` request, and starts returning errors for all requests if more than 500 credits worth of requests per second are issued. If your provider has such limits, then consider setting this to 1 or 2 to add a small delay between requests to keep yourself below the limit. #### `l2-timeout` This controls how long we wait for a response from the L2 provider before giving up. When you have backup providers, a request timeout on the primary provider will trigger the same request to a backup provider. The default is 5 seconds: if your provider is sometimes slow to respond you might want to increase this, and if you know your provider is very quick and low latency, you might want to lower it to try a backup sooner. #### `l2-check-interval` This value is the interval for "all-provider" RPC height checks: when `oxend` initiates a chain update, if it has been at least this many seconds since the last height check, `oxend` will request the current chain height from all providers (primary and all backups). If the backup is too many blocks behind the backups, `oxend` will then switch to the first backup that isn't too far behind and will make all requests to that backup provider until a future all-provider check indicates that the primary node has caught up again. The default is 170s, but note that this is only triggered on the regular refresh cycle (`l2-refresh`), and so this rounds up to the next refresh cycle (and so, with a default 60s refresh cycle, that means this happen every 3 minutes, not 2min50s). This option has no effect if there are no configured backup providers. #### `l2-check-threshold` When doing all-provider RPC height checks (see the previous section) this setting controls how many blocks behind the other nodes the primary has to be before we switch to a backup. It is normal to have a few blocks variation given Arbitrum's very fast 0.25s block time, and so this allows setting how far behind the primary has to be before oxend starts using a backup. The default is 120 blocks, which is about 30 seconds worth of Arbitrum blocks, but you can lower this if you want to switch over to a backup sooner if the primary starts lagging. `oxend` will issue warnings (even without changing the log level) when a provider starts lagging more than this threshold, providing you some indicating of when this setting (and switching between primary and backup) is taking place. If you see such log warnings frequently, then you might want to consider switching to a different primary RPC provider. #### `l2-skip-chainid` This setting can be set as `l2-skip-chainid=1` if you want to skip `oxend`'s builtin check during startup to make sure that your providers are on the correct chain. This will make oxend start slightly faster, and save you one request per provider on each restart, but disables the safety check against accidentally specifying a URL to the wrong chain. ### Oxend L2 proxy For operators running multiple service nodes you can configure one or more of your oxend's as proxies, and then point all the rest of the nodes to the proxies. Only the proxy nodes make L2 provider requests, and every other node gets its L2 updates from the proxies as soon as each proxy gets new L2 data. #### `l2-proxy` #### `l2-oxend` These are the two main options controlling proxy mode: `l2-proxy` enables a node to operate as a proxy, making requests to the L2 providers, and providing those results to other `oxend`s. `l2-oxend` configures a node to *use* a proxy rather than an `l2-provider` as its source of L2 information. Some notes about all of the above controls on this page: * For a proxy-using node, the `l2-provider=...` option must *not* be listed (or must be commented out with a leading `#`) in the config file. oxend will refuse to start if both `l2-oxend` and `l2-provider` options are used at the same time. All the other `l2-...` options listed here can still be listed in the config file, but will be ignored when using an oxend proxy. * For the proxy node itself (i.e. the one making the L2 requests), all of the options described on this page apply and control how the proxy gets its information, with one difference: the `l2-refresh` setting on a node configured as proxy defaults to 30s instead of 60s, to make the default proxy a little more redundant in its attempts to fetch updates. * Proxy-using nodes do not have a refresh interval in the same way as L2 provider using nodes: each proxy they are connected to will push L2 updates to any connected nodes as soon as they are retrieved, and so effectively the proxy's refresh interval becomes the update interval of all nodes using that proxy. See [Setting up an oxend L2 proxy](/contribute-to-the-session-network/running-a-session-node/setting-up-an-oxend-l2-proxy) for a full guide! # Setting up an oxend L2 proxy Learn how to set up an oxend L2 proxy for running multiple Session Nodes. With the 11.1.2 Oxen mainnet release and 11.0.8 Session stagenet (testnet) release, a new capability for oxend has been added to proxy requests to an L2 provider. This feature is aimed in particular at people running multiple nodes. This feature works by having only 2-3 of your nodes configured with an L2 provider URL, and having all the others configured to talk to those 2-3 nodes to get Arbitrum updates, without having to use multiple or paid tier accounts for your set of nodes. This feature works through the existing oxen "quorumnet" port, and so does not need to open additional ports, but it does require some one-time configuration that this guide will walk you through. ## Step 1: Choosing your proxies It is suggested to choose least two nodes, on different servers, ideally in different data centers. The idea here is redundancy: if one of your proxy nodes has a problem, you don't want that one node to take down *all* your other nodes relying on it. Configuring 2-3 different ones on different servers avoids this risk. Note that it doesn't matter if the proxies are active service nodes or not: the main point is that they are running in service node mode so that they will have a reachable quorumnet port that the proxy-using nodes use to communicate with the proxy. In other words, even if the proxy gets deregistered or unlocks the network, it will still continue to function as a proxy. On each of these proxies, you will need to edit the /etc/oxen/oxen.conf configuration file (or, if you are using a dedicated server with a multi-sn setup, the /etc/oxen/node-XX.conf file for whichever service node on the server will be the proxy), and add configuration lines to set up the L2 provider URLs. There are a couple of config items you'll need to add to the `oxen.conf` file: one or more `l2-provider` lines specifying how the proxies themselves fetch Arbitrum data, and an `l2-proxy=FILENAME` option that specifies a file containing the pubkey of other nodes allowed to use your node as a proxy.\ \ You'll edit the file (e.g. with `nano /etc/oxen/oxen.conf`) and add some lines like this: ``` l2-provider=https://first.provider.url/abc l2-provider=https://second.provider.url/xyz l2-proxy=/etc/oxen/proxy.txt ``` It's also suggested to add the following line when setting things up the first time so that you can track the L2 proxy usage in the logs. Once everything is set up and working, you can come back and delete this line to reduce the amount of log verbosity: ``` log-level=l2_proxy=debug,l2_tracker=debug ``` Also make a note of the `service-node-public-ip=xxx` line, and, if present, the `quorumnet-port=xxx` lines. You'll need these values in Step 4. (If the quorumnet-port= line is missing, that's fine. This just means it is using the default port). On the *second* proxy node, you'll need to to reverse the order of the two l2-provider lines. That way the first proxy will use "first.provider.url" as its primary source of info, and the second will use "second.provider.url", and each one will use the other's primary source as a backup source. This is only one possible suggestion: you may want to have more backups, or use completely different providers on each proxy. ## Step 2: Whitelisting proxy-using nodes The second step we need to do is to list the service node pubkeys of all of our nodes that are allowed to use the proxy in the /etc/oxen/proxy.txt. This is relatively straightforward (if a bit tedious, if you have a lot of nodes): ``` nano /etc/oxen/proxy.txt ``` Add the pubkeys of nodes to allow, one per line. You can use comments (starting with #) in here if you like. For example: ``` abc00a97b44e7a70202f8cb1f36637b25b9efc36ecab04a5e687290d1345e715 # my favourite def647edf7706aa9d4e17ae871992dab6cd3654653960a5c1d18585c53d848a9 #9f022f08ecb801299cb43fafba721dfb7d9deb10a7734951f46b9c7c8ec1c274 1f216f4a8d132fcf7d74657dd82167a2037c5bbe40abefdf7a533133f0134601 # vps on SuperAwesomeISP! ``` This would allow access from `abc0...`, `def6...`, and `1f21...` Two important notes here: * The proxies will monitor this file for changes, so it is *not* necessary to restart the oxend proxies if you add or remove node pubkeys to the file. * If you have very old nodes (first installed in Oxen 7.x or earlier) then you may have a node with different "primary" and "ed25519" keys: for such a node with dual keys you want to use the "ed25519" pubkey, not the main service node public key. (For nodes installed since then, the primary and ed25519 pubkeys will be the same. If you are unsure, dual-key service nodes will have both a `key` and a `key_ed25519` file; unified key nodes have only the `key_ed25519` file. Alternatively, you can look up your service node on : if the Session Node Details lists separate `Session Node Public Key` and `Session Node Auxiliary Pubkey` values then you want to use the latter (Auxiliary) key. ## Step 3: Restart the proxy nodes Now it's time to restart the proxy oxends with the new proxy-enabling configuration to set themselves up to allow proxy requests: ``` systemctl restart oxen-node ``` (If you are using a multi-sn config and have configured node "00" as the proxy, then you would use `oxen-node@00` instead of just `oxen-node`). ## Step 4: Configure the proxy-using nodes All of the nodes using proxies now need to be configured to get their L2 data from the proxies. To do this, you edit the config file of the proxy-using node (e.g. `nano /etc/oxen/oxen.conf`) and add lines to the config file for each oxend proxy such as: ``` l2-oxend=10.7.8.9:22025/1f203f36faecd16d1c1c9514143d4a6715be1b16e160760f57942ab6da3e4ed5 l2-oxend=10.99.88.77:22025/1f509f05c49da0478818ee5772c6e15b457b0923ece38d034d9d4f601a161419 ``` Also look for any existing `l2-provider=...` lines and either delete them or comment them out by adding a `#` at the beginning of the line: oxend does not support using L2 oxend proxies and direct L2 RPC providers at the same time. You need to replace the IPs, ports and pubkeys listed here with those of your proxy nodes. The whole line is logged by the proxy during startup, such as: ``` [2025-03-13 16:51:20] [+0.011s] [l2_proxy:info|l2_tracker_proxy.cpp:150] L2 proxy whitelist intialized with 3 pubkeys [2025-03-13 16:51:20] [+0.011s] [global:info|cryptonote_core.cpp:763] Running as an L2 proxy reachable at: 10.23.45.67:22501/9f301f21400a69a43286b8f5add7faec26b948de2862a745f71eab822ccd7b1c ``` But you don't have to get it that way: The IP and port you may have written down from Step 1; the pubkey here is the Ed25519 pubkey of the proxy. If you didn't write them down, the IP is simply the public IP of the proxy, and the port is the quorumnet port of the proxy: by default this is 22025 for mainnet nodes and 11025 for stagenet nodes, but if your proxy node config file specifies an alternative you will need to use that port value instead. The pubkey here is the node's Ed25519 pubkey, which could be different from the primary pubkey if node has dual pubkeys; see the note about this in Step 2. Once you have added the l2-oxend= line, restart the node with `systemctl restart oxen-node` (or `oxen-node@NN` for a multi-sn node). If you check the logs during startup, you should see some messages such as: ``` [2025-03-13 20:05:54] [+2.072s] [l2_proxy:info|l2_tracker_proxy.cpp:441] Connected to remote oxend L2 proxy 12345678...cdef @ tcp://1.2.3.4:22025 [2025-03-13 20:05:54] [+2.073s] [l2_proxy:info|l2_tracker_proxy.cpp:490] Subscribed to L2 updates from 12345678...cdef @ tcp://1.2.3.4:22025 ``` indicating that it has successfully subscribes to L2 updates from the proxy. ## All done! If you want to add new nodes in the future that use your proxies, all you need to do is add their pubkeys into your /etc/oxen/proxy.txt files on the proxies, and add the `l2-oxend=...` lines into the proxy-using oxend configs and restart the proxy-using oxends. (The proxy nodes themselves do *not* need to be restarted to pick up the proxy.txt changes). ## Advanced Configurations ### Non-service node proxy Proxies do not have to be running in service node mode at all, but you will have to make one additional config change to make the proxy accessible to other nodes if they are not (because non-service-nodes do not listen on the quorumnet port by default). The change is to add a line to the proxy's config of: ``` lmq-curve=tcp://0.0.0.0:12345 ``` This will add a listener on port 12345 (you can change this to whatever you like), accessible on the machine's IP. Note that you don't need to replace 0.0.0.0 here: that special address means to listen on all available IPs on the machine. The proxy-using nodes then specify the IP of the machine (the actual IP, *not* 0.0.0.0) and port 12345 in their config, along with the node's Ed25519 pubkey. Nothing stops you from adding this line on a service node to add an additional listener, though there is no noticeable benefit of doing on a service node compared to simply using the required quorumnet port. ### Local unix socket on the same machine If your proxy-using node is on the same machine as the proxy node itself then you can use its local oxend socket rather than the quorumnet port. In this case you would configure the proxy-using nodes using: ``` l2-oxend=ipc://PATH_TO_OXEND_SOCK ``` For example: ``` l2-oxend=ipc:///var/lib/oxen/oxend.sock ``` When using such a local unix socket connection, you do *not* append the proxy's pubkey to the l2-oxend= line, nor is it necessary to list the pubkeys of nodes accessing via the unix socket in the proxy.txt file (it won't hurt, but it isn't needed). # Staking to a Session Node Learn how to stake to Session Nodes (without needing to run your own node). Session Nodes can be run by a single contributor, or by multiple contributors who pool their SESH to meet the staking requirement of 25,000. This guide covers how to stake to a multicontributor node which is awaiting contribution. If you wish instead to register a node, you can find out how to do that [here](/contribute-to-the-session-network/running-a-session-node). > **Note:** You'll need Session Tokens (SESH) on the **Arbitrum One network** to be able to stake. If you have purchased SESH on the Ethereum network, you must bridge it to the Arbitrum One network via the [official Arbitrum bridge](https://stake.getsession.org/bridge/arbitrum) first. Please also make sure you have a small amount of ETH on the Arbitrum One network for gas. #### Step 1: Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. If you wish to stake your vesting SESH tokens, please ensure that Vesting Mode is **switched on.** #### Step 2: Navigate to the [Stake Now](https://stake.getsession.org/stake) page to view the list of nodes awaiting contribution (Available Session Nodes) The listed nodes will show the minimum and maximum contribution amounts, as well as the operator fee. #### Step 3: Once you have selected a node to stake to, hit **View** to examine the node details. From this menu you can enter the amount of SESH you wish to stake, and then hit the green 'Stake' button. #### Step 4: Your stake will be contributed to the node and once the total amount staked has reached 25,000 it will be registered on the network. After 24 hours of the node being registered and active on the network, you will begin earning rewards. > **Note:** To view rewards earned from staking vesting SESH, you'll need to **first turn off Vesting Mode**. Your rewards will be visible together with any rewards earned from non-vesting staked SESH on your [My Stakes](https://stake.getsession.org/mystakes) page. ### About the Multicontributor Operator Fee Operators can set an operator fee on their multicontributor nodes, which is collected in SESH. This fee helps operators to cover the costs of running a node. The fee is taken as a percentage of the node rewards allocated to the operator. Once the fee is deducted, the remaining rewards are distributed among all contributors (including the operator), proportional to stake amount. For example: If a node earns 1000 Session Tokens and the operator sets a 10% fee, the operator keeps 100 tokens as their fee, and the remaining 900 tokens are split based on stake amounts—so, if the operator staked 50%, they’d get 450 tokens (550 in total), and two contributors with 25% stakes each would get 225 tokens each. ### Unlocking your stake If you're contributing a stake to a node, you can request to unlock your stake under certain conditions. \ \ **Small contributors** (those contributing less than 1/4 of a full stake, or 6250 SESH) cannot initiate a unlock during the first 30 days a node operates, but can do so at any time after this initial 30-day period. The unlock period is 15 days, after which the stake can be reclaimed. \ \ **Large contributors** (those contributing 1/4 of a full stake or more than 6250 SESH) can initiate an unlock at any time, including within the first 30 days of a node’s operation. As above, the unlock period is 15 days, after which the stake can be reclaimed. # Frequently Asked Questions (FAQ) Find answers to common questions about running and staking to testnet nodes here. ## **What is the minimum and maximum I can stake to a Session node as an operator?** For single contributor nodes, you must provide the full stake of 25,000 SESH yourself. For multicontributor nodes, as the operator, you must provide a minimum stake of 6250 Session Tokens, and the remaining stake can be contributed by others. This allows for flexibility in multicontributor nodes, enabling collaboration while still requiring a minimum commitment from the operator. ## If I am running a multicontributor node, do I also have to stake SESH? Yes, if you run a multicontributor node, you are required to stake at least 6250 SESH as the node operator. This ensures you have a vested interest in the node's performance and helps secure the network by maintaining a minimum stake commitment. ## What is the multicontributor operator fee? Operators can set an operator fee on their multicontributor nodes, which is collected in SESH. This fee helps operators to cover the costs of running a node. The fee is taken as a percentage of the node rewards allocated to the operator. Once the fee is deducted, the remaining rewards are distributed among all contributors (including the operator), proportional to stake amount.\ \ For example: If a node earns 1000 Session Tokens and the operator sets a 10% fee, the operator keeps 100 tokens as their fee, and the remaining 900 tokens are split based on stake amounts—so, if the operator staked 50%, they’d get 450 tokens (550 in total), and two contributors with 25% stakes each would get 225 tokens each. ## How do staking rewards and operator fees get sent to my wallet address? SESH earned through staking rewards or operator fees on multicontributor nodes do not get automatically sent to your wallet. Instead, to save on gas fees, they are held in a smart contract until you manually claim them. You can claim rewards anytime on your [My Stakes](https://stake.getsession.org/mystakes) page. Simply hit the Claim button. Your SESH will then be sent to the rewards addressed you specified. This is either the wallet address you registered with, or a different address that you specified when configuring your node registration or stake to a multicontributor node. ## Can I specify a separate rewards address from the wallet I am registering my node with or staking from? Yes, you can specify a separate address to receive your rewards. The rewards address does not need to be the same as the wallet you are using to register your node or stake from. This allows you to direct rewards to a different wallet for added flexibility. Note that rewards are not automatically sent to your wallet. Instead, you can manually claim them anytime via your [My Stakes](https://stake.getsession.org/mystakes) page. ## How do I reserve a stake for specific contributors to my multicontributor node? To reserve a stake for specific contributors to your node, collect the wallet addresses of the contributors you wish to reserve stakes for. When registering your multicontributor node using the **Guided** setup mode, you will be prompted to reserve stakes. You can then allocate a reserved stake amount for each of your contributors. If using the **Express** setup mode, you can also edit reserved stakes when finalising your node before registering and staking. Reserving stakes is particularly useful if you are collaborating with trusted contributors or if certain stakeholders need to secure their participation in your node. ## How many contributors can I reserve stakes for on my multicontributor node? Each node can have 10 contributors staking to it, including the operator. This means you can reserve between 1 and 9 stakes for other contributors on your multicontributor node. If the full stake amount is not fully reserved, public contributors can contribute stakes to reach the full stake amount, and/or contributors with reserved stakes can increase the stake that they provide to reach the full stake amount. ## Can contributors stake more than their reserved amount on a multicontributor node? Yes, contributors can stake more than their reserved amount on a multicontributor node in the case where a node still has remaining stake available that has not been reserved. The reserved stake amount serves as a minimum threshold, ensuring contributors have a guaranteed portion they can contribute. If the full stake amount is not fully reserved, public contributors can contribute stakes to reach the full stake amount, and/or contributors with reserved stakes can increase the stake that they provide to reach the full stake amount. ## How do I activate my node once it is fully staked? If you have enabled automatic activation during registration, your node will automatically join the network once it is fully staked. If you have disabled automatic activation, you can manually activate your node to join the network when you are ready. The option to activate your node will appear on the [My Stakes](https://stake.getsession.org/mystakes) page once your node is fully staked. This can be useful if you want to ensure all configurations are correct before activating, or prevent the node from activating at a time that is inconvenient for you. ## What happens when a node gets liquidated? If a node is not exited within 7 days after becoming eligible (22 days after the initial exit request), the node becomes eligible for liquidation by other users. When a node gets liquidated, a 0.2% penalty is taken from the operator's stake: 0.03% of the operator’s stake is transferred to the liquidator, and 0.17% of the operator’s stake is returned to the Staking Reward Pool. ## What is the network-wide claims limit? To keep the Session Network secure, there is a network-wide limit on how much SESH can be claimed as rewards from the Staking Portal within a 12 hour period. This provides additional security against potential exploits. Up to 1,000,000 SESH can be claimed with a 12 hour period. The 12 hour periods span 00:00 UTC to 12:00 UTC and 12:00 UTC to 00:00 UTC. When you load the Staking Portal, it will fetch the total amount of SESH already claimed in the current claim cycle. If your claimable amount is greater than the tokens remaining in the claim limit, you'll see a "claim limit reached" screen with a countdown timer showing when the limit resets. For example, if there are 1,000 SESH remaining in the current limit and you have 999 SESH claimable, you will be able to claim and the portal will show you the claim option. However, if you have 1,001 SESH claimable, you'll see the limit reached screen and will need to wait for the next 12-hour cycle to begin. ## Can I unlock my stake from a multicontributor node before it starts operating? Yes, under certain conditions. It is not possible to unlock your stake from a multicontributor node for 24 hours after you contribute your stake. If the node has not been registered and begun to operate before this 24 hour period, you can unlock your stake. If the node has been registered and is currently operating, you can unlock your stake according to certain conditions, depending on how much you are staking (see below). ## Can I unlock my stake from a multicontributor node while it is operating? Yes, under certain conditions, depending on how much you are staking to the multicontributor node. \ \ Large contributors, who are staking more than ¼ of the full stake amount, can initiate an unlock at any time during the node's operation. The unlock period is 15 days, after which the stake can be reclaimed. \ \ Small contributors, who are staking less than ¼ of the full stake amount, cannot initiate an unlock during the first 30 days of a node's operation, but can do so at any time after this initial 30-day period. As above, the unlock period is 15 days, after which the stake can be reclaimed. # Testnet The Session [Testnet Incentive Program](https://token.getsession.org/testnet-incentive-program) ran from July 16, 2024 to May 9, 2025. While the Incentive Program is now closed, testnet will continue to be available for user testing following Session Token's TGE. \ \ To get started with testnet, drop a message into the **#testnet** channel in the [Session Token Discord](https://discord.gg/sessiontoken) expressing your interest in receiving tSESH (test Session Tokens). You will also need ETH on the Arbitrum Sepolia Test Network for gas on testnet, which is freely available from some [faucets](https://faucet.quicknode.com/arbitrum/sepolia). \ \ Once you have test SESH, you can set up your own node following this [guide](/contribute-to-the-session-network/testnet/session-stagenet-node-setup). It is also technically possible to stake to existing [multicontributor nodes](/contribute-to-the-session-network/testnet/staking-to-a-session-stagenet-multicontributor-node) on testnet, though depending on testing activity levels, there may not be many available at a given time. # Staking to a Session Stagenet Multicontributor Node ### Staking to a Stagenet Session Node Session Stagenet Nodes can be run by a single contributor, or by multiple contributors who pool their test SESH to meet the staking requirement of 20,000. This guide covers how to stake to a multi-contributor node which is awaiting contribution. If you wish instead to register a node, you can find out how to do that [here](/contribute-to-the-session-network/testnet/session-stagenet-node-setup). #### Step 1: Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. #### Step 2: Navigate to the [Stake Now](https://stake.getsession.org/stake) page to view the list of nodes awaiting contribution (Open Session Nodes) The listed nodes will show the minimum and maximum contribution amounts, as well as the operator fee. #### Step 3: Once you have selected a node to stake to, hit **View** to examine the node details. From this menu you can enter the amount of test SESH you wish to stake, and then hit the green button which reads 'Stake (Amount) SESH to Multicontributor Node' #### Step 4: Your stake will be contributed to the node and once the total amount staked has reached 20,000 it will be registered on the network and you will begin earning rewards. ### Unlocking your stake If you're contributing a stake to a node, you can also request to unlock your stake under certain conditions. \ \ **Small contributors** (those contributing less than 1/4 of a full stake) cannot initiate a unlock during the first 30 days a node operates, but can do so at any time after this initial 30-day period. As above, the unlock period is 2 days (15 days on mainnet), after which the stake can be reclaimed. \ \ **Large contributors** (those contributing 1/4 of a full stake or more) can initiate an unlock at any time, including within the first 30 days of a node’s operation. As above, the unlock period is 2 days (15 days on mainnet), after which the stake can be reclaimed. # Session Stagenet Node Setup This guide will walk you through the complete process of setting up, staking, and running a stagenet Session Node. ## Running a stagenet Session Node You can run the stagenet Session Node software on any device running a supported operating system, but for the purposes of this guide, we'll assume you will be setting up a stagenet Session Node on a remote Ubuntu or Debian server. If you're new to Linux or running servers in general, this is the most straightforward approach. If you're more experienced and would prefer to run your stagenet Session Node on a different operating system, you'll need to modify the syntax of some commands to suit your system of choice. #### **Running a stagenet Session Node: Requirements** These are the current basic requirements for running a stagenet Session Node. Note that these are generally much less than required for a mainnet node!
SpecRequirement
Latest stagenet Session Node softwareLatest stagenet Session Node .deb packages (installed via the steps below) or latest dev branch build from source.
Server operating systemUbuntu 20.04+ (latest LTS recommended) or Debian 11+ (latest stable recommended)
Storage2GB or more
RAM2GB
Connectivity100Mb or faster
#### Stagenet Session Nodes in a nutshell * A stagenet Session Node starts as a full node on the Oxen stagenet blockchain. * The full node becomes a stagenet Session Node when the owner locks the required amount of SESH (see below) and submits a registration transaction. * Once accepted by the network, the stagenet Session Node starts performing node operations and becomes eligible to earn rewards in the form of test SESH. **Stagenet Session Node functionality** Stagenet Session Nodes: * Monitor the Arbitrum Sepolia test network for new registrations and departures. * Provide signatures required to withdraw rewards via Arbitrum * Monitor other stagenet Session Nodes and vote on their performance * Produce new blocks for the network via [Pulse PoS](https://docs.oxen.io/oxen-docs/about-the-oxen-blockchain/pulse-pos-on-oxen) * Receive, store, and forward encrypted Session messages (not active currently)\* * Route Lokinet traffic (not active currently)\* * Are called into quorums that give them authority over Blink transactions (not active currently)\* *\*As of July 16, 2024, Stagenet Session Nodes will only run the oxend-stagenet program, and do not currently run the Storage Server or Lokinet programs. As these programs are integrated into future iterations of stagenet and testnet Session Nodes, the functionality and requirements of nodes may change accordingly.* ## Stagenet Session Node set-up for new users ### **Step 1: Obtaining a server** Choosing where to set up your stagenet Session Node is the first and most critical decision you will face in setting up and running your node. There are a number of factors to consider. Because you will be locking up test SESH as part of operating your stagenet Session Node, you will want to ensure, at a minimum, that your server meets the technical requirements given above. Your aim is to provide a stable, reliable server with good network connectivity, so that data can be efficiently routed to and from your node. An underpowered or poorly connected node will have a poor response time and add latency to the network for all users whose traffic passes through it, resulting in a less than optimal experience. It is possible to run a stagenet Session Node alongside an existing (mainnet) Oxen Service Node without interfering with the mainnet Node. Note that this will modestly increase the VPS requirements and should only be done if the mainnet Node has excess resources. If your server goes down while staked, your stagenet Session Node could be [deregistered from the network](https://docs.oxen.io/oxen-docs/using-the-oxen-blockchain/oxen-service-node-guides/service-node-deregistration) and your test SESH locked for 30 days (without receiving rewards). The simplest and cheapest way to host a server such as a stagenet Session Node is to lease a Virtual Private Server (VPS). There are literally hundreds of options when it comes to VPS providers, but some of the more commonly chosen companies and products are listed below. The costs referenced in the table below are currently reflective of pricing relevant for an Oxen Service Node, and running a stagenet Session Node will likely be lower cost. | Hosting Provider | Product Name | Cost Per Month ($USD) | | ---------------- | ----------------- | --------------------- | | Netcup | VPS 1000 G8 | 10.50 | | Evolution Host | STARTER | 5.50 | | Online.net | Start-2-S-SSD | 13.99 | | Scaleway | START1-M | 9.33 | | OVH | VPS SSD 2 | 7.61 | | Leaseweb | Virtual Server XL | 34.45 | | Digital Ocean | 4 GB, 2 vCPUs | 24 | | Linode | 4 GB, 2 vCPUs | 20 | | Feral Hosting | Neon Capability | 19.68 | | Trabia | VDS-8G | 38.54 | | Hetzner | EX41-SSD (30 TB) | 39.71 | Note: Session does not endorse any of these providers. This list is merely a selection of some of the popular options at the time of writing. Of course, this popularity comes at the expense of decentralisation. A useful resource in choosing a less common VPS provider is [ExoticVM](https://www.exoticvm.com/). Another good one is [Server Hunter](https://www.serverhunter.com/). In any case, do not just settle on the first provider you encounter. No two are alike. Do your own research and choose a provider that seems professional, reputable and fits your budget. The better ones will utilise [KVM](https://www.linux-kvm.org/page/Main_Page) [virtualisation technology](https://www.tradingfxvps.com/kvm-vs-vmware-vs-openvz-vs-xen/). In particular, you should steer clear of any VPS which uses OpenVZ. This is an incomplete form of virtualisation that allows VPS capacity to be oversold, and is usually incompatible with the full Session Node software. While it may function for the current stagenet, virtual machines created with it often lack a `/dev/tun` device, which effectively prevent it from providing the Lokinet service required for a mainnet Node. A good VPS provider will also allow you to monitor your machine's resource consumption, seamlessly upgrade to a more powerful server at a later date, remotely reboot the host if it becomes unresponsive, and even recover or rebuild the system using out-of-band access if, for example, a bad configuration change results in lost network access. When selecting your VPS’ operating system, please choose the latest Ubuntu LTS release or latest Debian stable release (currently 24.04 and 12, respectively) if you want to be able to follow the steps below verbatim. ### Step 2: Preparing your server Every provider has a slightly different way of issuing you access to your new VPS. Most will send an email with the IP address, root username, and a root password to the VPS. To access your server, you will need an SSH client for your operating system. Because this guide will use Windows to illustrate the setup process, we’ll download [PuTTY](https://www.putty.org/). macOS and Linux users can connect by opening a terminal and typing: ``` ssh root@[your VPS IP address] ``` To connect to your VPS, you'll need to paste the provided IP address into the SSH client’s “Host Name (or IP address)” input box and click the “Open” button. The Port number can usually just be left as `22`. A terminal window will now appear, prompting you for your log-in details, username (`root`) and password, as provided by your VPS provider. When entering your password, characters will not appear in the terminal. This is normal. Hit enter after typing or pasting your password, and you should be logged in to your VPS. *Note: After logging in for the first time, the VPS may prompt you for a new password for the root account. The terminal will require you to enter the new password twice before you can start running commands. If you aren't prompted for a new root password but want to change it anyway, type sudo passwd. Choose something very secure!* #### 2.1: Hot tips for using the console on Windows Consoles don't quite work like the rest of your computer. Here are some basic tips for navigating your way around the command line! * Don't try copying something by using the usual `Ctrl + C` hotkey! If you want to copy something, do so by highlighting text and then right clicking it and selecting Copy. Pasting works by right clicking a blank area in the console and selecting Paste. * If you want to kill a process or stop something from running, press `Ctrl + C`. (This is why you shouldn't try copying something with this hotkey!) * You can always check the directory you are in by typing `pwd`, and you can list its contents by typing `ls`. * You can always return to your home directory by typing `cd` and pressing Enter. * You can move into a given directory by typing `cd ` or move back up one level by typing `cd ..`. * PuTTY allows you to easily duplicate or restart a session by right clicking the top of the window. Handy if you’re trying to do a few things at once. #### 2.2: Server preparation continued Next, update your package lists (the lists that tell your server which software is available for install or upgrade). The following command downloads package lists from their respective package repositories and "updates" them to get information on the newest versions of packages and their dependencies. It will do this for all repositories and PPAs. ``` sudo apt update ``` You'll notice a bunch of package lists were downloaded. Once this is complete run the below command to fetch new versions of any packages that came preinstalled on the system. ``` sudo apt upgrade ``` You'll be prompted to authorise the use of disk space. Type `y` and Enter to authorise. If you are prompted during the upgrade that a new version of any file is available then click the up and down arrows until you are hovering over `install the package maintainer’s version` and click Enter. Alright, good to go. Our server is now set up, up to date, and is not running as root. On to the fun part! #### 2.3: Firewall configuration If you are using a firewall then ensure that the following ports are open/reachable * Port 11022 (blockchain syncing) * Port 11025 (stagenet Session Node to stagenet Session Node) ### Step 3: Initial repository setup You only need to do this step the first time you want to set up the Oxen repository; when you've done it once, the repository will automatically update whenever you fetch new system updates. To add the `apt` repository, run the following commands. This first command installs the public key used to sign the stagenet Session Node packages: ``` sudo curl -so /etc/apt/trusted.gpg.d/oxen.gpg https://deb.oxen.io/pub.gpg ``` The second command tells `apt` where to find the packages. {% code overflow="wrap" %} ``` echo "deb https://deb.oxen.io $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/oxen.list ``` {% endcode %} If your distribution does not have `lsb_release` available, you may substitute `` in the following command with the appropriate value to match your operating system. If your VPS is running Ubuntu 24.04 as recommended in this guide, replace `` with `noble`. {% code overflow="wrap" %} ``` echo "deb https://deb.oxen.io main" | sudo tee /etc/apt/sources.list.d/oxen.list ``` {% endcode %} Other supported distributions include: * bookworm (Debian 12) * bullseye (Debian 11) * noble (Ubuntu 24.04)\ jammy (Ubuntu 22.04) * focal (Ubuntu 20.04) There are also repositories for Debian testing (`trixie` or `testing`) and unstable (`sid` or `unstable`), and the latest or upcoming Ubuntu non-LTS release is typically supported. Note, however, that none of these distribution versions are recommended for production stagenet Session Nodes. Then resync your package repositories with: ``` sudo apt update ``` ### Step 4: Getting an Arbitrum Sepolia testnet RPC provider account You will need to set up an Arbitrum Sepolia RPC provider for your stagenet-oxend to interact with the Arbitrum Sepolia network. This setup will allow your stagenet Session node to communicate with the Arbitrum Sepolia blockchain and to witness and facilitate transactions. You can use public RPC providers like Infura and Alchemy or set up your own Arbitrum Sepolia full node and connect to that node locally . Whilst Arbitrum has several RPC providers available, getting familiar with these providers will be useful for mainnet where a reliable RPC connection is required for the stability of your node. For testnet the free tier of public providers is currently sufficient to participate. * Arbitrum’s recommendations: * Infura: See and get setup with a Arbitrum Sepolia node through Infura. * Alchemy: See to get setup with an Arbitrum Sepolia node through Alchemy. For example if you were using Alchemy as an RPC provider your URL would look something like: ``` https://arb-sepolia.g.alchemy.com/v2/32bfi3gb298fbb32byfb32bf ``` *Note: The RPC URL here uses a mock API key* Find your RPC URL and copy it for use in the next step. ### Step 5: Stagenet Session Node installation and operation To install the software needed to run a stagenet Session Node, simply install the `session-stagenet-node` package: ``` sudo apt install session-stagenet-node ``` This will detect your public IP (or allow you to enter it yourself), ask for your Arbitrum Sepolia testnet L2 provider URL, and create the `/etc/oxen/stagenet.conf` configuration file with the necessary additional settings to run a stagenet Session Node. #### 5.1: Interacting with the running `oxend-stagenet` So as to not interfere with current mainnet oxend nodes, the stagenet packaging installs its binary under the \`oxend-stagenet\` command. If you run the `oxend-stagenet` command with an appended command (note that `sudo` is not required!), the `oxend-stagenet` command forwards this instruction to the running `oxend-stagenet`. So, for example, to get the current `oxend-stagenet` status you can run you would run: ``` oxend-stagenet status oxend-stagenet print_sn_status ``` To see the output log of your node you can run the following command: ``` journalctl -u oxen-stagenet-node -f ``` This is useful to see if your node is syncing with the blockchain and to see other diagnostic messages that may come up from time to time. (Press `Ctrl-C` to stop watching the log). For a full list of supported commands run: ``` oxend-stagenet help ``` You can also get basic statistics (such as uptime proof and ping times) on the running daemon from the `systemctl status` commands: ``` systemctl status oxen-stagenet-node ``` ### Step 6: Stagenet Session Node Registration #### 6.1: Retrieving your wallet address You'll need your Ethereum wallet address to register your stagenet Session Node. Navigate to your Ethereum wallet and copy your wallet address. #### 6.2a: Individual Staking To run a stagenet Session Node as the sole contributor, you'll need: * A fully synchronized, up-to-date Oxen daemon running on your stagenet Session Node * An Ethereum wallet with at least 20,000 test SESH in it (to meet the staking requirement to register your stagenet Session Node), and sufficient test ETH on the Arbitrum Sepolia network for gas. If you don't have test SESH, join the [Session Token Discord](https://discord.gg/sessiontoken) to request some via the [referral program](https://token.getsession.org/blog/testnet-referrals). #### 6.2b: Multicontributor Staking To run a stagenet multicontributor Session Node as the operator, you'll need: * A fully synchronized, up-to-date Oxen daemon running on your stagenet Session Node * An Ethereum wallet with at least 5,000 test SESH in it (to meet the operator staking requirement to register your stagenet Session Node), and sufficient test ETH on the Arbitrum Sepolia network for gas. #### 6.3: Preparing your node for registration Log in (if not already logged in) to the VPS running the stagenet Session Node, then run the following command: ``` oxend-stagenet register [your ETH address] ``` The daemon will output something which looks similar to: {% code overflow="wrap" %} ``` Submitting operator-only information to stake.getsession.org, please wait. Submitted operator-only information to the staking website successfully! View your registration at: https://stake.getsession.org/register/[Session Node ID] ``` {% endcode %} *NOTE: This information will be automatically submitted to the stagenet staking website to help with creating the transaction on the Sepolia testnet.* #### 6.4a: Registering your single contributor Session Node To register and stake your stagenet Session Node, ensure your Etherem wallet has a balance of at least 20,000 test SESH as well as sufficient test ETH for gas. Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. On the **Register** page, the node you have prepared registration for will appear in the 'Your Prepared Registrations' list.\ \ View the prepared node’s details and confirm your registration and stake of 20,000 test SESH. #### 6.4a: Registering your multicontributor Session Node To register and stake your stagenet Session Node, ensure your Ethereum wallet has a balance of at least 5,000 test SESH as well as sufficient test ETH for gas. Navigate to the [Staking Portal](https://stake.getsession.org/) and connect your wallet. On the **Register** page, the node you have prepared registration for will appear in the 'Your Prepared Registrations' list. When you view the prepared node's details you can customise your stake amount and operator fee. Change these to whatever you wish, keeping in mind that the minimum Stake Amount for the operator is 5,000 test SESH. Once you have confirmed these values, hit 'Create & Stake to Multicontributor Node' You node will be listed on the [Staking Portal](https://stake.getsession.org/) as an Open Session Node, and anyone can stake to it from there. Once your node has reached full 20,000 test SESH stake amount, it will automatically be registered on the network. ### Step 7: Stagenet Session Node status check After you've staked to your stagenet Session Node, you can check that stagenet Session Node is running, recognised, and eligible to earn test SESH rewards on the [My Stakes](https://stake.getsession.org/mystakes) page. *Note: It can take a few minutes for your node to become fully registered and appear in the “My Stakes” page after submitting the Aribtrum Sepolia transactions* ## Operating your node ### Keeping your binaries up to date When a new release is available, upgrading is as simple as syncing with the repository: ``` sudo apt update ``` Then installing updates using: ``` sudo apt upgrade ``` *Note that this will install both updated* `oxend-stagenet` *packages and any available system updates (this is generally a good thing!)* During the upgrade, all instances of `oxend-stagenet` will be restarted if they are currently running in order to switch to the updated `oxend-stagenet`. If for some reason you want to install only Oxen package upgrades but not other system package updates, then instead of the `sudo apt upgrade` you can use: ``` sudo apt install session-stagenet-node ``` ### Monitoring Use the [My Stakes](https://stake.getsession.org/mystakes) page to monitor the status of your staked node. ### Back-ups You should immediately make a backup of your Stagenet Session Node's secret keys. This will allow you to migrate your node to a different hardware provider if necessary in the future. **IMPORTANT: These keys should always remain secret and should never be shared with anyone. Sharing these keys can result in the loss of funds or deregistration of your node.** The command to reveal the ed25519 secret keys is: ``` oxen-sn-keys-snapshot show /var/lib/oxen/stagenet/key_ed25519 ``` The command to reveal your BLS secret keys is: ``` oxen-sn-keys-snapshot show /var/lib/oxen/stagenet/key_bls ``` Alternatively, you can use a tool like *scp* to copy these files off-host for safekeeping. ### Restoration If you backed up your keys and want to restore an unregistered node to use those backed up keys you can use the following commands. The command to restore an ed25519 key into a file is: ``` oxen-sn-keys-snapshot restore /var/lib/oxen/stagenet/key_ed25519 ``` The command to restore BLS key into a file is: ``` oxen-sn-keys-snapshot restore-bls /var/lib/oxen/stagenet/key_bls ``` Those commands will create a new key file with the correct formatting called “key\_ed25519” and “key\_bls” respectively, if you want to overwrite an existing key file you can pass the “-- overwrite” flag as such: ``` oxen-sn-keys-snapshot restore --overwrite /var/lib/oxen/stagenet/key_ed25519 ``` For BLS keys: ``` oxen-sn-keys-snapshot restore-bls --overwrite /var/lib/oxen/stagenet/key_bls ``` You can choose either to overwrite your existing key files in the /var/lib/oxen/stagenet directory using this command or create new key files and swap them out with the existing files, once keys are overwritten or swapped your node can be restarted with the following command: ``` systemctl restart oxen-stagenet-node ``` IMPORTANT: Never remove or replace keys on an active, registered stagenet Session Node! ### Updating L2 Providers and additional node configuration You can reconfigure your Session by modifying the file at `/etc/oxen/stagenet.conf` where settings are kept for the current running instance. In `/etc/oxen/stagenet.conf` each line denotes a configurable option. \ \ For example, in the following, the Session node is configured to use `http://example.com` as the primary L2 provider and `http://backup.example.com` as a backup if the first provider falls behind. ``` data-dir=/var/lib/oxen/stagenet log-file=/var/log/oxen/stagenet.log service-node=1 stagenet=1 service-node-public-ip= l2-provider=http://example.com l2-provider=http://backup.example.com ``` Some additional options are available for advanced users to configure how the Session node talks to the L2 provider: * `l2-refresh` Specify the time (in seconds) between refreshes of the Ethereum L2 provider current state (default is 60) * `l2-timeout` Specify the timeout (in seconds) for requests to the L2 provider current state; if multiple providers are configured then after a timeout the next provider will be tried (default is 5) * `l2-max-logs` Specify the maximum number of logs we will request at once in a single request to the L2 provider. If more logs are needed than this at once then multiple requests will be used (default is 1000). * `l2-check-interval` When multiple L2 providers are specified, this specifies how often (in seconds) all of them should be checked to see if they are synced and, if not, switch to a backup provider. Earlier L2 providers will be preferred when all providers are reasonably close (default is 170) * `l2-check-threshold` When multiple L2 providers are specified, this is the threshold (in number of blocks) behind the best provider height before a given provider is considered out of sync (default is 120). An exhaustive list of available options can be found by running `oxend-stagenet --help`. After making your changes, you must restart your node for the new settings to apply. Use the following command: ``` systemctl restart oxen-stagenet-node ``` ### Unlocking your stake Stagenet Session Nodes will continually earn test SESH rewards indefinitely until an exit is requested or the node becomes deregistered. To request an exit to reclaim your test SESH stake, simply open the [Staking Portal](https://stake.getsession.org/) and navigate to the [My Stakes](https://stake.getsession.org/mystakes) page. You can then click Request Exit for any stake you wish to initiate an unlock for. Your stagenet Session Node will become eligible to exit 1 day after the initial request (and after 15 days on mainnet). When a stagenet Session Node has become eligible to exit (after 1 day has elapsed after an exit request), the node must formally exit the network within 2 hours of becoming eligible (or within 15 days after becoming eligible to exit on mainnet). Simply click the Exit button on the node in the Staking Portal. After exiting, you can claim your stake by clicking the Claim button on your My Stakes page. If the node is not removed within 2 hours becoming eligible to exit (or 7 days after becoming eligible on mainnet, 22 days after the initial exit request), the node becomes eligible for liquidation by other users. When a node gets liquidated, a 0.2% penalty is taken from the operator's stake: 0.03% of the operator’s stake is transferred to the liquidator, and 0.17% of the operator’s stake is returned to the Staking Reward Pool.
### Deregistrations Deregistrations can be issued at any point during the active lifecycle of a stagenet Session Node, including during the period after requesting an exit. Deregistration removes your stagenet Session Node from the network, and your stake(s) become locked and unspendable for 2 days (30 days on mainnet) from the block in which the stagenet Session Node was deregistered. After this period, operator and contributors can retrieve their stakes by clicking the Claim button in the Staking Portal. Receiving a deregistration **after** the node's participant(s) have already submitted an exit request overrides the 1 day stake unlock time (15 days on mainnet), and sets the unlock time to 2 days (30 days on mainnet). There are currently bugs affecting deregistrations, and development work is underway to optimise this process. Once finalized, this is how liquidations will work in the case of a deregistration: To avoid losing 0.2% of their stake to the liquidation penalty, operators can manually exit their node by clicking the Exit button in the Staking Portal. The stake will still remain locked for 30 days. If the node has not been manually exited within 2 hours following deregistration (7 days on mainnet), it is eligible for liquidation. Running a stagenet Session Node during will be more challenging than running an Oxen Service Node and deregistrations may be more likely. Please stay up to date with changes and ongoing development via [Discord](https://discord.com/invite/Xj3HpbWxbA). ### Conclusion Well done! Your stagenet Session Node is configured, operational, and will now begin receiving test SESH rewards. Having trouble? Head to the [Session Token Discord](https://discord.com/invite/Xj3HpbWxbA) to access support. # Setting up an oxend L2 proxy With the 11.1.2 Oxen mainnet release and 11.0.8 Session stagenet (testnet) release, a new capability for oxend has been added to proxy requests to an L2 provider. This feature is aimed in particular at people running multiple nodes. This feature works by having only 2-3 of your nodes configured with an L2 provider URL, and having all the others configured to talk to those 2-3 nodes to get Arbitrum updates, without having to use multiple or paid tier accounts for your set of nodes. This feature works through the existing oxen "quorumnet" port, and so does not need to open additional ports, but it does require some one-time configuration that this guide will walk you through. ## Step 1: Choosing your proxies It is suggested to choose least two nodes, on different servers, ideally in different data centers. The idea here is redundancy: if one of your proxy nodes has a problem, you don't want that one node to take down *all* your other nodes relying on it. Configuring 2-3 different ones on different servers avoids this risk. Note that it doesn't matter if the proxies are active service nodes or not: the main point is that they are running in service node mode so that they will have a reachable quorumnet port that the proxy-using nodes use to communicate with the proxy. In other words, even if the proxy gets deregistered or unlocks the network, it will still continue to function as a proxy. On each of these proxies, you will need to edit the /etc/oxen/oxen.conf configuration file (or, if you are using a dedicated server with a multi-sn setup, the /etc/oxen/node-XX.conf file for whichever service node on the server will be the proxy), and add configuration lines to set up the L2 provider URLs. There are a couple of config items you'll need to add to the `oxen.conf` file: one or more `l2-provider` lines specifying how the proxies themselves fetch Arbitrum data, and an `l2-proxy=FILENAME` option that specifies a file containing the pubkey of other nodes allowed to use your node as a proxy.\ \ You'll edit the file (e.g. with `nano /etc/oxen/oxen.conf`) and add some lines like this: ``` l2-provider=https://first.provider.url/abc l2-provider=https://second.provider.url/xyz l2-proxy=/etc/oxen/proxy.txt ``` It's also suggested to add the following line when setting things up the first time so that you can track the L2 proxy usage in the logs. Once everything is set up and working, you can come back and delete this line to reduce the amount of log verbosity: ``` log-level=l2_proxy=debug,l2_tracker=debug ``` Also make a note of the `service-node-public-ip=xxx` line, and, if present, the `quorumnet-port=xxx` lines. You'll need these values in Step 4. (If the quorumnet-port= line is missing, that's fine. This just means it is using the default port). On the *second* proxy node, you'll need to to reverse the order of the two l2-provider lines. That way the first proxy will use "first.provider.url" as its primary source of info, and the second will use "second.provider.url", and each one will use the other's primary source as a backup source. This is only one possible suggestion: you may want to have more backups, or use completely different providers on each proxy. ## Step 2: Whitelisting proxy-using nodes The second step we need to do is to list the service node pubkeys of all of our nodes that are allowed to use the proxy in the /etc/oxen/proxy.txt. This is relatively straightforward (if a bit tedious, if you have a lot of nodes): ``` nano /etc/oxen/proxy.txt ``` Add the pubkeys of nodes to allow, one per line. You can use comments (starting with #) in here if you like. For example: ``` abc00a97b44e7a70202f8cb1f36637b25b9efc36ecab04a5e687290d1345e715 # my favourite def647edf7706aa9d4e17ae871992dab6cd3654653960a5c1d18585c53d848a9 #9f022f08ecb801299cb43fafba721dfb7d9deb10a7734951f46b9c7c8ec1c274 1f216f4a8d132fcf7d74657dd82167a2037c5bbe40abefdf7a533133f0134601 # vps on SuperAwesomeISP! ``` This would allow access from `abc0...`, `def6...`, and `1f21...` Two important notes here: * The proxies will monitor this file for changes, so it is *not* necessary to restart the oxend proxies if you add or remove node pubkeys to the file. * If you have very old nodes (first installed in Oxen 7.x or earlier) then you may have a node with different "primary" and "ed25519" keys: for such a node with dual keys you want to use the "ed25519" pubkey, not the main service node public key. (For nodes installed since then, the primary and ed25519 pubkeys will be the same. If you are unsure, dual-key service nodes will have both a `key` and a `key_ed25519` file; unified key nodes have only the `key_ed25519` file. Alternatively, you can look up your service node on : if the Session Node Details lists separate `Session Node Public Key` and `Session Node Auxiliary Pubkey` values then you want to use the latter (Auxiliary) key. ## Step 3: Restart the proxy nodes Now it's time to restart the proxy oxends with the new proxy-enabling configuration to set themselves up to allow proxy requests: ``` systemctl restart oxen-node ``` (If you are using a multi-sn config and have configured node "00" as the proxy, then you would use `oxen-node@00` instead of just `oxen-node`). ## Step 4: Configure the proxy-using nodes All of the nodes using proxies now need to be configured to get their L2 data from the proxies. To do this, you edit the config file of the proxy-using node (e.g. `nano /etc/oxen/oxen.conf`) and add lines to the config file for each oxend proxy such as: ``` l2-oxend=10.7.8.9:22025/1f203f36faecd16d1c1c9514143d4a6715be1b16e160760f57942ab6da3e4ed5 l2-oxend=10.99.88.77:22025/1f509f05c49da0478818ee5772c6e15b457b0923ece38d034d9d4f601a161419 ``` Also look for any existing `l2-provider=...` lines and either delete them or comment them out by adding a `#` at the beginning of the line: oxend does not support using L2 oxend proxies and direct L2 RPC providers at the same time. You need to replace the IPs, ports and pubkeys listed here with those of your proxy nodes. The whole line is logged by the proxy during startup, such as: ``` [2025-03-13 16:51:20] [+0.011s] [l2_proxy:info|l2_tracker_proxy.cpp:150] L2 proxy whitelist intialized with 3 pubkeys [2025-03-13 16:51:20] [+0.011s] [global:info|cryptonote_core.cpp:763] Running as an L2 proxy reachable at: 10.23.45.67:22501/9f301f21400a69a43286b8f5add7faec26b948de2862a745f71eab822ccd7b1c ``` But you don't have to get it that way: The IP and port you may have written down from Step 1; the pubkey here is the Ed25519 pubkey of the proxy. If you didn't write them down, the IP is simply the public IP of the proxy, and the port is the quorumnet port of the proxy: by default this is 22025 for mainnet nodes and 11025 for stagenet nodes, but if your proxy node config file specifies an alternative you will need to use that port value instead. The pubkey here is the node's Ed25519 pubkey, which could be different from the primary pubkey if node has dual pubkeys; see the note about this in Step 2. Once you have added the l2-oxend= line, restart the node with `systemctl restart oxen-node` (or `oxen-node@NN` for a multi-sn node). If you check the logs during startup, you should see some messages such as: ``` [2025-03-13 20:05:54] [+2.072s] [l2_proxy:info|l2_tracker_proxy.cpp:441] Connected to remote oxend L2 proxy 12345678...cdef @ tcp://1.2.3.4:22025 [2025-03-13 20:05:54] [+2.073s] [l2_proxy:info|l2_tracker_proxy.cpp:490] Subscribed to L2 updates from 12345678...cdef @ tcp://1.2.3.4:22025 ``` indicating that it has successfully subscribes to L2 updates from the proxy. ## All done! If you want to add new nodes in the future that use your proxies, all you need to do is add their pubkeys into your /etc/oxen/proxy.txt files on the proxies, and add the `l2-oxend=...` lines into the proxy-using oxend configs and restart the proxy-using oxends. (The proxy nodes themselves do *not* need to be restarted to pick up the proxy.txt changes). ## Advanced Configurations ### Non-service node proxy Proxies do not have to be running in service node mode at all, but you will have to make one additional config change to make the proxy accessible to other nodes if they are not (because non-service-nodes do not listen on the quorumnet port by default). The change is to add a line to the proxy's config of: ``` lmq-curve=tcp://0.0.0.0:12345 ``` This will add a listener on port 12345 (you can change this to whatever you like), accessible on the machine's IP. Note that you don't need to replace 0.0.0.0 here: that special address means to listen on all available IPs on the machine. The proxy-using nodes then specify the IP of the machine (the actual IP, *not* 0.0.0.0) and port 12345 in their config, along with the node's Ed25519 pubkey. Nothing stops you from adding this line on a service node to add an additional listener, though there is no noticeable benefit of doing on a service node compared to simply using the required quorumnet port. ### Local unix socket on the same machine If your proxy-using node is on the same machine as the proxy node itself then you can use its local oxend socket rather than the quorumnet port. In this case you would configure the proxy-using nodes using: ``` l2-oxend=ipc://PATH_TO_OXEND_SOCK ``` For example: ``` l2-oxend=ipc:///var/lib/oxen/oxend.sock ``` When using such a local unix socket connection, you do *not* append the proxy's pubkey to the l2-oxend= line, nor is it necessary to list the pubkeys of nodes accessing via the unix socket in the proxy.txt file (it won't hurt, but it isn't needed).