A directory of guides for setting up and maintaining your Oxen Service Node.
How to configure a server as an Oxen Service Node (quickly)
How to configure a server as an Oxen Service Node (in depth)
How to stake to an Oxen Service Node using the Oxen GUI Wallet.
Explanation of the conditions under which a service node may be deregistered (removed from the network), and some tips on how to avoid deregistration.
Some handy tips and tools for maintaining your Oxen Service Node.
A simple calculator to help you estimate the rewards you should receive from operating an Oxen Service Node. Check it out:
A handy Telegram bot which can report on service node status, including uptime alerts and reward notifications.
This document explains how to stake via the Oxen GUI Wallet.
The latest version of the wallet can be downloaded here.
Please keep in mind, one can only stake via an open pool with the GUI wallet.
Open the Oxen GUI Wallet, enter your password, and let it fully sync to the latest blockheight.
Click on the SERVICE NODE button.
On this step you will need to enter the service node public key obtained from the node operator (or OxenSN) and the amount of Oxen you are contributing to the node.
This can be done automatically by clicking STAKE on one of the listed Service Nodes awaiting contribution in the wallet interface.
Once that is filled out, simply hit the STAKE button.
Please note, if you receive an error at this step you will need to click the
SWEEP ALLbefore you can stake from your wallet.
Congratulations, you're now staked!
If you have questions or need help with this guide feel free to reach out to us on Discord or Telegram.
Deregistration rules are used to manage the network in a decentralised way by having Oxen Service Nodes police each other's performance, ensuring all operational service nodes are up to date and performing adequately to maintain a healthy network.
Each Oxen Service Node can be in one of four states: awaiting, active, decommissioned or deregistered.
State
Description
Awaiting
Service node is awaiting the staking requirement being met.
Active
Service node is staked, performing tasks as required, and receiving rewards.
Decommissioned
Service node is not performing tasks as required or is not meeting uptime standards, and has been put into an inactive state where it does not receive rewards.
Deregistered
Service node has been inactive for too long, and has been deregistered.
Active Oxen Service Nodes earn "credits" which are then used up during any periods where the service node goes offline (or otherwise stops meeting network requirements) to stop a deregistration from occuring. A new service node starts out with INITIAL_CREDIT, and then builds up CREDIT_PER_DAY for each day the service node remains active, up to a maximum of DECOMMISSION_MAX_CREDIT.
Variable
Value
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 Oxen Service Node stops sending uptime proofs, a quorum of service nodes will analyse whether the service node has built up enough credits (at least MINIMUM). If so, instead of submitting a deregistration, the quorum instead submits a decommission. This removes the service node from the list of active service nodes, both for rewards and for any active network duties.
If the service node comes back online (i.e. starts sending the required performance proofs again) before its credits run out, a quorum will reinstate the service node using a recommission transaction, which adds the service node back to the bottom of the service node reward list, and resets the node's accumulated credits to 0. If the service 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.
A testing quorum is a random set of 10 Oxen Service Nodes that are required to test a portion of the network for uptime proofs and service node IP changes. At each block, a new quorum is formed, and this quorum is required to test 50 service nodes or 1% of the network.
If 7 of the 10 service nodes in a quorum (a "supermajority") vote that a service node is malicious or not meeting the minimum requirements then they will create a State_Change transaction to decommission or deregister the service node, or drop it to the bottom of the rewards list.
Task
Description
Uptime Proofs
The quorum will check to see if a service node has provided uptime proofs within the last 2 hours. If a Service Node is found to have 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
The quorum checks to see if the SN has advertised more than one IP to the network in the last 24 hours. If a service node's advertised IP has changed, it will be forced to the bottom of the service node reward list.
Checkpointing
A state change transaction changes the state of an Oxen Service Node. Typically, state change transactions are only created when a quorum comes to a consensus about a given service node's activities or lack thereof.
The only state change transaction that can be created by anyone is the Register transaction, which changes the state of a service node from awaiting to active.
State_Change_Transaction
Description
Register TX
A transaction (lock transfer) created from the client registering the service node.
State Change: Awaiting -> Active
Note: This is not a quorum transaction.
Decommission TX
The service node is temporarily deregistered; 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
The service node is added back to the service node list and placed at the bottom of the rewards list.
Stage Change: Decommissioned -> Active
IP Change TX
The service node is put at the bottom of the rewards list as punishment for changing its IP. Stage Change: N/A (no change)
Deregister TX
The service node is deregistered.
State Change: Active -> Deregistered / Decommissioned -> Deregistered
The quorum checks that each service node within the quorum has provided a hash of a block for a specific block height (refer to for more information on this procedure). If a service 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.
Thinking of running an Oxen Service Node? Awesome! The guide below will help you configure a device with the necessary Service Node software packages, and stake $OXEN to register the node on the Oxen network.
Note: This guide assumes some familiarity with the command line and running a Linux server. For a more detailed walkthrough, check out our full Service Node set-up guide.
One of:
Debian 12 ("bookworm")
Debian 11 ("bullseye")
Ubuntu 22.04 ("jammy")
Ubuntu 20.04 ("focal")
Recommended: the latest Debian stable or Ubuntu LTS release (12 and 22.04, respectively, as of the time of writing).
Note: There are strict uptime requirements for Service Nodes (see Service Node deregistration). It is strongly discouraged to run a Service Node on a device that will not be continuously on-line. We recommend running your Service Node on a VPS with a reputable provider.
If you are using a firewall then you should ensure that the following ports (TCP unless otherwise noted) are open and reachable:
Port 22020 (storage server connectivity; requires both TCP and UDP)
Port 22021 (client to storage server)
Port 22022 (blockchain syncing)
Port 22025 (Service Node to Service Node)
Port 1090 (Lokinet router data; UDP only)
Configuring a new Oxen Service Node is as simple as running the following 4 commands on the Linux server you want to become a node (these commands will work on Debian and Ubuntu; modifications may be necessary for other Linux distributions):
The services will run via systemd as oxen-node.service, oxen-storage-server.service, and lokinet-router.service.
Once the blockchain has synced to the server (which can take several hours), your Service Node will be ready to be staked. You can use the oxend status command to check the sync progress.
Alternatively, the blockchain can typically be downloaded in a fraction of the time required to sync it via the Service Node network, using the following command:
To add the Oxen repository, run the following commands.
Note: You only need to follow this step once, to set up the repository. The repository will subsequently be automatically updated whenever you fetch new system updates.
This first command installs the public key used to sign the Oxen Service Node packages:
The second command tells apt where to find the packages. Note: Replace <DISTRO>with the appropriate value to match your operating system.
To find your <DISTRO> run the following command: lsb_release -sc
Alternatively, <DISTRO> can be found in the following list:
sid (Debian testing/unstable)
bullseye (Debian 11)
buster (Debian 10)
jammy (Ubuntu 22.04)
focal (Ubuntu 20.04)
bionic (Ubuntu 18.04)
Then resync your package repositories with:
To configure your Service Node, simply install the oxen-service-node package:
This will detect your public IP (or allow you to enter it yourself) and automatically update the /etc/oxen/oxen.conf configuration file with the necessary additional settings to run a Service Node.
Congratulations! Your Service Node is now ready to be registered and staked.