This guide explains how to achieve good forward privacy by mixing with the Samourai Whirlpool coinjoin service. If you haven’t read the Quick Start guide yet, that’s a good place to learn how to install and get introduced to Sparrow.
It is an unfortunate truth that Bitcoin’s privacy guarantees are poor. While use of Bitcoin itself is pseudonymous in nature, most users obtain Bitcoin from an exchange which must keep a record of their identity and withdrawals due to KYC (Know Your Customer) regulations. Further, there are a number of common heuristics which can be applied to analyse the Bitcoin blockchain and make it possible to determine the ownership of funds across many transactions with a high degree of probability.
These heuristics are generally made possible because the values and script types involved for all Bitcoin transactions are public, and it can usually be assumed that all inputs are controlled by the same entity. If these differ when analysing the transaction inputs and outputs, it is possible to trace the ownership of funds across transactions with some confidence.
Coinjoin is a simple yet highly effective technique to make this kind of analysis difficult or impossible. Users of coinjoin coordinate to create a transaction that uses the same script type for all inputs, each contributing and receiving outputs of the same value. The structure of this transaction makes it impossible to trace ownership of funds with any certainty. In addition, when several ‘rounds’ of coinjoins are made in sequence, the probability of an analysis drops significantly with each round.
There are many kinds of coinjoins, each with different tradeoffs. Sparrow Wallet acts as a client for the Samourai Whirlpool coinjoin implementation. This implementation offers a high degree of anonymity through a number of design choices which have been well tested and reviewed over several years. You retain full ownership of your funds at all times. Importantly, Whirlpool offers good liquidity from other users. Each additional user in Whirlpool increases the potential anonymity set for all the other users.
Every Whirlpool mixing round offers the following guarantees:
- Maximum entropy
- Never mixing with yourself
- Never mixing previously seen coins together
- No deterministic links between inputs and outputs
- No address reuse
To better understand what anonymity Whirlpool offers, read Diving head first into Whirlpool Anonymity Sets.
Using Whirlpool is fairly simple.
In order to start, you will need a BIP39 software wallet (also known as a hot wallet).
This is simply a wallet where you have entered the seed words into Sparrow.
A hot wallet is required because the Whirlpool client needs to sign transactions as soon as the mixing round is ready.
The wallet needs to be a standard derivation on the default account #0 - for example,
m/84'/0'/0' for Native Segwit.
Taproot (P2TR) wallets and Electrum generated seeds are not currently supported.
If you already have a suitable wallet, you can use it directly. Otherwise, follow the Quick Start guide to create one. In order to start mixing, you will need a balance over 0.001 BTC (100,000 sats) in the wallet. If you are restoring an existing Whirlpool wallet, see the section on other mixing clients.
To start a mix, go to the UTXOs tab and select the UTXOs you want to mix (hold down Ctrl or Cmd to select multiple). Then click the Mix Selected button below (you need to be connected first).
You will be shown a dialog which contains some important details about Sparrow’s role as a Whirlpool client. For a coinjoin to take place, it is necessary for multiple users to coordinate to create a single transaction. In Whirlpool, this coordination is done by the Whirlpool server. For greater anonymity, all communication with the Whirlpool server is done via blinded inputs.
Further, if you have configured a Tor proxy, or are using an Electrum server on a
.onion address, communication with the Whirlpool server will be over Tor.
Note that you can configure a Tor proxy even if your server is on a local network IP address - Sparrow uses Tor only to connect to externally addressable services.
You can verify whether Tor is set up correctly with the status bar icon to the left of the server toggle.
Note that Sparrow does not ever use Samourai’s servers to provide wallet transactions or UTXO information. This information comes from your connected server, as it has always done. Only the independent Whirlpool server receives communication, and the data it receives is blinded so no privacy is lost when using Tor.
Once you’ve understood the privacy of Sparrow’s Whirlpool implementation, you can proceed with the Next button, or click Cancel to setup a Tor proxy if desired.
An internal Tor proxy will start automatically if you are connecting to an Electrum server or Bitcoin Core on a
.onion address. Otherwise, you will need to setup an external Tor proxy to use Tor.
The simplest way to get an external Tor proxy running is to download and run Tor Browser and enable the proxy in the server preferences to
localhost with port
Sparrow will use the configured Tor proxy for the Whirlpool coordinator (and all other external communication).
Coinjoin through Whirlpool involves a number of steps, and in addition a number of wallets. These wallets are all based off the same seed that you used to create the BIP39 software wallet you are using. They simply use different (but well known) derivation paths to derive other addresses. That means that you can always recover all your funds so long as you have the seed.
These wallets are described as follows:
- Premix This wallet contains the UTXOs from your premix transaction (also called the Tx0). Your premix transaction splits your UTXOs into equal amounts ready for mixing.
- Postmix This wallet contains the UTXOs from your mixes. Whirlpool will select UTXOs from both the Premix and the Postmix wallets to include in coinjoin transactions. Funds in this wallet can be considered mixed and are safe to spend anonymously, especially after a number of mixing rounds.
- Badbank This wallet contains the change from your premix (Tx0) transaction - whatever is left over from splitting your input UTXOs into equal amounts. Consider mixing any UTXOs here if they are large enough, but do not combine them with mixed funds! See here for further suggestions.
You’ll see all these wallets appear on the left of the wallet window later on. For now, the dialog gives you a preview of how they will appear.
As noted above, your premix (Tx0) transaction is required to split the UTXOs you have selected into equal amounts ready for coinjoining. In addition, with this transaction you will provide the miner fees necessary for the coinjoin transaction, and pay a small once-off fee to the Whirlpool server. If you have one, this fee can be discounted by entering a discount code or SCODE. You can also adjust the fee rate for the premix transaction. If you don’t have an SCODE, simply leave the field blank and proceed with Next.
Finally, you need to select which mixing pool you wish to enter. There are currently four different pools:
- 0.5 BTC
- 0.05 BTC
- 0.01 BTC
- 0.001 BTC
Only the pools which are smaller than your selected UTXO value will be shown. The choice of pool determines the size of the UTXOs in the coinjoin transaction. In addition, the Whirlpool fee is determined at 5% of the size of the pool (before any discount is applied). Importantly, you only pay this fee once for every premix transaction. Further rounds of mixing happen automatically to increase your anonymity, but come for free!
In the example above, the 0.001 BTC pool has been selected. Each Whirlpool coinjoin transaction has 5 outputs, which is termed an anonymity set (or anonset) of 5. The pool fee is shown as 5% of the pool size, and the UTXO provided is being split into 6 outputs.
Once you have selected your pool, you can click Preview Premix. Don’t worry, even though you may be asked for your wallet password, the premix transaction will not yet be broadcast.
Once you click Preview Premix, you will be presented with a view similar to the one below. Note first that the Premix, Postmix and Badbank wallets have been added on the left. The tabs allow you to select these wallets, which behave like normal Sparrow wallets except they do not offer addresses (so you cannot receive to them directly). Your existing wallet is named ‘Deposit’ and functions exactly as before.
Now consider the premix transaction displayed. Shown first in the transaction outputs are the Whirlpool Fee and the Badbank Change amount. Thereafter, the premix outputs are shown, as Premix Output #0, Premix Output #1 etc. These are slightly higher in value than the pool size, because the premix outputs are responsible for paying the miner fees for a coinjoin transaction. Finally, the miner fee for the premix transaction itself can be noted.
Once you’re ready to broadcast, click the Broadcast Premix Transaction button. If you want to change the UTXOs included, or the selected pool, simply return to the UTXOs tab.
Once the premix transaction has been broadcast, the Whirlpool client automatically starts. Click on the Premix wallet, and go to the UTXOs tab. It might take a few seconds before your server picks up the premix transaction. Once it does, you should see all of the premix outputs appear as Unconfirmed. Your first coinjoin transaction will start after the premix transaction has been mined, so you’ll need to wait for this to occur. Once confirmed, the Whirlpool client will select one of the UTXOs to be included in a mixing round. This is indicated by the progress bar that appears in the central ‘Mixes’ column. More information about the progress of the mixing round can be seen by hovering over the progress bar.
Once the Whirlpool coordinator has found enough available UTXOs from other users to join the round, it will ask the Whirlpool client to sign its input in the transaction, and the transaction will be broadcast. At this point, the progress bar will scan from left to right waiting for your server to pick up the newly broadcasted transaction. This transaction will spend the Premix UTXO to a new UTXO in the Postmix wallet. Click on the Postmix wallet on the left, and go to the UTXOs tab to see it.
Congratulations, your first coinjoin transaction is complete! The Whirlpool client will now proceed to select further premix UTXOs and mix them to postmix outputs.
Each postmix output that has been through one mixing round has an anonymity set of 5 (in other words, one of 5 possibilities). This is good, but not great. Ideally, you want this number to be higher to offer real anonymity. Acheiving this is very straightforward - simply keep Sparrow running with the wallet open. The Whirlpool client will continue to run and will select postmix UTXOs to participate in further mixing rounds. The great advantage is that it does not cost any further fees - your anonymity increases for free!
Important: While your UTXO is waiting to be selected, it is important that your computer does not sleep due to energy saving settings. If your computer sleeps, it will close the connection to the coordinator unilaterally causing the mix to fail. In order to protect other users, the coordinator will temporarily ban UTXOs that cause mixes to fail several times in short period. Disable computer sleep while mixing by using the Control Panel in Windows, the System Preferences in OSX and Power Management settings in Linux. Alternatively, you can install Caffeine (Windows), Amphetamine (OSX) or Caffeine NG (Linux). Sparrow can also prevent your computer from sleeping by keeping the display awake - see the function in the Tools menu.
If you wish, you can stop and start mixing with the button at the bottom of the UTXOs table. Sparrow will remember this setting across restarts.
The Postmix wallet can be used as a normal wallet for sending. By default, it will use the ‘Privacy’ setting when constructing a transaction. With this setting, the wallet attempts to create a fake 2 person coinjoin (also known as STONEWALL) when spending to further protect the anonymity of all postmix outputs. If this is not possible (generally due to insufficient funds), be aware that combining postmix UTXOs indicates common ownership over them and decreases your anonymity.
Below is an example of a fake two person coinjoin (STONEWALL) transaction. The first two outputs are of the same value, with one being the payment amount and the other returning to you as change (in addition to the normal change outputs). The inputs are carefully selected so that it is impossible to tell externally whether two people have coordinated to create a coinjoin to increase their privacy, or if this is simply a payment with additional outputs.
For a coinjoin mix to happen, there needs to be 2 to 3 premix UTXOs in each transaction. This ensures that the entropy remains high, and we are not simply mixing the same coins with each other over and over, which would provide little benefit. In addition, the premix UTXOs provide the miner fees for the transaction.
There are generally many more postmix UTXOs than premix UTXOs available to the pool. In practice, this means that your premix UTXOs will usually be mixed to postmix quickly, but once in the Postmix wallet it may take awhile before a postmix-to-postmix transaction happens. Selecting postmix UTXOs for remixing is done at random and therefore subject to variance - you might get several mixes in a short period, or wait a day for progress. Note that only one UTXO per pool is registered for a potential remix at a time. Leave Sparrow open in the background (note the Minimize to System Tray functionality in the View menu) and postmix transactions will occur as the UTXOs get selected into a round. Note also that random periods between mixes helps break pattern analysis.
More UTXOs in a given pool, along with a faster mixing cycle throughput increases the chances of being selected for a mix. One mix breaks deterministic links, while further mixes (from any of the mix outputs) increases your forward-looking anon set. Read Diving head first into Whirlpool Anonymity Sets to understand this better.
Sometimes, you may see an error icon next to your UTXO with a tooltip of “Input rejected”. Generally, this happens when there are too many failures, for example when client gets disconnected multiple times during a mix, causing too many mix failures in a short period of time. The Whirlpool coordinator implements an automatic temporary ban to protect itself against attacks or unstable clients. Such ban automatically expires after some time (about 12h). If you would like to get a UTXO in this state unbanned sooner, email email@example.com with the UTXO details so they can investigate.
Missing a postmix UTXO? Sometimes the Whirlpool client will advance the address index beyond the postmix wallet’s configured gap limit. You can increase the gap limit by going to the Settings tab and clicking the Advanced button. Be sure to Apply after closing the dialog.
It’s also possible to mix directly to cold storage (including multisig wallets!). With this feature, the postmix output goes directly into another open Sparrow wallet of your choosing after a configurable number of mixing rounds. This is vastly preferable to sending explicitly from postmix to another wallet, which may combine UTXOs and destroy your privacy gains. You can enable this feature by clicking the Mix to… button below the UTXOs table in the Postmix wallet. To ensure coinjoin outputs appear similar, only Native Segwit wallets are supported. It is also necessary for the cold storage wallet to be open for this feature to work. This is required to avoid address reuse.
The dialog that appears allows you to select the wallet, and minimum number of mixes to complete before mixing to it. Note that in order to increase privacy by reducing potential pattern analysis, there is a 75% chance of mixing to the selected wallet every mixing round after the minimum number of mixes has been reached. Practically, this means you can leave Sparrow to finish mixing, and all of the postmix outputs will appear in the cold storage wallet after awhile.
Since the cold storage wallet needs to be kept open in Sparrow, it is wise to lock the wallet from access using the function in the View menu. You can do this for the mixing hot wallet as well - the Whirlpool client will continue to run in the background.
Sparrow Terminal is a stripped down version of Sparrow that uses a text-based interface for the UI.
It can be run on systems without displays (typically servers).
To mix with Sparrow Terminal, download the appropriate Sparrow Server binary if you are running on a headless (no display) system.
You can also run Sparrow Terminal with the Sparrow Desktop binary on a normal system by specifying the
-t flag on the command line.
You will need to first configure your connected server in the Preferences, just as you do for the desktop application.
Then create the mixing wallet in Sparrow Terminal by entering the BIP39 seed, or transfer the
.mv.db wallet file from the Sparrow home folder on your desktop to the equivalent wallets folder on the server (see FAQ to locate these).
Finally, you may want to create or import a watch-only wallet to mix to.
You can create any wallet as watch-only (single or multisig) using the wallet’s output descriptor from clicking the Show/Edit button on the desktop Settings tab.
Once the wallets are set up, make sure both are loaded. Then you can configure the Mix To settings, and start and stop mixing from the Postmix UTXOs screen just as you do in Sparrow Desktop. If you want to mix the same wallet with both Sparrow Desktop and Sparrow Terminal at the same time, you will need to adjust the Mix To settings on both. Set the Index Range field on Sparrow Desktop to Even, and the Index Range field on Sparrow Terminal to Odd to avoid mix failures (or vice-versa).
There are currently two other Whirlpool clients - the Samourai Android wallet, and the Samourai CLI tool. The Samourai CLI comes as part of the Ronin Dojo node package, and can also be run on its own or connected to the Samourai GUI desktop tool.
It is possible to mix the same BIP39 wallet on either one of these clients and Sparrow at the same time. To do this, you will need to adjust the Mix To settings using the dialog described in the previous section.
- To mix simultaneously with Sparrow and the Samourai Wallet app, change the Index Range field to Even.
- To mix simultaneously with Sparrow and the Samourai CLI/GUI tool, change the Index Range field to Odd.
This will ensure that Sparrow does not try to mix to the same addresses as the other client by using different derivation indexes.
To restore a Samourai wallet on Sparrow for mixing (or a Sparrow Whirlpool wallet from seed), create a new wallet in Sparrow using the same process described in the Quick Start guide. However, instead of generating a new seed, enter your seed and passphrase from Samourai Wallet (or your backup). Once the wallet has been created, you can add the Whirlpool accounts (Premix, Postmix, Badbank) from the Settings tab. Select “Add Account” at the bottom, and then select “Whirlpool Accounts” from the dropdown.
Use of coinjoin is one of the best methods available to preserve your privacy. Every postmix UTXO can be said to have good forward privacy - in other words, it’s ownership cannot be determined from the past. Note that this doesn’t erase your past activity, but it does allow you to store and spend bitcoin privately. When considered in the context of Bitcoin’s global, open ledger, this is both valuable and necessary.