Signing transactions

Advanced

Bitcoin

Tutorial

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

Threshold ECDSA

Canisters can sign transactions with threshold ECDSA through the sign_with_ecdsa method.

To test canisters locally that use the following code snippets, you will need to enable local Bitcoin development. To do this, you can either start the local replica with dfx start --enable-bitcoin or you can include the following configuration in the project's dfx.json file:

motoko/basic_bitcoin/dfx.json

"defaults": {
  "bitcoin": {
    "enabled": true,
    "nodes": [
      "127.0.0.1:18444"
    ],
    "log_level": "info"
  },

See full example on GitHub

Learn more about dfx.json configuration options.

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

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinWallet.mo

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()
};

See full example on GitHub

Rust

rust/basic_bitcoin/src/basic_bitcoin/src/bitcoin_wallet/p2pkh.rs

async fn ecdsa_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 = SighashCache::new(&txclone)
            .legacy_signature_hash(
                index,
                &own_address.script_pubkey(),
                ECDSA_SIG_HASH_TYPE.to_u32(),
            )
            .unwrap();

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

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

        let mut sig_with_hashtype: Vec<u8> = der_signature;
        sig_with_hashtype.push(ECDSA_SIG_HASH_TYPE.to_u32() as u8);

        let sig_with_hashtype_push_bytes = PushBytesBuf::try_from(sig_with_hashtype).unwrap();
        let own_public_key_push_bytes = PushBytesBuf::try_from(own_public_key.to_vec()).unwrap();
        input.script_sig = Builder::new()
            .push_slice(sig_with_hashtype_push_bytes)
            .push_slice(own_public_key_push_bytes)
            .into_script();
        input.witness.clear();
    }

    transaction
}

See full example on GitHub

Threshold Schnorr

Canisters can sign transactions with threshold Schnorr through the sign_with_schnorr method.

Signing P2TR 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 address.

Rust

motoko/basic_bitcoin/src/basic_bitcoin/src/P2tr.mo

public func sign_key_spend_transaction(
    schnorr_canister_actor : SchnorrCanisterActor,
    own_address : BitcoinAddress,
    transaction : Transaction,
    amounts : [Nat64],
    key_name : Text,
    derivation_path : [Blob],
    aux : ?Types.SchnorrAux,
    signer : Types.SchnorrSignFunction,
) : async [Nat8] {
    // Obtain the scriptPubKey of the source address which is also the
    // scriptPubKey of the Tx output being spent.
    switch (Address.scriptPubKey(#p2tr_key own_address)) {
        case (#ok scriptPubKey) {
            assert scriptPubKey.size() == 2;

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

                let signature = Blob.toArray(await signer(schnorr_canister_actor, key_name, derivation_path, Blob.fromArray(sighash), aux));
                transaction.witnesses[i] := [signature];
            };
        };
        // Verify that our own address is P2TR key spend address.
        case (#err msg) Debug.trap("This example supports signing p2tr key spend addresses only: " # msg);
    };

    transaction.toBytes();
};

See full example on GitHub

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

rust/basic_bitcoin/src/basic_bitcoin/src/bitcoin_wallet/p2tr.rs

pub 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>>,
    merkle_root_hash: Vec<u8>,
    signer: SignFun,
) -> Transaction
where
    SignFun: Fn(String, Vec<Vec<u8>>, Option<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 encode signing data")
            .as_byte_array()
            .to_vec();

        let raw_signature = signer(
            key_name.clone(),
            derivation_path.clone(),
            Some(merkle_root_hash.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
}

See full example on GitHub

Learn more

Learn more about threshold ECDSA.

Learn more about threshold Schnorr.