How to start using your headless Gridcoin wallet

When starting with my first headless gridcoin wallet, I decided to write a tutorial to remember the steps I took and maybe even help others in the process.

If you're wondering what a 'headless wallet' is, it means the gridcoin software is installed on a command-line, text-only system. In other words you might not have a monitor connected to the PC (thus headless), and you are probably controlling the machine remotely through an SSH terminal.

This tutorial assumes you have successfully installed gridcoinresearchd on your machine running a debian-based (Debian / Ubuntu / Raspbian / etc) linux distribution. In other words, you already have your wallet created. Gridcoin daemon creates one for you automatically. All you need to do now is to protect it by encrypting it and backing it up.

Step 0 - Make sure your gridcoinresearchd daemon is running

At this point gridcoinresearchd should be installed, synced and running.

If you haven't started the gridcoin daemon yet, do so by typing gridcoinresearchd.

You can verify the daemon has started by typing gridcoinresearchd getinfo.

If the gridcoin daemon has not started yet, it will display error: couldn't connect to server.

If you just installed gridcoin, startup will take a long time as the blockchain needs to be downloaded. Check again tomorrow.

Keep running the gridcoinresearchd getinfo command every now and then until you get some real information out of it. When the daemon has started, it will display something like this:

{
    "version" : "v3.7.12.0-unk",
    "minor_version" : 7,
    "protocolversion" : 180323,
    "walletversion" : 60000,
    "balance" : 0.00000000,
    "newmint" : 0.00000000,
    "stake" : 0.00000000,
    "blocks" : 1263869,
    "timeoffset" : -263,
    "moneysupply" : 405006367.25869381,
    "connections" : 8,
    "proxy" : "",
    "ip" : "123.123.123.123",
    "difficulty" : {
        "proof-of-work" : 8.23948943,
        "proof-of-stake" : 6.64471954
    },
    "testnet" : false,
    "keypoololdest" : 1527934157,
    "keypoolsize" : 100,
    "paytxfee" : 0.00010000,
    "mininput" : 0.00000000,
    "unlocked_until" : 0,
    "errors" : ""
}

Step 1 - Stop bash from storing your password in the history file

Before you encrypt your gridcoin wallet, you should make sure that bash history is not in use. Otherwise your password will be stored in plaintext format in the .bash_history file of your home directory.

To get rid of the history file, edit your .bashrc file:
nano ~/.bashrc

Edit parameter HISTFILESIZE to 0, so your wallet passphrase is not stored in .bash_history file:
HISTFILESIZE=0

Press Ctrl-X and then Y to exit and save the file.

Then logout and login again to your server and check that .bash_history file is empty:
cat ~/.bash_history

If you got nothing as response, it means the .bash_history empty and your password will be safe.

Step 2 - Make your gridcoin wallet file readable only by your current user

Remove the file access permission from other users on the same linux machine.
chmod go-rwx ~/.GridcoinResearch/

Step 3 - Encrypt your wallet.dat file

Be sure to create a LONG passphrase! To do this, use keepass or some other password generation and storage tool. The password should be so complicated that there's no way you can remember it.

gridcoinresearchd encryptwallet <YOUR_VERY_LONG_WALLET_PASSPHRASE>

You will get a message saying something like:
wallet encrypted; Gridcoin server stopping, restart to run with encrypted wallet. The keypool has been flushed, you need to make a new backup.

Start gridcoin server again:
gridcoinresearchd

Wait for the server to start. Again, type the
gridcoinreserachd getinfo
command until you get the proper status message.

Step 4 - How to create a new address for receiving gridcoin

gridcoinresearchd getnewaddress
You will get a gridcoin address and are ready to receive some gridcoin.

To see all your gridcoin addresses, type:
gridcoinresearchd listaddressgroupings

You can now try to send a small amount - for example 1 GRC - to your new address. You can do this from an exchange or from another gridcoin wallet in your control.

To see the combined balance of all the addresses in your wallet, type:
gridcoinresearchd getbalance

Wait a few minutes and you should see the 1 GRC in your balance.

If you're impatient, you can see your upcoming balance before the transaction is fully confirmed:
gridcoinresearchd listreceivedbyaddress

Step 5 - Back up your wallet.dat

This is very important: Backup your wallet!

You don't need to back up your wallet every time you run getnewaddress. The addresses you get are already part of your wallet. I'm not sure of how many addresses are generated automatically with each gridcoin wallet. For bitcoin, it is 1000 addresses. In that case you would have to do a backup for every 1000 adresses you create. The idea is that normal users should only need to do one backup.

I did it to folder "grcbackup" in my home directory.

There is a command 'backupwallet' included in the client, but it seems it's not working at the moment I'm writing this. So you need to do stop the gridcoin daemon, manually copy your wallet.dat and gridcoinresearchd.conf to somewhere safe and then restart the daemon:

gridcoinresearchd stop
mkdir ~/grcbackup
cp ~/.GridcoinResearch/wallet.dat ~/grcbackup/
cp ~/.GridcoinResearch/gridcoinresearch.conf ~/grcbackup/
gridcoinresearchd

Now, move the data somewhere safe. Remember that USB sticks are not a safe way to store wallet data as they usually corrupt data when not used for a while.

Step 6 - Send a gridcoin transaction

If you have unlocked your wallet for staking, you need to first lock your wallet.
gridcoinresearchd walletlock

Then unlock your wallet for 5 minutes (300 seconds)
gridcoinresearchd walletpassphrase <YOUR_VERY_LONG_WALLET_PASSPHRASE> 300

Your getinfo command will now show something like this:
"unlocked_until" : 1527935993,

Do a transaction:
gridcoinresearchd sendtoaddress <ADDRESS_TO_SEND_TO> <AMOUNT_TO_SEND>

To lock your wallet again:
gridcoinresearchd walletlock

Step 7 - Unlock your wallet for staking

If you have several thousand GRC, you might want to consider staking to receive interest on it. You should have your gridcoin wallet running 24/7 for this to work.

Staking works only if your coins have 'matured'. This means the coins need to have been sitting in the current address and not staked for at least 16 hours.

If your coins haven't matured yet, you can still unlock the wallet for staking. The gridcoin daemon will automatically check for any matured coins to stake.

Unlock the wallet for the maximum time (9999999 seconds, about 115 days) and with an added parameter 'true'. This means it will unlock the wallet only for staking.

gridcoinresearchd walletpassphrase <YOUR_VERY_LONG_WALLET_PASSPHRASE> 9999999 true

Now, when the wallet is unlocked for staking only, you cannot make transactions. You need to lock the wallet and then unlock it again (see step 6).

Check the staking info:
gridcoinresearch getmininginfo

If you don't have any mature coins yet, it will show
"staking" : false

In that case, check again the next day and you will see the following parameters:
stakeweight.valuesum - amount of GRC you are staking. Should be same as the amount of coins you have in the wallet.
time-to-stake_days - estimated days to staking (receiving interest)

More info on the various parameters can be found here:
https://github.com/gridcoin-community/Gridcoin-Research/wiki/StakeMiner

Have fun!

If you have any questions or suggestions, feel free to leave a comment below!