Apple's Walled Garden

As you probably know, there are no iOS bitcoin wallets that support Samourai Whirlpool. If you wanted to initiate a mix from an iPhone, it is simply not possible, you'd have to use an Android phone running Samourai Wallet or a computer running Sparrow Wallet.

The primary reason for this is due to iOS wallet developers not willing to put in the development effort to build something that can be so easily blocked by Apple's App Store. Given Apple's propensity to crack the whip on anyone trying to build in payments that don't include their in-app payment system so they can take a cut, I don't blame them.

Modern Problems Require Modern Solutions

Today, for the first time ever, you are able to initiate Whirlpool mixes from an iPhone, thanks to the latest release of Sparrow Wallet (v1.7.1). To accomplish this, we are going to enlist some help from a Raspberry Pi to do the heavy lifting for us.

Sparrow Wallet is a bitcoin wallet with built-in support for Samourai Whirlpool. Since the last couple releases, Sparrow is now supported on systems without displays such as a Raspberry Pi via Sparrow Terminal. Sparrow Terminal also supports initiating Whirlpool mixes from a deposit account.

What this will enable you to do is connect to your Raspberry Pi running Sparrow Terminal, and control Sparrow from any device that can run a terminal.

Pre-requisites

For this guide, I'll be using:

• an iPhone
• Raspberry Pi (in my case, my Pi running Raspiblitz)
• WebSSH iOS app

Installing Sparrow Terminal

1. First, you need to install WebSSH on your iPhone. We will use this to create SSH connections to our Raspberry Pi.
2. Ensure that you are on the same network as your Pi.
3. Jump into your iOS Settings app, navigate to WebSSH, and ensure that Local Network is enabled, and Cellular Data is disabled.

4. Open the WebSSH app, and add a connection by clicking the top right corner + button on the home page of WebSSH.
5. Enter the following information
   1. Raspberry Pi's IP address
   2. SSH username
   3. SSH password
      Click the check mark in the top right corner to save this connection.

5. When taken back to the homescreen of WebSSH, click on your new connection in the center to SSH into your Raspberry Pi. You will be prompted to enter "yes" on the very first connection to confirm that you trust the device. After that, you will be connected to your Raspberry Pi. In my case, I'm greeted with the Raspiblitz CLI menu.

6. The key centered in the top row of the keyboard with 4 way arrow key allows you to hold it down, and slide in any direction to act as the directional keys of a keyboard. If you're greeted with the above screen, press and hold the 4 way arrow key, then slide to the right to move from Select to Exit, then press return on your keyboard. If you are already in a terminal window where you can type commands, you can skip this step.

   • Important: Get used to navigating with that 4 way arrow, you will use it often in WebSSH.

7. Run the following code in the terminal. If you paste it in there, it will automatically run all lines except for the last one. So if you paste the code, you will need to hit the return key one more time to run Sparrow in terminal mode

   Note: the command to run Sparrow after install from the terminal will always be /opt/sparrow/bin/Sparrow -t, unless you're using something like Tmux. More on that later.

# download
wget https://github.com/sparrowwallet/sparrow/releases/download/1.7.1/sparrow-server_1.7.1-1_arm64.deb
wget https://github.com/sparrowwallet/sparrow/releases/download/1.7.1/sparrow-1.7.1-manifest.txt
wget https://github.com/sparrowwallet/sparrow/releases/download/1.7.1/sparrow-1.7.1-manifest.txt.asc
# checksum check
sha256sum -c sparrow-1.7.1-manifest.txt --ignore-missing
# get PGP pubkey
curl https://keybase.io/craigraw/pgp_keys.asc | gpg --import
# signature check
gpg --verify sparrow-1.7.1-manifest.txt.asc

# install sparrow server
sudo dpkg -i "sparrow-server_1.7.1-1_arm64.deb"

# options
/opt/sparrow/bin/Sparrow --help

# start
/opt/sparrow/bin/Sparrow -t

If you've followed the steps correctly, you will be prompted with the main menu of Sparrow Terminal:

Configuring Sparrow Terminal

Navigate to Preferences > Server and configure Sparrow to use the bitcoin node of choice.

• If you're running this on a Raspiblitz and want to utilize the node running on the same device, use 127.0.0.1 for the IP address and:
  • Port 50001 for Electrs
  • Port 50021 for Fulcrum
• Enable the Tor proxy regardless of if you're going to be connecting to a node over Tor. If you don't enable Tor, then the Whirlpool client will connect to the Whirlpool coordinator over clearnet.
  • Set Use Proxy? to Yes
  • Set Proxy URL Box 1 to localhost and Box 2 to 9050 to use Sparrow's built in Tor connection.

Note: If you are unable to navigate to different sections of the menu with arrows, try using the TAB button in the top row of your keyboard

Select the Test option at the bottom to confirm your connection.

Select Done to return to the main menu.

Wallet configuration

Using an existing Sparrow Wallet file

If you already have a Sparrow Wallet file that you use with the standard Sparrow Desktop application, you will need to move it to the wallets directory. To identify this directory, from the main menu in Sparrow Terminal select Wallets > Open Wallet..., and you will see the wallets directory you will need to move the file into. In my case, that directory is /home/admin/.sparrow/wallets:

