diff --git a/common/defs/README.md b/common/defs/README.md index a57de51193..819c82d3e0 100644 --- a/common/defs/README.md +++ b/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 diff --git a/common/protob/messages-ethereum.proto b/common/protob/messages-ethereum.proto index a2014b6b09..6768f2fb56 100644 --- a/common/protob/messages-ethereum.proto +++ b/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 { diff --git a/core/embed/rust/src/crypto/merkle.rs b/core/embed/rust/src/crypto/merkle.rs index 1bcbfc74cb..551cfc2d8e 100644 --- a/core/embed/rust/src/crypto/merkle.rs +++ b/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(); diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 2bfd83badd..bcec52e04f 100644 --- a/docs/SUMMARY.md +++ b/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) - - [Solana definitions](common/solana-definitions.md) + - [External definitions](common/external-definitions.md) - [Storage](storage/index.md) - [Tests](tests/index.md) - [Device Tests](tests/device-tests.md) diff --git a/docs/common/ethereum-definitions.md b/docs/common/external-definitions.md similarity index 68% rename from docs/common/ethereum-definitions.md rename to docs/common/external-definitions.md index 183de8f219..d88f68ff03 100644 --- a/docs/common/ethereum-definitions.md +++ b/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 -to know parameters of those networks and tokens, namely: +A lot of modern blockchains support _tokens_ tradeable on top of the base chain. For +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, -* SLIP44 identifier to unlock the appropriate BIP-32 subtrees. +Similarly, the "Ethereum" implementation in Trezor actually supports any EVM chain, but +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 -externally and must be sent to Trezor as a signed blob. +Currently, Trezor has the capability to load external definitions of: + +* 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) -* tokens - [`tokens.json`](https://github.com/trezor/trezor-firmware/blob/master/common/defs/ethereum/tokens.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/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//network.dat` +`https://data.trezor.io/firmware/definitions/eth/chain-id//network.dat` `` 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//token-.dat` +`https://data.trezor.io/firmware/definitions/eth/chain-id//token-.dat` `` is again a decimal number.
`` 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//network.dat` +`https://data.trezor.io/firmware/definitions/eth/slip44//network.dat` `` 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/.dat` + +`` 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 -`EthereumTokenInfo` and packaged in the following binary format. +Each definition is encoded as a protobuf message specified in the file +[`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 diff --git a/docs/common/index.md b/docs/common/index.md index 3b2bd21c65..b236bffb88 100644 --- a/docs/common/index.md +++ b/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 diff --git a/docs/common/solana-definitions.md b/docs/common/solana-definitions.md deleted file mode 100644 index f0607bfdb8..0000000000 --- a/docs/common/solana-definitions.md +++ /dev/null @@ -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.