Constructing and Signing Transactions - Taproot

In this section, we will construct a Taproot transaction.

This is the cargo commands that you need to run this example:

cargo add bitcoin --features "std, rand-std"

First we'll need to import the following:

use std::str::FromStr;

use bitcoin::hashes::Hash;
use bitcoin::key::{Keypair, TapTweak, TweakedKeypair, UntweakedPublicKey};
use bitcoin::locktime::absolute;
use bitcoin::secp256k1::{rand, Message, Secp256k1, SecretKey, Signing, Verification};
use bitcoin::sighash::{Prevouts, SighashCache, TapSighashType};
use bitcoin::{
    transaction, Address, Amount, Network, OutPoint, ScriptBuf, Sequence, Transaction, TxIn, TxOut,
    Txid, Witness,
};

Here is the logic behind these imports:

• std::str::FromStr is used to parse strings into Bitcoin primitives
• bitcoin::key is used to tweak keys according to BIP340
• bitcoin::hashes::Hash is used to hash data
• bitcoin::locktime::absolute is used to create a locktime
• bitcoin::secp256k1::{rand, Message, Secp256k1, SecretKey, Signing, Verification} is used to sign transactions
• use bitcoin::sighash::{Prevouts, SighashCache, TapSighashType} is used to create and tweak taproot sighashes
• bitcoin::{Address, Network, OutPoint, ScriptBuf, Sequence, Transaction, TxIn, TxOut, Txid, Witness} is used to construct transactions

Next, we define the following constants:

use bitcoin::Amount;
const DUMMY_UTXO_AMOUNT: Amount = Amount::from_sat(20_000_000);
const SPEND_AMOUNT: Amount = Amount::from_sat(5_000_000);
const CHANGE_AMOUNT: Amount = Amount::from_sat(14_999_000); // 1000 sat fee.

• DUMMY_UTXO_AMOUNT is the amount of the dummy UTXO we will be spending
• SPEND_AMOUNT is the amount we will be spending from the dummy UTXO
• CHANGE_AMOUNT¹ is the amount we will be sending back to ourselves as change

Before we can construct the transaction, we need to define some helper functions²:

use bitcoin::secp256k1::{rand, Secp256k1, SecretKey, Signing};
use bitcoin::key::Keypair;
fn senders_keys<C: Signing>(secp: &Secp256k1<C>) -> Keypair {
    let sk = SecretKey::new(&mut rand::thread_rng());
    Keypair::from_secret_key(secp, &sk)
}

senders_keys generates a random private key and derives the corresponding public key hash. This will be useful to mock a sender. In a real application these would be actual secrets³. We use the SecretKey::new method to generate a random private key sk. We then use the Keypair::from_secret_key method to instantiate a Keypair type, which is a data structure that holds a keypair consisting of a secret and a public key. Note that senders_keys is generic over the Signing trait. This is used to indicate that is an instance of Secp256k1 and can be used for signing.

use std::str::FromStr;
use bitcoin::{Address, Network};
fn receivers_address() -> Address {
    Address::from_str("bc1p0dq0tzg2r780hldthn5mrznmpxsxc0jux5f20fwj0z3wqxxk6fpqm7q0va")
        .expect("a valid address")
        .require_network(Network::Bitcoin)
        .expect("valid address for mainnet")
}

receivers_address generates a receiver address. In a real application this would be the address of the receiver. We use the method Address::from_str to parse the string "bc1p0dq0tzg2r780hldthn5mrznmpxsxc0jux5f20fwj0z3wqxxk6fpqm7q0va"⁴ into an address. Hence, it is necessary to import the std::str::FromStr trait. Note that bc1p0dq0tzg2r780hldthn5mrznmpxsxc0jux5f20fwj0z3wqxxk6fpqm7q0va is a Bech32 address. This is an arbitrary, however valid, Bitcoin mainnet address. Hence we use the require_network method to ensure that the address is valid for mainnet.

