Tutorials

How to use the command line to install or upgrade PIVX and start staking on Linux.

The first few commands will help you backup your files for an upgrade, but brand new installs can skip down to the highlighted location. This guide should be updated as new versions are released, but make sure you use the latest version in the download step.

Change Directory to the home directory (/home/pi in this case)

pivx2.PNG

Stop the currently running PIVX daemon. Your PIVX binaries may be in a different location like Downloads

pivx3.PNG

Make a backup of the current wallet (to a network share in this case but you can copy to a USB too). Backing up your wallet to a safe location is always a good idea

pi@barry:~ $ cp .pivx/wallet.dat /media/Crypto/walletBackups/wallet.dat.pivx.20171130.bak

New installs being here
Download the new binaries from the official github repository. Make sure you get the right build for your device. For a Raspberry Pi, you want the 32-bit ARM release (pivx-3.1.1-arm-linux-gnueabihf.tar.gz)

pi@barry:~ $ wget https://github.com/PIVX-Project/PIVX/releases/download/v3.1.1/pivx-3.1.1-x86_64-linux-gnu.tar.gz
--2017-11-30 20:32:22-- https://github.com/PIVX-Project/PIVX/releases/download/v3.1.1/pivx-3.1.1-x86_64-linux-gnu.tar.gz

...

Saving to: ‘pivx-3.1.1-x86_64-linux-gnu.tar.gz’

pivx-3.1.1-x86_64-l 100%[===================>] 35.79M 7.89MB/s in 5.9s

2018-07-13 09:30:58 (6.11 MB/s) - ‘pivx-3.1.1-x86_64-linux-gnu.tar.gz’ saved [37533970/37533970]

Extract the tar.gz file to the pivx-3.0.6 folder, still in the home directory

pivx1.PNG

New installs only: Create the .pivx folder and pivx configuration with the RPC lines required for pivx-cli to talk to pivxd

pi@barry:~ $ mkdir ~/.pivx
pi@barry:~ $ nano ~/.pivx/pivx.conf

#Add the following lines to the file. For the X's, press 16+ random keys on the keyboard. You don't need to record or remember these random values:

rpcuser=XXXXXXXXXXXXXXXX
rpcpassword=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Start the PIVX daemon

pivx5.PNG

Be impatient and spam getinfo to see if it's ready yet so you can get staking. "Blockchain information not yet available" just means it's still starting, which takes a few minutes and quite a bit longer on a single board computer.pivx6.PNG

The daemon is ready and the version number indicates the newest version in the "version" line. However we are not staking yet, as indicated in the "staking status" line.pivx7.PNG

Remember to be safe and always encrypt your wallet before holding any PIVX!
You can give your wallet a password by using the commands:

vWvpivx7.PNG

The wallet will turn off once it has completed encrypting. All you need to do is run to get it started! 

pivx8.PNG

Unlock the wallet for staking only. The syntax is
walletpassphrase <passphrase> <unlock time> <for staking/anonymization only true/false>
Introduced in v2.3 is the ability to unlock indefinitely by using an unlock time of 0. It is recommended that you start the command with a space so it is not saved in bash history with your passhrase. If you've already done this, you can use nano to remove the entry from ~./bash_history

pi@barry:~ $ ~/pivx-3.1.1/bin/pivx-cli walletpassphrase 9jF5rujKLo96t$4erfdy76tf 0 true

Staking active!

pivx9.PNG

If you have unlocked your wallet but staking is still not active, please refer to the troubleshooting guide here: https://pivx.freshdesk.com/support/solutions/articles/30000023125-how-to-troubleshoot-staking-activation

 

 

 

How to hash a file to confirm its integrity

Windows
On Windows, you can open up a command prompt and use the certUtil command.
Usage: certUtil -hashfile <filepath> SHA256

C:\Users\turtleflax>certUtil -hashfile "C:\Users\turtleflax\Downloads\pivx-3.0.6-win64-setup-unsigned.exe" SHA256

SHA256 hash of C:\Users\turtleflax\Downloads\pivx-3.0.6-win64-setup-unsigned.exe:

2ae1e5f9e6b7ca6119891fd09713b3fca53d52f4c36bb84b4528a4b9440b88ec

