trezor-firmware/common/tools/README.md

Common Tools

This directory contains mostly tools that can manipulate definitions in defs/.

Tools are written with Click, so you always get a help text if you use the --help option.

All tools require Python 3.6 or higher and a bunch of dependencies, listed in requirements.txt. You can install them all with pip3 install -r requirements.txt.

Tools overview

cointool.py

This is a general-purpose tool to examine coin definitions. Currently it implements the following commands:

• render: generate code based on a Mako template. By default, cointool.py render foo.bar.mako will put its result into file foo.bar in the same directory. See usage in trezor-core.
• check: check validity of json definitions and associated data. Used in CI.
• dump: dump coin information, including support status, in JSON format. Various filtering options are available, check help for details.
• coindefs: generate signed protobuf descriptions of coins. This is for future use and could allow us to not need to store coin data in Trezor itself.

Use cointool.py command --help to get more information on each command.

support.py

Used to query and manage info in support.json. This mainly supports the release flow.

The following commands are available:

• check: check validity of json data. Used in CI.
• fix: fix expected problems: prune keys without associated coins and ensure that ERC20 tokens are correctly entered as duplicate.
• show: keyword-search for a coin and show its support status for each device.
• set: set support data.
• release: perform the release workflow.

Use support.py command --help to get more information on each command.

coins_details.py

Generates coins_details.json, source file for https://trezor.io/coins. Collects data on coins, downloads market caps and puts everything into a single file. Caches market cap data so you don't have to download it every time.

diffize_coins_details.py

Compares generated coins_details.json to the released version currently served on https://trezor.io/coins, in a format that is nicely readable to humans and hard(er) to mess up by diff.

coin_info.py

In case where code generation with cointool.py render is impractical or not sufficient, you can query the data directly through Python. Short usage example:

import coin_info

defs = coin_info.coin_info()
list_of_all_coins = defs.as_list()
dict_by_coin_key = defs.as_dict()

for token in defs.erc20:
    print(token["key"], token["name"], token["shortcut"])

support_info = coin_info.support_info(defs.misc)
for key, support in support_info.values():
    t2_support = support["trezor2"]
    coin_name = dict_by_coin_key[key]
    if t2_support == "soon":
        print(coin_name, "will be supported soon!")
    elif t2_support:
        print(coin_name, "is supported since version", t2_support)
    else:
        print(coin_name, "is not supported")

See docstrings for the most important functions: coin_info() and support_info().

The file coindef.py is a protobuf definition for passing coin data to Trezor from the outside.

marketcap.py

Module for obtaining market cap and price data used by coins_details.py and maxfee.py.

maxfee.py

Updates the maxfee_kb coin property based on a specified maximum per-transaction fee. The command fetches current price data from https://coinmarketcap.com/ to convert from fiat-denominated maximum fee.

Release Workflow

This entails collecting information on coins whose support status is unknown, marking coins whose support status is soon, and including new ERC20 tokens.

Maintaining Support Status

When a new coin definition is added, its support status is unknown. It is excluded from code generation by default. If you want to include a coin in a firmware build, you need to switch it to soon first. You can set multiple support statuses at the same time:

$ ./support.py show Ontology
misc:ONT - Ontology (ONT)
 * connect : NO
 * trezor1 : support info missing
 * trezor2 : support info missing
 * suite : NO

$ ./support.py set misc:ONT trezor1=no -r "not planned on T1" trezor2=soon
misc:ONT - Ontology (ONT)
 * connect : NO
 * trezor1 : NO (reason: not planned on T1)
 * trezor2 : SOON
 * suite : NO

Afterwards, review and commit changes to defs/support.json, and update the trezor-common submodule in your target firmware.

If you're adding multiple coins at once, you can use support.py release 1 --soon to automatically add all currently-unknown coins to soon. (The 1 indicates that this is for Trezor One)

ERC20 tokens in unknown state are considered soon as well, unless their symbols are duplicates. Use support.py fix to synchronize duplicate status in support.json file. Or mark them as unsupported explicitly.

Releasing a new firmware

Step 1: update the tokens repo

pushd defs/ethereum/tokens
git checkout master
git pull
popd
git add defs/ethereum/tokens

Step 2: run the release flow

./tools/support.py release 2

The number 2 indicates that you are releasing Trezor 2. The version will be automatically determined, based on currently released firmwares. Or you can explicitly specify the version with -r 2.1.0.

All currently known unreleased ERC20 tokens are automatically set to the given version.

All coins marked soon are set to the current version. This is automatic - coins that were marked soon were used in code generation and so should be released. If you want to avoid this, you will have to manually revert each coin to soon status, either with support.py set, or by manually editing support.json.

Coins in state unknown, i.e., coins that are known in the definitions but not listed in support files, will be also added. But you will be interactively asked to confirm each one. Use -y or --add-all to auto-add all of them.

Use -n or --dry-run to see changes without writing them to support.json. Use -v or --verbose to also show ERC20 tokens which are processed silently by default.

Use -g or --git-tag to automatically tag the current HEAD with a version, e.g., trezor2-2.1.0. This might become default in the future.

XXX this should also commit the changes though, otherwise the tag will apply to the wrong commit.

Step 3: review and commit your changes

Use git diff to review changes made, commit and push. If you tagged the commit in the previous step, don't forget to git push --tags too.

Step 4: update submodule in your target repository

Go to trezor-core or trezor-mcu checkout and update the submodule. Checkout the appropriate tag if you created it. If you're in trezor-core, run make templates to update source files.