docs: improve external definition documentation

and introduce the new URL scheme

[no changelog]

common/defs/README.md

@@ -42,7 +42,7 @@ Definitions for Ethereum chains (networks) and tokens (erc20) are split in two p
    and tokens in [`ethereum/tokens.json`](ethereum/tokens.json).
 2. external definitions - dynamically generated from multiple sources. Whole process is
    described in separate
-   [document](https://docs.trezor.io/trezor-firmware/common/ethereum-definitions.html).
+   [document](https://docs.trezor.io/trezor-firmware/common/external-definitions.html).
 
 We generally do not accept updates to the built-in definitions. Instead, make sure your
 network or token is included in the external definitions. A good place to start is the

common/protob/messages-ethereum.proto

@@ -36,7 +36,7 @@ message EthereumPublicKey {
 message EthereumGetAddress {
     repeated uint32 address_n = 1;      // BIP-32 path to derive the key from master node
     optional bool show_display = 2;     // optionally show on display before sending the result
-    optional bytes encoded_network = 3; // encoded Ethereum network, see ethereum-definitions.md for details
+    optional bytes encoded_network = 3; // encoded Ethereum network, see external-definitions.md for details
     optional bool chunkify = 4;         // display the address in chunks of 4 characters
 }
 
@@ -132,7 +132,7 @@ message EthereumTxAck {
 message EthereumSignMessage {
     repeated uint32 address_n = 1;      // BIP-32 path to derive the key from master node
     required bytes message = 2;         // message to be signed
-    optional bytes encoded_network = 3; // encoded Ethereum network, see ethereum-definitions.md for details
+    optional bytes encoded_network = 3; // encoded Ethereum network, see external-definitions.md for details
     optional bool chunkify = 4;         // display the address in chunks of 4 characters
 }
 
@@ -168,7 +168,7 @@ message EthereumSignTypedHash {
     repeated uint32 address_n = 1;              // BIP-32 path to derive the key from master node
     required bytes domain_separator_hash = 2;   // Hash of domainSeparator of typed data to be signed
     optional bytes message_hash = 3;            // Hash of the data of typed data to be signed (empty if domain-only data)
-    optional bytes encoded_network = 4;         // encoded Ethereum network, see ethereum-definitions.md for details
+    optional bytes encoded_network = 4;         // encoded Ethereum network, see external-definitions.md for details
 }
 
 /**
@@ -181,7 +181,7 @@ message EthereumTypedDataSignature {
 }
 
 /**
- * Contains an encoded network and/or token definition. See ethereum-definitions.md for details.
+ * Contains an encoded network and/or token definition. See external-definitions.md for details.
  * @embed
  */
 message EthereumDefinitions {

core/embed/rust/src/crypto/merkle.rs

@@ -2,7 +2,7 @@ use super::sha256;
 
 /// Calculate a Merkle root based on a leaf element and a proof of inclusion.
 ///
-/// Expects the Merkle tree format specified in `ethereum-definitions.md`.
+/// Expects the Merkle tree format specified in `external-definitions.md`.
 pub fn merkle_root(elem: &[u8], proof: &[sha256::Digest]) -> sha256::Digest {
     let mut out = sha256::Digest::default();
 

docs/SUMMARY.md

@@ -37,8 +37,7 @@
     - [Bitcoin signing](common/communication/bitcoin-signing.md)
   - [Reproducible builds](common/reproducible-build.md)
   - [Message Workflows](common/message-workflows.md)
-  - [Ethereum definitions](common/ethereum-definitions.md)
+  - [External definitions](common/external-definitions.md)
-  - [Solana definitions](common/solana-definitions.md)
 - [Storage](storage/index.md)
 - [Tests](tests/index.md)
   - [Device Tests](tests/device-tests.md)

docs/common/external-definitions.md

@@ -1,25 +1,34 @@
-# Ethereum definitions
+# External definitions
 
-For support of the huge number of EVM chains (networks) and ERC-20 tokens, Trezor needs
+A lot of modern blockchains support _tokens_ tradeable on top of the base chain. For
-to know parameters of those networks and tokens, namely:
+proper support in Trezor, we need to know parameters of the tokens that are not part of
+the signed data -- most typically, the name, currency symbol and the number of decimal
+places.
 
-* currency symbol and number of decimal places, to correctly display amounts,
+Similarly, the "Ethereum" implementation in Trezor actually supports any EVM chain, but
-* SLIP44 identifier to unlock the appropriate BIP-32 subtrees.
+we again need some identifying data about the chain in order to display amounts in an
+user-friendly way.
 
-A subset of Ethereum definitions is built into the firmware image. The rest is generated
+Currently, Trezor has the capability to load external definitions of:
-externally and must be sent to Trezor as a signed blob.
+
+* EVM chains (networks), identified by their chain ID,
+* ERC20 tokens, identified by the chain ID and token address,
+* Solana tokens, identified by the mint account.
 
 ## Built-in definitions
 
+A subset of definitions for the most common EVM chains and ERC20 tokens is baked into
+the firmware image.
+
 The set of built-in definitions is declared in the following files:
-* networks - [`networks.json`](https://github.com/trezor/trezor-firmware/blob/master/common/defs/ethereum/networks.json)
+* networks - [`networks.json`](https://github.com/trezor/trezor-firmware/blob/main/common/defs/ethereum/networks.json)
-* tokens - [`tokens.json`](https://github.com/trezor/trezor-firmware/blob/master/common/defs/ethereum/tokens.json)
+* tokens - [`tokens.json`](https://github.com/trezor/trezor-firmware/blob/main/common/defs/ethereum/tokens.json)
 
 These definitions need to be modified manually.
 
 ## External definitions
 
-A full list of Ethereum definitions is compiled from multiple sources and is available
+A full list of definitions is compiled from multiple sources and is available
 [in a separate repository](https://github.com/trezor/definitions).
 
 From this list, a collection of binary blobs is generated, signed, and made available
@@ -30,30 +39,32 @@ typically one month before firmware release. This means that a client applicatio
 either always fetch fresh definitions from the official URLs, or refresh its local copy
 frequently.
 
-### Retrieving the definitions
+## Retrieving the definitions
 
-The base URL for the definitions is `https://data.trezor.io/firmware/eth-definitions/`.
+The base URL for the definitions is `https://data.trezor.io/firmware/definitions/`.
 
-#### Known chain ID
+### EVM ecosystem
+
+#### Chain ID is known
 
 To look up a network definition by its chain ID, use the following URL:
 
-`https://data.trezor.io/firmware/eth-definitions/chain-id/<CHAIN_ID>/network.dat`
+`https://data.trezor.io/firmware/definitions/eth/chain-id/<CHAIN_ID>/network.dat`
 
 `<CHAIN_ID>` is a decimal number, e.g., `1` for Ethereum mainnet.
 
 To look up a token definition for a given chain ID and token address, use the following URL:
 
-`https://data.trezor.io/firmware/eth-definitions/chain-id/<CHAIN_ID>/token-<TOKEN_ADDRESS>.dat`
+`https://data.trezor.io/firmware/definitions/eth/chain-id/<CHAIN_ID>/token-<TOKEN_ADDRESS>.dat`
 
 `<CHAIN_ID>` is again a decimal number.<br>
 `<TOKEN_ADDRESS>` is all lowercase (no checksum) token address hex without the `0x` prefix.
 
 E.g., this is the URL for Görli TST token:
-[https://data.trezor.io/firmware/eth-definitions/chain-id/5/token-7af963cf6d228e564e2a0aa0ddbf06210b38615d.dat]
+[https://data.trezor.io/firmware/definitions/eth/chain-id/5/token-7af963cf6d228e564e2a0aa0ddbf06210b38615d.dat]
 
 
-#### Unknown chain ID
+#### Chain ID is not known
 
 Certain Ethereum calls, such as `EthereumGetAddress` and `EthereumSignMessage`, do not
 require the caller to know the chain ID, because their results do not depend on it.
@@ -61,7 +72,7 @@ require the caller to know the chain ID, because their results do not depend on
 For this situation, it is possible to look up a network definition by a SLIP-44
 identifier on the following URL:
 
-`https://data.trezor.io/firmware/eth-definitions/slip44/<SLIP44_ID>/network.dat`
+`https://data.trezor.io/firmware/definitions/eth/slip44/<SLIP44_ID>/network.dat`
 
 `<SLIP44_ID>` is a decimal number, e.g., `60` for Ethereum mainnet.
 
@@ -74,17 +85,26 @@ derivation path.
 When using Ethereum's SLIP-44 number 60 in the derivation path, the caller does not need
 to provide the network definition, because Ethereum network is always built-in.
 
+### Solana
+
+To look up a token definition for a given token mint account, use the following URL:
+
+`https://data.trezor.io/firmware/definitions/solana/token/<MINT_ACCOUNT>.dat`
+
+`<MINT_ACCOUNT>` is base58-encoded mint account of the token, e.g., `So11111111111111111111111111111111111111112`.
+
 ### Full set of definitions
 
 It is possible to download the full set of signed definitions in a single tar archive
 from the following URL:
 
-[`https://data.trezor.io/firmware/eth-definitions/definitions.tar.xz`](https://data.trezor.io/firmware/eth-definitions/definitions.tar.xz).
+[`https://data.trezor.io/firmware/definitions/definitions.tar.xz`](https://data.trezor.io/firmware/definitions/definitions.tar.xz).
 
 ## Definition format
 
-Each definition is encoded as a protobuf message `EthereumNetworkInfo` or
+Each definition is encoded as a protobuf message specified in the file
-`EthereumTokenInfo` and packaged in the following binary format.
+[`messages-definitions.proto`](https://github.com/trezor/trezor-firmware/blob/main/common/protob/messages-definitions.proto)
+and packaged in the following binary format.
 
 All numbers are unsigned little endian.
 
@@ -124,7 +144,7 @@ For each leaf, its proof is a sequence of neighbor hashes going up the tree. One
 keep track of the proof is, whenever constructing an internal node, add the right hash
 to the left child's proof list and vice versa.
 
-A [reference implementation](https://github.com/trezor/trezor-firmware/blob/master/python/src/trezorlib/merkle_tree.py) is provided.
+A [reference implementation](https://github.com/trezor/trezor-firmware/blob/main/python/src/trezorlib/merkle_tree.py) is provided.
 
 ## Data sources
 

docs/common/index.md

@@ -6,9 +6,9 @@ Common contains files shared among Trezor projects.
 
 JSON coin definitions and support tables.
 
-## Ethereum definitions
+## External definitions
 
-Description of Ethereum definitions and the process of their generation. See [Ethereum definitions](ethereum-definitions.md).
+Description of external definitions for the Ethereum and Solana tokens and the process of their generation. See [External definitions](external-definitions.md).
 
 ## Protobuf Definitions
 

docs/common/solana-definitions.md

@@ -1,26 +0,0 @@
-# Solana definitions
-
-To allow nicer token presentation on the device, Trezor allows passing a token
-definition as part of the additional info. Currently only one token can be included in
-the definitions. Solana tokens are uniquely identified by their mint account. Trezor
-additionally expects a name and a ticker symbol.
-
-In the future we might also include definitions for instructions.
-
-## Retrieving the definitions
-A full list of Solana definitions is compiled from multiple sources and is available [in
-a separate repository](TODO).
-
-From this list, a collection of binary blobs is generated, signed, and made available
-online.
-
-A given Trezor firmware will only accept signed definitions newer than a certain date,
-typically one month before firmware release. This means that a client application should
-either always fetch fresh definitions from the official URLs, or refresh its local copy
-frequently.
-
-The base URL for the definitions is `https://data.trezor.io/firmware/solana-definitions/`.
-
-## Definition format
-
-Look at [`ethereum-definitions.md`'s](ethereum_definitions.md) `Definition Format` section.