Hey guys, I thought I would put together an in-depth tour of the Gridcoin wallet software for all of our recent newcomers. Here I'll be outlining all the features and functions the windows GUI wallet has to offer, along with some basic RPC command usage. I'll be using the windows wallet as an example, but both linux and macOS should be rather similar. I'll be including as many pictures as I can as embedded hyperlinks.
This is my first post like this, so please forgive me if this appears a little scatter-brained.
This will not cover the mining setup process for pool or solo miners.
When you launch the wallet software for the first time you should be greeted with this screen.
- If you're a pool miner or investor, press cancel.
- If you're a solo miner, enter your email you used to sign up for projects and press OK.
- If you're not sure or haven't decided yet, press cancel. We can come back to this later.
overview tab
After that prompt, you should be left sitting on the main overview tab with several fields on it.
From top to bottom:
- Available: All coins available to be sent or staked (I'll cover this term later).
- Stake: All coins that are currently staking.
- Unconfirmed: All coins that have been received and have not yet received 10 confirmations.
- Total: All coins in your wallet. (The sum of the above fields)
- Blocks: How many blocks your client has in it's chain. Your wallet just started syncing with the network so this number will be low.
- Difficulty: How difficult it is for someone to stake the next block.
- Net Weight: An estimate for how many coins are staking on the entire network.
- Coin Weight: How many of your coins that are currently staking.
- Magnitude: A quantifier for how much work you put in mining. For solo miners only. For pool miners, this value will always be 0.
- Project: Displays the projects you're working on, one at a time. For solo miners only. For pool miners, this will always say "INVESTOR".
- CPID: Cross Project Identifier. Used to keep track of users across projects. For solo miners only. For pool miners, this will always say "INVESTOR".
- Status: Displays various status messages.
- Current Poll: Displays the latest poll.
- Client Messages: Displays various client messages.
send tab
Now onto the other tabs on the left side. Currently we're on the Overview tab, lets move down to the Send tab. This tab it pretty self-explanatory, you use it if you want to send coins, but I'll go over the fields here:
- Pay To: Enter a valid gridcoin address to send coins too. Gridcoin addresses always start with an S or and R.
- Label: Enter a label here and it will put that address in your "address book" under that label for later use. You can leave it blank if you don't want it in your address book.
- Message: Enter a message here if you want it attached to your transaction.
- Amount: How many coins you want to send.
- Add Attachment: Leave this alone, it is broken.
- Track Coins: This doesn't do anything.
receive tab
Now down to the Receive tab. Here you should have a single address listed. If you double click on the label field, you can edit it's label.
- New: Generate a new address.
If you click on an address, the rest of the options should be clickable.
- Copy: Copy the selected address to your clipboard.
- Show QR Code: Show a scan-able QR code for the selected address.
- Sign Message: Cryptographically sign a message using the selected address.
transactions tab
The Transactions tab is pretty boring considering we have no transactions yet. But as you can see there are some sorting tools at the top for when you do have transactions listed.
address book tab
The Address Book is where all the addresses you've labeled (that aren't yours) will show up.
- Verify Message: Verifies a message was signed by the selected address.
The rest of the functions are similar to the functions on the Receive tab.
voting tab
Onto the Voting tab. There wont be any polls because we aren't in sync yet.
- Reload Polls: Pretty self-explanatory, I've never had to use this.
- Load History: By default, the wallet will only display active polls. If you want to view past polls you can use this.
- Create Poll: You can create a network-wide poll. You must have 100,000 coins as a requirement to make a poll. (Creating a poll does not consume the coins)
Here's what the Voting tab will look like once you're in sync
context bar
Now onto the context bar menus on the top.
Under File you have:
- Backup Wallet/Config: This lets you backup your wallet configuration file just in case.
- Export: You can export your Transactions tab or Address Book in CSV format.
- Sign message: Does the same thing as on the Receive tab.
- Verify message: Does the same thing as on the Address Book tab.
- Exit: Close the wallet.
Under Settings you have:
- Encrypt Wallet: Encrypts your wallet with a password. (we'll come back to this)
- Change Passphrase: Allows you to change your encryption password.
- Options: Opens the options menu. (We'll come back to this)
Under Community you have:
- Block Explorer: Redirects you to gridcoinstats block explorer.
- Exchange: Redirects you to the exchange section of the official gridcoin website.
- BOINC: Redirects you to team gridcoins page on BAM!.
- GRC Chat Room: Redirects you to the contact section of the official gridcoin website
- Website: Redirects you to the official gridcoin website
Under Advanced you have:
- Advanced Configuration: Opens the Advanced Configuration menu. (Not so advanced if you ask me)
- Neural Network: Allows you to view solo miners project statistics. It will be largely blank if you're not in sync yet.
- FAQ: Don't touch this, It is broken.
- Foundation: Don't touch this, It is broken.
- Rebuild Block Chain: Starts the client syncing from 0. Don't worry, using this will not make you lose coins.
- Download Blocks: Downloads the latest official snapshot, can help speed up syncing. The download progress tends to sit at 99.99% for a long time, don't worry, it's working.
Under Help you have:
- Debug window: Opens the debug window. (We'll come back to this)
- Diagnostics: Don't touch this, it is broken.
- About Gridcoin: Opens the About Dialog. This gives you your client version and other information.
options
Now back to the options menu under Settings > Options.
Here we have the options menu main tab:
- Pay transaction fee: The transaction fee that will be automatically paid when you make a transaction.
- Reserve: You can reserve an amount so that it will always be available for spending.
- Start Gridcoin on system login: Pretty self-explanatory
- Detach databases at shutdown: Speeds up shutdown, but causes your blockchain file to no longer be portable.
On the Network tab:
- Map port using UPnP: Attempts to connect to nodes through UPnP.
- Connect through SOCKS proxy: Allows you to connect through a proxy.
The window tab is pretty self-explanatory.
The Display tab is also pretty self-explanatory, with the exception of:
- Display coin control features (experts only!): This allows you to have a great deal of control over the coins in your wallet, check this for now and I'll explain how to use it further down. Don't forget to click "Apply".
encrypting your wallet
Now that all of that is out of the way. The first thing you'll want to do is encrypt your wallet. This prevents anybody with access to your computer from sending coins. This is something I would recommend everyone do.
Go to Settings > Encrypt Wallet and create a password. YOU CANNOT RECOVER YOUR COINS IF YOU FORGET YOUR PASSWORD.
Your wallet will close and you will have to start it up again. This time when it opens up, you should have a new button in the bottom left. Now if you want to stake you will have to unlock your wallet. Notice the "For staking only" box that is checked by default. If you want to send a beacon for solo mining or vote, you will need to uncheck this box.
getting in sync and icons
Before we continue, Let's wait until we're in sync. Depending on your internet speeds, this could take from several hours to over a day or 2. This can be sped up by using Advanced > Download Blocks, but this can still take several hours.
This is what an in-sync client should look like. Notice the green check to the right of the Receive tab. All of these icons give you information when you hover your mouse over them.
The arrow tells you if you're staking. If you aren't staking, it will tell you why you're not staking. If you are staking it will give you an estimated staking time. Staking is a very random process and this is only an estimate, not a countdown.
The connection bars tell you how many connections to the network you have.
The check tells you if you're in sync.
what is staking?
Now I've said "stake" about a million times so far and haven't explained it. Gridcoin is a Proof of Stake (PoS) coin.
Unlike bitcoins Proof of Work (PoW), PoS uses little system resources, so you can use those resources for scientific work. PoS works by users "Staking" with their balance. The higher the balance, the higher the chance to create, or "stake" a block. This means you need to have a positive balance in order to stake. Theoretically, you can stake with any amount over 1 coin, but in practice it's recommended to have at least 2000 coins to reliably stake.
Staking is important for solo miners, because they get paid when they stake. Pool miners don't need to stake in order to get paid however. So if you want to solo mine, you'll need to buy some coins from an exchange or start in the pool first and move to solo when you have enough coins.
In addition to Research Rewards for miners, anyone who holds coins (solo miners, pool miners, and investors) gets 1.5% interest annually on top of your coins. So it can be beneficial for pool miners to stake as well.
Here is a snippet of what a research rewards transaction looks like from my personal wallet. I have a label on that address of "Payout address" as you can see here.
UTXOs and coin control
At this point you'll need some coins. You can use one of our faucets like this one or this one to test coin control out.
First let me explain what a UTXO is. UTXO stands for Unspent Transaction Output. Say you have an address with 0 coins in it, and someone sends you 10 coins like I've done here. Those 10 coins are added to that address in the form of a UTXO, so we have an address with one 10 coin UTXO in it.
Now we receive another 5 coins at the same address, like so. Now we have an address with one 10 coin UTXO and one 5 coin UTXO. But how do we view how our addresses are split up into different UTXOs?
Earlier we checked the "Display coin control features" box in Settings > Options > Display. Once that's checked you'll notice there's another section in the Send tab labeled "Coin Control Features". If you click the "Inputs" button, you'll get a new window. And look, there's our 2 UTXOs.
All UTXOs try to stake separately from each other, and remember that the chance a UTXO has to stake is proportional to it's size. So in this situation, my 10 coin UTXO has twice the chance to stake as my 5 coin UTXO. Now wallets, especially ones that make a lot of transactions, can get very fragmented over time. I've fragmented my wallet a little so I can show you what I'm talking about.
How do we clean this up? We can consolidate all this into one UTXO by checking all the boxes on the left and selecting OK.
Now pay attention to the fields on the top:
- Quantity: The total amount of UTXOs we have selected.
- Amount: The total amount of coins we have selected.
- Fee: How much it would cost in fees to send all those UTXOs (more UTXOs = more transaction data = more fees)
- After Fee: Amount - Fees.
- Bytes: How large the transaction is in bytes.
- Priority: How your client would prioritize making a transaction with this specific set of UTXOs selected had you not used coin control.
- Low Output: If your transaction is less than 0.01 coins (I think).
- Change: What you will get back in change.
- custom change address: You can set the address you get your change back at, by default it will generate a new address.
So let's fill out our transaction so we end up with 1 UTXO at the end.
In "Pay To:" Just put any address in your wallet, and for the amount put what it has listed in the "After Fee" Field. Just like this.
Notice how we get no change back.
Now click "Send", we'll be prompted to enter our passphrase and we're asked if we want to pay the fee, go ahead and click "Yes".
Now if we go back to the Overview tab we get this funky icon. If you hover your mouse over it, it says "Payment to yourself", and the -0.0002 GRC is the network transaction fee.
(Ignore the first one, that was me fragmenting my wallet)
Now if we look at the Coin Control menu, we can see that we've slimmed our wallet down from 7 UTXOs to 1.
Now why would you want to use coin control?
2 Situations:
- UTXOs less than 1 coin cannot stake. So you can combine a lot of tiny, useless UTXOs into 1 bigger one that can stake.
- After a UTXO stakes, it cannot stake for another 16 hours. So if you have 1 large UTXO that is big enough to stake more than once every 16 hours, you can split it into smaller UTXOs which can allow you to stake slightly more often.
- By default, the wallet will always generate a new address for change, which can make your wallet get very messy if you're sending lots of transactions. Keep in mind that more UTXOs = larger transactions = more fees.
Sidenote - When you stake, you will earn all research rewards owed reguardless of which UTXO staked. However, you'll earn the 1.5% interest for that UTXO. Not your whole wallet.
forking
A fork is when the network splits into multiple chains, with part of the network on each chain. A fork can happen when 2 blocks are staked by different clients at the same time or very close to the same time, or when your client rejects a block that should have been accepted due to a bug in the code or through some other unique circumstance.
How do I know if I'm on a fork?
Generally you can spot a fork by looking at the difficulty on your Overview tab. With current network conditions, if your difficulty is below 0.1, then you're probably on a fork.
You can confirm this by comparing your blockhash with someone elses, like a block explorer.
Go to [Help > Debug Window > Console]. This is the RPC console, we can use to do a lot of things. You can type help to get a list of commands, and you can type help [command you need help with] (without the brackets) to get information on a command. We'll be using the getblockhash [block number] command.
Type getblockhash [block number] in the console, but replace [block number] with the number listed next to the "Blocks:" field on the Overview tab.
This will spit out a crazy string of characters, this is the "blockhash" of that block.
Now head over to your favorite block explorer, I'll be using gridcoinstats. Find the block that you have the hash for, use the search bar or just find it in the list of blocks.
Now compare your hash with the one gridcoinstats gives you. Does it match?
If it matches, then you're probably good to go. If it matches but you still think you're on a fork, then you can try other block explorers, such as gridcoin.network or neuralminer.io.
If it doesn't match, then you need to try to get off that fork.
How do I get off a fork?
Just wait for an hour or two. 95% of the time your client is able to recover itself from a fork given a little time.
Restart the client, wait a few minutes to see if it fixes itself. If it doesn't restart again and wait. Repeat about 4 or 5 times.
Find where the fork started. Using the
getblockhashcommand, go back some blocks and compare hashes with that on a block explorer so you can narrow down what the last block you and the block explorer had in common. Then usereorganize [the last block hash you had in common]. Note thatreorganizetakes a blockhash, not a block number.If none of this works, you can take a look at social media (reddit/steemit) and see what other people are saying.
configuration file
Your configuration file depends on your operation system:
On Windows: %appdata%\GridcoinResearch\
On Linux: ~/.GridcoinResearch/
On MacOS: /Users/USERNAME/Library/Application/Support/GridcoinResearch/
If you open up your gridcoinresearch.conf, you'll see the default one it generated. Note that if you entered your email earlier, the first line will have your email on it instead of "investor". If you decided you want to solo mine but didn't enter your email when you first started the wallet, go ahead and put your email on the first line in place of "investor". If you're a pool miner, just leave it as "investor".
Next, it's recommended that you use the addnodes on the gridcoin wiki. So our gridcoinresearch.conf will look like this.
A useful line for solo miners is PrimaryCPID=[YOUR CPID]. Sometimes your wallet can pick up on the wrong CPID so it's good to have that in there if you're solo mining.
running a listening node
A listening node is a node that listens for blocks and transactions broadcasted from nodes and forwards them on to other nodes. For example, during the syncing process when you're getting your node running for the first time, you're downloading all the blocks from listening nodes. So running a listening node helps support the network.
Running a gridcoin listening node is simple. All you need to do is add listen=1 to your gridcoinresearch.conf and you need to forward port 32749 on your router.
If you don't know how to port forward, I'd suggest googling "How to port forward [your router manufacturer]".
quick links
Gridcoin.science Unofficial Website
Gridcoinstats.eu Block Explorer
And that's all I have for now!
I plan to keep this post up-to-date with changes in the client. So if anyone has any suggestions, have clarifications they want made, or maybe I got something wrong, then please feel free to leave a comment below or PM me on reddit!