Before I begin anything about the process involved here, there are several statements and caveats I would like to make. First and foremost, even as I write this I am still a bit torn over making this available to "the masses", as it were. I have long been a proponent of using bitcoin as a means of peer-to-peer value exchange, and decidedly not simply as a collectible which I prayed would attain a higher USD exchange rate. Bitcoin was made to be used, it wants to be used. For too long a dominant narrative in the larger bitcoin community has been one of "Just HODL", just wait out all the bad things and government agencies, just wait until the USD price rises and all your problems will suddenly seem much smaller. I vehemently reject the notion.
However, and as Samourai Wallet himself pointed out only days ago on the Dirtcoin Diaries after hours stream, there is quite a large swath of users which long to safely secure at least a portion of their bitcoin holdings in an offline fashion, free from worries about hacks or other fears. This group of users are currently using Samourai Wallet's Whirlpool coinjoin implementation to break the links of their past transaction history and then are having to make transactions out of the postmix wallet and into their storage solution, whether that be a Coldcard, a Passport, or any of a host of hardware wallet products. Because there has been no way to go immediately from mixing in Whirlpool to the storage device, users are having to give up the all-important equal amount of the utxo's, and often times are merging their entire postmix wallet balance into a single transaction in order to cut down on fees, even despite the wallet giving several warnings to not do the very action they are about to undertake. This is damaging to their privacy since they essentially reveal common ownership of all the inputs to the transaction, and also does slight damage to each mix the utxo is pulled from as well. Whirlpool mitigates this much better than other implementations, but the reality remains.
But what if instead of sending utxo's into Whirlpool and then paying transaction fees and merging inputs to spend to an offline storage solution, what if users could simply send the utxo's into Whirlpool, leave them remixing for free for a period of time, and then finally have the utxo's individually land on a fresh address in their offline storage solution automatically, while maintaining the essential equal pool amount of each utxo? This solves the problem of users using poor spending habits by merging many inputs at once, solves the issue of losing the equal amounts, and saves the users money since they don't even have to pay the transaction fee to send each utxo to storage. If users are going to perform the action whether Samourai assists them or not, then it stands to reason that Samourai (and by-proxy all Samourai users) are better served by facilitating this transfer to storage in a way which preserves the integrity of their mixes.
Additionally, one of the main drawbacks of users leaving Samourai postmix wallet and sending to a hardware wallet is that these users then lose the enormous benefit of the Samourai postmix spending tools. Tools like STONEWALL and the Cahoots suite are powerful weapons in the fight against chain surveillance companies and other entities intent on deanonymizing bitcoin users. Without being able to utilize them to add entropy in transactions from an offline storage solution, users are left with 100% deterministic links in their transaction history. But what if users could store funds in an offline Samourai wallet that had never had private keys on the internet, and when the time came to spend from storage could simply restore that Samourai Wallet and immediately begin transacting in a privacy preserving manner?
So, as reluctant as I may be to reinforce a "Just HODL" mindset, the fact remains that users are going to do what users want to do with their funds. If they want to mix and send to storage, they are going to do so with or without the help of Samourai Wallet. Thus today I plan to outline, in detail, a process which allows users to utilize all the tools at their disposal to effect an optimal outcome for themselves and other Whirlpool users alike. But not so fast--there is still a catch.
Experts Only Beyond This Point
Okay, so maybe I am being a little hyperbolic with the word "experts". This process does not require you to have intimate knowledge of the inner workings of the bitcoin protocol, nor of computers themselves. However-- it does require at least a basic level of comfort with Samourai Wallet, with the handling of private keys, and with using the terminal window on a desktop device. You won't need to know how to code, and I will lay out the steps in a very detailed, almost copy/paste fashion in an effort to avoid mistakes, but the risk of making a mistake remains nonetheless.
The functionality I will be going over is currently released in Samourai, is fully tested and fully functioning. It does not have any "official" documentation other than inside the open source code on Gitlab, and this is not intended to serve as any such documentation. I am not a member of the Samourai Wallet team, and as such any directions I give should not reflect on the team nor their product suite. In the past, Samourai have always followed a very deliberate development path with new features. They develop and code it out, then it is released available to more technical, "power users". Afterward, the team begins the process of working the functionality into the UI/UX of the wallet itself, to the point that it is available to all users.
This path was followed for nearly all major improvements, ranging from Dojo to Whirlpool itself, and I am sure this will eventually find a home somewhere inside the mobile app behind some fast action buttons. Thus, if you don't count yourself a "power user", my advice is simply to wait it out, keep those utxo's mixing, and when the day comes that the full feature is released to the mobile app, use it. My purpose here is simply to get more of the "power user" crowd actually using this functionality in an attempt to provide feedback for the developers so that everyone may make use of it in the future.
Do not attempt to follow these directions if you do not understand what is happening, or do not feel comfortable using command line tools and terminal windows
Grab Your Coat, It's Getting Chilly In Here
For the remaining readers, it's time to get started creating an offline Samourai Wallet for storage, and then to set up your Whirlpool CLI to mix to that external storage. Hold on to your butts. First let me preface this by saying, this offline wallet method I describe will not be considered "air-gapped", and thus some in the bitcoin community would dismiss it outright as a storage solution. I reject that notion, personally. But just in case you don't, understand that the offline wallet creation part of this guide can be completely ignored if you like. The CLI is going to send the funds to whatever BIP 84 xpub you enter into it, so if you have generated a secure, air-gapped, offline cold storage wallet by another means, then feel free to use that instead of an offline Samourai backed by your own Dojo. Bitcoin Q+A has an excellent guide to create such a wallet using Passport which you can use if you like.
As mentioned, the external destination xpub is restricted to only BIP84 Segwit zpubs, so the CLI will not send, for example, to a BIP49 xpub that generates P2SH, or "3..." addresses. It will only send to Native Segwit bech32, or "bc1q..." addresses on the
m/84' derivation path. If you have one of these wallets generated offline instead of generating a Samourai wallet as I am about to go over, then feel free, pop that BIP84 xpub in instead. Again, one of my main gripes with other wallet solutions is the lack of postmix spending tools being available when it is time to spend, however. So I strongly advise you make sure whatever offline generated wallet you create is compatible for restoration with Samourai. This shouldn't be that much of a problem, as Samourai is capable of restoring any BIP39 compatible wallet.
For the rest of you, you will need an already set up Samourai wallet, the one you are likely currently using to mix and spend, and you will also need to be able to download and install a second Samourai wallet briefly, which will serve as the offline storage wallet. This can be done a variety of ways, easiest among them would be to either have a second Android device, or by making use of the "profiles" feature on some Android devices which allow you to act as a completely different user than the primary account. You will also need a desktop device that will be capable of running constantly, whether that be a Raspberry Pi or a laptop you are okay with letting run. This will be the device that runs your standalone CLI for Whirlpool.
The first step is to download everything we need, starting with the Whirlpool CLI from Gitlab, which you can do by clicking this link. For purposes of this guide, I will choose to download the file into my
Downloads folder, or
Once you have that, you can move on to downloading the necessary apps onto your phone. First you can grab Samourai's watch-only wallet offering, called Sentinel, and which can be downloaded by clicking this link.
Next is the download of the second Samourai wallet itself, which is of course available through either Google Play, through F-droid, or through direct apk.
Additionally, if you are a Dojo user, it will be helpful to go ahead and open Tor browser and log into your Dojo Maintenance Tool so that you have the qr pairing code readily available. This will ensure that all parts of your offline storage wallet will be backed by your own node.
Let's start with Sentinel. Open the Sentinel app, choose
mainnet, and then select the WiFi looking network icon in the top right corner.
You will see there the ability to activate Tor, which you should do by choosing
enable. Next, if a Dojo user, you can choose
enable for Dojo connection, then scan the qr pairing code from your Dojo Maintenance Tool. Once all networking is set up, you can exit Sentinel.
Next is the important part where we will create a Samourai wallet without allowing the private keys to hit the internet at large. So open your newly downloaded Samourai wallet, and choose
mainnet. You will be greeted with a newly revamped onboarding screen.
Get Started at the bottom, and you will be taken to a screen where you can enable Tor and connect to your Dojo, just like you just did with Sentinel.
Immediately after connecting to Dojo and/or Tor, put the phone into Airplane Mode which can be found by pulling the top of the phone screen down and selecting the airplane icon.
This prevents the phone from connecting to the internet at large, and immediately places Samourai Wallet in "Offline Mode". Now that the wallet is offline, press the
Create A New Wallet button at the bottom of the screen.
This will begin the process of creating a new wallet, which means you will be required to enter a BIP39 passphrase (make it good and strong, this is your offline storage for your stack) and will be given the 12 seed words which represent your private keys. Be sure to store these seed words securely offline, and preferably in a separate location from the passphrase, since both are needed to restore your funds.
There is a Samourai specific metal backup plate on the market designed with exactly this in mind. They are designed by CrazyK, and will be available at the Kiboruto website, though the site may not be fully finished as of yet. But you will be able to find these sleek metal backup plates for your offline Samourai wallet, and ensure safekeeping of your private keys into the future.
You will also be asked to create a PIN. Once complete, you will be presented with the Account 0 portion of Samourai Wallet, albeit offline.
You will also be asked if you want to claim your PayNym ID, but will need to choose to
Skip this portion, because the wallet is in offline mode, and therefore cannot connect to paynym.is for registration. If you would like to test and make sure the wallet is offline, go ahead and attempt to claim it, but know that you will just get stuck unable to connect. You can also check by pressing the WiFi looking network icon in the top right corner, which should show you something like this:
All we need to do in this wallet is to grab the xpub so that we can present it to the CLI for sending funds from mixing. So choose the 3 dots menu in the top right corner, choose
Settings, and then choose
Wallet section, you will need to scroll down until you see an option to
Show Segwit Zpub, which is the public key you will need for the CLI.
Select that option, and then choose to copy the zpub to your clipboard in your phone. Note that during the CLI setup you will need this same zpub on your desktop device to enter into the CLI. So my advice is to either paste this zpub digitally into a note app to be transferred to your desktop device later, or manually write down the zpub to be typed later, or if your desktop device has the ability to scan and decode qr images into text, go ahead and scan this qr and have the zpub text on your desktop for later use.
As soon as you have the zpub copied to your clipboard, back all the way out of Samourai wallet using the back button, then once exited go ahead and completely uninstall Samourai from your device. This ensures that your private keys have never been opened or connected to the internet at large, but instead you have secured them in an offline fashion for safekeeping.
Next, disable airplane mode so that you regain internet connectivity and then open the Sentinel app. Press the
Start+ button located in the center of the screen to begin the process of adding the zpub.
In the popup message that presents, you will need to select
Segwit Bitcoin Wallet from the options presented.
Next, choose the
Manual option for adding the zpub to Sentinel.
Now paste the zpub you have copied on your device into the available area, and select
You will then be able to label the watch-only storage wallet with any name you choose, and again select
The process will then begin, and may take a few minutes to complete. On the off chance that the process fails to add the zpub correctly, simply repeat the procedure until it does take it. Once finished, you will be presented with a watch-only wallet labeled with your chosen name in Sentinel.
All Mixed Up
Next begins the process of setting up the standalone Whirlpool CLI to run in a terminal window on your desktop device. The process I will be outlining will be for using a standard linux (Ubuntu/Debian) computer, but you can modify commands as needed to complete the task. The very first thing that will need to be done is to get the Whirlpool GUI pairing payload from your current Samourai wallet transferred to your desktop device. There are several ways to do this, and they vary depending on the capabilities of your machine.
The pairing code itself is found in your Samourai wallet by selecting the 3 dots menu in the top right corner, followed by
Settings, and then
Transactions. At the bottom of the screen you will find a button marked
Pair to Whirlpool GUI, which when selected will reveal your pairing payload.
If the desktop device you are going to be using to run the CLI has a camera capable of scanning a qr code and an application that reads and decodes qr input into text you can copy, then simply scan this qr code and then copy the text to your desktop device's clipboard.
If you do not have a camera on the desktop device, there are a few other ways to transfer this payload from your phone. The payload itself is encrypted using your wallet passphrase, so it has a measure of security inherent within. One method I have used is to PGP encrypt the pairing payload on my phone using OpenKeychain, and then either emailing it to myself using an encrypted email like CTemplar or by saving the PGP encrypted message as a secure note, either using Bitwarden or Standard Notes. The point is to use a service that is available on both your mobile phone and your desktop device, so as to utilize copy/paste for the Whirlpool pairing code.
As soon as you have the pairing payload on your desktop device, regardless how it got there, go ahead and copy it to your clipboard. Next, open a terminal window and type the command
java -version and press enter. You should get an output similar to this, depending on what version you have installed:
openjdk version "11.0.11" 2021-04-20 OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04) OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode)
If you do not see an output similar to this, you will need to install OpenJDK 8+ on your device. On an Ubuntu/Debian computer this can be done by simply entering
$ sudo apt install openjdk-8-jdk
Once done, again enter the command
java -version to ensure your output looks similar to the one above. Once that is settled, it is time to start the CLI.
The command to start the CLI contains the path to the CLI within the command, so this will vary depending on where you downloaded the file and on your device and OS. It looks like so
$ java -jar ~/path/to/downloaded/cli/file/whirlpool-client-cli-0.10.11-run.jar --init
So, if you downloaded the CLI file into the
Downloads folder as I mentioned earlier, then the command will be
$ java -jar ~/Downloads/whirlpool-client-cli-0.10.11-run.jar --init
This will begin the process of setting up and pairing the standalone CLI with your current Samourai wallet, and begins by asking you to enter the pairing payload from your wallet.
Paste the pairing payload you have copied in your clipboard here, and press enter. Next, it will as if you want to initialize Tor.
y, and then press enter. Finally, it will ask for your passphrase to unlock your wallet. Remember, this is the passphrase to your current, mixing Samourai wallet.
Once entered, the CLI will connect to and open your Samourai Wallet. As soon as you see it loaded and running correctly, go ahead and
Ctrl+C to stop the process. The CLI is now initialized and connected to your wallet.
Next we will need the zpub you made note of earlier in this process, as we will set up the CLI to mix to that external destination. So grab the zpub, either by copying to your clipboard or by just getting it in your sight to be manually typed in. Now in the terminal window, enter the command to begin the mix to external destination interactive script.
$ java -jar ~/Downloads/whirlpool-client-cli-0.10.11-run.jar --set-external-xpub
You will first need to enter your wallet passphrase to open the CLI. Next, you will be asked for the external xpub (zpub) you wish to send funds to.
Either paste the copied zpub here, or manually type it in. Either way, once finished hit enter. Next you will be asked to choose the chain, or derivation path you wish to use. Simply type
0 for the standard
m/84'/0' path, and press enter.
Next up is the wallet index number you wish to start on, and again since this is a brand new wallet there is no reason to choose anything but the standard default, so type
0 and hit enter.
In the next step you will be asked how many mixes you want the CLI to perform on each utxo before sending it to your external destination. One cool thing about this program is Samourai coded in a bit of randomness to this process as well. The CLI will choose certain utxo's randomly to add up to 4 additional mixes to before sending to storage. So for example, if you want to have at least 5 mixes per utxo before going to storage, here you will simply type the number
5 and press enter. When running, however, the CLI will mix some utxo's up to 9 times before sending to storage, just in an effort to mitigate against any sort of pattern attacks on users.
Really cool part of this thing if you ask me. Now finally after you've chosen the number of mixes, you will be presented with 3 sample addresses that the CLI calculates from the zpub you entered. This will allow you to check and make sure the zpub is entered correctly, and that addresses match what they should in the wallet.
At this point you can open the Sentinel app you have the zpub entered into, and press the fast action
+ button in the bottom right corner. You will then see an option to select
Deposit, which will show you an address in your wallet which can receive funds.
Deposit button and then compare the address shown to the sample addresses given in the CLI terminal window. You should be able to press the back button in Sentinel and then repeat the process of pressing
Deposit two more times to compare all 3 sample addresses to the addresses shown in Sentinel. They should all be identical, which gives you piece of mind knowing everything is set up correctly. Once you are confident these addresses are correct, type in
y and press enter.
You will get confirmation that the external destination xpub has been properly configured, and the CLI will shut down and restart automatically. It will ask you for your wallet passphrase to reopen, and voila! Your CLI is now running and mixing any eligible utxo's in your postmix wallet! As soon as a utxo reaches your selected number of mixes, it will be automatically sent to the external xpub you supplied, and be sitting in an offline storage wallet in the same equal amount, having paid no transaction fees to get there.
If you decided to go with the offline Samourai wallet creation outlined in this guide, the final step you can undertake is to find the encrypted backup that Samourai made for you automatically during wallet creation, and store that in a safe place for super easy restoration which will keep all metadata, like Dojo connection, intact. This means when you want to restore your offline wallet and spend, you only need this encrypted backup and your BIP39 passphrase to do so, eliminating the need for all 12 words + passphrase, and eliminating the need to rescan the Dojo pairing qr code upon restoration. The backup file will be in the place you chose to store it during wallet creation, and will be in the form of a file called
samourai.txt. You can PGP encrypt this file, save it to an encrypted USB stick, and then store it securely offline if you wish, or any other myriad ways users undertake security. Just be aware that it exists, and use it as you see fit.
Tools to Mix and Chill
This process is a bit involved at the moment, which as stated earlier is par for the course for Samourai. They will almost surely eventually develop this into the actual mobile wallet UI/UX at some point in the future, making it available to any and all users of the wallet. But as of today, right now, it is available to users bold enough and technically savvy enough to pull it off.
These tools are made for using, and I hope this guide helps to get some Samourai users set up and mixing some of their funds to their offline storage devices. By leveraging the Samourai + Sentinel suite of tools, you can now have offline, secure storage available after breaking transaction history links, while maintaining the important equal amounts, and able to be easily restored into Samourai to make use of the postmix spending tools when the time comes. This doesn't mean everyone should stop having utxo's mixing constantly for spending, not at all. It just means that for those users looking to mix and then send to cold storage, the option is available for them to do so without harming themselves or others in their mixes through careless postmix consolidation transactions. There's no rush to get to storage, but if and when you are ready to store away some sats for a rainy day, use these tools to accomplish your goals in a fully sovereign, permissionless, and efficient way!