Merge pull request #1951 from mintlayer/trezor_firmware_versioning_followup

ImplOfAnImpl · web-flow · commit fc15fa97c488 · 2025-08-13T21:59:51.000+03:00
Update TREZOR_SUPPORT.md
diff --git a/wallet/TREZOR_SUPPORT.md b/wallet/TREZOR_SUPPORT.md
@@ -13,7 +13,7 @@ From the Trezor perspective, there are two types of firmware: a) the official on
 Since Mintlayer is not officially supported by Trezor, the firmware we provide falls into the latter category. This has certain implications:
 - When installing the firmware, the device will show the warning "UNSAFE, DO NOT USE!".
 - When installing custom firmware over the official one, **the device will be wiped clean**. Make sure you have a backup of your seed phrase.
-- When installing custom firmware over different custom firmware, the device will **not** be wiped clean. This makes it succeptible to the so-called "evil maid attack",
+- When installing custom firmware over different custom firmware, the device will **not** be wiped clean. This makes it susceptible to the so-called "evil maid attack",
 where the attacker has physical access to your device. It goes like this:
   * The "maid" temporarily steals your device and installs on it firmware that she has built herself; it looks identical to the previously installed firmware, but also logs the PIN and the passphrase entered by the user. Then she puts the device back.
   * You use the device.
