(Tutorial) Configuring Peercoin Proof-of-Stake Minting on OS X

So, you’re a Mac user and you’ve got a couple of Peercoins that you’ve bought/mined/traded for… now what? This tutorial will show you how to enable Proof-of-Stake minting on the coins that you have, and provide an overview of what to expect. Currently, the Peercoin client is at version 0.3.0 and the settings to enable Proof-of-Stake minting have not yet been made available within the Peercoin wallet.

Tutorial Level of Difficulty:

[ul][li]If you are familiar with using the command line: Easy[/li]
[li]If that didn’t make sense: Moderate (but we’ll get you through)[/li][/ul]

Step 0: Download the Peercoin client and ppcoind
Dec. 2013 Update: I’ve written a walkthrough for getting started with using the Peercoin wallet on the Mac. You can find it on Devtome, http://www.devtome.com/doku.php?id=getting_started_with_peercoin_on_mac_os_x . If you would like to review the original PeercoinTalk.org link that discusses getting set up, you can find that one here: http://www.peercointalk.org/index.php?topic=21.msg251#msg251

Download these to a location that you can easily access them. Because we’ll be moving them in a later step, I’m going to assume that you put them in your “Downloads” folder, which tends to be where OS X places things by default when you download them from the web.

Note: I’ve heard that there may be problems with the Mega download link for ppcoind. I’ve put a copy up on Dropbox, in case you need to get it from a second source. This is the exact file that you would download from Mega, so the SHA should match if you want to confirm that I haven’t modified it in any way.

Step 1: Encrypt wallet
Make sure that your wallet is encrypted and that you’ve got the passphrase memorized. To do this, launch PPCoin-Qt and from the file menu, select Settings > Encrypt Wallet

Step 2: Synch the blockchain
Depending on your internet connection, this may take a while. You’ll know it is complete when you see a green checkmark in the lower-right of the PPCoin-QT interface. If you hover over it, a tooltip will let you know that you are “Up to date.” and then provide information about how recently the client grabbed the latest block.

Note: You can do the following steps from the OS X system interface, but I've found better results if you use the underlying command line interface instead. The results tend to be predictable, and you gain the added advantage of learning a bit more about how to interact with the operating system.

