Skip to content

Latest commit

 

History

History
227 lines (148 loc) · 6.62 KB

README.md

File metadata and controls

227 lines (148 loc) · 6.62 KB
Raw

Ledger Zcash app

stability-wip License GithubActions

zondax_light zondax_dark

Please visit our website at zondax.ch

This app is still work in progress!

  • Ledger Nano S/S+/X Zcash app
  • Specs / Documentation
  • Rust unit tests
  • Zemu tests

Description of the Project

Welcome to the Ledger Zcash app repository developed by Zondax. This project contains the Zcash application for Ledger Nano S+ and X, providing users with the ability to securely manage their ZEC assets. This application supports sapling, enabling transfers between shielded and non shielded addresses.

ATTENTION

Please:

  • Do not use in production
  • Do not use a Ledger device with funds for development purposes.
  • Have a separate and marked device that is used ONLY for development and testing

Download and install a prerelease

Once the app is approved by Ledger, it will be available in their app store (Ledger Live). You can get builds generated by Github Actions from the release tab. THESE ARE UNVETTED DEVELOPMENT RELEASES

With our Zondax Hub you can install asset apps to your Ledger device and test them. This can be done with both released and unreleased versions developed by the zondax team. To install the Ledger Zcash App on your Ledger device, you can simply:

  1. Go to http://hub.zondax.ch/
  2. Connect your wallet
  3. Install the app

Another way to install the app is by downloading the installer script from the release page (https://github.com/Zondax/ledger-zcash/releases) and follow these commands. You only need zxtool.sh

If the file is not executable, run

chmod +x ./installer_s.sh

then run:

./installer_s.sh load

Troubleshooting

If you encounter any issues while using the App, please create and issue in this repository and the team will review it. You can also send an email to [email protected]

Contact Information/Support

For support, feedback, or inquiries, please reach out to us at: [email protected]

Development

Preconditions

  • Be sure you checkout submodules too:

    git submodule update --init --recursive

  • Install Docker CE

  • We only officially support Ubuntu. Install the following packages:

    sudo apt update && apt-get -y install build-essential git wget cmake \
libssl-dev libgmp-dev autoconf libtool

  • Install node > v16.0. We typically recommend using n

  • You will need python 3 and then run

    • make deps

  • This project requires latest Ledger firmware

Warning: Some IDEs may not use the same python interpreter or virtual environment as the one you used when running pip. If you see conan is not found, check that you installed the package in the same interpreter as the one that launches cmake.

How to build ?

We like clion or vscode but let's have some reproducible command line steps

  • Building the app itself

    If you installed what is described above, just run:

    make

Running tests

  • Running rust tests (x64)

    If you installed the what is described above, just run:

    make rust_test

  • Running C/C++ tests (x64)

    If you installed the what is described above, just run:

    make cpp_test

  • Running device emulation+integration tests!!

     Use Zemu! Explained below!

How to test with Zemu?

What is Zemu?? Great you asked!! As part of this project, we are making public a beta version of our internal testing+emulation framework for Ledger apps.

Npm Package here: https://www.npmjs.com/package/@zondax/zemu

Repo here: https://github.com/Zondax/zemu

Let's go! First install everything:

At this moment, if you change the app you will need to run make before running the test again.

make zemu_install

Then you can run JS tests:

make zemu_test

To run a single specific test:

At the moment, the recommendation is to run from the IDE. Remember to run make if you change the app.

Quick running

To build the application and run Zemu tests for all devices, we provide a shortcut.

make test_all

This command will build the application for every device with PRODUCTION_BUILD=1, install all the JS dependencies, and finally run all the integration tests available in the project.

Using a real device

How to prepare your DEVELOPMENT! device:

You can use an emulated device for development. This is only required if you are using a physical device

Please do not use a Ledger device with funds for development purposes.

Have a separate and marked device that is used ONLY for development and testing

There are a few additional steps that increase reproducibility and simplify development:

1 - Ensure your device works in your OS

2 - Set a test mnemonic

Many of our integration tests expect the device to be configured with a known test mnemonic.

  • Plug your device while pressing the right button

  • Your device will show "Recovery" in the screen

  • Double click

  • Run make dev_init. This will take about 2 minutes. The device will be initialized to:

    PIN: 5555
Mnemonic: equip will roof matter pink blind book anxiety banner elbow sun young

3 - Add a development certificate

  • Plug your device while pressing the right button

  • Your device will show "Recovery" in the screen

  • Click both buttons at the same time

  • Enter your pin if necessary

  • Run make dev_ca. The device will receive a development certificate to avoid constant manual confirmations.

Loading into your development device

The Makefile will build the firmware in a docker container and leave the binary in the correct directory.

  • Build

    make                # Builds the app

  • Upload to a device The following command will upload the application to the ledger. Warning: The application will be deleted before uploading.

    make load          # Builds and loads the app to the device

APDU Specifications