Signing transactions

Advanced

Bitcoin

Tutorial

Overview

Before a transaction can be sent to the Bitcoin network, each input must be signed.

Signing transactions with threshold ECDSA

Canisters can sign transactions form addresses using ECDSA by using the sign_with_ecdsa API.

The following snippet shows a simplified example of how to sign a Bitcoin transaction for the special case where all the inputs are referencing outpoints that are owned by own_address and own_address is a P2PKH address.

Motoko

public func sign_transaction(
    own_public_key : [Nat8],
    own_address : BitcoinAddress,
    transaction : Transaction,
    key_name : Text,
    derivation_path : [Blob],
    signer : SignFun,
  ) : async [Nat8] {
    // Obtain the scriptPubKey of the source address which is also the
    // scriptPubKey of the Tx output being spent.
    switch (Address.scriptPubKey(#p2pkh own_address)) {
      case (#ok scriptPubKey) {
        let scriptSigs = Array.init<Script>(transaction.txInputs.size(), []);

        // Obtain scriptSigs for each Tx input.
        for (i in Iter.range(0, transaction.txInputs.size() - 1)) {
          let sighash = transaction.createSignatureHash(
              scriptPubKey, Nat32.fromIntWrap(i), SIGHASH_ALL);

          let signature_sec = await signer(key_name, derivation_path, Blob.fromArray(sighash));
          let signature_der = Blob.toArray(Der.encodeSignature(signature_sec));

          // Append the sighash type.
          let encodedSignatureWithSighashType = Array.tabulate<Nat8>(
            signature_der.size() + 1, func (n) {
              if (n < signature_der.size()) {
                signature_der[n]
              } else {
                Nat8.fromNat(Nat32.toNat(SIGHASH_ALL))
              };
          });

          // Create Script Sig which looks like:
          // ScriptSig = <Signature> <Public Key>.
          let script = [
            #data encodedSignatureWithSighashType,
            #data own_public_key
          ];
          scriptSigs[i] := script;
        };
        // Assign ScriptSigs to their associated TxInputs.
        for (i in Iter.range(0, scriptSigs.size() - 1)) {
          transaction.txInputs[i].script := scriptSigs[i];
        };
      };
      // Verify that our own address is P2PKH.
      case (#err msg)
        Debug.trap("This example supports signing p2pkh addresses only.");
    };

    transaction.toBytes()
  };

View in the full example.

Rust

async fn sign_transaction<SignFun, Fut>(
    own_public_key: &[u8],
    own_address: &Address,
    mut transaction: Transaction,
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
    signer: SignFun,
) -> Transaction
where
    SignFun: Fn(String, Vec<Vec<u8>>, Vec<u8>) -> Fut,
    Fut: std::future::Future<Output = Vec<u8>>,
{
    // Verify that our own address is P2PKH.
    assert_eq!(
        own_address.address_type(),
        Some(AddressType::P2pkh),
        "This example supports signing p2pkh addresses only."
    );

    let txclone = transaction.clone();
    for (index, input) in transaction.input.iter_mut().enumerate() {
        let sighash =
            txclone.signature_hash(index, &own_address.script_pubkey(), SIG_HASH_TYPE.to_u32());

        let signature = signer(key_name.clone(), derivation_path.clone(), sighash.to_vec()).await;

        // Convert signature to DER.
        let der_signature = sec1_to_der(signature);

        let mut sig_with_hashtype = der_signature;
        sig_with_hashtype.push(SIG_HASH_TYPE.to_u32() as u8);
        input.script_sig = Builder::new()
            .push_slice(sig_with_hashtype.as_slice())
            .push_slice(own_public_key)
            .into_script();
        input.witness.clear();
    }

    transaction
}

View in the full example.

Signing transactions with threshold Schnorr

Canisters can sign transactions from addresses using Schnorr by using the sign_with_schnorr API.

Signing P2TR untweaked key path transactions

The following snippet shows a simplified example of how to sign a Bitcoin transaction for the special case where all the inputs are referencing outpoints that are owned by own_address and own_address is a P2TR untweaked key path address.

It's important to make sure that own_address is a P2TR untweaked key path address. If own_address is a tweaked key path address, the verification of the Bitcoin transaction will fail. See the generating addresses section for more details.

Rust

// Sign a P2TR key spend transaction.
//
// IMPORTANT: This method is for demonstration purposes only and it only
// supports signing transactions if:
//
// 1. All the inputs are referencing outpoints that are owned by `own_address`.
// 2. `own_address` is a P2TR script path spend address.
async fn schnorr_sign_key_spend_transaction<SignFun, Fut>(
    own_address: &Address,
    mut transaction: Transaction,
    prevouts: &[TxOut],
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
    signer: SignFun,
) -> Transaction
where
    SignFun: Fn(String, Vec<Vec<u8>>, Vec<u8>) -> Fut,
    Fut: std::future::Future<Output = Vec<u8>>,
{
    assert_eq!(own_address.address_type(), Some(AddressType::P2tr),);

    for input in transaction.input.iter_mut() {
        input.script_sig = ScriptBuf::default();
        input.witness = Witness::default();
        input.sequence = Sequence::ENABLE_RBF_NO_LOCKTIME;
    }

    let num_inputs = transaction.input.len();

    for i in 0..num_inputs {
        let mut sighasher = SighashCache::new(&mut transaction);

        let signing_data = sighasher
            .taproot_key_spend_signature_hash(
                i,
                &bitcoin::sighash::Prevouts::All(&prevouts),
                TapSighashType::Default,
            )
            .expect("Failed to ecnode signing data")
            .as_byte_array()
            .to_vec();

        let raw_signature = signer(
            key_name.clone(),
            derivation_path.clone(),
            signing_data.clone(),
        )
        .await;

        // Update the witness stack.
        let witness = sighasher.witness_mut(i).unwrap();
        let signature = bitcoin::taproot::Signature {
            sig: Signature::from_slice(&raw_signature).expect("failed to parse signature"),
            hash_ty: TapSighashType::Default,
        };
        witness.push(&signature.to_vec());
    }

    transaction
}

View in the full example.

Signing P2TR script path transactions

The following snippet shows a simplified example of how to sign a Bitcoin transaction for the special case where all the inputs are referencing outpoints that are owned by own_address and own_address is a P2TR script path address.

Rust

// Sign a P2TR script spend transaction.
//
// IMPORTANT: This method is for demonstration purposes only and it only
// supports signing transactions if:
//
// 1. All the inputs are referencing outpoints that are owned by `own_address`.
// 2. `own_address` is a P2TR script path spend address.
async fn schnorr_sign_script_spend_transaction<SignFun, Fut>(
    own_address: &Address,
    mut transaction: Transaction,
    prevouts: &[TxOut],
    control_block: &ControlBlock,
    script: &ScriptBuf,
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
    signer: SignFun,
) -> Transaction
where
    SignFun: Fn(String, Vec<Vec<u8>>, Vec<u8>) -> Fut,
    Fut: std::future::Future<Output = Vec<u8>>,
{
    assert_eq!(own_address.address_type(), Some(AddressType::P2tr),);

    for input in transaction.input.iter_mut() {
        input.script_sig = ScriptBuf::default();
        input.witness = Witness::default();
        input.sequence = Sequence::ENABLE_RBF_NO_LOCKTIME;
    }

    let num_inputs = transaction.input.len();

    for i in 0..num_inputs {
        let mut sighasher = SighashCache::new(&mut transaction);

        let leaf_hash = TapLeafHash::from_script(&script, LeafVersion::TapScript);

        let signing_data = sighasher
            .taproot_script_spend_signature_hash(
                i,
                &bitcoin::sighash::Prevouts::All(&prevouts),
                leaf_hash,
                TapSighashType::Default,
            )
            .expect("Failed to ecnode signing data")
            .as_byte_array()
            .to_vec();

        let raw_signature = signer(
            key_name.clone(),
            derivation_path.clone(),
            signing_data.clone(),
        )
        .await;

        // Update the witness stack.

        let witness = sighasher.witness_mut(i).unwrap();
        witness.clear();
        let signature = bitcoin::taproot::Signature {
            sig: Signature::from_slice(&raw_signature).expect("failed to parse signature"),
            hash_ty: TapSighashType::Default,
        };
        witness.push(signature.to_vec());
        witness.push(&script.to_bytes());
        witness.push(control_block.serialize());
    }

    transaction
}

View in the full example.

Learn more

Learn more about using the threshold ECDSA signing API.

Learn more about using the threshold Schnorr signing API.

Next steps

Now that your transaction is signed, it can be submitted to the Bitcoin network.

Learn how to submit Bitcoin transactions.