Single Address Staking
This guide provides an overview of verifying stake addresses for Horizen Super Nodes along with links to specific instructions and resources.
About Stake Verification
The Horizen Stake Verification Tool is an application used to verify ownership of a transparent address used to stake ZEN for Super Nodes. This feature is known as Single Address Staking (SAS) and provides multiple benefits:
Only one stake address is needed for multiple nodes instead of one for each node
The destination address of payouts can be different than the stake address removing the need for batch withdrawal transactions from individual stake addresses
The payouts can be split across multiple addresses (up to 5) with varying percentages of the total
Total transaction count can be reduced, improving wallet performance
The stake balance can be increased and new nodes assigned without having to create new addresses
How The Ownership Verification Works
A stake address is verified by sending a deterministically derived amount of ZEN from the stake address back to the same address and submitting the resulting transaction id and the information used to derive the amount back to the node tracking server.
In simple terms, a small predetermined amount of ZEN is sent from a stake address and the results are sent to the tracking system to be verified. Once the address is verified it can be populated with one or more stake amounts (e.g. at least 1500 ZEN for three Super Nodes). Holding more than the required stake for the number of nodes you’re running does not result in any additional rewards.
Overview Of The Verification Process
The Stake Verification Tool has three general steps and supports multiple methods to complete the verification process:
Create a stake verification request. This generates the amount needed to send from the stake address either from a wallet or optionally creates a raw transaction to sign.
Send the verification amount from your wallet and obtain the transaction id or sign the raw transaction with your private key using signtxtool (signtxtool can do this offline).
Send the verification request to the desired Node Tracking Servers (include the transaction id if sent from a wallet)
The tracking servers validate the verification request and check the transaction on the blockchain.
Detailed instructions to perform the steps can be found in the following places:
The Stake Verification Tool help system accessed through the command line
The USAGE.md document containing all help messages in the staketool git repository
The Horizen online instructions for Stake Tool
Linking Nodes To A Verified Stake Address
Once a stake address is verified it can be used by one or more nodes (within the same tracking system).
Each node must be linked to the stake address in the following manner:
The node must be configured with the stake address as it normally is
The node must be configured to use the ‘category’ field that is associated with the API subkey used in the verification process for that specific address.
Setting up API keys for Super Nodes API
Maintaining The Balance
The balance in the stake address must be kept at or above the total needed for all nodes using the stake address. If the balance falls below the total of all the nodes, then the newest (by node creation date) node that is up at the time will receive a low stake balance Exception. As the balance falls below each threshold amount (a multiple of the stake required) the next newest node will receive an Exception. Sending funds to the stake address to increase the amount above the total needed will close the Exceptions.
Changing An Existing Node To A Verified Stake Address
A node is changed to a verified stake address using the usual process with the additional step of ensuring that the category of the node matches the category associated with the API subkey used to create the verification request, see Change Stake instructions.
Note: if funds need to be transferred from multiple existing addresses to a new verified stake address the optimum time to do the transfer is right before the end of the earning period. The estimated time and block height is sent to the node tracker when the stake address is changed. The time and block height are also available on the bottom of the home page of each of the tracking servers.
Before You Start
There are a number of things you need to know before starting the verification process.
Only transparent addresses are supported as stake addresses (not private z-addresses).
A stake address must be ‘fresh’. It cannot be an existing stake address used previously by any Super Nodes.
A stake address cannot be used across both systems, i.e. it can’t be both a Super Node stake address.
There is no upper limit on the amount in a stake address and any excess ZEN over the amount needed for the associated nodes does not have any advantage or earn any extra rewards.
Staketool does not yet support creating multisignature transactions verifying an address, though it is possible to verify multisignature addresses by manually creating and signing a raw transaction with the required amount. Contact Support for instructions.
The verification process and assignment of nodes to the address requires an API subkey which can be obtained from your hosting provider or created on a tracking system server if you do your own hosting.
Once a verification request has been submitted the transaction must be broadcast to the network and included in a block within four hours.
What You Will Need
The following items should be addressed before using the Stake Tool to process a verification request:
The ZEN address where the stake amount will reside.
A small amount (<0.1 ZEN) to create the verification transaction is needed in this address.
One to five 'payout' addresses.
If more than one payout address is used a percentage of the node earnings may be assigned to each address.
Prebuilt Staketool binaries for your OS from Github or nodejs and the Staketool source code.
The private key of the stake address, unless you prefer to send the verification transaction from a wallet like Sphere by Horizen or use the zen-cli command line.
A Horizen Super Node API subkey. This subkey is provided by your Node hosting provider or, if you host your own nodes, you can create it on the Super Node API Settings page.
About the Stake Tool Application
The tool consists of two command line applications:
staketool
creates verification requests and ZEN transactions
sends signed ZEN transactions to the blockchain and verification requests to the servers
signtxtool
signs ZEN transactions using the private key of the stake address
Stand alone binaries (executables) for multiple platforms can be downloaded under releases.
If you prefer to run the CLI apps under nodejs (>=14) you can do so by cloning the repository and running npm ci. After that you can run the tools by using ‘node staketool.js’ and ‘node signtxtool.js’.
Help is available for general or specific commands when using the command line tool.
Examples:
./staketool help
./staketool createstakeverification help
Help is also available for the ./signtxtool in the same way.
Additional help to get started using the stake tool can be found under Staketool Intro & Setup
Stake Tool Verification Requests
The Stake Tool tracks the information about a verification request in local files in the same folder as the application or in files specified on the command line. Verification progress for each system and testnet are saved in different folders under the main ‘verificationfiles’ folder (subfolders are: super, and testnet). If any issues arise, the files can be viewed and status checked. No private keys are ever saved to the files.
The overall process expects one stake address at a time to be completed from start to finish (request status is verified or active). Verifying multiple stake addresses simultaneously can be accomplished by using the input file parameter on the command line to point to the corresponding verification file in ‘verificationfiles’ folder. Please see the command line help.
Creating A Request
A verification request is generated automatically by the data entered on the command line. Validation checks are performed on the command line arguments and any errors are reported to the user. Once the verification request is created instructions are displayed about how to create and send the transaction to the blockchain.
There are three main methods that may be used (set using the -m= argument) depending on how you would like to send a transaction:
A raw transaction can be created. The signtxtool application can then be used to sign the transaction with the private key of the stake address. This may be done on a separate secure/offline computer by transferring the request tracking file and the signtxtool application to the secure computer.
Instructions for a node zen-cli command (to run manually on a zen node) can create a raw transaction to sign using the zen-cli signrawtransaction command on the computer where the stake address resides.
Sending the verification amount using other methods like Sphere by Horizen wallet or zen-cli z_sendmany (with zen-cli z_getoperationstatus) node command. The resulting transaction id is captured and including on the command line when submitting the verification request.
Please see USAGE.md for full the command line reference.
Signing A Verification Transaction
The simplest way to create and send a verification transaction is to use the information displayed by the stake tool to send the amount indicated from the wallet that contains the stake address. The amount is sent from the stake address back to the same address. The only cost is the transaction fee needed to send the transaction. The resulting transaction id is used in the next step to complete the verification request and send it to the tracking servers for validation and verification.
If a wallet cannot be used then one of the other methods using the private key of the stake address may be used to sign the transaction.
The signtxtool can sign the transaction created by staketool and update the verification request directly.
If you are using an ‘air-gapped’ (not connected to a network) computer, the signtxtool application and the verification folder can be copied to that system, the transaction signed with the private key, and the verification folder copied back to the network enabled system so the verification request can be submitted.
If you have access to a zen node, zen-cli can be used to sign the transaction. Alternatively you could use a z_sendmany command to create and send the transaction.
Submitting A Verification Request
Once a request has been created it must be submitted to the appropriate tracking server (designated on the command line).
If the signtxtool was used to sign the transaction then submitting the request will also send the transaction to the blockchain and obtain the transaction id.
If a wallet or other method was used for the transaction, then the transaction id must be included on the command-line to complete the request.
The staketool sendtxandstakeverification method sends the request to the server and returns a status from the server. Your API subkey will be needed to complete submitting the request.
A verification request will take 6 block confirmations before it is accepted. Until then the status is returned as waiting for confirmation.
Verification Request Status
The status may be checked using one of the following methods:
Re-submit the same request. This is useful if you have just submitted a request and are waiting for it to confirm
Using staketool liststakes with your API subkey to return a list of verified stake address
Opening the My Stakes page under the Nodes menu of the tracking server
The My Stakes page also provides a list of nodes assigned to the stake address along with the minimum balance needed to cover all the nodes.
Super Nodes: My Stakes
A verification request may have one of the following statuses:
confirming - the verification request was successfully submitted and the server is waiting for at least 6 blocks to confirm the request.
verified - the request has been confirmed and the stake address is ready to be used. A new node can be registered with the stake address or a stake change request can be submitted by changing the stake on an existing node.
active -
a verified stake address is new and no nodes are using it yet or
the stake address is being changed (new request for the same address) and a new earning period has started. Any nodes using the stake address will have been updated through automatically created stake change requests.
cancelled - a request that was in confirming or verified state was cancelled using staketool
replaced - a change was made to the payto settings and the changes have been confirmed and applied. The new settings are active.
failed - there was an issue verifying or confirming the request. The request should be fixed and re-submitted.
Cancelling A Request
A request that is confirming or verified may be cancelled if you no longer want to have the request processed.
Use the command staketool cancelstakeverification with the appropriate arguments to cancel the request.
Note: along with the API subkey, the stake id of the request to change must be supplied. This can be found by using the staketool liststakes command.
Changing Payout Addresses Or Percentages
The payout addresses can be changed at any time by creating another verification request using the same stake address but different payto addresses or changes to the percent allocated to the same set of addresses.
The tracking servers recognize the changes and create an internal stake change request after successful verification of the new/changed 'payto' addresses. The changes take effect starting from the next payment period.
Additional Features
The staketool may also be used to:
List Existing Stakes - Retrieve the current list of stakes and their status from the tracking servers using staketool liststakes with your API subkey
Get Address Balance - Check the current balance of any zen address (retrieve from a Horizen block explorer) using staketool getbalance along with the address to check
The signtxtool may be used to:
Retrieve the private keys from a BIP39 seed phrase using: signtxtool keysfromseed --seed='my seed phrase'
CAUTION: only perform this action on a secure system.
Complete Command-line Instructions
Please see USAGE.md for full the command line reference.