Generating a Bitcoin address

Advanced

Bitcoin

Overview

For a canister to receive Bitcoin payments, it must generate a Bitcoin address. In contrast to most other blockchains, Bitcoin doesn't use accounts. Instead, it uses a UTXO model. A UTXO is an unspent transaction output, and a Bitcoin transaction spends one or more UTXOs and creates new UTXOs. Each UTXO is associated with a Bitcoin address, which is derived from a public key or a script that defines the conditions under which the UTXO can be spent. A Bitcoin address is often used as a single use invoice instead of a persistant address to increase privacy.

Bitcoin address types

Bitcoin uses multiple address types:

Legacy addresses

These addresses start with a 1 and are called P2PKH (Pay to Public Key Hash) addresses. They encode the hash of an ECDSA public key.

There is also another type of legacy address that starts with a 3 called P2SH (Pay to Script Hash) that encodes the hash of a script. The script can define complex conditions such as multisig or timelocks.

SegWit addresses

SegWit addresses are newer addresses following the Bech32 format that start with bc1. They are cheaper to spend than legacy addresses and solve transaction malleability which is important for advanced use cases like Partially Signed Bitcoin Transcations (PSBT) or the Lightning Network. SegWit addresses can be of three types:

• P2WPKH (Pay to Witness Public Key Hash): A SegWit address that encodes the hash of an ECDSA public key.
• P2WSH (Pay to Witness Script Hash): A SegWit address that encodes the hash of a script.
• P2TR (Pay to Taproot): A SegWit address that can be unlocked by a Schnorr signature or a script.

Generating a Bitcoin address

As mentioned above, a Bitcoin address is derived from a public key or a script. To generate a Bitcoin address that can only be spent by a specific canister or a specific caller of a canister, you need to derive the address from a canister's public key.

Generating addresses with threshold ECDSA

An ECDSA public key can be retrieved using the ecdsa_public_key API. The basic Bitcoin example demonstrates how to generate a P2PKH address from a canister's public key.

Motoko

/// Returns the P2PKH address of this canister at the given derivation path.
public func get_p2pkh_address(network : Network, key_name : Text, derivation_path : [[Nat8]]) : async BitcoinAddress {
    // Fetch the public key of the given derivation path.
    let public_key = await EcdsaApi.ecdsa_public_key(key_name, Array.map(derivation_path, Blob.fromArray));

    // Compute the address.
    public_key_to_p2pkh_address(network, Blob.toArray(public_key))
};

// Converts a public key to a P2PKH address.
func public_key_to_p2pkh_address(network : Network, public_key_bytes : [Nat8]) : BitcoinAddress {
    let public_key = public_key_bytes_to_public_key(public_key_bytes);

    // Compute the P2PKH address from our public key.
    P2pkh.deriveAddress(Types.network_to_network_camel_case(network), Publickey.toSec1(public_key, true))
};
  

View in the full example.

Rust

/// Returns the P2PKH address of this canister at the given derivation path.
pub async fn get_p2pkh_address(
    network: BitcoinNetwork,
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
) -> String {
    // Fetch the public key of the given derivation path.
    let public_key = ecdsa_api::ecdsa_public_key(key_name, derivation_path).await;

    // Compute the address.
    public_key_to_p2pkh_address(network, &public_key)
}

// Converts a public key to a P2PKH address.
fn public_key_to_p2pkh_address(network: BitcoinNetwork, public_key: &[u8]) -> String {
    Address::p2pkh(
        &PublicKey::from_slice(public_key).expect("failed to parse public key"),
        transform_network(network),
    )
    .to_string()
}

View in the full example.

Generating addresses with threshold Schnorr

A Schnor public key can be retrieved using the schnorr_public_key API. The basic Bitcoin example also demonstrates how to generate two different types of P2TR addresses, an untweaked key path address and a script spend address, from a canister's public key.

The Internet Computer currently supports exclusively one of both types of addresses, but not addresses that can use both key path and script path, meaning that an address supporting the key path cannot spend with a script and vice versa.

Generating an untweaked key path address

It is important to make sure that the address is generated from an untweaked key or the signature verification and thus the Bitcoin transaction will fail. Most libraries will automatically tweak the key when creating a taproot address by default, so make sure to use the correct function to generate the address as, for example, shown in the example below.

Rust

/// Returns the P2TR address of this canister at the given derivation path.
pub async fn get_address(
    network: BitcoinNetwork,
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
) -> Address {
    let public_key = schnorr_api::schnorr_public_key(key_name, derivation_path).await;
    let x_only_pubkey =
        bitcoin::key::XOnlyPublicKey::from(PublicKey::from_slice(&public_key).unwrap());
    let tweaked_pubkey = TweakedPublicKey::dangerous_assume_tweaked(x_only_pubkey);
    Address::p2tr_tweaked(tweaked_pubkey, super::common::transform_network(network))
}

View in the full example.

Generating a script path address

Rust

/// Returns the P2TR address of this canister at the given derivation path.
pub async fn get_address(
    network: BitcoinNetwork,
    key_name: String,
    derivation_path: Vec<Vec<u8>>,
) -> Address {
    let public_key = schnorr_api::schnorr_public_key(key_name, derivation_path).await;
    public_key_to_p2tr_script_spend_address(network, public_key.as_slice())
}

// Converts a public key to a P2TR address. To compute the address, the public
// key is tweaked with the taproot value, which is computed from the public key
// and the Merkelized Abstract Syntax Tree (MAST, essentially a Merkle tree
// containing scripts, in our case just one). Addresses are computed differently
// for different Bitcoin networks.
pub fn public_key_to_p2tr_script_spend_address(
    bitcoin_network: BitcoinNetwork,
    public_key: &[u8],
) -> Address {
    let network = super::common::transform_network(bitcoin_network);
    let taproot_spend_info = p2tr_scipt_spend_info(public_key);
    Address::p2tr_tweaked(taproot_spend_info.output_key(), network)
}

fn p2tr_scipt_spend_info(public_key: &[u8]) -> TaprootSpendInfo {
    let spend_script = p2tr_script(public_key);
    let secp256k1_engine = Secp256k1::new();
    // This is the key used in the *tweaked* key path spending. Currently, this
    // use case is not supported on the IC. But, once the IC supports this use
    // case, the addresses constructed in this way will be able to use same key
    // in both script and *tweaked* key path spending.
    let internal_public_key = XOnlyPublicKey::from(PublicKey::from_slice(&public_key).unwrap());

    TaprootBuilder::new()
        .add_leaf(0, spend_script.clone())
        .expect("adding leaf should work")
        .finalize(&secp256k1_engine, internal_public_key)
        .expect("finalizing taproot builder should work")
}

/// Computes a simple P2TR script that allows the `public_key` and no other keys
/// to be used for spending.
fn p2tr_script(public_key: &[u8]) -> ScriptBuf {
    let x_only_public_key = XOnlyPublicKey::from(PublicKey::from_slice(public_key).unwrap());
    bitcoin::blockdata::script::Builder::new()
        .push_x_only_key(&x_only_public_key)
        .push_opcode(bitcoin::blockdata::opcodes::all::OP_CHECKSIG)
        .into_script()
}

View in the full example.

Learn more

See more examples of addresses generated using rust-bitcoin.

Learn more about Bitcoin addresses using ECDSA.

Learn more about Bitcoin addresses using Schnorr: taproot signatures BIP340, taproot addresses BIP341, taproot scripts BIP342.

Learn more about the ecdsa_public_key API.

Learn more about the schnorr_public_key API.

Next steps

Learn how to create a Bitcoin transaction to spend the BTC received by the address.