Documentation

English
  • English
  • Russian
Mina Overview

Ledger Hardware Wallet

You can use your Ledger Nano S hardware wallet to securely store your Mina private keys.

We are working on support for Ledger Nano X, but it is not yet completed.

The operations supported are

  • Keypair generation
  • Signing payment transactions
  • Signing delegation transactions

The app is not yet available for install through the Ledger Live user interface, but if you have a Nano S, you can sideload it onto your Ledger device by following the instructions below.

warning

We are currently wrapping up a security audit which has found no vulnerabilities, otherwise development is nearly completed.

Use at your own risk. Make sure you have a backup of your Ledger's BIP39 secret mnemonic phrase or use a separate Ledger device for testing this app.

Never reuse the same keypair from a testnet on mainnet!

Contents

Installing on Ubuntu

Before installing please make sure your Ledger device is updated to the latest firmware and fully configured. In particular, make sure that Ledger's udev rules are installed.

If the udev rules are installed then /etc/udev/rules.d/20-hw1.rules will exist. If this file is not present then you need to visit Ledger's website and follow the Linux instructions for fixing connection issues or, for advanced users, you can find the udev rules on the LedgerHQ Github.

1) Install Python 3

$ sudo apt-get install python3

2) Install pip3

$ sudo apt-get install python3-pip

3) Install prerequisite libraries

sudo apt-get install libudev-dev libusb-1.0-0-dev python-dev virtualenv

4) Install Python tools for Ledger Blue, Nano S and Nano X

$ sudo pip3 install ledgerblue

5) Download ledger-app-mina

Download the Latest Ledger App Mina Release from Github. We've currently tested version 1.0.0-beta.4

6) Verify the checksum

sha256sum ledger-app-mina-1.0.2-0-g843e809c.tar.gz

Compare the output of the above command to the SHA256 hash on the release download page. If they match, then proceed to the next step.

7) Extract the archive

$ tar xvzf ledger-app-mina-1.0.2-0-g843e809c.tar.gz
ledger-app-mina-1.0.2-0-g843e809c/README
ledger-app-mina-1.0.2-0-g843e809c/install.sh
ledger-app-mina-1.0.2-0-g843e809c/uninstall.sh
ledger-app-mina-1.0.2-0-g843e809c/mina_ledger_wallet
ledger-app-mina-1.0.2-0-g843e809c/bin/app.hex

8) Launch the installation script

Note: You can uninstall via uninstall.sh if you've installed a prior version.

$ cd ledger-app-mina-1.0.2-0-g843e809c
$ ./install.sh
Please unlock your Ledger device and exit any apps (press any key to continue)
Generated random root public key : b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'
Using test master key b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'

This will begin the installation of the app (continued in the next steps).

Important: If you have verified the checksum in step (6), you can ignore the public keys above and the "Application identifier" and "Application full hash" in subsequent steps. These warnings are because ledger-app-mina is not yet an approved Ledger app.

9) Allow the "unsafe manager"

Your Ledger device will warn you that the install script is an unsafe manager.

< X Deny unsafe manager >

Click left until you see

< ✓ Allow unsafe manager >

Select this option.

10) Install app Mina

Your Ledger device will ask if you want to install the Mina app.

< M Install app Mina >

Click left until you see

< ✓ Perform installation >

Select this option and enter your Ledger PIN code.

If the installation was successful the install script will terminate successfully and you will see the Mina logo among your list of installed apps.

11) Install the command-line wallet

$ sudo cp ./mina_ledger_wallet /usr/local/bin/

Installing on Mac

Before installing please make sure your Ledger device is updated to the latest firmware and fully configured.

1) Install Homebrew

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

For more information please visit the Homebrew website

2) Install python3

brew install python3

3) Install Python tools for Ledger Blue, Nano S and Nano X

$ pip3 install ledgerblue

4) Download ledger-app-mina

Download the Latest Ledger App Mina Release from Github.

5) Verify the checksum

shasum -a 256 ledger-app-mina-1.0.2-0-g843e809c.tar.gz

Compare the output of the above command to the SHA256 hash on the release download page. If they match, then proceed to the next step.

6) Extract the archive

$ tar xvzf ledger-app-mina-1.0.2-0-g843e809c.tar.gz
ledger-app-mina-1.0.2-0-g843e809c/README
ledger-app-mina-1.0.2-0-g843e809c/install.sh
ledger-app-mina-1.0.2-0-g843e809c/uninstall.sh
ledger-app-mina-1.0.2-0-g843e809c/mina_ledger_wallet
ledger-app-mina-1.0.2-0-g843e809c/bin/app.hex

7) Launch the installation script

Note: You can uninstall via uninstall.sh if you've installed a prior version.

$ cd ledger-app-mina-1.0.2-0-g843e809c
$ ./install.sh
Please unlock your Ledger device and exit any apps (press any key to continue)
Generated random root public key : b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'
Using test master key b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'

This will begin the installation of the app (continued in the next steps)

