Skip to content
This repository has been archived by the owner on Aug 22, 2024. It is now read-only.

Commit

Permalink
doc: document var issues
Browse files Browse the repository at this point in the history
  • Loading branch information
dj8yf0μl committed Jan 9, 2024
1 parent 3ead76b commit b4194a4
Show file tree
Hide file tree
Showing 20 changed files with 232 additions and 129 deletions.
183 changes: 54 additions & 129 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,135 +1,60 @@
# Ledger Rust Near Application

![Rule enforcer](https://github.com/dj8yfo/app-near-rs/actions/workflows/guidelines_enforcer.yml/badge.svg) ![Build and tests](https://github.com/dj8yfo/app-near-rs/actions/workflows/build_and_functional_tests.yml/badge.svg)
## Successful cases

This is a Near application written in Rust which can be forked to start a new project for the Ledger Nano S/X/SP devices.
### Case 1 (1 transfer action, parsed after header review):

* Implements standard features (display address, transaction signature...),
* Has functional tests using [Ragger](https://github.com/LedgerHQ/ragger),
* Has CI workflows mandatory for app deployment in the Ledger store.

### Links

* 📚 [Developer's documentation](https://developers.ledger.com/)<br/>
* 🗣️ [Ledger's Discord server](https://discord.gg/Ledger)

## Quick start guide

### With VS Code

You can quickly setup a development environment on any platform (macOS, Linux or Windows) to build and test your application with [Ledger's VS Code extension](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools).

By using Ledger's own developer tools [Docker image](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-app-dev-tools), the extension allows you to **build** your apps with the latest SDK, **test** them on **Speculos** and **load** them on any supported device.

* Install and run [Docker](https://www.docker.com/products/docker-desktop/).
* Make sure you have an X11 server running :
* On Ubuntu Linux, it should be running by default.
* On macOS, install and launch [XQuartz](https://www.xquartz.org/) (make sure to go to XQuartz > Preferences > Security and check "Allow client connections").
* On Windows, install and launch [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (make sure to configure it to disable access control).
* Install [VScode](https://code.visualstudio.com/download) and add [Ledger's extension](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools).
* Open a terminal and clone `app-near-rust` with `git clone git@github.com:dj8yfo/app-near-rs.git`.
* Open the `app-near-rust` folder with VSCode.
* Use Ledger extension's sidebar menu or open the tasks menu with `ctrl + shift + b` (`command + shift + b` on a Mac) to conveniently execute actions :
* **Build** the app for the device model of your choice with `Build`.
* **Test** your binary on the [Speculos emulator](https://github.com/LedgerHQ/speculos) with `Run with emulator`.
* You can also **run functional tests**, load the app on a physical device, and more.

ℹ️ The terminal tab of VSCode will show you what commands the extension runs behind the scene.

## Compilation and load

If you do not wish to use the [VS Code extension](#with-vs-code), you can follow the following steps to setup a development environment on a host running a Debian based Linux distribution (such as Ubuntu).

### Prerequisites

* 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

```bash
# Clang compiler, GCC ARM cross-compiling toolchain
apt install clang gcc-arm-none-eabi gcc-multilib
# Rust nightly toolchain used to compile ledger devices binaries
rustup install nightly-2022-12-02
# Install required component of the nightly toolchain
rustup component add rust-src --toolchain nightly-2022-12-02
```

* 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
pip install ledgerwallet
# Install latest cargo-ledger from crates.io
cargo install cargo-ledger
# Setup the custom nightly Rust toolchain as default
rustup default nightly-2022-12-02
# Run cargo-ledger command to install custom target files on the custom nightly toolchain
cargo ledger setup
```

You are now ready to build the Near app for Ledger devices !

### Building

Now that you have followed the [prerequisites](#prerequisites) guide, you can build the Near with the following command executed in the root directory of the app.
For following transaction with [tested larger buffers](https://github.com/dj8yfo/app-near-rs/blob/master/src/parsing/types/transaction_prefix/mod.rs#L16-L17):

```bash
cargo ledger nanox build
```

This command will build the app for the Nano X, but you can use any supported device (`nanos`, `nanox`, `nanosplus`)

### Loading

ℹ️ Your device must be connected, unlocked and the screen showing the dashboard (not inside an application).

[cargo-ledger](https://github.com/LedgerHQ/cargo-ledger) also allows you to side load the binary with the following command line executed in the root directory of the Near app.

```bash
cargo ledger build nanox --load
```

As for the build command, you can replace `nanos` with `nanox` or `nanosplus`.

## Test

### Ragger functional tests

This Near app comes with functional tests implemented with Ledger's [Ragger](https://github.com/LedgerHQ/ragger) test framework.

* Install the tests requirements

```bash
pip install -r tests/requirements.txt
```

* Run the functional tests (here for Nano S Plus but available for any supported device once you have built the binaries) :

```shell
mkdir -p build/nanos2/bin && cp target/nanosplus/release/app-near-rust build/nanos2/bin/app.elf
pytest tests/ --tb=short -v --device nanosp
```

### Emulator

You can also run the app directly on the [Speculos emulator](https://github.com/LedgerHQ/speculos)

```bash
speculos --model nanox target/nanox/release/app-near-rust
```

## Continuous Integration

The following workflows are executed in [GitHub Actions](https://github.com/features/actions) :
[2024-01-09T18:14:52Z INFO sign_transaction::common] ---
[2024-01-09T18:14:52Z INFO sign_transaction::common] Transaction:
[2024-01-09T18:14:52Z INFO sign_transaction::common] Transaction {
signer_id: AccountId(
"1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41.42.43.44.45.46.47.48.49.50.51.52.53.54.55.56.57.58.59.60.61.62.63.64.65.66.67.68.69.70.71.72.73.74.75.76.77.78.79.80.81.82.83.84.85.86.87.88.89.90.91.92.93.94.95.96.97.98.99.100.101.102.103.104.105.106.107.108.109.110.111.112.113.114.115.116.117.118.119.120.121.122.123.124.125.126.127.128.129.130.131.132.133.134.135.136.137.138.139.140.141.142.143.144.145.146.147.148.149.150.151.152.153.154.155.156.157.158.159.160.161.162.163.164.165.166.167.168.169.170.171.172.173.174.175.176.177.178.179.180.181.182.183.184.185.186.187.188.189.190.191.192.193.194.195.196.197.198.199.200.201.202.203.204.205.206.207.208.209.210.211.212.213.214.215.216.217.218.219.220.221.222.223.224.225.226.227.228.229.230.231.232.233.234.235.236.237.238.239.240.241.242.243.244.245.246.247.248.249.250.251.252.253.254.255.256.257.258.259.260.261.262.263.264.265.266.267.268.269.270.271.272.273.274.275.276.277.278.279.280.281.282.283.284.285.286.287.288.289.290.291.292.293.294.295.296.297.298.299.300.301.302.303.304.305.306.307.308.309.310.311.312.313.314.315.316.317.318.319.320.321.322.323.324.325.326.327.328.329.330.331.332.333.334.335.336.337.338.339.340.341.342.343.344.345.346.347.348.349.350.351.352.353.354.355.356.357.358.359.360.361.362.363.364.365.366.367.368.369.370.371.372.373.374.375.376.377.378.379.380.381.382.383.384.385.386.387.388.389.390.391.392.393.394.395.396.397.398.399.400\n",
),
public_key: ed25519:9Lab2du3zZg5MrZPJCAd1fka7nHuP9Rgo643d8C8hGiJ,
nonce: 103595482000005,
receiver_id: AccountId(
"1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41.42.43.44.45.46.47.48.49.50.51.52.53.54.55.56.57.58.59.60.61.62.63.64.65.66.67.68.69.70.71.72.73.74.75.76.77.78.79.80.81.82.83.84.85.86.87.88.89.90.91.92.93.94.95.96.97.98.99.100.101.102.103.104.105.106.107.108.109.110.111.112.113.114.115.116.117.118.119.120.121.122.123.124.125.126.127.128.129.130.131.132.133.134.135.136.137.138.139.140.141.142.143.144.145.146.147.148.149.150.151.152.153.154.155.156.157.158.159.160.161.162.163.164.165.166.167.168.169.170.171.172.173.174.175.176.177.178.179.180.181.182.183.184.185.186.187.188.189.190.191.192.193.194.195.196.197.198.199.200.201.202.203.204.205.206.207.208.209.210.211.212.213.214.215.216.217.218.219.220.221.222.223.224.225.226.227.228.229.230.231.232.233.234.235.236.237.238.239.240.241.242.243.244.245.246.247.248.249.250.251.252.253.254.255.256.257.258.259.260.261.262.263.264.265.266.267.268.269.270.271.272.273.274.275.276.277.278.279.280.281.282.283.284.285.286.287.288.289.290.291.292.293.294.295.296.297.298.299.300.301.302.303.304.305.306.307.308.309.310.311.312.313.314.315.316.317.318.319.320.321.322.323.324.325.326.327.328.329.330.331.332.333.334.335.336.337.338.339.340.341.342.343.344.345.346.347.348.349.350.351.352.353.354.355.356.357.358.359.360.361.362.363.364.365.366.367.368.369.370.371.372.373.374.375.376.377.378.379.380.381.382.383.384.385.386.387.388.389.390.391.392.393.394.395.396.397.398.399.400\n",
),
block_hash: Cb3vKNiF3MUuVoqfjuEFCgSNPT79pbuVfXXd2RxDXc5E,
actions: [
Transfer(
TransferAction {
deposit: 150000000000000000000000,
},
),
],
}
[2024-01-09T18:14:52Z INFO sign_transaction::common] transaction byte array length: 3086
[2024-01-09T18:14:52Z INFO sign_transaction::common] ---
```


![prelude](mds/imgs/case1/prelude.png)
![header](mds/imgs/case1/header_1.png)
![header](mds/imgs/case1/header_2.png)
![header](mds/imgs/case1/header_3.png)

...

![header](mds/imgs/case1/header_4.png)
![header](mds/imgs/case1/header_5.png)
![header](mds/imgs/case1/header_6.png)

...

![header](mds/imgs/case1/header_7.png)
![header](mds/imgs/case1/header_8.png)
![header](mds/imgs/case1/header_9.png)
![header](mds/imgs/case1/header_10.png)
![header](mds/imgs/case1/header_11.png)
![header](mds/imgs/case1/action_1.png)
![header](mds/imgs/case1/action_2.png)
![header](mds/imgs/case1/action_3.png)
![header](mds/imgs/case1/action_4.png)
![header](mds/imgs/case1/action_5.png)


## [Binary sizes](./mds/binary_sizes.md)

* Ledger guidelines enforcer which verifies that an app is compliant with Ledger guidelines. The successful completion of this reusable workflow is a mandatory step for an app to be available on the Ledger application store. More information on the guidelines can be found in the repository [ledger-app-workflow](https://github.com/LedgerHQ/ledger-app-workflows)
* Compilation of the application for all supported devices in the [ledger-app-builder](https://github.com/LedgerHQ/ledger-app-builder) docker image
* End-to-end tests with the [Speculos](https://github.com/LedgerHQ/speculos) emulator and [ragger](https://github.com/LedgerHQ/ragger) (see [tests/](tests/))
* Various lint checks :
* Source code lint checks with `cargo fmt`
* Python functional test code lint checks with `pylint` and `mypy`
135 changes: 135 additions & 0 deletions README.old.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Ledger Rust Near Application

![Rule enforcer](https://github.com/dj8yfo/app-near-rs/actions/workflows/guidelines_enforcer.yml/badge.svg) ![Build and tests](https://github.com/dj8yfo/app-near-rs/actions/workflows/build_and_functional_tests.yml/badge.svg)

This is a Near application written in Rust which can be forked to start a new project for the Ledger Nano S/X/SP devices.

* Implements standard features (display address, transaction signature...),
* Has functional tests using [Ragger](https://github.com/LedgerHQ/ragger),
* Has CI workflows mandatory for app deployment in the Ledger store.

### Links

* 📚 [Developer's documentation](https://developers.ledger.com/)<br/>
* 🗣️ [Ledger's Discord server](https://discord.gg/Ledger)

## Quick start guide

### With VS Code

You can quickly setup a development environment on any platform (macOS, Linux or Windows) to build and test your application with [Ledger's VS Code extension](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools).

By using Ledger's own developer tools [Docker image](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-app-dev-tools), the extension allows you to **build** your apps with the latest SDK, **test** them on **Speculos** and **load** them on any supported device.

* Install and run [Docker](https://www.docker.com/products/docker-desktop/).
* Make sure you have an X11 server running :
* On Ubuntu Linux, it should be running by default.
* On macOS, install and launch [XQuartz](https://www.xquartz.org/) (make sure to go to XQuartz > Preferences > Security and check "Allow client connections").
* On Windows, install and launch [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (make sure to configure it to disable access control).
* Install [VScode](https://code.visualstudio.com/download) and add [Ledger's extension](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools).
* Open a terminal and clone `app-near-rust` with `git clone git@github.com:dj8yfo/app-near-rs.git`.
* Open the `app-near-rust` folder with VSCode.
* Use Ledger extension's sidebar menu or open the tasks menu with `ctrl + shift + b` (`command + shift + b` on a Mac) to conveniently execute actions :
* **Build** the app for the device model of your choice with `Build`.
* **Test** your binary on the [Speculos emulator](https://github.com/LedgerHQ/speculos) with `Run with emulator`.
* You can also **run functional tests**, load the app on a physical device, and more.

ℹ️ The terminal tab of VSCode will show you what commands the extension runs behind the scene.

## Compilation and load

If you do not wish to use the [VS Code extension](#with-vs-code), you can follow the following steps to setup a development environment on a host running a Debian based Linux distribution (such as Ubuntu).

### Prerequisites

* 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

```bash
# Clang compiler, GCC ARM cross-compiling toolchain
apt install clang gcc-arm-none-eabi gcc-multilib
# Rust nightly toolchain used to compile ledger devices binaries
rustup install nightly-2022-12-02
# Install required component of the nightly toolchain
rustup component add rust-src --toolchain nightly-2022-12-02
```

* 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
pip install ledgerwallet
# Install latest cargo-ledger from crates.io
cargo install cargo-ledger
# Setup the custom nightly Rust toolchain as default
rustup default nightly-2022-12-02
# Run cargo-ledger command to install custom target files on the custom nightly toolchain
cargo ledger setup
```

You are now ready to build the Near app for Ledger devices !

### Building

Now that you have followed the [prerequisites](#prerequisites) guide, you can build the Near with the following command executed in the root directory of the app.

```bash
cargo ledger nanox build
```

This command will build the app for the Nano X, but you can use any supported device (`nanos`, `nanox`, `nanosplus`)

### Loading

ℹ️ Your device must be connected, unlocked and the screen showing the dashboard (not inside an application).

[cargo-ledger](https://github.com/LedgerHQ/cargo-ledger) also allows you to side load the binary with the following command line executed in the root directory of the Near app.

```bash
cargo ledger build nanox --load
```

As for the build command, you can replace `nanos` with `nanox` or `nanosplus`.

## Test

### Ragger functional tests

This Near app comes with functional tests implemented with Ledger's [Ragger](https://github.com/LedgerHQ/ragger) test framework.

* Install the tests requirements

```bash
pip install -r tests/requirements.txt
```

* Run the functional tests (here for Nano S Plus but available for any supported device once you have built the binaries) :

```shell
mkdir -p build/nanos2/bin && cp target/nanosplus/release/app-near-rust build/nanos2/bin/app.elf
pytest tests/ --tb=short -v --device nanosp
```

### Emulator

You can also run the app directly on the [Speculos emulator](https://github.com/LedgerHQ/speculos)

```bash
speculos --model nanox target/nanox/release/app-near-rust
```

## Continuous Integration

The following workflows are executed in [GitHub Actions](https://github.com/features/actions) :

* Ledger guidelines enforcer which verifies that an app is compliant with Ledger guidelines. The successful completion of this reusable workflow is a mandatory step for an app to be available on the Ledger application store. More information on the guidelines can be found in the repository [ledger-app-workflow](https://github.com/LedgerHQ/ledger-app-workflows)
* Compilation of the application for all supported devices in the [ledger-app-builder](https://github.com/LedgerHQ/ledger-app-builder) docker image
* End-to-end tests with the [Speculos](https://github.com/LedgerHQ/speculos) emulator and [ragger](https://github.com/LedgerHQ/ragger) (see [tests/](tests/))
* Various lint checks :
* Source code lint checks with `cargo fmt`
* Python functional test code lint checks with `pylint` and `mypy`
43 changes: 43 additions & 0 deletions mds/binary_sizes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# nanos

```bash
❯ du -B1 target/nanos/release/app*
86016 target/nanos/release/app.hex
151552 target/nanos/release/app-near-rust
65536 target/nanos/release/app-near-rust.apdu
4096 target/nanos/release/app-near-rust.d
```

vs

```bash
❯ du -B1 workdir/app-near/build/nanos/bin/*
53248 workdir/app-near/build/nanos/bin/app.apdu
77824 workdir/app-near/build/nanos/bin/app.elf
69632 workdir/app-near/build/nanos/bin/app.hex
4096 workdir/app-near/build/nanos/bin/app.sha256
```

# nanosplus

```bash
❯ du -B1 target/nanosplus/release/app*
90112 target/nanosplus/release/app.hex
155648 target/nanosplus/release/app-near-rust
69632 target/nanosplus/release/app-near-rust.apdu
4096 target/nanosplus/release/app-near-rust.d
```

vs

```bash
❯ du -B1 workdir/app-near/build/nanos2/bin/*
69632 workdir/app-near/build/nanos2/bin/app.apdu
163840 workdir/app-near/build/nanos2/bin/app.elf
94208 workdir/app-near/build/nanos2/bin/app.hex
4096 workdir/app-near/build/nanos2/bin/app.sha256
```




Binary file added mds/imgs/case1/action_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/action_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/action_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/action_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/action_5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_10.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_11.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_7.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_8.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/header_9.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added mds/imgs/case1/prelude.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit b4194a4

Please sign in to comment.