use bitcoin::{Amount, OutPoint, ScriptBuf, TxOut, Txid};
use bitcoin::hashes::Hash;
use bitcoin::key::UntweakedPublicKey;
use bitcoin::locktime::absolute;
use bitcoin::secp256k1::{Secp256k1, Verification};
const DUMMY_UTXO_AMOUNT: Amount = Amount::from_sat(20_000_000);
fn dummy_unspent_transaction_output<C: Verification>(
   secp: &Secp256k1<C>,
   internal_key: UntweakedPublicKey,
) -> (OutPoint, TxOut) {
    let script_pubkey = ScriptBuf::new_p2tr(secp, internal_key, None);

    let out_point = OutPoint {
        txid: Txid::all_zeros(), // Obviously invalid.
        vout: 0,
    };

    let utxo = TxOut { value: DUMMY_UTXO_AMOUNT, script_pubkey };

    (out_point, utxo)
}

dummy_unspent_transaction_output generates a dummy unspent transaction output (UTXO). This is a P2TR (ScriptBuf::new_p2tr) UTXO. It takes the following arguments:

• secp is a reference to a Secp256k1 type. This is used to verify the internal key.
• internal_key is a UntweakedPublicKey type. This is the internal key that is used to generate the script pubkey. It is untweaked, since we are not going to tweak the key.
• merkle_root is an optional TapNodeHash type. This is the merkle root of the taproot tree. Since we are not using a merkle tree, we are passing None.

Verification is a trait that indicates that an instance of Secp256k1 can be used for verification. The UTXO has a dummy invalid transaction ID (txid: Txid::all_zeros()), and a value of the const DUMMY_UTXO_AMOUNT that we defined earlier. P2TR UTXOs could be tweaked (TweakedPublicKey) or untweaked (UntweakedPublicKey). We are using the latter, since we are not going to tweak the key. We are using the OutPoint struct to represent the transaction output. Finally, we return the tuple (out_point, utxo).

Now we are ready for our main function that will sign a transaction that spends a p2tr unspent output:

use std::str::FromStr;

use bitcoin::hashes::Hash;
use bitcoin::key::{Keypair, TapTweak, TweakedKeypair, UntweakedPublicKey};
use bitcoin::locktime::absolute;
use bitcoin::secp256k1::{rand, Message, Secp256k1, SecretKey, Signing, Verification};
use bitcoin::sighash::{Prevouts, SighashCache, TapSighashType};
use bitcoin::{
    transaction, Address, Amount, Network, OutPoint, ScriptBuf, Sequence, Transaction, TxIn, TxOut,
    Txid, Witness,
};

const DUMMY_UTXO_AMOUNT: Amount = Amount::from_sat(20_000_000);
const SPEND_AMOUNT: Amount = Amount::from_sat(5_000_000);
const CHANGE_AMOUNT: Amount = Amount::from_sat(14_999_000); // 1000 sat fee.

fn senders_keys<C: Signing>(secp: &Secp256k1<C>) -> Keypair {
    let sk = SecretKey::new(&mut rand::thread_rng());
    Keypair::from_secret_key(secp, &sk)
}

fn receivers_address() -> Address {
    Address::from_str("bc1p0dq0tzg2r780hldthn5mrznmpxsxc0jux5f20fwj0z3wqxxk6fpqm7q0va")
        .expect("a valid address")
        .require_network(Network::Bitcoin)
        .expect("valid address for mainnet")
}

fn dummy_unspent_transaction_output<C: Verification>(
   secp: &Secp256k1<C>,
   internal_key: UntweakedPublicKey,
) -> (OutPoint, TxOut) {
    let script_pubkey = ScriptBuf::new_p2tr(secp, internal_key, None);

    let out_point = OutPoint {
        txid: Txid::all_zeros(), // Obviously invalid.
        vout: 0,
    };

    let utxo = TxOut { value: DUMMY_UTXO_AMOUNT, script_pubkey };

    (out_point, utxo)
}