Important: If you have verified the checksum in step (5), you can ignore messages about the public keys above and the "Application identifier" and "Application full hash" in subsequent steps. These warnings are because ledger-app-mina is not yet an approved Ledger app.

8) Allow the "unsafe manager"

Your Ledger device will warn you that the install script is an unsafe manager.

< X Deny unsafe manager >

Click left until you see

< ✓ Allow unsafe manager >

Select this option.

9) Install app Mina

Your Ledger device will ask if you want to install the Mina app.

< M Install app Mina >

Click left until you see

< ✓ Perform installation >

Select this option and enter your Ledger PIN code.

If the installation was successful the install script will terminate successfully and you will see the Mina logo among your list of installed apps.

10) Install the command-line wallet

$ sudo cp ./mina_ledger_wallet /usr/local/bin/

Installing on Windows

Before installing please make sure your Ledger device is updated to the latest firmware and fully configured.

1) Install Python 3.9.1

Download and run the python installer: (https://www.python.org/ftp/python/3.9.1/python-3.9.1-amd64.exe)

2) Open Windows Powershell

Press Windows + R to open the run menu, type 'powershell.exe', and press Enter to launch Powershell

3) Install Python tools for Ledger Blue, Nano S and Nano X

In the powershell terminal, run the following command:

$ pip3 install ledgerblue

4) Download ledger-app-mina

Download the Latest Ledger App Mina Release from Github.

5) Verify the checksum

In the powershell terminal, run the following command:

Get-FileHash -Path ledger-app-mina-1.0.2-0-g843e809c.zip

Compare the output of the above command to the SHA256 hash on the release download page. If they match, then proceed to the next step.

6) Extract the archive

Right-click the .zip file in your Downloads folder and select Extract All.... In the resulting window just press "Extract" to unpack the archive.

7) Change directory to the newly extracted archive

PS > cd ledger-app-mina-1.0.2-0-g843e809c

8) (Optional) Uninstall a previous version of the mina app

If you have installed the mina app before, begin by uninstalling the old version with the following command:

PS ...\ledger-app-mina-1.0.2-0-g843e809c> python3 -m ledgerblue.deleteApp "--targetId" "0x31100004" "--appName" "Mina"

Make sure to approve any prompts on the ledger device itself.

9) Start the Installation of the new release

PS ...\ledger-app-mina-1.0.2-0-g843e809c> python3 -m ledgerblue.loadApp "--path" "44'/12586'" "--appFlags" "0x240" "--tlv" "--targetId" "0x31100004" "--targetVersion=1.6.0" "--delete" "--fileName" "bin/app.hex" "--appName" "Mina" "--appVersion" "1.0.0" "--dataSize" "64" "--icon" "010000000000ffffffffffffffffffeff7c7e393c9b3cdb3cdb3cdb3cdb3cd33cc799effffffffffff"

Please unlock your Ledger device and exit any apps (press any key to continue)
Generated random root public key : b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'
Using test master key b'04e95715d4813ab98c92833da9b169d3ff6ee11a4f94a465503cc91e77aaea688d45a0449f41bfaa2a1a789730e72d0ace759ca7c2b8a12e82c94cda61530cc363'

This will begin the installation of the app (continued in the next steps)

Important: If you have verified the checksum in step (5), you can ignore messages about the public keys above and the "Application identifier" and "Application full hash" in subsequent steps. These warnings are because ledger-app-mina is not yet an approved Ledger app.

10) Allow the "unsafe manager"

Your Ledger device will warn you that the install script is an unsafe manager.

< X Deny unsafe manager >

Click left until you see

< ✓ Allow unsafe manager >

Select this option.

11) Install app Mina

Your Ledger device will ask if you want to install the Mina app.

< M Install app Mina >

Click left until you see

< ✓ Perform installation >

Select this option and enter your Ledger PIN code.

If the installation was successful the install script will terminate successfully and you will see the Mina logo among your list of installed apps.

12) Using the command line wallet

When a command references mina_ledger_wallet later on in these docs, run the commands as ./mina_ledger_wallet ... from the same powershell prompt.

Generating a keypair

Note that on a Ledger device, generating a keypair doesn't actually store anything! The Ledger rederives the key every time it runs. This means you don't need to worry about losing your key when you uninstall/reinstall this application.

To derive a keypair and obtain the associated Mina address, open the Mina app on your Ledger device and then on your terminal use mina_ledger_wallet command.

