Whirlpool is an immensely powerful CoinJoin tool that breaks deterministic links using the “Zerolink Protocol“. It is simple to use and the most effective CoinJoin implementation available, bringing high-quality and affordable CoinJoin services to mobile devices.
For a brief, beginner-friendly explanation of Whirlpool, check out my previous Whirlpool article.
Installing Whirlpool CLI.
SSH into your node and create a new Whirlpool directory for your Whirlpool data files.
mkdir ~/whirlpool
cd ~/whirlpool
Visit the Whirlpool CLI repo release page and copy the link for the latest “run.jar” file, downloading it with the “wget” command. At the time of writing, the latest version is 0.10.16, so modify commands accordingly.
wget https://code.samourai.io/whirlpool/whirlpool-client-cli/uploads/63621e145967f536a562851853bd0990/whirlpool-client-cli-0.10.16-run.jar
Before running the file, check that Java is installed. If using a fresh Ubuntu system, it likely won’t be installed. Check your currently installed java version with the following command.
java --version
If Java is installed, the version number will be outputted. If not, you can install the latest version (at time of writing) with the following command.
sudo apt install openjdk-19-jre-headless
Before initialising Whirlpool, ensure you have ready your Samourai Wallet’s passphrase and pairing code. You can find your pairing code in Samourai Wallet under Settings > Transaction > Pair to Whirlpool GUI.
Copy the code to your mobile device’s clipboard and then share it using whatever secure method you can access on your desktop computer. As a Bitwarden user, I like to use their “Send” feature, which allows you to securely share files or text between devices with access to your Bitwarden account.
Once ready, initiate Whirlpool with the following command, entering your pairing code and passphrase when prompted.
java -jar whirlpool-client-cli-0.10.16-run.jar --init
It may take a minute to connect, but you will know it’s successfully paired once you begin to see logs for your postmix account. If you are returned to the command prompt, the pairing has failed, and you will need to rerun until successful.
Once paired, exit the logs. You now need to create a system file to start the Whirlpool service automatically on system boot.
sudo nano /etc/systemd/system/whirlpool.service
Paste the following lines, ensuring to edit for your Whirlpool version number. If you did not use the username “satoshi” when installing Ubuntu, edit accordingly.
[Unit] Description=Whirlpool After=tor.service [Service] WorkingDirectory=/home/satoshi/whirlpool ExecStart=/usr/bin/java -jar whirlpool-client-cli-0.10.16-run.jar --server=mainnet --tor --auto-mix --mixs-target=0 --listen User=satoshi Group=satoshi Type=simple KillMode=process TimeoutSec=60 Restart=always RestartSec=60 [Install] WantedBy=multi-user.target
Save and exit the file, then enable and start the Whirlpool service file.
sudo systemctl daemon-reload
sudo systemctl enable whirlpool
sudo systemctl start whirlpool
sudo systemctl status whirlpool
The final command outputs the status of the Whirlpool service. You should see a green light and an “active” status if all is correct.
Installing the Whirlpool GUI.
Samourai have also provided users with a graphical user interface to make the use of Whirlpool easier without needing to use CLI commands. Download the GUI to your computer from the official Samorai Wallet downloads page under the “Whirlpool” heading.
Once installed, open the GUI and check the box for “Advanced: remote CLI“. In the “CLI” field, you need to enter the address for your remote Whirlpool installation. This will be a combination of your node’s local IP address and the port number 8899, for example;
https://192.168.1.100:8899
Below that field, you will see a line of text saying, “Configure API key“. Click this, and a new field will appear where you need to enter your key.
To find your key, you will once again need to return to your terminal and run the following command;
nano ~/whirlpool/whirlpool-cli-config.properties
You can find your key at the top of the file next to where it says “cli.apiKey=“. Paste this into the “API key” field and press the connect button. The connection is over Tor, so it could take a few seconds, but you will know it’s connected once the GUI prompts for your wallet passphrase. Enter the passphrase, and the wallet will unlock.
You can now initialise and monitor mixes from Samourai Wallet, Whirlpool CLI and Whirlpool GUI.
If you are having difficulties pairing the GUI with your wallet, close the GUI, restart your node’s Tor service, then reopen the GUI and try again. The initial pairing sequence can sometimes encounter this. You can restart your node’s Tor service via SSH with the following command.
sudo systemctl restart tor
UFW Hardening.
The final step is hardening your node’s security by configuring and enabling UFW, allowing access only to the ports essential for your node to operate.
UFW, or Uncomplicated Firewall, is a simple-to-use, command-line-based interface for working with a Linux system’s firewall.
SSH into the node, create the following UFW rules and then enable the firewall.
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 8899/tcp
sudo ufw allow 28334/tcp
sudo ufw allow 28333/tcp
sudo ufw allow 8332/tcp
sudo ufw allow 50002/tcp
sudo ufw allow 4080/tcp
sudo ufw enable
You will be prompted that enabling the firewall may cause connection issues with the session. Since we already created a rule allowing SSH, it’s safe to confirm with “y” and enable the firewall.
You can check the status of UFW and the list of allowed ports with the following command.
sudo ufw status
Finally, I recommend opening Tor browser and logging into your Dojo Maintenance Tool to ensure that you still see a full house of green ticks on the dashboard. Everything should remain perfectly synchronised with the firewall rules you just defined.
And that’s a wrap. Congratulations, you now have a fully functional bitcoin node, utilising Mempool, Fulcrum, Dojo and Whirlpool. Although it is a long and much more complex process than setting up a plug-and-play node, the costs are minimal, and the learning experience is incredibly rewarding.
I hope you enjoyed reading and that you gained some value from taking the time to follow along.