@@ -24,19 +24,17 @@ where the attacker has physical access to your device. It goes like this:
   * keep your device in a safe place;
   * preferably, use a dedicated device with a dedicated seed phrase and PIN specifically for Mintlayer;
 - In order to install custom firmware on a Trezor Safe family device (e.g. Safe 3 or Safe 5), you have to [unlock the bootloader first](https://trezor.io/learn/security-privacy/how-trezor-keeps-you-safe/unlocking-the-bootloader-on-trezor-safe-devices);
-this is an irreversible operation after which the device authenticity check will no longer work. This means that every time you use Trezor Suite, you will be presented with a warning "Your device may have been compromised" (unless you disable
-the authenticity check in the Trezor Suite's device settings).
+this is an irreversible operation after which the device authenticity check will no longer work.
+This means that every time you use Trezor Suite, you will be presented with a warning "Your device may have been compromised"
+(unless you disable the authenticity check in the Trezor Suite's device settings).
 
-### Building and flashing the firmware
-
-#### A note about versioning
+### A note about versioning
 
 Firmware built from the Mintlayer fork has two version numbers:
 - A version number assigned by Trezor; this is the original release that we've based our release upon
   and this is what is shown to you on the device screen when you flash the firmware.
-- An additional version number assigned by us, to which we refer as "Mintlayer firmware version".
-  It is obtainable via `trezorctl mintlayer get-firmware-info` and it's what
-  our wallets display in their UI.
+- An additional version number assigned by us, to which we refer as "Mintlayer firmware version";
+  this is what our wallets display in their UI.
 
 The table of correspondence between the two versions can be found in the [firmware repository](https://github.com/mintlayer/mintlayer-trezor-firmware/blob/mintlayer-master/README.md).
 
@@ -50,28 +48,47 @@ Note: if you've built Core wallets directly from `master` instead of using a spe
 you'll probably won't be able to use a specific release for the firmware either.
 Instead, you'll have to build it from `mintlayer-master`.
 
-#### How to build
+### Flashing pre-built firmware
+
+If you are interested in a particular release, you may just go to [the firmware releases page](https://github.com/mintlayer/mintlayer-trezor-firmware/releases),
+download the `.bin` file corresponding to your device model and install it via Trezor Suite:
+- Inside Trezor Suite go to "Settings" -> "Device" -> "Danger area" -> "Install custom firmware" and click "Install".
+- Follow the instructions that will appear on your screen.
+
+Note:
+- Trezor Safe 3 comes in two revisions, A and B, that look identical but require different firmware.\
+  Determining the revision of your particular device is non-trivial, unfortunately:
+  * If you have `trezorctl` installed, which is the Trezor command line tool, you may run `trezorctl get-features`[^1]
+    (after having connected the device to the PC and having entered the PIN) and then look for the `internal_model` value
+    in the output - 'T2B1' will mean you have revision A and 'T3B1' revision B.
+  * In any case, the device won't allow you to install wrong firmware, so you may try the one for revision A
+    and if that fails, try the one for revision B instead.
+- Trezor Model One is not supported.
+
+### Building the firmware from source
+
+There are two options here:
+- A more verbose approach using `Nix`, useful during development.
+- A simpler approach using `Docker`; this results in reproducible builds and is used on our CI when creating releases.
+
+In either case, you'll first need to clone the repository and checkout the required revision:
+- If you want the latest version that is in development, checkout the `mintlayer-master` branch.
+- If you want a particular release, checkout the tag corresponding to that release. The list of tags
+  can be found [here](https://github.com/mintlayer/mintlayer-trezor-firmware/tags).
+
+In the examples below we'll be assuming that you want the release 1.0.0, whose tag is `mintlayer-v1.0.0`.
+
+#### Building the firmware using `Nix`
 
 ##### Get the source code
 
-Clone the repository and `cd` into it:
+Clone the repository, `cd` into the directory and checkout the required revision:
 ```sh
 git clone --recurse-submodules https://github.com/mintlayer/mintlayer-trezor-firmware
 cd mintlayer-trezor-firmware
+git checkout --recurse-submodules mintlayer-v1.0.0
 ```
 
-Then checkout the required revision:
-- If you want the latest version that is in development, checkout the `mintlayer-master` branch:
-  ```sh
-  git checkout --recurse-submodules mintlayer-master
-  ```
-- If you want a particular release, checkout the tag corresponding to that release. The list of tags
-  can be found [here](https://github.com/mintlayer/mintlayer-trezor-firmware/tags).
-  Assuming that you've chosen `mintlayer-v1.0.0`, run:
-  ```sh
-  git checkout --recurse-submodules mintlayer-v1.0.0
-  ```
-
 ##### Install `Nix`
 
 On a Debian-based system you can do this via `sudo apt install nix-bin`.
@@ -81,7 +98,7 @@ Check that `Nix` works by running `nix-shell -p hello --run hello`
 If you're getting the error `getting status of /nix/var/nix/daemon-socket/socket: Permission denied`
 on your Linux machine, you may need to add the current user to the `nix-users` group:
 ```sh
-sudo usermod -aG nix-users your_username
+sudo usermod -aG nix-users $USER
 ```
 You'll also need to re-login after that.
 
@@ -117,29 +134,76 @@ The possible values are:
 | T3B1               | Safe 3 revision B |
 | T3T1               | Safe 5            |
 
-Note:
-- Trezor Safe 3 revision A and B look identical. To determine the revision of your particular device,
-  first connect the device (which means, both connect it physically and enter the PIN) and then run:
-  ```sh
-  nix-shell --run "poetry run trezorctl get-features"
-  ```
-  Look for the `internal_model` value in the output.
-- Trezor Model One is not supported.
+So in the example above we're building it for Safe 5.
 
 ##### Flash the firmware
 
+The file `core/build/firmware/firmware.bin` in the source directory will be the firmware that you've just built,
+so you can go ahead and install it via Trezor Suite.
+
+However you can also do it via the command line:
+
 First you need to put your device into bootloader mode. To do so
 - On Safe 3, hold the left button when connecting the USB cable.
 - On Model T and Safe 5, swipe across the screen when connecting the USB cable.
 
 After that the device will present you with an option to install firmware, select that option.
 
-Now you can flash the firmware by running:
+Now you can flash the firmware by running[^2]:
 ```sh
 nix-shell --run "poetry run make -C core upload"
 ```
 
-Note: instead of executing `nix-shell --run "poetry run the_command"` every time, you can enter
-the nix-shell by running `nix-shell`
-and then inside the nix-shell enter poetry shell by running `poetry shell`.
-After this, you can run the commands directly, e.g. `trezorctl get-features`.
+Note: after having installed the firmware you may use Mintlayer-specific commands of `trezorctl`. Run
+```sh
+nix-shell --run "poetry run trezorctl mintlayer --help"
+```
+to see what commands are available.
+
+#### Building the firmware using `Docker`
+
+##### Make sure `Docker` is installed and set up correctly
+
+##### Get the source code
+
+Clone the repository, `cd` into the directory and checkout the required revision:
+```sh
+git clone https://github.com/mintlayer/mintlayer-trezor-firmware
+cd mintlayer-trezor-firmware
+git checkout mintlayer-v1.0.0
+```
+
+Note that the `--recurse-submodules` parameter is not needed in this case. This is because the build script will
+do the cloning again, so this initial clone is mainly to get the correct build script.
+
+##### Build the firmware
+
+Run:
+```sh
+PRODUCTION=0 ./build-docker.sh --models T3T1 --skip-bitcoinonly --targets firmware mintlayer-v1.0.0
+```
+
+Note:
+- The value of the `--models` parameter is a comma-separated list of target device models.
+  The possible values are the same as for the `TREZOR_MODEL` variable used in the previous section.
+  E.g. here we will be building the firmware for Safe 5.
+- The last argument is the repository revision from which the firmware will be built. Make sure you
+  specify the same revision that you've used during the initial checkout. Also note that it has to
+  be either a branch name or a tag, but not an arbitrary commit hash.
+- `PRODUCTION=0` is needed to produce the "UNSAFE, DO NOT USE!" firmware with the "DEVEL" signature
+  (as opposed to the "Trezor" firmware without a signature, which would be unusable).
+
+The resulting binary will be `build/core-MODEL/firmware/firmware.bin`, where MODEL is the model identifier
+that you've specified via the `--models` parameter
+(i.e. in this particular example the path will be `build/core-T3T1/firmware/firmware.bin`).\
+Install it via Trezor Suite.
+
+[^1]: If you instead decide to build the firmware from source using the `Nix` approach,
+you'll be able to run `trezorctl` directly from the source directory like this:
+`nix-shell --run "poetry run trezorctl get-features"`.\
+I.e. you won't have to install it separately in this case.
+
+[^2]: instead of executing `nix-shell --run "poetry run YOUR_COMMAND"` every time,
+you can enter the nix-shell by running `nix-shell`
+and then inside the nix-shell enter poetry shell by running `poetry shell`.\
+After this, you can run `YOUR_COMMAND` directly, e.g. `make -C core upload` or `trezorctl get-features`.
