7 min read

How to Compile Samourai Wallet

Pepe, the Samourai Dev, drinking coffee

Compiling is the process of converting code written in a programming language, which can be understood by humans, into machine code, which can be executed by computers.β€Œβ€Œ
In this article we'll see how to compile Samourai Wallet and why that matters.β€Œβ€Œ
It's not as difficult as it might seem!

1. Why Compile the Software?

Suppose you are at some diner and you have just finished eating a slice of pie, which you really liked. You tell the cook how much you've loved it and ask for the recipe, which he happily gives you.

Now, how can you know if that recipe does indeed produce that pie? The only way to assure it is following the steps in the recipe and checking if the result is that very same pie.

Of course, the analogy isn't perfect. Cooking isn't math and you'd hardly end up with the exact pie, specially if you aren't a cook. But luckily we don't have that problem with software.

So, the first reason to compile is:

Don't Trust, Verify

  • If you compile and upload the software to your phone, you aren't trusting anyone;
  • If you download the apk and verify the signature, you are trusting the developer; but
  • If you download the wallet from Google or Apple, you are pretty much trusting everybody: the developers, the store provider, the government;

In our case, since the software is a wallet that controls our bitcoins, we'd better not trust anyone!


The second reason is customization. If there's some detail in the wallet you dislike or would prefer to change, open source software allows us to modify it.β€Œβ€ŒSure, this is more difficult than just compiling, but we'll see a few simple examples.


This last reason is undoubtedly the hardest. In case you believe your changes would be useful to others, you can request your code to be merged to the wallet, making it part of a future release and benefiting all users.

2. Compilation

We are going to use Ubuntu Linux in this tutorial, but the process is pretty much the same for any Linux distribution. Let's go through each step.

2.1 Get the Samourai Wallet Code

We need the git VCS (Version Control System) installed to obtain the code. If you don't have it yet, it can be installed in Debian-based distros with sudo apt install git.
Now, let's clone Samourai's repository with:

$ git clone https://code.samourai.io/wallet/samourai-wallet-android
$ cd samourai-wallet-android

We have downloaded the code into the samourai-wallet-android directory and entered it. If you now type git status, you will see a message like On branch develop.
Git repositories are organized in branches and we are currently in the develop branch, which is meant for code that is being worked on to be part of a future release.

Since our purpose here is to build Samourai for our own use, we should check out a branch that corresponds to a release, so we would have the same code that was released.
First, check the available branches with git branch -a.

At the time of this writing, the latest version released is 0.99.98f. Let's switch to that version using git checkout 0.99.98f. Now the files in the directory have been changed by the ones of version 0.99.98f.

2.2 Install Android Studio

Go the Android Studio download page and get the latest Linux version, which currently is Android Studio Dolphin | 2021.3.1 Patch 1 for Linux 64-bit:

Download Android Studio

Extract the contents of that package somewhere using the GUI or with tar xvf android-studio-2021.3.1.17-linux.tar.gz. In my case, I extracted them to /home/user/android-studio.

2.3 Open the Project

Inside Android Studio's directory there's the bin directory with the IDE executable. Start it with ./studio.sh. Android Studio will start loading.
The default options are fine to accept. At the welcome screen, select Open and choose the place where you've cloned the project. If asked if you want to trust the project, confirm it:

Opening the project can take a while. Some IDE errors might pop up and many messages about stuff being indexed will appear at the bottom. Just wait until those messages are gone.
Finally, Gradle will download the project dependencies. Be patient! I wrote this tutorial on a virtual machine, so it's very likely that it took longer for me than it will take for you :)

After all those indexing and downloads are done, it's very likely that the IDE will offer updates in the Gradle plugin or even in Android Studio itself. I recommend you install all of them (I also check the recommended steps), restarting the IDE if asked to do so.

Upgrading Gradle plugin

2.4 Build the Project

Now that we've updated everything and there are no more notifications left,we are ready to build the wallet. Open the Build menu and select Generate Signed Bundle / APK..., then choose APK.

Next, it will ask for a key store to sign the APK. Click on Create New..., then choose a path and password. You will also need an alias for the key with its own password (it can be the same password as the key store) and a name for the certificate. In the next dialog, you will input the information of this key store (check images below):

Finally, we need to select the build variant. We can choose a production or staging build and also a release or debug one.

Build variant

Production is meant to be used in mainnet whereas staging is more suitable for testnet. There are a few differences between both builds. For example, the production build does not allow the PIN entry screen to be recorded or screenshot for security purposes.

One thing to note here is that you can't have more than one production or staging APK in the same phone at the same time. So, if you would like for now to just try this procedure, you should probably choose staging. When you feel more comfortable with using your own compiled version in mainnet, you can go with production. In this latter case, you will have to first uninstall your already existing Samourai Wallet (remember to check your backup first!) and then install your APK.

The other choice is debug or release. As the name suggests, the former is indicated for debugging whereas release will generate an optimized version. We won't debug anything here, so choose release.

If you would like to have a third Samourai in your phone (like for testing PayNym transactions between 2 testnet wallets), you can easily create a new build variant. Open the app/build.gradle file and, under productFlavors, add one more variant. Here, I'm creating a dev variant:

dev {
	applicationId 'com.samourai.wallet.dev'
	versionCode 193
	versionName "0.99.98f"
	resValue "string", "app_name", "Samourai Dev"
	resValue "string", "version_name", "0.99.98f"

Anyway, after you've decided either you want a productionRelease or stagingRelease build, click Finish. Be a little more patient and, if everything goes well, a notification will appear. Click locate to be taken to the APK location.
Now you just have to copy the APK to your phone and install it.

Build successful

Congratulations! You have just built your Samourai Wallet from source and are now more sovereign :)

3. Customization

As I've said before, changing the source code requires having knowledge of Android development, so it's outside the scope of the tutorial, but let's see a few examples of simple things that can be done.

Change the app language: I like to use my Samourai Wallet in English instead of the the phone's language. There's no way to configure this in the app itself, but we can easily achieve that by going into the app/src/main/res/values/strings directory and deleting the undesirable strings.xml files. In my case, I delete those inside directories like values-es, values-de etc, keeping only the values directory.

Change the app icon and name: this is a bit silly, but the app can be disguised from a potencial physical attacker. You can disguise your app as TikTok, for example.
Download the TikTok app from a website like Apkpure, unzip the apk and get the icon from one of the directories under res. The icon is either called a.png or b.png.
Rename it to tiktok.png and copy it to app/src/main/res/drawable-hdpi.

Edit AndroidManifest.xml and, under <application>, change the android:icon value to @drawable/tiktok and android:label to TikTok:


Ask for PIN before transactions: this is a little more advanced, but I also like my wallet to ask me for the PIN before every transaction, so I created a preference for that:

PIN confirm preference

4. Conclusion

Building the wallet isn't really that difficult and allows us to make sure we aren't trusting anyone: we are indeed using the published open source code. Furthermore, one can change parts of the wallet, with code either made by himself or by others.

It's true there are many steps to be followed, but most of them only have to be done once.
For future releases, we'd only have to get the new code with git pull, switch to the newest release branch with git checkout, rebuild and upload the APK to the phone.

If this article was helpful for you, please consider a donation to the author.