Step 3: Accessing the Command Line
Let’s start up the OS X utility application, Terminal. You can either use Spotlight to find it (click on the magnifying glass at the top-right of the screen and type "Terminal’) or you can find it in the [font=courier]Applications > Utilities[/font] folder. When you start it up, you will be presented with a monochrome window that reads something like this:

Last login: Mon Nov 25 11:42:08 on ttys001
mymac:~ username$ 

You will be entering commands into this window and each line of instruction will begin with a “$”. Also, if this is the first time you’ve used Terminal, please note that it is keyboard driven only, so if you need to edit a command before you hit enter, you’ll need to use the keyboard arrow keys to get to the point in the text, rather than using your mouse to insert the cursor.

For more information about using the command line in OS X, check out this Treehouse blog entry: http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line

Step 4: Moving ppcoind to the right directory
The first thing we need to do is to move the ppcoind file from your Downloads folder to the PPCoin folder. Using the command line, type in the following commands

NOTE: Whenever you see “$” at the beginning of a line in the follow steps, do not include it in the text that you include. “$” is just included here to let you know where the prompt begins.

$ cd ~/Downloads/

Press ENTER. “cd” is the command to “change directory” to whatever follows. In this case, we want to change to the current user’s (you) Downloads directory. “~/” is used to represent the current user’s home directory (and thus, you avoid having to type in a longer path every time you want to do something).

The prompt should now read:

mymac:Downloads username$ 

Assuming that you know that ppcoind is in here, we can move the file to proper directory, PPCoin, using the following command:

$ mv ppcoind ~/Library/Application\ Support/PPCoin/

Step 5: Creating a ppcoin.conf file

Once you’ve moved ppcoind to the right directory, you can move yourself over into the same one because we’ll be doing most of our work here now.

$ cd ~/Library/Application\ Support/PPCoin/
$ ls

“ls” = list directory. This command will output a list of all the files in the directory for you. You should see something like this:

mymac:PPCoin username$ ls
__db.001     __db.005     blkindex.dat	     debug.log     wallet.dat     __db.002     
__db.006     daemon      __db.003     addr.dat     database     ppcoind     
__db.004     blk0001.dat	 db.log		     

We need to create a configuration file, ppcoin.conf, and to do that we’ll use a command line text editor called Nano (or, if you’d rather, Emac, Vi or anything else works just as well). First, use the “touch” command to create the file, and then open it with Nano:

$ touch ppcoin.conf
$ nano ppcoin.conf

The terminal output will change and you’ll be in the editor. Copy and paste in the following configuration lines — we’ll make a couple of changes once you’ve got it pasted into the Nano window:

# ppcoin.conf configuration file. Lines beginning with # are comments.
# Network-related settings:

# Run on the test network instead of the real peercoin network.

# Connect via a socks4 proxy - default none

# Accepting incoming connections

# UPnP

# Use as many addnode= settings as you like to connect to specific peers

# ... or use as many connect= settings as you like to connect ONLY
# to specific peers:

# Maximum number of inbound+outbound connections.

# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)
# server=1 tells PPcoin-QT to accept JSON-RPC commands.

# You must set rpcuser and rpcpassword to secure the JSON-RPC api

# How many seconds peercoin will wait for a complete RPC HTTP request.
# after the HTTP connection is established.

# By default, only RPC connections from localhost are allowed. Specify
# as many rpcallowip= settings as you like to allow connections from
# other hosts (and you may use * as a wildcard character):

# Listen for RPC connections on this TCP port:

# You can use ppcoind to send commands to ppcoind
# running on another host using this option:

# Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate with ppcoind

# OpenSSL settings used when rpcssl=1

# Pre-generate this many public/private key pairs, so wallet backups will be valid for
# both prior transactions and several dozen future transactions.

#The reserve balance field is the minimum amount of coins you want to have available and NOT put up as stake.  
#The reason for this is that if you are generating proof of stake you cannot spend those coins for 520 blocks.

Note: Lines that being with a “#” are considered “commented out” and won’t be processed when the configuration file is read.

All of the settings above are fairly generic, and should be fine for your system. The only two things that you need to change are the “rpcuser” and “rpcpassword” entries. You can make these anything you want, and they should not match your wallet passphrase.

Once you’ve used the keyboard to move your cursor down to those two entries, we’ll want to “WriteOut” the changes (CONTROL+O, ENTER) and then exit Nano (CONTROL+X)

Congratulations, you’ve created a file from scratch.

Step 6: Creating a bash script to enable PoS Minting
Proof-of-Stake minting can be triggered from the command line, but rather than having to retype the same thing over and over again, it’s easier if you create a script to do it for you. Like before, we’ll start by creating a file using the “touch” command and then we’ll use Nano to edit and save it.

$ touch start.sh
$ nano start.sh

Inside the newly created start.sh file (a bash shell script), copy and paste in these lines:

UPDATE: The forum was messing up the type of quotation marks used in the script, and causing an EOF error. Please use the text provided in this Gist for your start.sh script. You should be able to copy and paste it in from Github without a problem.

Like before, WriteOut the file and then exit Nano. Once you’re out of Nano and back to the command prompt, you’ve done the hard part!

Step 6b: Updating file permissions for start.sh
There’s a chance that when you created the new start.sh script, that it didn’t inherit the correct file permissions. First, check to see if this step is needed. From the command line, list the files and sub-directories in the PPCoin directory, along with their permissions:

$ ls -la

Compare what you see in your Terminal window for [font=courier]start.sh[/font]:


-rwxrwxr-x 1 benrossi staff 228 27 Nov 20:57 start.sh

PERMISSIONS NEED TO BE UPDATED (continue with this step)

-rw-r--r-- 1 benrossi staff 228 27 Nov 20:57 start.sh

Use the following command to update the script’s permissions. For most “standard” system installations, you’ll be prompted for your OS X SYSTEM password (this is not your wallet passphase) because you used sudo.

$ sudo chmod 775 start.sh

Next, check the directory’s contents again to ensure that the permission update was applied correctly to [font=courier]start.sh[/font]:

$ ls -la

If it was, you will see

-rwxrwxr-x 1 benrossi staff 228 27 Nov 20:57 start.sh

With that fixed, move on to Step 7…

Step 7: Running the Start script
Now, for the moment of truth…

With PPCoin-Qt running, from the command line, type the following command:

$ ./start.sh

If all has gone as planned, you’ll see this output in the console:

mymac:PPCoin username$ ./start.sh
Make sure you’ve started PPCoin-qt first.
Enter PPCoin wallet passphrase : 

Enter your passphrase that you use to unlock your wallet and press ENTER. If you entered it correctly, you’ll see this in your console:

mymac:PPCoin username$ ./start.sh
Make sure you’ve started PPCoin-qt first.
Enter PPCoin wallet passphrase : Starting PPCoind with stake minting enabled
mymac:PPCoin username$

And that’s it, you’re now set up to mint with stake!

[b]Note[/b]: With v0.3.0 of the client, I've noticed that if I have an incoming transaction that has not yet cleared validation, that if you've run[font=courier] start.sh[/font], the PPCoin-Qt interface won't remove the "wallet is locked' message. Once that transaction has cleared, the client will correctly remove the message.

From what I can tell, and from what polling ppcoind directly tells me, you’re set up for minting stake if you’ve followed the steps above. Running start.sh again, after it’s been run correctly once, reports back with:

error: {"code":-17,"message":"Error: Wallet is already unlocked, use walletlock first if need to change unlock settings."}

I’ll add an issue to the Github repository calling this out, and if I hear any updates, I’ll add them to this post.

Step 8: Confirming that your wallet is unlocked for Proof-of-Stake Minting
If you take a look at PPCoin-Qt, you’ll notice that the warning note about “minting disabled for a locked wallet” has been removed. In the lower-right corner of the interface, if you hover of the “lock” icon, you’ll see that the tooltip now reads:

Wallet is encrypted and currently unlocked for block minting only.

Once you’ve seen this, you’ve confirmed that everything worked up to this point, and that as soon as you have coins in your wallet that qualify for Proof-of-Stake minting (details to follow), that you’ll automatically being to mint.

NOTE: The start.sh script must be rerun any time you close PPCoin-Qt or restart your machine. In a future update to this tutorial, I’ll include a way to launch that script from a file on your desktop, rather than having to go in through Terminal, but for now, the command line is your best bet.


Reserved for future updates

General and Troubleshooting Tips

[b]GENERAL TIP[/b]: Ben, why is it such a pain to get to the PPCoin directory? Isn't there something that I can do to not have to type in that long path every time?

I’m glad you asked! If you’re anything like me, after the 100th time that you’ve had to type “[font=courier]cd ~/Library/Application\ Support/PPCoin/[/font]”, you’ll wonder if there is a better way. Well, there is :slight_smile:

There’s a hidden file in your Mac’s user directory called [font=courier].bash_profile[/font]. When Terminal loads up a shell environment, it looks to this file to see what startup configurations and preferences it will need. You can make all sorts of changes with it here, like changing the color of text, enhancing functionality (such as adding the branch you are on if you use Git) and much more.

To make it simple to get back to the PPCoin directory, with a single command, rather than requiring you to enter the entire line, we’re going to update your [font=courier].bash_profile[/font] (the user-specific file that Terminal uses to configure how it works on your machine) to include an alias.

Your .bash_profile is located under your user’s home directory (~/), so first we’ll need to change to that directory, and once there, open it up with the Nano text editor:

$ cd ~/
$ nano .bash_profile

Depending on what you’ve done in the past (manually, or as part of a separate installation or configuration), you may have settings already in your [font=courier].bash_profile [/font]file. If you do, add these lines to the bottom of the file, or, if there are already lines in the file that start with “alias”, add them to the end of that section. If the file is empty, you can just add this in for the first line.

alias peercoin="cd ~/Library/Application\ Support/PPCoin/"

WriteOut the file and save it. When Nano closes, you need to refresh Terminal with the changes:

$ source ~/.bash_profile

From now on, you can jump directly to your PPCoin directory using this shortcut:

$ peercoin

Reserved for details about Proof-of-Stake

Please let me know if you have any questions at all about any of the steps in the guide. I think I caught everything, but if something doesn’t work for you, let me know what step you had a problem with and I’ll make sure the instructions were correct. If they were, and you’re still having issues, we can see if there needs to be an addendum, or if a troubleshooting tip can be included.

Thank you!

Ben I’m loving your work :slight_smile: making this thread sticky as very useful info in here for mac users


[quote=“Ben, post:5, topic:939”]Step 6: Creating a bash script to enable PoS Minting
Inside the newly created start.sh file (a bash shell script), copy and paste in these lines:

#echo “Make sure you've started PPCoin-qt first."
read -s -p "Enter PPCoin wallet passphrase  : " passphrase
echo “Starting PPCoind with stake minting enabled"
./ppcoind walletpassphrase $passphrase 9999999 true

Like before, WriteOut the file and then exit Nano. Once you’re out of Nano and back to the command prompt, you’ve done the hard part!

Step 7: Running the Start script
Now, for the moment of truth…

With[size=12pt]out[/size] PPCoin-Qt running, from the command line, type the following command:

$ ./start.sh [/quote]

Excellent work, Ben!
I just want to add one thought: have you tried running the daemon only for PoS minting (in difference to your statement “Make sure you’ve started PPCoin-qt first”)?
I know that we are talking about something with a small threat level, but the lesser the threat the better :wink:
I felt free to edit your quoted post :wink:

As far as I remember the MacOS version of ppcoin-qt is affected from that PoS minting flaw that allows actions which should normally require a password in case of encrypted wallet that is supposedly unlocked for PoS minting only.
As I have no MacOS and can not test that myself, I encourage you to try running the daemon only. If it is implemented like for other operating systems, there should be a lock of the blockchain and other files which prevent ppcoin-qt from starting once ppcoind is running. That can protect from unexpected behaviour, because ppcoind seems to work properly in terms of “password required actions”.
That would secure your system (whilst running PoS minting) against accidental or malicious loss of coins, but needs a test to confim my assumption.
I refer to this post: http://www.peercointalk.org/index.php?topic=979.msg9069#msg9069

I have ppcoind running on a headless RaspberryPi. I have not yet tried executing ppcoin-qt as I have not compiled it yet.
But I can report from the ppcoind on Raspbian that PoS minting works properly: PoS minting is running, transactions are not possible without password. I assume it is the same for MacOS. Would be glad to have that verified.

Thank you so much for making this. I have a troubleshooting question. I am getting an error when trying to start the process (start.sh). It is saying Permission Denied. Any help would be greatly appreciated.

Hi, Ahbartsch.

Can you do me a favor and from the [font=courier]~/Library/Application\ Support/PPCoin/[/font] directory check to see what the permissions are for the files and folders it contains?

You can do that with this command:

$ ls -la

Just take the full output that you see in Terminal and post it into a comment here. I want to check the file permissions against what I’ve got.

Awesome, really appreciate it Ben. I got stuck up on the same thing. Here’s what I get

total 474904
drwxr-xr-x 20 bradporter staff 680 27 Nov 20:57 .
drwx------+ 41 bradporter staff 1394 19 Nov 19:04 …
-rw-r–r--@ 1 bradporter staff 12292 27 Nov 20:55 .DS_Store
-rw------- 1 bradporter staff 0 10 Nov 10:06 .lock
-rw------- 1 bradporter staff 24576 27 Nov 20:57 __db.001
-rw------- 1 bradporter staff 999424 27 Nov 20:57 __db.002
-rw------- 1 bradporter staff 32776192 27 Nov 20:57 __db.003
-rw------- 1 bradporter staff 1179648 27 Nov 20:57 __db.004
-rw------- 1 bradporter staff 4653056 27 Nov 20:57 __db.005
-rw------- 1 bradporter staff 40960 27 Nov 20:57 __db.006
-rw------- 1 bradporter staff 708608 27 Nov 21:02 addr.dat
-rw------- 1 bradporter staff 116942404 27 Nov 21:03 blk0001.dat
-rw------- 1 bradporter staff 78143488 27 Nov 21:03 blkindex.dat
drwx------ 5 bradporter staff 170 27 Nov 20:59 database
-rw------- 1 bradporter staff 0 10 Nov 10:06 db.log
-rw------- 1 bradporter staff 1929525 27 Nov 21:03 debug.log
-rw-r–r-- 1 bradporter staff 2350 27 Nov 20:54 ppcoin.conf
-rwxr-xr-x@ 1 bradporter staff 5668888 29 Apr 2013 ppcoind
-rw-r–r-- 1 bradporter staff 228 27 Nov 20:57 start.sh
-rw------- 1 bradporter staff 49152 27 Nov 21:03 wallet.dat

Thanks so much for making this! I actually am having the same experience as ahbartsch with ‘Permission Denied’. Interested to hear if we made the same error. Thanks for any help.

[quote=“Ben, post:4, topic:939”]# You must set rpcuser and rpcpassword to secure the JSON-RPC api

This is a dumb question (I am working from zero knowledge and just following your instructions): when altering these two parts, I am correct in assume one does not leave in < or >, yes? Or does it even matter?

[quote=“malaise, post:17, topic:939”][quote=“Ben, post:4, topic:939”]# You must set rpcuser and rpcpassword to secure the JSON-RPC api

This is a dumb question (I am working from zero knowledge and just following your instructions): when altering these two parts, I am correct in assume one does not leave in < or >, yes? Or does it even matter?[/quote]

Although I don’t know it for sure, I strongly guess that you can even let the “<” and “>” in as both rpcuser and rpcpassword are only strings. You can (or should) randomly choose them. The only recommendation I can give is to make those strings long enough to secure them against brute force attacks.
Maybe someone knows about limitations in terms of characters that can be used as rpcuser and rpcpassword; I don’t know of any…
And I think there are no such things like dumb questions - only dumb answers :wink:

@masterOfDisaster: Running PPCoind in headless mode appears to work. I say appears, because I’d like to figure out a way to have the activity log piped out so it can be seen that it is actually running, but that shouldn’t be too difficult once I figure out what the command is.

$ ./ppcoind getinfo

GetInfo may contain what I need, if polled periodically. I have a feeling there is something better though, so if you have any recommendations, let me know.

I’ll go back through the steps to make sure I’ve got them down and then provide an update to the tutorial with both options.

For the questions that have come in over the last couple of hours, I haven’t forgotten about you, I’ve just had a bunch going on. I’ll answer your questions later this morning, once I’ve had a chance to do a few things around the house :slight_smile: Thanks for the feedback and the questions!

@ Ben
I don’t know where the user profile is located on MacOS, but I assume at the least a debug.log to be written there.
On linux you could check the status of ppcoind by e.g. tailing the debug.log (I hope “tail” is available on MacOS, but as it is UNIX based, I guess so…):

tail -n 30 ~/.ppcoin/debug.log

You can verify the correct limitation of ppcoind methods (most important: unlocked for stake minting only and not being able to execute transactions etc.) by trying to send PPC to yourself:

ppcoind sendfrom <accountname> <receivingaddress> <amount>

If you want to have a complete list of methods for ppcoind, try

ppcoind help

E.g. if you want to know the name of one of your accounts, you can try

ppcoind listaccounts

And most important:
can ppcoin-qt be started once the ppcoind is runing?
I assume it can’t because of locked files. And that would be great :wink:

I hope this helps a bit…

And in response to your request in the chat box here is a code snippet to get a quick and dirty compact overview of transactions:

ppcoind listtransactions | grep time |  sed -e "s/.* : //" -e "s/,//" | sort | xargs -n 1 -I '{}' date --date=@'{}'