fn main() {
    let secp = Secp256k1::new();

    // Get a keypair we control. In a real application these would come from a stored secret.
    let keypair = senders_keys(&secp);
    let (internal_key, _parity) = keypair.x_only_public_key();

    // Get an unspent output that is locked to the key above that we control.
    // In a real application these would come from the chain.
    let (dummy_out_point, dummy_utxo) = dummy_unspent_transaction_output(&secp, internal_key);

    // Get an address to send to.
    let address = receivers_address();

    // The input for the transaction we are constructing.
    let input = TxIn {
        previous_output: dummy_out_point, // The dummy output we are spending.
        script_sig: ScriptBuf::default(), // For a p2tr script_sig is empty.
        sequence: Sequence::ENABLE_RBF_NO_LOCKTIME,
        witness: Witness::default(), // Filled in after signing.
    };

    // The spend output is locked to a key controlled by the receiver.
    let spend = TxOut { value: SPEND_AMOUNT, script_pubkey: address.script_pubkey() };

    // The change output is locked to a key controlled by us.
    let change = TxOut {
        value: CHANGE_AMOUNT,
        script_pubkey: ScriptBuf::new_p2tr(&secp, internal_key, None), // Change comes back to us.
    };

    // The transaction we want to sign and broadcast.
    let mut unsigned_tx = Transaction {
        version: transaction::Version::TWO,  // Post BIP-68.
        lock_time: absolute::LockTime::ZERO, // Ignore the locktime.
        input: vec![input],                  // Input goes into index 0.
        output: vec![spend, change],         // Outputs, order does not matter.
    };
    let input_index = 0;

    // Get the sighash to sign.

    let sighash_type = TapSighashType::Default;
    let prevouts = vec![dummy_utxo];
    let prevouts = Prevouts::All(&prevouts);

    let mut sighasher = SighashCache::new(&mut unsigned_tx);
    let sighash = sighasher
        .taproot_key_spend_signature_hash(input_index, &prevouts, sighash_type)
        .expect("failed to construct sighash");

    // Sign the sighash using the secp256k1 library (exported by rust-bitcoin).
    let tweaked: TweakedKeypair = keypair.tap_tweak(&secp, None);
    let msg = Message::from_digest(sighash.to_byte_array());
    let signature = secp.sign_schnorr(&msg, &tweaked.to_inner());

    // Update the witness stack.
    let signature = bitcoin::taproot::Signature { signature, sighash_type };
    sighasher.witness_mut(input_index).unwrap().push(&signature.to_vec());

    // Get the signed transaction.
    let tx = sighasher.into_transaction();

    // BOOM! Transaction signed and ready to broadcast.
    println!("{:#?}", tx);
}

Let's go over the main function code block by block.

let secp = Secp256k1::new(); creates a new Secp256k1 context with all capabilities. Since we added the rand-std feature to our Cargo.toml, we can use the SecretKey::new method to generate a random private key sk.

let keypair = senders_keys(&secp); generates a keypair that we control, and let (internal_key, _parity) = keypair.x_only_public_key(); generates a XOnlyPublicKey that represent an X-only public key, used for verification of Schnorr signatures according to BIP340. We won't be using second element from the returned tuple, the parity, so we are ignoring it by using the _ underscore. let address = receivers_address(); generates a receiver's address address. let (dummy_out_point, dummy_utxo) = dummy_unspent_transaction_output(&secp, internal_key); generates a dummy unspent transaction output dummy_utxo and its corresponding outpoint dummy_out_point. All of these are helper functions that we defined earlier.

In let input = TxIn {...} we are instantiating the input for the transaction we are constructing Inside the TxIn struct we are setting the following fields:

• previous_output is the outpoint of the dummy UTXO we are spending; it is a OutPoint type.
• script_sig is the script code required to spend an output; it is a ScriptBuf type. We are instantiating a new empty script with ScriptBuf::new().
• sequence is the sequence number; it is a Sequence type. We are using the ENABLE_RBF_NO_LOCKTIME constant.
• witness is the witness stack; it is a Witness type. We are using the default method to create an empty witness that will be filled in later after signing. This is possible because Witness implements the Default trait.

