Ledger Sideloading Instructions - MacOS

Sideloading is no longer necesasry to load the Radix app onto your Ledger hardware wallet device. Please see these instructions on installing Radix on Ledger Nano S or X via the Ledger Live application.

Before you start these instructions, make sure you have read and done everything on the introduction and prerequisites first.

This process has been tested on MacOS Big Sur, Catalina, Mojave, and High Sierra. It may work on other versions, but this has not been verified.

These instructions assume that the Mac you use to do the sideload does not already have developers tools like Homebrew or Python installed. If it does, then things may not precisely follow the flow described below. It should still work with slight modifications, but we will assume that if the Mac’s owner has developer tools, they should readily see what modifications might have to be made as you go.

Install the Radix Ledger App

Have your Ledger Nano S device ready, with its USB cable to allow it to connect to the MacOS computer where you will perform the sideload install using the steps below.

If Ledger Live is installed on this computer, make sure you quit the Ledger Live desktop application before starting the sideload installation, as it takes exclusive control of the connection to the Ledger device and you will not be able to connect from the command line when it is open.

Open the Finder, and in the “Go” menu at the top of the screen, select “Home” to go to your home folder. Now in the File menu, select “New Folder” and rename the folder: Radix

Leave this Finder window open.

Double-click the downloaded zip file to unzip it, and you should now have a folder called app-radix. Drag that entire folder inside the Radix folder that you just created above in your home folder. (For those of you inclined to check hashes, this link provides the md5. If you don’t know what this is, you can safely skip it and move on.)

Double check that you now have an app-radix folder inside your Radix folder, which is inside your home directory. Also ensure that you have not named the folder radix or RADIX – the capitalization matters. The rest of these instructions rely on these names and locations.

Open Spotlight (it’s the little magnifying glass icon near the upper right of your screen), type “Terminal”, and press return. This should open the Terminal application, which will look like a mostly-blank window with a prompt where you can type commands. Something like this:

empty terminal

My prompt shown in this screenshot is: [email protected] ~ %

Yours will be different, and depends on your own computer and user name. Seeing the prompt means that Terminal is waiting for your input. Remember what your particular prompt looks like, as it will tell you when a command has finished and Terminal is waiting for your next command.

Now we’re ready to get down to business. To do the Ledger app sideload, we’re going to be running a number of commands in Terminal. It’s going to look a little scary if you’re not familiar with these sorts of things, but have no fear, we’ll talk you through it.

You’re going to be copying commands from this page, and pasting them into your Terminal application. When there is a command for you to copy, we’ll put it in a box like this:

echo Hello!

To copy the text in the box, move your mouse over the box and you should see a small clipboard icon in its upper right. Click this icon to copy the full text of the box (you should see "copied!"). You can then go to your Terminal application and paste the text, either using the Edit > Paste menu, or the command-V keyboard shortcut.

To try this out, copy the command in the box above, paste it into Terminal. Before you press return to run any command, double check that what you see in Terminal includes everything you see in the box you copied it from.

Press return now and the output of the command should be a friendly Hello! message, like this:

hello terminal

You are now a command line jockey like a proper hacker. Let’s get to work.

First, we will install a tool called “Homebrew” that will make it easier to get some other tools we need. Run the following command (again, by clicking the copy icon in the upper right of the text box, pasting it into Terminal, checking it, and then pressing return):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

In the Terminal window, you may now be asked to enter a password. Enter your computer’s system password and press return to proceed.

The password needed here is the same password that you use to log into your computer when you turn it on.

When you input your password, you will not see any letters or asterisks come up on the screen. Not to worry, your password is still being received by the Terminal application. If you type your password and press return, it will then move onto the next stage of the process. If your password is rejected, just try entering it again.

The Terminal command will now automatically download and install Homebrew. This will likely take many minutes depending on your internet speed – and will involve a lot of text scrolling by in your Terminal window.

Depending on your version of MacOS, you may see the message: Press RETURN to continue or any other key to abort. If you do, press return

You may also be asked to enter you password in Terminal again. If you are, just enter your computer’s system password again, just as you did before.