CertUtil: -hashfile command completed successfully.

Mac
On Mac, you can open a terminal window and use the openssl command.
Usage: openssl sha -sha256 <filepath>

pivx10.PNG

Linux
On Linux, you can open a terminal window and use the sha256sum command.
Usage: sha256sum <filepath>

pi@barry:~$ sha256sum ~/Downloads/pivx-3.0.6-x86_64-linux-gnu.tar.gz
1b987933112560641ac3d8f9b56509ae5dcfc2df2179a1a07b6c9535744d8e58 pivx-3.0.6-x86_64-linux-gnu.tar.gz

Why would I want to do this process?

PIVX Core releases are posted to github with their SHA256 checksum values in a file called SHA256SUMS.asc. You can open this file in notepad or any other text editor to view the contents. You will see that it is a PGP signed message with a SHA256 value for each associated binary file with that PIVX Core version. The purpose of the SHA256 value is to confirm that the file you downloaded matches the official github release file exactly. If it does not, it could indicate a download problem or MITM (Man in the Middle) attack.

Here is an example SHA256SUMS.asc file from the v3.0.6 release:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

141be1f2305dc133cb96f6fe7122f53be99f1bb6ed88a8f36199ab3e436d1f2e pivx-3.0.6-aarch64-linux-gnu.tar.gz
46e157d13a3718868732e6c86110d699c6fc8b9087b08774611240700a5718bb pivx-3.0.6-arm-linux-gnueabihf.tar.gz
f49d4f3140b7231539a40b2704487940f2520654b48684eaef50cc52d56fda68 pivx-3.0.6-i686-pc-linux-gnu.tar.gz
80677ac9c9c6b0656fd9c6c8958d5e00518ab2f3fb4baddf024d7ea11b16df5b pivx-3.0.6-osx64.tar.gz
5eedaa29157f586ea28f0b558ff526bae6d164a5cafacb4f65f871625d8249d5 pivx-3.0.6-osx-unsigned.dmg
87fafd709e602537c4e9d4f02b397181c82e260d967fa4d50fb0813d30117bc0 pivx-3.0.6.tar.gz
a1e58750b217ab8a1ca12e2f157c92de652c664221f79731453540c3a9a175b1 pivx-3.0.6-win32-setup-unsigned.exe
970e08bf934daf00612b3bb53c71b063bbc952a9b9f26f7f813307f00fcb4e71 pivx-3.0.6-win32.zip
2ae1e5f9e6b7ca6119891fd09713b3fca53d52f4c36bb84b4528a4b9440b88ec pivx-3.0.6-win64-setup-unsigned.exe
f113435a0e514bf3d8ac7a0186d9013a5dbfe95fe2000111b8a03abb508f8870 pivx-3.0.6-win64.zip
1b987933112560641ac3d8f9b56509ae5dcfc2df2179a1a07b6c9535744d8e58 pivx-3.0.6-x86_64-linux-gnu.tar.gz
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - https://gpgtools.org

iQIcBAEBCAAGBQJaH52hAAoJEDvc2i2HqIHZfU0P/jHiqzOoZra2hDaqW/jnLTH9
/BNmeDxd4B1/zpYo/uHS/xML+IKuscp/VPWxJ9AYVX19FP7SZo4HLfjHfmEBggGO
weqNxHmK7Etik3kOqx6d+cTXG/7OLz2EPMEuJgrR1byfgg51j1eGTQ5jGnOSI/VU
NuG1CXr5CfUBJm8fxFqoQ+yb9nmkhqmNA0mbJyczg5q8bZcabUj1eviI9GVJB9Ck
5nncL74bK0Qthj15nfPhcRT8Du79m7QZ5vmR1uZDBWlxad36HGQ+wbd2w4A3U8gp
TM7tIiHpYKYSD1SmE0rz6OYkZJGYbV2dj0CEIBNJudYlSB72BFwgDFsW0b9LGuKn
VzqHUFSXgSykTjIQH12F57oe8sdLvtnIoX5CFSrHwNF5Q/8gJimGKyumg3u1TPYx
owq5WSeBxZOmSXasX1kR6zelBMulF5fKpzQU1jBPLhiRzp9Q+JWsyBET+69fj74f
IwOqEVKfAGSzTmcZvqA+Sf4yJAf7ijmxBrqYqgBbW+0av20sbheqUI7wCavRTa4y
Gyie85fvc6gVA58LaNbNdD2ZJoGSjf9lJdIKgMCnOFJXuocX6xsA4bY1rtjwKXRC
9xr4m9+mI8IM5vHvj1MSEPCWK3bDaoFRH8vFMbThNr7/e5EJ1LGo5cKQ5UQqR/cn
skuiUEGo+W6OBYP1RgRw
=3YAP
-----END PGP SIGNATURE-----