In let spend = TxOut {...} we are instantiating the spend output. Inside the TxOut struct we are setting the following fields:

• value is the amount we are spending; it is a u64 type. We are using the const SPEND_AMOUNT that we defined earlier.
• script_pubkey is the script code required to spend a P2TR output; it is a ScriptBuf type. We are using the script_pubkey method to generate the script pubkey from the receivers address. This will lock the output to the receiver's address.

In let change = TxOut {...} we are instantiating the change output. It is very similar to the spend output, but we are now using the const CHANGE_AMOUNT that we defined earlier⁵. This is done by setting the script_pubkey field to ScriptBuf::new_p2tr(...), which generates P2TR-type of script pubkey.

In let unsigned_tx = Transaction {...} we are instantiating the transaction we want to sign and broadcast using the Transaction struct. We set the following fields:

• version is the transaction version; it is a i32 type. We are using version 2 which means that BIP68 applies.
• lock_time is the transaction lock time; it is a LockTime enum. We are using the constant ZERO This will make the transaction valid immediately.
• input is the input vector; it is a Vec<TxIn> type. We are using the input variable that we defined earlier wrapped in the vec! macro for convenient initialization.
• output is the output vector; it is a Vec<TxOut> type. We are using the spend and change variables that we defined earlier wrapped in the vec! macro for convenient initialization.

We need to reference the outputs of previous transactions in our transaction. We accomplish this with the Prevouts enum. In let prevouts = vec![dummy_utxo];, we create a vector of TxOut types that we want to reference. In our case, we only have one output, the dummy_utxo that we defined earlier. With let prevouts = Prevouts::All(&prevouts); we create a Prevouts::All variant that takes a reference to a vector of TxOut types.

In let mut sighash_cache = SighashCache::new(unsigned_tx); we are instantiating a SighashCache struct. This is a type that efficiently calculates signature hash message for legacy, segwit and taproot inputs. We are using the new method to instantiate the struct with the unsigned_tx that we defined earlier. new takes any Borrow<Transaction> as an argument. Borrow<T> is a trait that allows us to pass either a reference to a T or a T itself. Hence, you can pass a Transaction or a &Transaction to new.

sighash_cache is instantiated as mutable because we require a mutable reference when creating the sighash to sign using taproot_signature_hash to it. This computes the BIP341 sighash for any flag type. It takes the following arguments:

• input_index is the index of the input we are signing; it is a usize type. We are using 0 since we only have one input.
• &prevouts is a reference to the Prevouts enum that we defined earlier. This is used to reference the outputs of previous transactions and also used to calculate our transaction value.
• annex is an optional argument that is used to pass the annex data. We are not using it, so we are passing None.
• leaf_hash_code_separator is an optional argument that is used to pass the leaf hash code separator. We are not using it, so we are passing None.
• sighash_type is the type of sighash; it is a TapSighashType enum. We are using the All variant, which indicates that the sighash will include all the inputs and outputs.

Taproot signatures are generated by tweaking the private (and public) key(s). let tweaked: TweakedKeypair = keypair.tap_tweak(&secp, None); accomplishes this.

We create the message msg by converting the sighash to a Message type. This is a the message that we will sign. The Message::from method takes anything that implements the promises to be a thirty two byte hash i.e., 32 bytes that came from a cryptographically secure hashing algorithm.

We compute the signature sig by using the sign_schnorr method. It takes a reference to a Message and a reference to a Keypair as arguments, and returns a Signature type.

In the next step, we update the witness stack for the input we just signed by first converting the sighash_cache into a Transaction by using the into_transaction method. We access the witness field of the first input with tx.input[0].witness. It is a Witness type. We use the push method to push the serialized public and private Taproot keys. It expects a single argument of type AsRef<[u8]> which is a reference to a byte slice. We are using the as_ref method to convert the signature sig to a byte slice.

As the last step we print this to terminal using the println! macro. This transaction is now ready to be broadcast to the Bitcoin network.