Once you have a file loaded, it will appear here, and you will be able to open it.

Creating a new Sparrow Wallet file

1. To create a new wallet, from the main menu, select Wallets > Create Wallet...

2. Select Software (BIP39) wallet and continue to next screen
3. When creating a new wallet, you can either enter the seed words to recover an existing wallet, or choose Generate New at the bottom to generate new seed words. As you'd expect, you also have the option to include a BIP39 passphrase.

Once the wallet has been created, you are presented with a screen that shows the name of your new wallet, and gives you a few options:

4. Let's add the Whirlpool accounts to our wallet (pre-mix, post-mix, badbank). Navigate to Settings > Add Account > select the drop down > Whirlpool Accounts, then finally select Add Account again.

If successful, you will be prompted with the following message:

Now if we navigate back to the wallet, you will see WalletName - Deposit at the top, with an option to switch to different Accounts at the bottom:

Mixing from Sparrow Terminal

1. Select Receive, and fund the newly generated address within your deposit wallet with some UTXOs that you want to mix in Whirlpool.
   • To be able to copy the address from the terminal, long press the Terminal window, and select Show Scrollback Buffer. You will then be able to select the address and copy it.

2. Once you've funded your wallet, select Back and go to the UTXOs screen

3. Select the UTXOs you want to mix my using the arrows to navigate to a UTXO, and press the space bar to select the UTXO. You'll see a (*) on the left side of the UTXO that's marked for selection.

4. Press Tab to navigate to the Mix Selected option, enter an SCODE (if you have one), select your desired Premix Priority, then select Next

5. Select the Pool size (100k, 1M, 5M or 50M sats), then select Broadcast

Once broadcasted, you should get the TXID of the broadcasted pre-mix transaction:

Congratulations! You've initiated a Whirlpool mix from an iPhone. As long as the Sparrow Terminal application continues running, and your SSH connection doesn't drop, it will mix your selected UTXOs and continue remixing them.

There's a problem here though - Once I disconnect the SSH window, or my connection drops, Sparrow Terminal will shut down and my mixing will no longer continue. So how do we remedy this?

Enter Tmux.

Enabling continuous remixing on Sparrow Terminal

When Sparrow Terminal was released in Sparrow v1.7.0, it was mentioned that a Sparrow Daemon would be released in a future update. A daemon a process that runs in the background. When the Sparrow Daemon is released, it will be very easy to run as a background process.

In the mean time, we need to come up with a workaround so that Sparrow Terminal can continuously run in the background.

Tmux is a terminal application that allows for running terminal sessions that you can "detach" from and "reattach" to later. This allows for any terminal sessions to continue running in the background while you are not connected.

We will leverage tmux to run Sparrow Terminal as a background process so it can continuously remix for us.

Installing tmux

1. Disconnect your terminal session by clicking the Eject button in the top left corner of WebSSH
2. Reconnect to your Pi by clicking on the Pi connection in WebSSH
3. Select Exit to get to the terminal
4. Install tmux by running the command sudo apt install tmux

Running Sparrow in the background with tmux

1. Start a tmux session named sparrow by running the command tmux new -s sparrow in the terminal window
   • If you want the session to be named something else, replace sparrow in the above command with your desired session name
2. Start Sparrow by running the comand /opt/sparrow/bin/Sparrow -t
3. Unlock the wallet you want to mix by open the wallet and entering any password or passphrases necessary

That's it! Now, your Sparrow Terminal is running in a Tmux session.

• To list all your tmux sessions, run the command tmux ls
• You can always reconnect to the session by running the command tmux attach-session -t sparrow, where the last argument sparrow is the name of the session.

Configuring your post-mix wallet on iOS

In order to spend from a post-mix wallet on iOS, you need to import the seed (and passphrase, if applicable) to a mobile bitcoin wallet like BlueWallet that allows you to specify derivation paths. The derivation path for the post-mix wallet is m/84'/0'/2147483646'

Make sure that you are connected to your own node (or a trusted Electrum server over Tor) before you import your post-mix wallet.

1. Install BlueWallet if you have not done so already
2. Configure Node settings ... > Network > Electrum Server
3. Add a wallet with Add now button
4. Select Import wallet
5. Enter your seed words (and passphrase, if applicable)
6. Enable Search accounts, then Import
7. Select the HD SegWit wallet with the m/84'/0'/2147483646' derivation path
   • Note: You will have to manually enter this derivation path if your post-mix wallet has never received a UTXO. That's because BlueWallet's search acccounts feature looks for derivations paths where there has been at least one transaction.

Done! You now have your post-mix wallet configured on your iPhone so you can spend post-mix sats on the go. On top of this, you can now initiate mixes from your iPhone via SSH. Happy mixing!

Caution: There are currently no wallets on iOS that support post-mix tools, such as Stonewall/Stonewall2x/Stowaway. That includes BlueWallet. If you want to maintain best privacy practices, you will want to spend from a wallet like Sparrow or Samourai that supports these post-mix tools.