Skip to main content

Creating Bitcoin transactions

Bitcoin

Unspent transaction outputs (UTXOs) are used as inputs to build a Bitcoin transaction. Every Bitcoin transaction spends one or more UTXOs and in return creates new UTXOs. A UTXO exists until it is used as input for a future transaction. In order to create a Bitcoin transaction, you need to:

  1. Get the available UTXOs corresponding to a Bitcoin address controlled by your ICP smart contract using the bitcoin_get_utxos API endpoint.

  2. Calculate an appropriate transaction fee using the bitcoin_get_current_fee_percentiles API endpoint.

  3. Select a subset of the available UTXOs to spend that covers the transaction amount and fee.

  4. Create a transaction that spends the selected UTXOs and creates new UTXOs. You will need at least one for the recipient and, in most cases, one to collect the change.

A UTXO has the following structure:

/// An unspent transaction output.
public type Utxo = {
    outpoint : OutPoint;
    value : Satoshi;
    height : Nat32;
};

/// A reference to a transaction output.
public type OutPoint = {
    txid : Blob;
    vout : Nat32;
};

Get available UTXOs​

The following snippet shows how to get the available UTXOs corresponding to own_address. Note that an ICP smart contract can control multiple addresses and each one can have multiple UTXOs associated with it.

To create a transaction that sends X satoshis to a destination address, you need to select a subset of the available UTXOs that cover the amount X plus the transaction fee.

To implement the following code snippets in your dapp, you will need to setup a local development environment and create a project.

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo
/// Returns the UTXOs of the given Bitcoin address.
///
/// NOTE: Relies on the `bitcoin_get_utxos` endpoint.
/// See https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_utxos
public func get_utxos(network : Network, address : BitcoinAddress) : async GetUtxosResponse {
  ExperimentalCycles.add<system>(GET_UTXOS_COST_CYCLES);
  await management_canister_actor.bitcoin_get_utxos({
      address;
      network;
      filter = null;
  })
};

Calculate transaction fee per byte​

The transaction fee of a Bitcoin transaction is calculated based on the size of the transaction in bytes. An appropriate fee per byte can be determined by looking at the fees of recent transactions on the Bitcoin mainnet. The following snippet shows how to estimate the fee per byte for a transaction using the bitcoin_get_current_fee_percentiles API endpoint and choosing the 50th percentile.

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo
/// Returns the 100 fee percentiles measured in millisatoshi/vbyte.
/// Percentiles are computed from the last 10,000 transactions (if available).
///
/// Relies on the `bitcoin_get_current_fee_percentiles` endpoint.
/// See https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_current_fee_percentiles
public func get_current_fee_percentiles(network : Network) : async [MillisatoshiPerVByte] {
  ExperimentalCycles.add<system>(GET_CURRENT_FEE_PERCENTILES_COST_CYCLES);
  await management_canister_actor.bitcoin_get_current_fee_percentiles({
      network;
  })
};

Build the transaction​

Now the transaction can be built. Since the fee of a transaction is based on its size, the transaction has to be built iteratively and signed with a mock signer that adds the respective size of the signature. Each selected UTXO is used as an input for the transaction and requires a signature.

The following snippet shows a simplified version of how to build a transaction that will be signed by a P2PKH address:

motoko/basic_bitcoin/src/basic_bitcoin/src/P2pkh.mo
// Builds a transaction to send the given `amount` of satoshis to the
// destination address.
func build_transaction(
    ecdsa_canister_actor : EcdsaCanisterActor,
    own_public_key : [Nat8],
    own_address : BitcoinAddress,
    own_utxos : [Utxo],
    dst_address : BitcoinAddress,
    amount : Satoshi,
    fee_per_vbyte : MillisatoshiPerVByte,
) : async [Nat8] {
    let dst_address_typed = Utils.get_ok_expect(Address.addressFromText(dst_address), "failed to decode destination address");

    // We have a chicken-and-egg problem where we need to know the length
    // of the transaction in order to compute its proper fee, but we need
    // to know the proper fee in order to figure out the inputs needed for
    // the transaction.
    //
    // We solve this problem iteratively. We start with a fee of zero, build
    // and sign a transaction, see what its size is, and then update the fee,
    // rebuild the transaction, until the fee is set to the correct amount.
    let fee_per_vbyte_nat = Nat64.toNat(fee_per_vbyte);
    Debug.print("Building transaction...");
    var total_fee : Nat = 0;
    loop {
        let transaction = Utils.get_ok_expect(Bitcoin.buildTransaction(2, own_utxos, [(dst_address_typed, amount)], #p2pkh own_address, Nat64.fromNat(total_fee)), "Error building transaction.");

        // Sign the transaction. In this case, we only care about the size
        // of the signed transaction, so we use a mock signer here for efficiency.
        let signed_transaction_bytes = await sign_transaction(
            ecdsa_canister_actor,
            own_public_key,
            own_address,
            transaction,
            "", // mock key name
            [], // mock derivation path
            Utils.ecdsa_mock_signer,
        );

        let signed_tx_bytes_len : Nat = signed_transaction_bytes.size();

        if ((signed_tx_bytes_len * fee_per_vbyte_nat) / 1000 == total_fee) {
            Debug.print("Transaction built with fee " # debug_show (total_fee));
            return transaction.toBytes();
        } else {
            total_fee := (signed_tx_bytes_len * fee_per_vbyte_nat) / 1000;
        };
    };
};