Staketool - Intro & Setup

Owned by Nathan Bode
Last updated: Mar 17, 2024 by Johncarlo Maddalena
5 min read

Expand all   Collapse all

Languages
  • Spanish/Español
  • Chinese/中文

Horizen Stake Verification Tool

This tool is used to verify the ownership of a ZEN transparent address used for staking Horizen Super Nodes.

Verified addresses allow:

  • up to five alternate 'payto' addresses
  • multiple stake amounts in one address

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 to the tracking servers. The tracking servers validate the stake address, the payto addresses and check the amount on the blockchain to complete the verification.

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

This guide covers the most commonly used steps of verifying an address. The tools supports alternative methods which may be more suited for your situation.


For the purposes of this guide, we will be using the Linux installation binaries. For all binary files please see: https://github.com/HorizenOfficial/staketool/releases/latest

Note: The Horizen Stake Verification Tool does not need to be executed from your node's CLI (command line interface) over SSH.
It can be executed from any local internet connected terminal. This guide will be making use of a Linux CLI using the terminal.

Guide Summary

  1. Download and extract the staketool binaries
  2. Explore and familiarize yourself with the help menu
  3. Create a Node API sub key (if not already created or delivered to you by a hosting provider)
    1. This sub key 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
  4. Fund an unused address (has not been used as the stake address of a node before)
  5. Create a new stake verification request with payto addresses (up to five). This step creates the amount to send (<0.1 ZEN)
  6. Send amount of ZEN specified from and to the address specified from the verification request
  7. Send the stake verification request using a TXID, and api sub key
  8. Check status of stake verification
  9. Update the node's stake address

Staketool Setup

1

Download and extract the latest staketool binaries

curl --silent "https://api.github.com/repos/HorizenOfficial/staketool/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/' | xargs -I{} wget https://github.com/HorizenOfficial/staketool/releases/download/{}/staketool-linux-{}.tar.gz  -O - | tar -xz

Help Menu

2Display help menu options for staketool and signtxtool
./staketool help
./signtxtool help
3Further information can be displayed about each particular command by adding help afterward

Example

./staketool createstakeverification help
Example Output

zenops@localhost:~$ ./staketool createstakeverification help

Horizen supernode stake ownerhsip verification tool

USAGE
./staketool createstakeverification [OPTIONS]

DESCRIPTION
Creates a stake verification request and optionally creates a raw transaction or outputs instructions to send funds

OPTIONS
-s= | --stake=stakeaddress (required) stakeaddress to verify
-p= | --payaddress='[]' (required) JSON array of payaddress objects, see NOTES

-sys=| --system=super,testnet (required) tracking system must be: super, or testnet
-m= | --method=tool|zen-cli|instructions (optional) [default: tool] method to use to create and sign the transaction, see NOTES
-o= | --outputfile=path/filename (optional) [default: ./verificationfiles/<stakeFirst8Chars>_<satoshis>.json] override default filename or path/filename
-ez= | --extrazen=zen (optional) an amount in zen to add to the verification transaction, see NOTES
-v | --verbose (optional) displays additional messages to help with troubleshooting


NOTES
Payaddress: The addresses in --payaddress need to be 1 to 5 valid transparent zen addresses. The sum of all "pct" needs to equal 100.00. A payaddress can be the same as the stakeaddress. Some platforms may not need to have quotes escaped or may not have to encapsulate the array in single quotes.
Example:–payaddress='[{"address":"ztcXfXAdPoDtyBJhzNmC3DzUkq3r22phsbt","pct":66.66},{"address":"zrFzxutppvxEdjyu4QNjogBMjtC1py9Hp1S","pct":33.34}]'

Tracking System: The system where the stake address will be used: super, or testnet. A stake address can only be used for super node systems.

Method: Option "tool" creates a raw transaction to be used by the tool (using zencashjs) and returns transaction and verification data.
Option "zen-cli" displays a zen-cli command to run manually that creates a raw transaction to sign using the zen-cli signrawtransaction command.
Option "instructions" displays links to documentation on how to create the transaction using other methods like Sphere by Horizen or zen-cli z_sendmany.

Extrazen: By default the tool creates a transaction smaller than 1 zen, in some circumstances this might be lower than a minimum transaction size.
With this option you can specifiy the minimum amount to send in the verification transaction. Must be a whole number (no decimals).