At some points during this installation, it may even look like nothing is happening, but just be patient. When it is done, you will be returned to your prompt (the bit of text you first saw above when opening Terminal).

Are you back to your prompt again? Great, we can move on to the next steps.

Near the end of the previous installation step, just before your prompt, you may see a suggestion to do something like this:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/myusername/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

If you do, you will need to take an extra couple of steps here. (If you don’t see these lines in Terminal, you can just skip this box entirely and move on.)

First copy the line starting with echo from your Terminal window – not from the example shown here. Paste that full line back into Terminal and press return.

Second, do the same thing with the second line starting with eval, again copying it from your Terminal window and pasting it back there and pressing return. After you’ve done both of these steps, move on to the following instructions.

With the Homebrew install now complete, we’ll use it to install "Python" - a tool that is required for the Radix Ledger app install:

brew install [email protected]

This may again take a few minutes, with lots of text scrolling by. Just wait to be returned to your prompt.

It’s possible that a window may pop up here, asking you to allow access to your keychain. If you see this, just enter your computer’s system password and click "always allow".

Now run this command to add a few necessary libraries:

brew install libtiff libjpeg webp little-cms2

This also may take a few minutes.

Then using Python’s “pip3”, we’ll install another tool called “virtualenv”, which is also required, by running this command:

pip3 install virtualenv --user

Don’t worry if you see warnings about using an older version of pip. We’re using the version we want.

The next command creates a “virtual environment” that will contain the Ledger HQ-provided sideloading tool. It will put this virtual environment in the Radix folder that you created earlier:

python3 -m venv ~/Radix/radixenv

Now we load up the virtual environment for the next steps:

source ~/Radix/radixenv/bin/activate

Then we can install Ledger HQ’s sideloading tool “ledgerblue”:

pip3 install ledgerblue

This step might take a few minutes as it downloads and installs ledgerblue. As with the Homebrew installation, just make sure to wait until you see your prompt once again.

Then we go into the folder where we earlier put the Radix Ledger app source code:

cd ~/Radix/app-radix

Now we’re finally ready to do the sideload.

At this point, connect your Ledger Nano S with its USB cable, and unlock it with your PIN. You should see the Ledger’s menu on the device screen, where you might have a Bitcoin or Ethereum app if you installed one of these already.

Once again – do not open the Ledger Live application on the computer! You only need to connect the Ledger device itself.

