Proto commits in BitBoxSwiss/bitbox02-firmware

These 81 commits are when the Protocol Buffers files have changed:

2025-05-08

api/device_info: add ble fw version

2025-05-06

da14531: Add support for new chip

2025-01-30

bitcoin: display account name when sending to self Before, we did this only when sending to the same account. This commit extends this to work when sending to an address of a *different* account of the same keystore. The bitcoin transaction script_configs field is used for inputs and change outputs. We add a similar list, `output_script_configs`, which allows to attach script configs of different accounts to outputs, with `output_script_config_index` to reference them in the output. To ensure backwards compatibility, `output_script_config_index` is added as a new field, which takes precedence over `script_config_index` when set. The output script configs are validated, but since one can send to any address of the same keystore, the output script config validation allows any combination of script configs, unlike the input script configs. To not duplicate lots of code, a few refactors are done: - validate_script_configs is now used for generic validation and is used to validate the output script configs as well as the input script configs - validate_input_script_configs performs additional validation as before (can't mix multisig and single sig inputs, can't mix inputs from different accounts, etc). - the multisig/policy name is stored in ValidatedScriptConfig, so we don't have to fetch it twice The Python lib version was downgraded from 8.0.0 to 7.0.0, it seems it was bumped before in error - the previous release tag and release is 6.3.0.

The documentation is generated from this commit.

2024-12-30

cardano: allow serialization using 258-tagged sets Since the Conway era, the CBOR serialization of inputs and certificates can optionally be tagged with the 258-tag. This will become mandatory in a future hardfork. - https://github.com/IntersectMBO/cardano-ledger/blob/6e2d37cc0f47bd02e89b4ce9f78b59c35c958e96/eras/conway/impl/cddl-files/extra.cddl#L5 - https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml The protobuf field is named `tag_cbor_sets` to be consistent with other tooling that names it the same way: https://github.com/vacuumlabs/ledgerjs-cardano-shelley/blob/4a59d8818402a1d1d4c9939a6a8f606940f51d55/src/types/public.ts#L1874 This change is needed now as some wallets/tools already use this tag, e.g. delegating to a drep using the https://gov.tools/ DApp.

2024-09-18

cardano: Allow vote delegation Allow cardano based on conway.cddl to sign messages containing Vote Delegation certificate. This is needed for withdrawing rewards. Signed-off-by: RostarMarek <rostarmarek@gmail.com> cardano: Add Test and minor improvements Adds unit test for vote delegation and adresses minor issues mentioned in PR. Signed-off-by: RostarMarek <rostarmarek@gmail.com> cardano: Adress review issues Addresses review issues found during the review process Signed-off-by: RostarMarek <rostarmarek@gmail.com> cardano: Add confirmation screen Adds confirmation screen for drep vote delegation dislpaying type and if present drep credential hash. Signed-off-by: RostarMarek <rostarmarek@gmail.com>

2024-09-17

bitcoin: support sending to silent payment addresses

2024-09-11

bitcoin: add regtest support It has a different bech32 address HRP (prefix). Third party integrations sometimes are missing this and use testnet as a workaround, but proper support is nicer.

2024-08-07

eth tx verification: use same address case as in input Previously, no matter the format of the adress given by user to the client, BitBox02 was showing this address in mixed case in the verification step(see 'mixed-case checksum address encoding in EIP-55'). Even though this is acceptable, we thought that this could create confusion among users when they see that the address they inputted is not the same on the device(only difference is in the case though). To avoid any questions, this commit achieves showing the address in the same case as in user input on the device. Valid cases are : all upper, all lower or mixed(EIP-55). The client libraries will also implement a mechanism to categorize the case of the input address to pass to BitBox02 firmware. Signed-off-by: asi345 <inanata15@gmail.com>

2024-04-29