Please note, checksums do not rule out a Github level breach because the attacker could have replaced both the binaries and SHA256 file. That is where the PGP signature comes in. You can use the developers public keys to confirm that the SHA256 file was signed with their private key.

How to resync your blockchain cache

If your PIVX Core blockchain cache has become corrupt or forked, you may wish to resync it using one of the methods below. **Please note that during the sync your balance will show as 0 until near the end, this is normal and nothing is lost**

Preparation - Before trying any of the methods below, please consider these steps

  1. It is always a good idea to make new wallet.dat and zPIV seed backups
  2. Make sure you are running the latest version of PIVX Core. Running old software can be a reason that your wallet forked in the first place and it will likely fork again if you have not updated.

Method 1 - Resync the blockchain from scratch
(Takes the longest, but it is the easiest. This method will sync you from block 1 and your computer will download and validate every block. CPU and bandwidth heavy)
Graphic User Interface (GUI) users:
"Tools > Wallet Repair > Delete Local Blockchain Folders (-resync)" to initiate the full re-sync.
Command line users:
You can initiate the full resync during daemon startup with the command switch `pivxd -resync`

Method 2 - Use a bootstrap
(Medium Difficulty: Takes a medium amount of time to resync. This will provide a zip that your computer can import and validate blocks from that will save on bandwidth. CPU heavy)
https://pivx.freshdesk.com/support/solutions/articles/30000021125-using-the-bootstrap

Method 3 - Restore a snapshot
(Medium Difficulty: Takes almost no time to sync because it is not downloading or validating any blocks. Instead you are trusting the data in the snapshot is correct)
https://pivx.freshdesk.com/support/solutions/articles/30000026470-how-can-i-use-a-snapshot-

Method 4 - Manual Resync
(Medium Difficulty: Only use this option if all others have failed. Your computer will download and validate all new blocks. CPU and bandwidth heavy)

  1. Gracefully shut down your PIVX wallet
  2. Navigate to your PIVX data directory and delete ONLY the files noted in the follow image:
    (Do NOT delete backups, masternode.conf, pivx.conf, or wallet.dat)

pivx11.PNG

3. Now re-launch the wallet and wait for it to sync. This can take few hours on slower computers or internet connections.


After you have finished syncing your PIVX blockchain, you can create a snapshot to save yourself some time in the future if you need to resync: https://pivx.freshdesk.com/support/solutions/articles/30000004666-how-do-i-make-a-backup-of-the-blockchain-so-i-can-avoid-a-full-resync-if-something-goes-wrong-


 

 

How to backup or restore your zPIV seed

 


What is a zPIV seed?
PIVX's dzPIV (deterministic zPIV) technology greatly simplifies your backup scheme. Instead of a new backup after every mint, you can back up the seed once and you'll have a failsafe copy for all activity based on that seed in case it's ever needed.
For more information about dzPIV, see the guide here


How to backup your seed
GUI (Graphic User Interface)

  1. If your wallet is encrypted, unlock the wallet with Settings-> Unlock Wallet. Make sure that you uncheck for staking an anonymization only
  2. Go Tools -> Debug Console -> Console
  3. Type getzpivseed
  4. Your zPIV seed will be output to the console. The seed is a 64 character hexadecimal string (256bit). It is not a mnemonic phrase. Backup this seed in a safe location, preferably offline.

CLI (Command Line Interface)

1. Make sure your wallet is fully unlocked (not just for staking) by using the command. On Linux, use a space at the beginning so your passphrase isn't saved in your shell history

pivx12.PNG

2. Use getzpivseed to output your seed string. Store this securely and never share it because it provides access to all your current and future zPIV

pivx13.PNG