Also, make sure that you don’t launch any Ledger apps on the Ledger device (such as a Bitcoin or Ethereum app. You simply need to enter your PIN and wait at the main menu.

Once the Ledger device is connected and ready, we’re going to do one last scary-looking Terminal command that will perform the sideload install:

python -m ledgerblue.loadApp \
--path "44'/1022'" \
--curve secp256k1 \
--tlv \
--targetId 0x31100004 \
--delete \
--fileName bin/app.hex \
--appName Radix \
--dataSize $((0x`cat debug/app.map |grep _envram_data | tr -s ' ' | cut -f2 -d' '|cut -f2 -d'x'` - 0x`cat debug/app.map |grep _nvram_data | tr -s ' ' | cut -f2 -d' '|cut -f2 -d'x'`)) \
--icon 0100000000ffffff00ffffffffffffffffffe1fffdfffce7fe4ffe1fffbfffffffffffffffffffffff \
--rootPrivateKey b5b2eacb2debcf4903060e0fa2a139354fe29be9e4ac7c433f694a3d93297eaa

Just like all of the other commands, click the copy button at upper right of the box and paste the whole thing into your Terminal at once. Once you make sure it matches what you see here, press return.

You’ll now start seeing more strange text in the Terminal, but this time you’ll be asked to confirm some things on your Ledger Nano S device itself using its buttons.

From here on, we’ll show messages shown on the Ledger device’s screen marked with a Ledger icon like this:

ledger 20x20 Ledger screen text

First, you should see:

ledger 20x20 Deny unsafe manager

Don’t panic about this being an “unsafe manager”! This is just your Ledger device being suitably cautious about sideloaded apps. In this case we trust what we are loading and so we can safely ignore this warning.

Here you will need to use the device’s right button to advance through some screens before you get to a screen where you can use both buttons to confirm that you want to allow the “unsafe manager”, like this:

ledger 20x20 > public key (9 screens) > Allow unsafe manager

You may see a warning about a “broken certificate chain” in Terminal here. You can safely ignore this.

Shortly, you should see on your Ledger screen:

ledger 20x20 Loading, please wait

Once the progress bar fills, this will be followed by:

ledger 20x20 Install app Radix

Here again you will have to use the device’s right button to advance through some screens before you get to a screen where you can use both buttons to confirm like this:

ledger 20x20 > Version > Identifier (5 screens) > Code Identifier (5 screens) > Perform Installation

Note: The “Version” screen may not actually show any version information. Again, this is normal and expected for this sideloading process.

Then you’ll be asked to enter your Ledger’s PIN again. Once you do so, momentarily you should be returned to your prompt in Terminal.

You’ve just completed the sideload!

If this last command failed, check that you are indeed on the latest Ledger firmware, that your Ledger is connected with the PIN entered, and that you have enough space remaining on your Ledger. You may have to remove one or two other Ledger apps if you do not have enough space.

Loading the Radix Ledger App

You’ll now see the Radix app listed as one of the options on your Ledger Nano S. If you have other apps like Bitcoin or Ethereum installed, you may have to press the buttons to scroll to the Radix app.

Go ahead and try launching it by pushing both buttons.

Because we did the installation by sideload, rather than using Ledger’s own Manager, the Ledger shows a warning that This app is not genuine. This is nothing to worry about; just click through the screens and confirm like this:

ledger 20x20 > Identifier (5 screens) > Open application

You should now see Radix is ready on the Ledger’s screen, which means that you’re ready to go to use the Radix Desktop Wallet. You’ll have to do this last step each time you want to use your Ledger device with the Radix Desktop Wallet.

You can now disconnect your Ledger Nano S and you’ll have the Radix app there whenever you plug it in. If you’re a Windows user borrowing a Mac from a friend, you can thank them and go back to your own PC.

From here, you can learn how to connect your Ledger to the Radix Desktop Wallet and start doing transactions.

Uninstalling the Radix Ledger App

If you no longer want the Radix Ledger app on your device, you can easily uninstall it with the sideloading tools.

When the Radix Ledger app becomes listed on the Ledger Live Manager, you will want to do this before switching to the Manager version of the app.

To do the uninstallation, the easiest option is to the same computer that you originally used to do the sideloading above, as it will already have all of the tools required installed.

If you no longer have access to that computer, then simply repeat the installation instructions above starting with the command that starts /bin/bash -c "$(curl …​ and continue until you get to the command pip3 install ledgerblue. Do this pip3 step, quit Terminal (so you have a fresh Terminal for the instructions below), and then return back here to do the uninstall.

Open your Terminal application again, and run the following command:

source ~/Radix/radixenv/bin/activate

Now connect your Ledger Nano S and enter your PIN. Do not open the Radix app, or any other app on the Ledger device.

Then run this command:

python -m ledgerblue.deleteApp \
--targetId 0x31100004 \
--appName Radix \
--rootPrivateKey b5b2eacb2debcf4903060e0fa2a139354fe29be9e4ac7c433f694a3d93297eaa

This will begin the uninstall, and you will need to confirm some things on your Ledger device’s screen.

Just like when you did the install, first you should see:

ledger 20x20 Deny unsafe manager

Again you will need to use the device’s right button to advance through some screens before you get to a screen where you can use both buttons to confirm that you want to allow the “unsafe manager”, like this:

ledger 20x20 > public key (9 screens) > Allow unsafe manager

Then you should see:

ledger 20x20 Uninstall Radix

Use the Ledger’s buttons to scroll to the right and confirm like this:

ledger 20x20 > Identifier (5 screens) Confirm action

And that’s it! The Radix Ledger app should now be uninstalled.