Create A Stake Verification Request

4

Fund an unused (never registered) transparent (T) address with 0.1 ZEN and wait for at least one confirmation.

This method of authentication will require <0.1 ZEN to be spent from and back to the source or staking address being verified.

After this process is completed, a balance of at least 500 ZEN for super nodes must be transferred to the staking address verified using this guide.

Note: This staking address can be any transparent address you control the private keys to, IE a hardware wallet such as Ledger or Coolwallet or a software wallet like Sphere By Horizen.

5

Create a new stake verification request.

You will need to modify the supplied examples with your own addresses. 
-s signifies the staking address holding the 0.1 ZEN, and -p signifies the payto address(es).

Note: Note: you may include up to five payto addresses and the percentages or "pct" must add up to 100.

Payto Example for two different addresses with 10% and 90% payout distribution.

./staketool createstakeverification -s=znXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -p='[{"address":"znYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY","pct":10.00},{"address":"znZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ","pct":90.00}]' -sys=super

Payto Example for one payout address.

./staketool createstakeverification -s=znXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -p='[{"address":"znYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY","pct":100.00}]' -sys=super

Note: the Payto addresses can be absolutely any transparent (T) address. It will be the address or addresses that all node payments will be sent to.
It is recommended that a wallet capable of handling/spending large sets of UTXOs be used for payto receiving address like Sphere By Horizen.
It is not recommended to use an exchange deposit address as a payto address.

Example Output

zenops@localhost:~$ ./staketool createstakeverification -s=znawdGp9aF1a1eqpDgxdqF4wiwArPta2qXY -p='[{"address":"znVjfAQpsAUD84JThD8Unk3ivHJdMWi6o8A","pct":100.00}]' -sys=super
{
stake: 'znawdGp9aF1a1eqpDgxdqF4wiwArPta2qXY',
amount: 0.00472112,
satoshis: 472112,
fee: 0.0001,
request: 'eyJzdGFrZSI6Inp0YXdkR3A5YUYxYTFlcXBEZ3hkcUY0d2l3QXJQdGEycVhZIiwicGF5dG8iOlt7ImFkZHJlc3MiOiJ6dFZqZkFRcHNBVUQ4NEpUaEQ4VW5rM2l2SEpkTVdpNm84QSIsInBjdCI6MTAwfV19',
filename: 'znawdGp9_472112.json',
system: 'super'
}

6

Send the exact amount of ZEN specified from the output of your last command from the staking address back to itself and record the transaction ID.

Note: you will need to wait for at least one confirmation to occur before proceeding to the next step.

Note: Example shown is for the Sphere By Horizen wallet. You may use any other wallet for this operation that you control the private keys to.

7

Using your API sub key and your transaction ID recorded in prior steps, reconstruct the following example command to use your relevant variables.

-a signifies the API sub key, -tx signifies the transaction ID

./staketool sendtxandstakeverification -a=xnd59ce59fe90eef708b11021b413b81a38fdf8993 -tx=802553ad615f5d38efc488d80cd39c2157bfff2af73302adf48a54bc18bce67f -sys=super
Example Output

zenops@localhost:~$ ./staketool sendtxandstakeverification -a=xnd59ce59fe90eef708b11021b413b81a38fdf8993 -tx=802553ad615f5d38efc488d80cd39c2157bfff2af73302adf48a54bc18bce67f -sys=super
Confirming stake address request with same payaddresses and txid. Nothing to change. 4 more blocks until verified. Status: confirming

8

Check on the status of your verification request by repeating the last command.

Your stake and payto address(es) are authenticated and active once you can repeat your last command and receive a status of active.

Example Output

zenops@localhost:~$ ./staketool sendtxandstakeverification -a=xnd59ce59fe90eef708b11021b413b81a38fdf8993 -tx=802553ad615f5d38efc488d80cd39c2157bfff2af73302adf48a54bc18bce67f -sys=super
Existing active stake address found with same paytos. Nothing to change. Status: active

9

If you're running your own node, you will still need to update your node's staking address. You can find instructions for doing so at the following: Change Staking Address

If you're using a hosting provider, you will need to notify them of the change of staking address so they can update the node configuration.

Note: a new staking address must have it's minimum stake balance in the verified address with at least 5 confirmations



© 2020 Horizen. All rights reserved.