How to restore your seed

Using the zPIV Seed to restore the information about your zPIV is computationally expensive, it can take several hours to restore all of the coins. Although it requires a lot of computation, it does provide a good fail safe in the case of wallet corruptions, machine failure, or other situations.

Importing a seed
Important Warning: It is extremely important that if you are importing a seed, you should be aware that you are setting the wallet's current seed to 'inactive'. Right now the wallet is only coded to handle one seed at a time. If the wallet you import to has zPIV generated by a different seed, then these zPIV will not be spendable until you switch the seed back.
Using the RPC command setzpivseed to replace the wallets existing seed with the seed you are importing. Please read the warning above before doing this!
As seen above, a dzPIV is comprised of your master zPIV seed and the count the coin is in the sequence. If you know that you have only generated a few zPIV, the wallet will likely automatically detect those for you because it will pregenerate the public value of the zPIV (called PublicCoin within the codebase) and will search the blockchain for any knowledge of that zPIV.

Extended Search
If the automatic import does not work, there are likely gaps in your generation sequence. For example when staking zPIV, you may have had 20 orphans in a row, thus bumping the count up by 20 without any of those Public Coins making it onto the blockchain. In this situation, you are able to tell your wallet to search a certain count range on the blockchain.
In this example, I think my wallet generated up to count 100. I import my zPIV seed to a fresh wallet.dat using RPC command setzpivseed

pivx14.PNG

The wallet automatically generates mints 1-20 and checks the chain for those values. If it finds that count 15 was used and on the blockchain, it will then generate up to 35 (keeping a buffer of 20) and check if any of those were added to the chain. The wallet loops through that process until no coins are found in the buffer of 20.
After the wallet stops syncing dzPIV, I type in command dzpivstate which will return something like this:

pivx15.PNG

My wallet stopped generating at 35, but I suspect my mints could be all the way up to count 100. I tell the wallet to generate up to count 100. I want the wallet to start at count 35 because I have already generated up to count 35. I want my wallet to generate an additional 65 zPIV so that it will check up to count 100. Searching for zPIV takes computation, so I am going to run it on two threads. I type the following command searchdzpiv

pivx16.PNG

When the process is finished it will return the message done. I can now use dzpivstate to see what the current count is (the last found zPIV added to the blockchain + 1). I can also go to the Privacy Dialog and check that my zPIV have been added.

Troubleshooting PIVX Core Wallet startup issues

Symptoms
Your PIVX wallet software does not start. When you try to run it nothing happens, an error is displayed, the window disappears, the loading window never completes, or another startup issue is encountered.

Cause

An abnormal exit of the wallet could result in corruption of your local blockchain cache. This can happen due to a power loss, unexpected reboot, OS updates, or if the local blockchain cache becomes corrupt by other means.

Resolution

Method 1

  1. Make a backup of your wallet.dat file and zPIV seed (Best practices)
  2. Make sure you are running the latest PIVX Core software
  3. Try using the -forcestart startup flag to see if it will recover from a failed start.
    In the Windows GUI, you will need to make a shortcut to the pivx-qt.exe file

pivx17.PNG

Then, edit the shortcut properties and append it to the end of the "Target" field, so that the end reads:pivx-qt.exe" -forcestart

pivx18.PNG

From the command line on all operating systems you can call the pivxd daemon with the switch -forcestart

Method 2
If Method 1 does not resolve the startup issue, try to resync the blockchain using the steps in this link

 

How to open and use the debug console

What is the debug console?

The debug console is a way to use advanced features of the wallet while in the pivx-qt GUI. It is similar to how a command-line user would issue RPC commands using pivx-cli.

How do I open the debug console?

To open the debug console, you'll use 'Tools > Debug Console' as shown below:

  1. In your wallet's menu (usually in the top left of the window or screen depending on your OS), select Tools. It should be listed among File, Settings, Tools, and Help.

pivx19.PNG

2. Once you click tools, select Debug console and you should see a window appear similar to the one below:

pivx20.PNG

3. Once here, go ahead and enter commands at the bottom where noted in the image.

To use the debug menu, type "help" for a list of commands or reference this article: https://pivx.freshdesk.com/support/solutions/articles/30000020865-debug-console-command-line