Merge pull request #70 from Zondax/dev

New Release

.github/workflows/main.yml

@@ -45,6 +45,12 @@ jobs:
         run: make zemu_install
       - name: Run tests
         run: make zemu_test
+      - name: Upload Snapshots (only failure)
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: snapshots-tmp
+          path: tests_zemu/snapshots-tmp/
 
   build_package_nanosp:
     needs: [configure, build_and_test]

README.md

@@ -11,19 +11,73 @@ _Please visit our website at [zondax.ch](https://www.zondax.ch)_
 
 ---
 
-## Compilation and load
+This project contains the Ironfish DKG app for Ledger Nano S+, Stax and Flex.
 
-You can follow the following steps to setup a development environment on a host running a Debian based Linux distribution (such as Ubuntu).
+- Ledger Nano S+/Stax/Flex Ironfish app
+- Specs / Documentation
+- Zemu tests
 
-### Prerequisites
+## ATTENTION
 
-* Install the [Rust language](https://www.rust-lang.org/)
+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*
+
+Download a release from here (https://github.com/Zondax/ledger-ironfish/releases). You only need `installer.sh`
+
+If the file is not executable, run
+```sh
+chmod +x ./installer.sh
+```
+
+then run:
+
+```sh
+./installer.sh load
+```
+
+# Development
+
+## Preconditions
+
+- Be sure you checkout submodules too:
+
+    ```
+    git submodule update --init --recursive
+    ```
+
+- Install Docker CE
+    - Instructions can be found here: https://docs.docker.com/install/
+
+- 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 > v13.0`. We typically recommend using `n`
+
+- You will need python 3 and then run
+    - `make deps`
+
+- This project requires Ledger firmware 2.0
+    - The current repository keeps track of Ledger's SDK but it is possible to override it by changing the git submodule.
+
+- Install the [Rust language](https://www.rust-lang.org/)
 
 ```bash
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-* Install Ledger Rust building tools dependencies
+- Install Ledger Rust building tools dependencies
 
 ```bash
 # Clang compiler, GCC ARM cross-compiling toolchain 
@@ -36,7 +90,7 @@ rustup default nightly-2023-11-10
 rustup component add rust-src --toolchain nightly-2023-11-10
 ```
 
-* Install [ledgerwallet](https://github.com/LedgerHQ/ledgerctl/) and [cargo-ledger](https://github.com/LedgerHQ/cargo-ledger)
+- Install [ledgerwallet](https://github.com/LedgerHQ/ledgerctl/) and [cargo-ledger](https://github.com/LedgerHQ/cargo-ledger)
 
 ```bash
 # Install ledgerwallet, a Python dependency of cargo-ledger to sideload binaries on Ledger devices
@@ -47,14 +101,125 @@ cargo install cargo-ledger
 cargo ledger setup
 ```
 
-You are now ready to build the app for Ledger devices!
+*Warning*: Some IDEs may not use the same python interpreter or virtual enviroment 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 the what is described above, just run:
+    ```bash
+    make all
+    ```
+
+## Running tests
+
+- Running rust tests (x64)
+
+    If you installed the what is described above, just run:
+    ```bash
+    make rust_test
+    ```
+
+- Running device emulation+integration tests!!
+
+   ```bash
+    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
 
-### Building
+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.
 
-Now that you have followed the [prerequisites](#prerequisites) guide, you can build the app with the following command executed in the root directory of the app.
+```bash
+make zemu_install
+```
+
+Then you can run JS tests:
 
 ```bash
-cargo ledger build nanox
+make zemu_test
 ```
 
-This command will build the app for the Nano X, but you can use any supported device (`nanox`, `nanosplus`, `stax`, `flex`)
+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.
+
+## 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**
+- In Linux hosts it might be necessary to adjust udev rules, etc.
+
+  Refer to Ledger documentation: https://support.ledger.com/hc/en-us/articles/115005165269-Fix-connection-issues
+
+**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
+
+- [APDU Protocol](docs/APDUSPEC.md)

app/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ledger-ironfish-dkg"
-version = "0.0.0" # The version is being taken from Makefile.version file
+version = "0.0.0"            # The version is being taken from Makefile.version file
 edition = "2021"
 
 [[bin]]
@@ -9,8 +9,8 @@ test = false
 path = "bin-app/app.rs"
 
 [dependencies]
-ledger_device_sdk = { git = "https://github.com/Zondax/ledger-device-rust-sdk", rev = "9408c1ffc278a363e1903b4cc0b765a31c4eeace", optional = true }
-# ledger_device_sdk = { version="1.14.0" , optional = true}
+# ledger_device_sdk = { git = "https://github.com/Zondax/ledger-device-rust-sdk", rev = "923e5cf53d09e0e81c64eecc92c26800fad4bf45", optional = true }
+ledger_device_sdk = { version = "1.17.1", optional = true }
 # ledger_device_sdk = { path="../../ledger-device-rust-sdk/ledger_device_sdk" , optional = true}
 include_gif = "1.2.0"
 serde = { version = "1.0.192", default_features = false, features = ["derive"] }
@@ -44,7 +44,9 @@ lazy_static = { version = "1.5.0", default-features = false, features = [
 spin = { version = "0.9.8", default-features = false, features = [
     "spin_mutex",
 ], optional = true }
-lexical-core = { version = "1.0.1", default-features = false, features = ["write-integers"] }
+lexical-core = { version = "1.0.1", default-features = false, features = [
+    "write-integers",
+] }
 
 [dev-dependencies]
 lazy_static = { version = "1.5.0" }
@@ -70,6 +72,8 @@ lto = true
 [features]
 default = ["ledger"]
 ledger = ["ledger_device_sdk", "spin", "lazy_static/spin_no_std"]
+# This will require to use zondax ledger device sdk, where zlog is added.
+ledger-debug = ["ledger_device_sdk", "spin", "lazy_static/spin_no_std"]
 
 [package.metadata.ledger]
 curve = ["ed25519"]

app/Makefile.version

@@ -3,4 +3,4 @@ APPVERSION_M=0
 # This is the minor version
 APPVERSION_N=5
 # This is the patch version
-APPVERSION_P=1
+APPVERSION_P=2

app/src/app_ui/run_action.rs

@@ -87,7 +87,7 @@ pub fn ui_review_transaction<'a>(
             .map(|(name, value)| Field { name, value })
             .collect();
 
-        let mut review = NbglReview::new()
+        let review = NbglReview::new()
             .tx_type(TransactionType::Transaction)
             .titles("Review", "Transaction", "Approve Transaction?")
             .glyph(&FERRIS);
@@ -391,7 +391,7 @@ pub fn ui_review<'a>(
         #[cfg(target_os = "flex")]
         const ICON: NbglGlyph = NbglGlyph::from_include(include_gif!("flex_icon.gif", NBGL));
 
-        let mut review = NbglReview::new()
+        let review = NbglReview::new()
             .tx_type(TransactionType::Operation)
             .light()
             .titles(title, _subtitle, _finish_title)

app/src/bolos.rs

@@ -1,4 +1,4 @@
-#[cfg(feature = "ledger")]
+#[cfg(feature = "ledger-debug")]
 extern "C" {
     fn check_app_canary();
     fn zemu_log_stack(ctx: *const u8);
@@ -7,14 +7,14 @@ extern "C" {
 }
 
 pub fn app_canary() {
-    #[cfg(feature = "ledger")]
+    #[cfg(feature = "ledger-debug")]
     unsafe {
         check_app_canary()
     }
 }
 
 pub fn zlog(_buf: &str) {
-    #[cfg(feature = "ledger")]
+    #[cfg(feature = "ledger-debug")]
     unsafe {
         zemu_log(_buf.as_bytes().as_ptr())
     }
@@ -23,17 +23,17 @@ pub fn zlog(_buf: &str) {
 }
 
 pub fn zlog_stack(_buf: &str) {
-    #[cfg(feature = "ledger")]
+    #[cfg(feature = "ledger-debug")]
     unsafe {
         zemu_log_stack(_buf.as_bytes().as_ptr())
     }
     #[cfg(test)]
     std::println!("{_buf}")
 }
 
-pub fn zlog_num(buf: &str, num: u32) {
-    #[cfg(feature = "ledger")]
+pub fn zlog_num(_buf: &str, _num: u32) {
+    #[cfg(feature = "ledger-debug")]
     unsafe {
-        zemu_log_num(buf.as_bytes().as_ptr(), num)
+        zemu_log_num(_buf.as_bytes().as_ptr(), _num)
     }
 }