For example, to get the Mina address corresponding to hardware wallet account 42 (BIP44 account 44'/12586'/42'/0/0) you would issue the following command.

$ mina_ledger_wallet get-address 42

You will be prompted to confirm

Get address for account 42 (path 44'/12586'/42'/0/0)
Continue? (y/N) y

Once confirmed, you will see

Generating address (please confirm on Ledger device)...

on your terminal while the Ledger device will display

👁  Get Address    >

This tells you what type of operation is being requested.

Follow the arrow indicator by pressing and releasing the right button on your Ledger.

The Ledger will now display the BIP44 path for the address you are requesting.

    Path (1/2)
  44'/12586'/42'/0 >

Note that the 42' in the path above corresponds to the account number. Check that your path's account number matches whatever account number argument you supplied to your get-address command.

Press the right button again until the Ledger displays

        ✓
<    Generate     >

Now press both left and right buttons simultaneously to select this option and generate the address.

The Ledger will now display

Processing...

whilst it generates the keypair.

Since Mina uses new elliptic curves that are not yet supported in hardware, this process can take up to 47 seconds.

Once completed the Ledger will display the address for you to carefully check and confirm.

  Address (1/4)
B62qnh5DZeX6eYFv >

Once approved the mina_ledger_wallet command will output the result, which you can use.

Received address: B62qnh5DZeX6eYFvtBn4nBTniXbN7R6cgKo6gYqQ7E2bKwLD3PTYZ4b

Your address 42 will be different than the one above.

note

When generating addresses you should, if possible, start with account 0 and increase the account number sequentially each time you require a new address.

Validating your private key

In order to validate your private key. make sure you have updated to the latest version of the mina damemon. Installation instructions can be found on the connecting page.

Now that you've created your key -- you'll want to validate that it works. For this keypair, it suffices to verify that signed transactions coming out of the ledger are parsed correctly and that the signature verifies on Mina.

Run the following command:

mina_ledger_wallet test-transaction --network mainnet 42 B62qnzbXmRNo9q32n4SNu2mpB8e7FYYLH8NmaX6oFCBYjjQ8SbD7uzV | mina advanced validate-transaction

Replace "B62q... " with your public key and 42 with your BIP44 account number. Warning: Make sure that your account_address is the one that corresponds to the account_number!

You'll need to go to your Ledger, check the transaction details and either "Accept" or "Reject".

If you reject, no test-transaction will be generated and this command will exit with an error.

If you accept, a test-transaction will be generated and you should see the following output:

Transaction was valid
All transactions were valid

Offline Mode

An alternate method for sending transactions is to use the offline mode of the ledger tool. This mode allows you to sign a transaction without connecting your ledger device to a running daemon. You can append the flag --offline to any commands with the mina_ledger_wallet tool but we will provide an example of how to use offline mode to send a transaction.

Sign an offline transaction

First step is to sign a transaction using the offline mode of the ledger:

  1. Generate a signed transaction with the following command:
mina_ledger_wallet send-payment --offline

In offline mode you must specify the --nonce and --fee parameters. To sign testnet transactions you must specify the --network testnet parameter (the default is mainnet).

note

If you are not on the mainnet, make sure you include the flag --network testnet so the ledger knows to sign the transaction for the testnet. Signed transactions for mainnet can be replayed on mainnet.

  1. Copy the output of this command.

The output will be a JSON blob that you will need for the next section. It should look something like this:

{
  "signature": "389ac7d4077f3d485c1494782870979faa222cd906b25b2687333a92f41e40b925adb08705eddf2a7098e5ac9938498e8a0ce7c70b25ea392f4846b854086d43",
  "payment": {
    "to": "B62qnzbXmRNo9q32n4SNu2mpB8e7FYYLH8NmaX6oFCBYjjQ8SbD7uzV",
    "from": "B62qnzbXmRNo9q32n4SNu2mpB8e7FYYLH8NmaX6oFCBYjjQ8SbD7uzV",
    "fee": "10000000",
    "token": "1",
    "nonce": "0",
    "memo": null,
    "amount": "1000000000",
    "valid_until": "4294967295"
  },
  "stake_delegation": null,
  "create_token": null,
  "create_token_account": null,
  "mint_tokens": null
}

Submit the transaction

This step currently requires a running daemon that's connected to the network, but you can also submit this transaction to any third-party gateway.

  1. Run a daemon on Devnet.

  2. Execute the following send-rosetta-transactions command.

mina advanced send-rosetta-transactions
  1. Paste the output from the mina_ledger_wallet in the previous section and then press Ctrl-D to submit the transaction.

This will send the signed transaction on the network. You should see the following output if the transaction was successfully sent:

Dispatched command with TRANSACTION_ID 4Rs6xMHVyo1J1TTQDCzynYvWPdBr9QRY23fuqvnHFvQiM2B4YD14dtWY2sDccbgx7eh5FYAsPSNrZ2M3AqEPfXoXjNxuWTgiwkL3nwaTaGhSoPA7LcfqiWT6uN9oookDeR6ZSMfd2bs9QSPRit8gPt3FSrDo8i3qM383AEG6g5pEm2i1m1cTTwrUe7y4Z2eB6DdWKhFhoYnx5ndQRtZt3D3o7gojdwwdpRzrWZgT9KcJfbXdZNTfXxr3G1VCVqgqmNJ6iGzn4uTGqpqCmJf6zRn196SWUyZ4DYrphvGF8GhJZYyPTwA2BMTBkF9xWC9zzJP8ZrAeyV1qV8k94dZaiyVt7Fac3r6BcDaMonMcpvnGy8fHF9Q25L2tjzHzwKMePkJztB5r

Audit

A security audit of the Mina Ledger app and its integration for the Nano S/X Hardware wallet was conducted by Least Authority. To read the report, click here