bitcoin/signtx: add support for payment requests We implement a subset of the payment requests protocol described in SLIP-24: https://github.com/satoshilabs/slips/blob/master/slip-0024.md Subset means, unlike the full SLIP-24 proposal, this commit does not implement: - support for multiple outputs per payment request - support for multiple payment requests per transaction - memo types other than text memo - non-empty nonces The subset is sufficient to cover the first application: selling Bitcoin via PocketBitcoin. The protobuf messages and code has been designed so that support for the above missing features can be added in a backwards compatible way. This is why there is a `payment_request_index` in the output, which has to be `0` if present, and where at most one output can attach to a payment request. To allow a payment request to request payout to multiple addresses in the future, multiple outputs can have the same index, and the sighash computation (the outputs hash part of it) would need to be streamed and validation done at the end. To allow multiple payment requests per transaction, the payment_request_index can be incremented. SLIP-24 does not go much into how the trusted party is identified. For now we identify them by the recipient name with one hardcoded pubkey per recipient. We might want to extend this with a certificate chain (root key signs signing keys, possibly with expiry dates, which sign payment requests) - this is postponed until we finalize the design.

2024-02-20

api: add a custom BIP85 derivation for Lightning hot wallets For the generation of a mnemonic for Breez-SDK Lightning hot wallets in the BitBoxApp. Using the regular BIP85-BIP39 path like `m/83696968'/39'/0'/12'/0'` for this is problematic as a user might use the same mnemonics for something else, e.g. another cold storage wallet. In such a case, the derived mnemonic of the user would become hot without the user realizing it. For the purpose of generating entropy for a lightning hot wallet using BIP85, we should instead use a different application number dedicated to this. We are going with number `19534'`, which is unlikely to interfere with other uses. It's hex representation `0x4c4e` spells `LN` in ASCII. The BIP85 derivation would then be `m/83696968'/{app_no}/{language}'/{words}'/` as in BIP85-BIP39, but use `19534'` for the `app_no` instead of `39'`, so: m/83696968'/19534'/0'/12'/0' We restrict to only 16 byte derived entropy (equivalent of 12 words mnemonics) for LN hot wallet mnemonics for simplicity and easier recovery for users. The index represents the account number - for now we only allow `0` (the first account), and can extend to multiple if there is ever a need.

bip85: restructure api messages to allow for different bip85 apps For now the same app as before is supported - bip39, but explicit. The empty message now returns InvalidInput - would have been a breaking change but the BIP85 API endpoint was never released (disabled by not activating the app-bip85 Rust feature). Reason: we want to add another dedicated app number for the generation of deterministic entropy for the Breez SDK Lightning hot wallet in the BitBoxApp. This will segregate keys so that BIP85-BIP39 mnemonics which the user already might use (or will use) are not unintentionally re-used and made hot in the Lightning wallet.

2023-12-28

api: add support for BIP85-derived BIP39 mnemonics See https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki#bip39. Some of the other "apps" (derived secrets) using BIP-85 are not added with this commit and may be added in the future. For now we add the app that is probably used the most, which is deriving BIP-39 mnemonics. The new protobuf messages are empty messages instead of reusing e.g. the `Success {}` message so they can be extended in the future without having to return different types of response messages (e.g. Success OR a custom message).

2023-11-16

eth: add support for EIP-1559 transactions https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md EIP-1559 transactions start with a 0x02 byte followed by an RLP encoding of the transaction fields. The chainID is newly included in the fields directly instead of being encoded in the `v` value of the signature. We add a new proto message for EIP1559 signing as opposed to extending the existing one for clarity - some fields don't exist anymore (`coin`, `gas_price`) while new fields are introduced (`max_priority_fee_per_gas` etc.). `access_list` is presumed empty for the time being - we can add support for a non-empty list if there is demand for it in the future. The firmware verison is bumped to v9.16.0. The Python/Go/Rust client libs assume that this is the version where EIP1559 is introduced.

2023-09-18

messages: add backticks to proto docstring These docs make their way into generated code in downstream libs like bitbox-api-rs, where these end up in Rust code interpreted as markdown. `<..>` are then interpreted as illegal/unclosed tags.

2023-07-06

miniscript: register policy and check registration when receiving The policy is registered just like a multisig account, by computing a hash of the policy and storing it with a user-chosen account name. The registration is checked before displaying a receive address. The hash function does not include the origin and keypath of the key origin info, as they don't influence the result: if e.g. a keypath would change to one of our own keys, the xpub would change and so would the hash. For keys that are not ours, we don't care about the origin/keypath.

2023-06-29

miniscript: add proto messages We will support miniscript as part of output descriptors. Descriptors are an expression language to specify Bitcoin outputs. For example, `wsh(multi(2,<pubkey1>,<pubkey2>,<pubkey3>))` is a 2-of-3 multisig wrapped in a P2WSH (pay-to-witness-script-hash) output. Descriptors specification: https://github.com/bitcoin/bitcoin/blob/8f402710371a40c5777dc3f9c4ba6ca8505a2f90/doc/descriptors.md In fragments wrapping SCRIPT expressions, SCRIPT can also be a miniscript expression, for example: `wsh(or_b(pk(<pubkey1>),s:pk(<pubkey2>)))`. With hardware signers, we want to use xpubs with derivations instead of raw pubkeys, and also have a shorter representation than inlining the xpubs for readability. That is why we will follow the 'Wallet Policies for Descriptor Wallets' proposal specied here: https://github.com/bigspider/bips/blob/bip-wallet-policies/bip-wallet-policies.mediawiki (https://github.com/bitcoin/bips/pull/1389). The above example then become `wsh(or_b(pk(@0/**),s:pk(@1/**)))`. The `@NUM` references a key provided in the keys list. For the policy with the keys, one can then derive pkScripts for receive and change addresses and use these to create addresses.

2023-03-21

eth: fix protobuf generated file to remove Goerli In 8b454550f4961b2d7380885fbd45526d8c5d42bd, Goerli was added, but accidentally in the generated file, not in the source file. The generated file is only refreshed if the source files change, which is why the CI did not catch it. Since we changed to using chainID instead of ETHCoin in 519a58b17e4692f5d2e6a5793f4c8fc09a312e2c, we remove it again from the protobuf file. Similarly, the generated files were not regenerated when updating Prost to 0.11. in 412e3400d627ab0b994df5a92f34c95478535ae5, which adds more changes to the generated file, like formatting and the `as_str_name`/`from_str_name` methods.

2022-10-25

bitcoin/signtx: allow displaying BTC values as sats This allows the BitBoxApp and other wallets which are able to display BTC values as satoshis to direct the BitBox02 to also display them as satoshis during signing.

2022-07-23

prost/protobuf: generate backup.proto for Rust Make the backup.proto protobuf messages available in Rust, so we can work with microSD backups in Rust. The package name of backup.proto is changed as it is 100% independent of the other .proto files, which all deal with the firmware API. This results in the different file for the definitions in Rust. The Docker image is updated because prost-build as modified and it is pre-compiled during image generation.

2022-07-19

backup: fix backup length field to 0 This field is kind of dead code in that it is not used or checked or interpreted by the firmware when loading/checking a backup. It is part of the backup checksum though, so we can't get rid of it completely, otherwise loading existing backups would fail checksum verification. Having a non-zero value here is a maintenance burden (i.e. when porting this code to Rust), so we just stop using it. The `test_fixture` unit test in hww/api//backup.rs ensures that backups created before this change continue to load correctly.

2022-06-01

ethereum: add support for EIP-712 structured data signing

2022-02-27

api/eth: use chain ID to identify the network, add BNB/MATIC Until now a BitBox2 client had to provide the network they want to interact using the ETHCoin enum. This has the downside that the list of supported networks has to be mirrored in the client library, to map from the chain id (usually provided by an ETH wallet such as MyEtherWallet/Rabby) to the ETHCoin enum. To avoid this duplication and make things simpler, we now allow the client to provide the chain ID instead. ETHCoin is kept for backwards compatibility. BSC is added as a first network that can only by identified by chain ID.

2022-02-13

btc: add P2TR script type, generate taproot receive addresses According to BIP-86: https://github.com/bitcoin/bips/blob/edffe529056f6dfd33d8f716fb871467c3c09263/bip-0086.mediawiki.

2021-12-20

Merge branch 'cardano-tokens'

cardano: add support for tokens Every transaction output can also have tokens attached to it. Specification: https://github.com/input-output-hk/cardano-ledger/blob/80d2624174b3fc598c95ab9bf0a21c9bc7e045d3/eras/alonzo/test-suite/cddl-files/alonzo.cddl#L362 Every output containing tokens also needs to have a minimum amount of ADA in it, accoding to https://github.com/input-output-hk/cardano-ledger/blob/80d2624174b3fc598c95ab9bf0a21c9bc7e045d3/doc/explanations/min-utxo-alonzo.rst. The format for making `asset...` identifiers: https://github.com/cardano-foundation/CIPs/tree/ae83a0420be5485f7fe81cdc23d73cf6a237c16a/CIP-0014 General info about tokens: https://docs.cardano.org/native-tokens/learn https://github.com/input-output-hk/cardano-ledger/blob/80d2624174b3fc598c95ab9bf0a21c9bc7e045d3/doc/explanations/token-bundles.rst

2021-12-10

btc: add P2TR output type to enable sending to taproot addresses Bitcoin activated the Taproot softfork recently. This commit adds pay-to-taproot as an output type so users can send to taproot addresses. Taproot addresses are bech32m encoded, using witness version 1. The witness program is a 32 byte x-only public key, see https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki.

2021-12-02

btc: rename output `hash` to `payload` When confirming a tx, the recipient address is reconstructed from the payload provided in the protobuf `BTCSignOutputRequest` type and displayed for confirmation. We previously named the payload `hash` as it always was a hash: either a pubkey hash in case of P2WPKH (pay to witness pubkey hash), or a script hash in case of P2SH (pay to scripthash) or P2WSH (pay to witness script hash). With the Taproot softfork that recently activated on Bitcoin, the payload is no longer a hash of something but a 32 byte public key. See https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki ("Why is the public key directly included in the output?"). "Payload" as a term is also used in other Bitcoin libraries for the decoded address input, e.g. in rust-bitcoin. We apply the same rename to the relevant helper functions in btc_common.h. This is not a breaking change for the BitBox02 API, as the protobuf names are not present in the binary serialization, so existing downstream integrations are not affected. Projects that update to the changed protobuf file will have to rename `hash` to `payload` in the code generated from the protobuf files. Alternatives considered: - Keep `hash` as is, add another field `pubkey`. This puts as much burden on the client libraries as renaming to payload, but adds complexity to the firmware code. - Add `encoded_address`, and let the firmware decode it into the payload and validate it. This would be a new way of showing recipient addresses, but we'd need to keep supporting the old way for backwards compatibility. In some inputs, e.g. PSBT, there is no address string to provide, so it does not even make it easier for downstream projects in all cases. It seems that the rename was the easiest solution.

2021-12-01

cardano: allow ttl=0 Before, ttl=0 was interpreted as "not provided", which means that it is not serialized and signed. According to the spec, zero is a valid value for the TTL. It means however that the transaction can never be mined, as the current slot will always be bigger than 0. According to the Adalite team, this type of transaction is used in meta protocols: https://github.com/vacuumlabs/adalite/pull/1212#discussion_r755973295 > But TTL = 0 is in theory a semantically valid TTL the transaction can have - advanced users may leverage that to sign a transaction and ensure it won't ever be accepted by the blockchain - it's used e.g. with Ledger when CLI users need to sign separately voting registration metadata (but the device allows signing only the full tx) and therefore want to throw away the rest of the signed transaction. (of course, they can use ttl=1 which would do as well, but mapping 0 to null seems worth avoiding for the sake of predictability of the interface and overall consistency) To be backwards compatible, we add a new protobuf field `allow_zero_ttl` and take it into account. "Transaction cannot be mined" is shown to the user in this case. Since it touches the same code, I also extended the "Transaction cannot be mined" case to when the validity start is bigger than the TTL. A note on the new protobuf field: - it is a new field that does not change the behvior if set to the default, false. This is for compatibility for older client libraries talking to newer firmware. - `optional` would have been great, and is available in a newer proto3 version, but prost does not support it yet, and possibly it is also not supported by other protobuf code generators.

2021-10-20

cardano: add validity_interval_start Since the Allegra update, the TTL transaction field has been replaced with the validity interval `[start, end]`. See https://hydra.iohk.io/build/7840126/download/1/shelley-ma.pdf for details. All wallets I looked at only use the validity interval start. The cddl specification file also is explicit about the validity interval start, but not about the end: https://github.com/input-output-hk/cardano-ledger-specs/blob/d0aa86ded0b973b09b629e5aa62aa1e71364d088/eras/alonzo/test-suite/cddl-files/alonzo.cddl#L59 It seems to me that the validity interval end and TTL are the same, and that the TTL field is used for that purpose since Allegra.

2021-10-17

cardano: update spec references from Shelley to Alonzo Alonzo is the currently newest era and up to date spec. See: https://github.com/input-output-hk/cardano-ledger-specs/tree/d0aa86ded0b973b09b629e5aa62aa1e71364d088

2021-10-13

cardano: implement transaction signing

cardano: add xpubs api call Can query multiple xpubs at once because Adalite queries multiple at once, making it a bit faster.

cardano: scaffold API request/response

2021-08-30

messages: remove BitBoxBase BitBox02 libraries will not need BitBoxBase support.

2021-08-05

commander: remove RandomNumber API request No client uses it. The BitBoxApp was the only known user and dropped the feature in v4.26.0. Technically this constitutes a major version bump (breaking change), but we cheat and only do a minor version bump to v9.7.0. This is a shortcut because we are nearly certain that no client uses this feature and will not notice the breaking change. A major bump would be a big hassle as downstream integrations would need to be changed to accept the new major version. For the Python library, we can bump the major version without a problem.

2021-04-18

protobuf: add reboot purpose The user will be able to reboot into the bootloader for multiple reasons: - Upgrade device (default, backwards compatible) - Going to the startup settings, to change e.g. the setting to display the firmware hash at boot

2021-04-13

messages: add securechip_model to DeviceInfoResponse "ATECC608A" or "ATECC608B".

2021-02-17

protobuf: add antiklepto to ETH tx and ETH/BTC msg signing

2021-01-14

antiklepto: add protobuf messages for BTC signing with antiklepto Part of the ECDAS Anti-Klepto protocol. A antiklepto.proto file is added as the messages will be used also for ETH tx/msg signing.

2020-11-11

apps/btc: allow entering multisig account name on the device This will make integrations easier with downstream wallets integrating with the BitBox02. Many of them use the HWI cli, and providing custom UI elements for the BitBox02 is a lot of effort. The more that can be done on the device itself, the easier any integration becomes.

2020-10-12

btc: add xpub formatting option to BTCRegisterScriptConfig Most, if not all wallets except for Electrum use `xpub...` and `tpub...` only for formatting xpubs. When registering a multisig setup, so far the bitbox02 showed the xpubs as Zpub,Ypub,Vpub,Upub depending on the network and script type. This commit adds an option to force xpub or tpub in a backwards compatible manner.

2020-10-07

apps/btc: add p2wsh-p2sh multisig script type and keypath validation Valid keypath: m/48'/coin'/account'/script_type' with script_type' = 1'.

apps/btc: add Upub and Ypub xpub encodings Used for p2wsh-p2sh legacy multisig in Electrum.

2020-10-05

api/btc: add BTCSignMessage to btc.proto

2020-06-28

protobuf: add package name to .proto files - Adds proper namespaces when the proto files are used in other libraries - Python hack to insert the package name with `sed` removed - C names kept the same as before by using mangle_names:M_STRIP_PACKAGE - avoid super long C struct/enum/define names.

2020-06-25

backup: fix call to _encode_backup_data, wrong tag _encode_backup_data() is called manually to calculcate the length of the serialization of the `data` field. Just passing `BackupData_fields` is wrong though, as that points to the first field in the BackupData message, not the `data` field. Practically the length did not change as serializing the tag for the first field or the data field resulted in the same length, but it was very confusing to understand what was going on. This will help when upgrading nanopb, which changes the fields representation.

2020-06-14

apps/btc/sign: allow multiple script configs in a tx Before, one script config (address type) was allowed for all inputs and changes. This commit changes the API of the signing workflow to allow specifying multiple script configurations that can be used in a tx, instead of only one. In each output and change, the `script_config_index` now references which script config to use. The current commit still only allows only one (see TODO), but implements the change on the API level. The TODO will be handled in a subsequent commit.

2020-05-13

test/sign: wrap tx input in a struct to make space for the prev tx Previous transaction referenced by each input will have to be streamed, so in the test it's easier to put the prev tx together with the actual input.

2020-03-02

Add endpoint to get the electrum encryption key This commit adds an endpoint that returns the encryption key electrum uses at keypath m/4541509'/1112098098'.

Add endpoint to get the electrum encryption key This commit adds an endpoint that returns the encryption key electrum uses at keypath m/4541509'/1112098098'.

2020-02-11

Merge branch 'eth-sign-msg'

ETH: Add message signing

commander: add script registration api calls Exposing memory_multisig_get_by_hash and memory_multisig_set_by_hash.

apps/btc: add multisig to the possible script configs In the next commits, this will be used to: - register multisig script configs on the device with a user chosen name - generate receive addresses - sign multisig transactions

2020-01-28

apps/btc/common: enable xpub for m/48'/coin'/account'/2', Zpub, Vpub Allow retrieval and verification of multisig xpubs. The versions are taken from Electrum (Zpub for mainnet, Vpub for testnet, for p2wsh scripts).

2020-01-24

apps/btc/common: add btc_common_multisig_is_valid Validate a multisig setup.

2020-01-23

apps/btc/common: add btc_common_pkscript_from_multisig

2020-01-22

apps/btc/sign: keypath_account added to BTCSigninit It is the derivation to the account, e.g. m/84'/0'/1'. It is a prefix to all input and change keypaths. This subsumes bip44_account (as it is part of it), and will make it easier to verify the account to be used during signing upfront. Doing it that way is easier to read/maintain, as we don't need to cache the result so each input/change don't have to redo the validation.

2020-01-21

apps/btc: upgrade script_type to script_configuration So other types of scripts can be handled as well. The previous script types are combined under the name "simple", meaning: single pubkey, no additional inputs.

2020-01-20

apps/btc: remove unused script types

apps/btc: split BTCPub into xpub and address The request is better encoded, which leads to less consistency checks, and easier maintainability and extensibility.

protobuf: add XPub message and conversion function

2020-01-17

messages: fix outdated comments

2020-01-14

Add ability to get the root fingerprint This commits adds an endpoint that returns the fingerprint of the root public key. The fingerprint is the first 4 bytes of the hash160 of the key according to https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#key-identifiers

2019-12-03

Merge branch 'pr/239' into hsm

Add testnet segwit upub and vpub BIP49: Testnet uses 0x044a5262 "upub" and 0x044a4e28 "uprv." BIP84: Testnet uses 0x045f1cf6 "vpub" and 0x045f18bc "vprv." Reload the generated python protobuf code. Add extra fields to the BTCPubRequest for each of them.

biboxbase: Add a few more description texts

2019-11-21

bitboxbase: Add new message definitions

2019-10-28

protobufs: Split up into different files

2019-09-24

hww.proto: remove unused field

Restore u2f counter to timestamp

2019-09-16

commander/eth: display address for erc-20 tokens Display token unit instead of 'Ethereum' for the tokens.

2019-08-12

commander: add api call to restore from mnemonic

2019-07-25

commander: add reset api call - Check user password - Get user confirmation - Factory reset the device

2019-06-25

eth: comments and small improvements

eth: sign transaction

2019-06-21

eth: return xpub instead of pubkey

2019-06-19

eth: enable retrieving public key

app: add initial eth ETHRequest/ETHResponse wrap all Ethereum messages, to contain them and make future upgrades easier.

2019-06-14

commander: remove perform_attestation It is now an op code instead of a protobuf message.

2019-06-06

BitBox02 public release