bitcoin: add support for OP_RETURN outputs

We enforce 0 value on them, so the confirmation screen is not a the
usual recipient component, but can be a full screen confirmation not
showing the amount. We use verify_message flow as it handles both
ascii/binary.

We also only support OP_RETURN outputs with one data push, though an
OP_RETURN output could contain multiple data pushes. This restriction
is for simplicity and because we don't know of a use case. In the
future, support for this can be added if needed.

Author: benma

CHANGELOG.md

@@ -14,6 +14,7 @@ customers cannot upgrade their bootloader, its changes are recorded separately.
 - simulator: simulate a Nova device
 - Add API call to fetch multiple xpubs at once
 - Add the option for the simulator to write its memory to file.
+- Bitcoin: add support for OP_RETURN outputs
 
 ### 9.23.1
 - EVM: add HyperEVM (HYPE) and SONIC (S) to known networks

messages/btc.proto

@@ -175,6 +175,7 @@ enum BTCOutputType {
   P2WPKH = 3;
   P2WSH = 4;
   P2TR = 5;
+  OP_RETURN = 6;
 }
 
 message BTCSignOutputRequest {

py/bitbox02/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 # 7.1.0
 - Add `btc_xpubs()` to fetch multiple xpubs at once
+- Bitcoin: add support for OP_RETURN outputs
 
 # 7.0.0
 - get_info: add optional device initialized boolean to returned tuple

py/bitbox02/bitbox02/bitbox02/bitbox02.py

@@ -467,6 +467,16 @@ def btc_sign(
             # Attaching output info supported since v9.22.0.
             self._require_atleast(semver.VersionInfo(9, 22, 0))
 
+        if any(
+            map(
+                lambda output: isinstance(output, BTCOutputExternal)
+                and output.type == btc.BTCOutputType.OP_RETURN,
+                outputs,
+            )
+        ):
+            # OP_RETURN supported sice v9.24.0
+            self._require_atleast(semver.VersionInfo(9, 24, 0))
+
         supports_antiklepto = self.version >= semver.VersionInfo(9, 4, 0)
 
         sigs: List[Tuple[int, bytes]] = []

py/bitbox02/bitbox02/communication/generated/btc_pb2.py

@@ -70,6 +70,7 @@ class _BTCOutputTypeEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._
     P2WPKH: _BTCOutputType.ValueType  # 3
     P2WSH: _BTCOutputType.ValueType  # 4
     P2TR: _BTCOutputType.ValueType  # 5
+    OP_RETURN: _BTCOutputType.ValueType  # 6
 
 class BTCOutputType(_BTCOutputType, metaclass=_BTCOutputTypeEnumTypeWrapper): ...
 
@@ -79,6 +80,7 @@ P2SH: BTCOutputType.ValueType  # 2
 P2WPKH: BTCOutputType.ValueType  # 3
 P2WSH: BTCOutputType.ValueType  # 4
 P2TR: BTCOutputType.ValueType  # 5
+OP_RETURN: BTCOutputType.ValueType  # 6
 global___BTCOutputType = BTCOutputType
 
 @typing.final

py/bitbox02/bitbox02/communication/generated/btc_pb2.pyi

@@ -788,6 +788,43 @@ def _sign_btc_policy(self) -> None:
         for input_index, sig in sigs:
             print("Signature for input {}: {}".format(input_index, sig.hex()))
 
+    def _sign_btc_op_return(
+        self,
+        format_unit: "bitbox02.btc.BTCSignInitRequest.FormatUnit.V" = bitbox02.btc.BTCSignInitRequest.FormatUnit.DEFAULT,
+    ) -> None:
+        # pylint: disable=no-member
+        bip44_account: int = 0 + HARDENED
+        inputs, outputs = _btc_demo_inputs_outputs(bip44_account)
+        outputs.append(
+            bitbox02.BTCOutputExternal(
+                output_type=bitbox02.btc.OP_RETURN,
+                output_payload=b"hello world",
+                value=0,
+            )
+        )
+        sigs = self._device.btc_sign(
+            bitbox02.btc.BTC,
+            [
+                bitbox02.btc.BTCScriptConfigWithKeypath(
+                    script_config=bitbox02.btc.BTCScriptConfig(
+                        simple_type=bitbox02.btc.BTCScriptConfig.P2WPKH
+                    ),
+                    keypath=[84 + HARDENED, 0 + HARDENED, bip44_account],
+                ),
+                bitbox02.btc.BTCScriptConfigWithKeypath(
+                    script_config=bitbox02.btc.BTCScriptConfig(
+                        simple_type=bitbox02.btc.BTCScriptConfig.P2WPKH_P2SH
+                    ),
+                    keypath=[49 + HARDENED, 0 + HARDENED, bip44_account],
+                ),
+            ],
+            inputs=inputs,
+            outputs=outputs,
+            format_unit=format_unit,
+        )
+        for input_index, sig in sigs:
+            print("Signature for input {}: {}".format(input_index, sig.hex()))
+
     def _sign_btc_tx_from_raw(self) -> None:
         """
         Experiment with testnet transactions.
@@ -896,6 +933,7 @@ def _sign_btc_tx(self) -> None:
             ("Taproot inputs", self._sign_btc_taproot_inputs),
             ("Taproot output", self._sign_btc_taproot_output),
             ("Policy", self._sign_btc_policy),
+            ("OP_RETURN", self._sign_btc_op_return),
             ("From testnet tx ID", self._sign_btc_tx_from_raw),
         )
         choice = ask_user(choices)

py/send_message.py

@@ -211,7 +211,8 @@ impl Payload {
         }
     }
 
-    /// Converts a payload to an address.
+    /// Converts a payload to an address. Returns an error for invalid input or if an address does
+    /// not exist for the output type (e.g. OP_RETURN).
     pub fn address(&self, params: &Params) -> Result<String, ()> {
         let payload = self.data.as_slice();
         match self.output_type {
@@ -252,6 +253,7 @@ impl Payload {
                 }
                 encode_segwit_addr(params.bech32_hrp, 1, payload)
             }
+            BtcOutputType::OpReturn => Err(()),
         }
     }
 
@@ -289,6 +291,11 @@ impl Payload {
                 );
                 ScriptBuf::new_p2tr_tweaked(tweaked)
             }
+            BtcOutputType::OpReturn => {
+                let pushbytes: &bitcoin::script::PushBytes =
+                    payload.try_into().map_err(|_| Error::InvalidInput)?;
+                ScriptBuf::new_op_return(pushbytes)
+            }
         };
         Ok(script.into_bytes())
     }
@@ -657,6 +664,22 @@ mod tests {
                 output_type: BtcOutputType::P2tr,
                 expected_pkscript: "5120a60869f0dbcf1dc659c9cecbaf8050135ea9e8cdc487053f1dc6880949dc684c",
             },
+            Test {
+                payload: "aabbcc",
+                output_type: BtcOutputType::OpReturn,
+                expected_pkscript: "6a03aabbcc",
+            },
+            Test {
+                payload: "",
+                output_type: BtcOutputType::OpReturn,
+                expected_pkscript: "6a00",
+            },
+            Test {
+                // 80 byte payload
+                payload: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                output_type: BtcOutputType::OpReturn,
+                expected_pkscript: "6a4c50aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            },
         ];
 
         for test in tests {
@@ -667,15 +690,17 @@ mod tests {
             };
             assert_eq!(
                 hex::encode(payload.pk_script(params).unwrap()),
-                test.expected_pkscript
+                test.expected_pkscript,
             );
 
-            // Payload of wrong size
-            let payload = Payload {
-                data: hex::decode(&test.payload[2..]).unwrap(),
-                output_type: test.output_type,
-            };
-            assert_eq!(payload.pk_script(params), Err(Error::Generic));
+            // Payload of wrong size. Does not apply to OpReturn, almost any size is accepted.
+            if test.output_type != BtcOutputType::OpReturn {
+                let payload = Payload {
+                    data: hex::decode(&test.payload[2..]).unwrap(),
+                    output_type: test.output_type,
+                };
+                assert_eq!(payload.pk_script(params), Err(Error::Generic));
+            }
         }
     }
 }

src/rust/bitbox02-rust/src/hww/api/bitcoin/common.rs

@@ -1,4 +1,4 @@
-// Copyright 2022-2024 Shift Crypto AG
+// Copyright 2022-2025 Shift Crypto AG
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -853,12 +853,18 @@ async fn _process(
             };
         }
 
-        if tx_output.value == 0 {
+        let output_type = pb::BtcOutputType::try_from(tx_output.r#type)?;
+
+        // We don't allow regular outputs to have 0 value.
+        // OP_RETURN outputs however we require to have 0 value.
+        if output_type == pb::BtcOutputType::OpReturn {
+            if tx_output.value != 0 {
+                return Err(Error::InvalidInput);
+            }
+        } else if tx_output.value == 0 {
             return Err(Error::InvalidInput);
         }
 
-        let output_type = pb::BtcOutputType::try_from(tx_output.r#type)?;
-
         // Get payload. If the output is marked ours, we compute the payload from the keystore,
         // otherwise it is provided in tx_output.payload.
         let payload: common::Payload = if tx_output.ours {
@@ -949,16 +955,21 @@ async fn _process(
         if !is_change {
             // Verify output if it is not a change output.
             // Assemble address to display, get user confirmation.
-            let address = if let Some(sp) = tx_output.silent_payment.as_ref() {
-                sp.address.clone()
-            } else {
-                payload.address(coin_params)?
+            let address = || -> Result<String, Error> {
+                if let Some(sp) = tx_output.silent_payment.as_ref() {
+                    Ok(sp.address.clone())
+                } else {
+                    Ok(payload.address(coin_params)?)
+                }
             };
 
             if let Some(output_payment_request_index) = tx_output.payment_request_index {
                 if output_payment_request_index != 0 {
                     return Err(Error::InvalidInput);
                 }
+                if output_type == pb::BtcOutputType::OpReturn {
+                    return Err(Error::InvalidInput);
+                }
                 if payment_request_seen {
                     return Err(Error::InvalidInput);
                 }
@@ -970,7 +981,7 @@ async fn _process(
                     coin_params,
                     &payment_request,
                     tx_output.value,
-                    &address,
+                    &address()?,
                 )
                 .is_err()
                 {
@@ -979,6 +990,16 @@ async fn _process(
                 }
 
                 payment_request_seen = true;
+            } else if output_type == pb::BtcOutputType::OpReturn {
+                // OP_RETURN value was validated to be 0 above, so we don't need to show the amount.
+                crate::workflow::verify_message::verify(
+                    hal,
+                    "OP_RETURN",
+                    "OP_RETURN",
+                    &tx_output.payload,
+                    false,
+                )
+                .await?;
             } else {
                 // When sending coins back to the same account (non-change), or another account of
                 // the same keystore (change or non-change), we show a prefix to let the user know.
@@ -1001,9 +1022,9 @@ async fn _process(
                 hal.ui()
                     .verify_recipient(
                         &(if let Some(prefix) = prefix {
-                            format!("{}: {}", prefix, address)
+                            format!("{}: {}", prefix, address()?)
                         } else {
-                            address
+                            address()?
                         }),
                         &format_amount(coin_params, format_unit, tx_output.value)?,
                     )
@@ -3683,4 +3704,102 @@ mod tests {
             ]
         );
     }
+
+    #[test]
+    fn test_op_return() {
+        let transaction =
+            alloc::rc::Rc::new(core::cell::RefCell::new(Transaction::new(pb::BtcCoin::Btc)));
+
+        // Attach OP_RETURN output
+        {
+            let mut tx = transaction.borrow_mut();
+            tx.outputs.push(pb::BtcSignOutputRequest {
+                r#type: pb::BtcOutputType::OpReturn as _,
+                value: 0,
+                payload: b"hello world".to_vec(),
+                ..Default::default()
+            });
+        }
+
+        mock_host_responder(transaction.clone());
+        mock_unlocked();
+        bitbox02::random::fake_reset();
+        let init_request = transaction.borrow().init_request();
+
+        let mut mock_hal = TestingHal::new();
+        let result = block_on(process(&mut mock_hal, &init_request));
+
+        match result {
+            Ok(Response::BtcSignNext(next)) => {
+                assert!(next.has_signature);
+                assert_eq!(
+                    hex::encode(next.signature),
+                    "f49c71b89ec3510ebebae9aff9f967ad9bb6cc0c4cddbdf851f97e47e9922646622459e522b0751fa246e49a8e48417344a5384a9f68c1c85cd03804b35e1e1e",
+                );
+            }
+            _ => panic!("wrong result"),
+        }
+
+        assert!(mock_hal.ui.contains_confirm("OP_RETURN", "hello world"));
+    }
+
+    #[test]
+    fn test_op_return_nonascii() {
+        let transaction =
+            alloc::rc::Rc::new(core::cell::RefCell::new(Transaction::new(pb::BtcCoin::Btc)));
+
+        // Attach OP_RETURN output
+        {
+            let mut tx = transaction.borrow_mut();
+            tx.outputs.push(pb::BtcSignOutputRequest {
+                r#type: pb::BtcOutputType::OpReturn as _,
+                value: 0,
+                payload: vec![1, 2, 3, 4, 5],
+                ..Default::default()
+            });
+        }
+
+        mock_host_responder(transaction.clone());
+        mock_unlocked();
+        bitbox02::random::fake_reset();
+        let init_request = transaction.borrow().init_request();
+
+        let mut mock_hal = TestingHal::new();
+        let result = block_on(process(&mut mock_hal, &init_request));
+        assert!(result.is_ok());
+
+        assert!(
+            mock_hal
+                .ui
+                .contains_confirm("OP_RETURN\ndata (hex)", "0102030405")
+        );
+    }
+
+    #[test]
+    fn test_op_return_fail_nonzero_value() {
+        let transaction =
+            alloc::rc::Rc::new(core::cell::RefCell::new(Transaction::new(pb::BtcCoin::Btc)));
+
+        // Attach OP_RETURN output
+        {
+            let mut tx = transaction.borrow_mut();
+            tx.outputs.push(pb::BtcSignOutputRequest {
+                r#type: pb::BtcOutputType::OpReturn as _,
+                value: 100,
+                payload: b"hello world".to_vec(),
+                ..Default::default()
+            });
+        }
+
+        mock_host_responder(transaction.clone());
+        mock_unlocked();
+        bitbox02::random::fake_reset();
+        let init_request = transaction.borrow().init_request();
+
+        let mut mock_hal = TestingHal::new();
+        assert_eq!(
+            block_on(process(&mut mock_hal, &init_request)),
+            Err(Error::InvalidInput)
+        );
+    }
 }