readme and small improvements

Author: altkdf

motoko/basic_bitcoin/README.md

@@ -15,12 +15,9 @@ For a deeper understanding of the ICP < > BTC integration, see the [Bitcoin inte
 ## Prerequisites
 
 - [x] Install the [IC
-  SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install). For local testing, `dfx >= 0.22.0` is required.
+  SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install).
 - [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples`
 
-> [!WARNING]
-> This example is designed to be deployed on the mainnet. It will return errors when deployed locally; these errors are expected.
-
 Begin by opening a terminal window.
 
 ## Step 1: Setup the project environment
@@ -89,58 +86,40 @@ to check [this
 article](https://bitcoinmagazine.com/technical/bitcoin-address-types-compared-p2pkh-p2sh-p2wpkh-and-more)
 if you are interested in a high-level comparison of different address types.
 These addresses can be generated from an ECDSA public key or a Schnorr
-([BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki))
-public key. The example code showcases how your canister can generate and spend
-from three types of addresses:
+([BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki),
+[BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)) public
+key. The example code showcases how your canister can generate and spend from
+three types of addresses:
 1. A [P2PKH address](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash)
    using the
    [ecdsa_public_key](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-method-ecdsa_public_key)
    API.
 2. A [P2TR
    address](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)
-   where the funds can be spent using the raw (untweaked) internal key
-   (so-called P2TR key path spend, but untweaked). The advantage of this
-   approach compared to P2TR script spends is its significantly smaller fee per
-   transaction because checking the transaction signature is analogous to P2PK
-   but uses Schnorr instead of ECDSA. The limitation of untweaked P2TR addresses
-   is that they cannot be used with scripts. IMPORTANT: Note that
-   [BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#cite_note-23)
-   advises against using taproot addresses that can be spent with an untweaked
-   key. This precaution is to prevent attacks that can occur when creating
-   taproot multisigner addresses using specific multisignature schemes. However,
-   the Schnorr API of the internet computer does not support Schnorr
-   multisignatures.
+   where the funds can be spent using the internal key only ([P2TR key path
+   spend with unspendable script
+   tree](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#cite_note-23)).
 3. A [P2TR
    address](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)
-   where the funds can be spent using the provided public key with the script
-   path, where the Merkelized Alternative Script Tree (MAST) consists of a
-   single script allowing to spend funds by exactly one key.
-
-Note that P2TR *key path* spending with a tweaked key is currently not available
-on the IC because the threshold Schnorr signing interface does not allow
-applying BIP341 tweaks to the private key. In contrast, the
-tweaked public key is used to spend in the script path, which is availble on the
-IC. For a technical comparison of different ways of how single-signer P2TR
-addresses can be constructed and used, you may want to take a look at [this
-post](https://bitcoin.stackexchange.com/a/111100) by Pieter Wuille.
+   where the funds can be spent using either 1) the internal key or 2) the
+   provided public key with the script path, where the Merkelized Alternative
+   Script Tree (MAST) consists of a single script allowing to spend funds by
+   exactly one key.
 
 On the Candid UI of your canister, click the "Call" button under
 `get_${type}_address` to generate a `${type}` Bitcoin address, where `${type}`
-is one of `[p2pkh, p2tr_raw_key_spend, p2tr_script_spend]`.
+is one of `[p2pkh, p2tr_key_only, p2tr]` (corresponding to the three types of
+addresses described above, in the same order).
 
 Or, if you prefer the command line:
 
 ```bash
 dfx canister --network=ic call basic_bitcoin get_${type}_address
 ```
 
-* The Bitcoin address you see will be different from the one above because the
-  ECDSA public key your canister retrieves is unique.
-
 * We are generating a Bitcoin testnet address, which can only be
 used for sending/receiving Bitcoin on the Bitcoin testnet.
 
-
 ## Step 3: Receiving bitcoin
 
 Now that the canister is deployed and you have a Bitcoin address, it's time to receive
@@ -150,7 +129,6 @@ to receive some bitcoin.
 Enter your address and click on "Send testnet bitcoins". In the example below we will use Bitcoin address `n31eU1K11m1r58aJMgTyxGonu7wSMoUYe7`, but you will use your address. The Bitcoin address you see will be different from the one above
 because the ECDSA/Schnorr public key your canister retrieves is unique.
 
-
 Once the transaction has at least one confirmation, which can take a few minutes,
 you'll be able to see it in your canister's balance.
 
@@ -171,15 +149,16 @@ Checking the balance of a Bitcoin address relies on the [bitcoin_get_balance](ht
 ## Step 5: Sending bitcoin
 
 You can send bitcoin using the `send_from_${type}` endpoint on your canister, where
-`${type}` is on of `[p2pkh, p2tr_raw_key_spend, p2tr_script_spend]`.
+`${type}` is one of
+`[p2pkh_address, p2tr_key_only_address, p2tr_address_key_path, p2tr_address_script_path]`.
 
 In the Candid UI, add a destination address and an amount to send. In the example
 below, we're sending 4'321 Satoshi (0.00004321 BTC) back to the testnet faucet.
 
 Via the command line, the same call would look like this:
 
 ```bash
-dfx canister --network=ic call basic_bitcoin send_from_p2pkh '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
+dfx canister --network=ic call basic_bitcoin send_from_p2pkh_address '(record { destination_address = "tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt"; amount_in_satoshi = 4321; })'
 ```
 
 The `send_from_${type}` endpoint can send bitcoin by:

motoko/basic_bitcoin/src/basic_bitcoin/src/Main.mo

@@ -88,12 +88,12 @@ actor class BasicBitcoin(network : Types.Network) {
     await P2tr.get_address(schnorr_canister_actor, NETWORK, KEY_NAME, p2trDerivationPaths());
   };
 
-  public func send_from_p2tr_address_key_spend(request : SendRequest) : async TransactionId {
-    Utils.bytesToText(await P2tr.send_key_spend(schnorr_canister_actor, NETWORK, p2trDerivationPaths(), KEY_NAME, request.destination_address, request.amount_in_satoshi));
+  public func send_from_p2tr_address_key_path(request : SendRequest) : async TransactionId {
+    Utils.bytesToText(await P2tr.send_key_path(schnorr_canister_actor, NETWORK, p2trDerivationPaths(), KEY_NAME, request.destination_address, request.amount_in_satoshi));
   };
 
-  public func send_from_p2tr_address_script_spend(request : SendRequest) : async TransactionId {
-    Utils.bytesToText(await P2tr.send_script_spend(schnorr_canister_actor, NETWORK, p2trDerivationPaths(), KEY_NAME, request.destination_address, request.amount_in_satoshi));
+  public func send_from_p2tr_address_script_path(request : SendRequest) : async TransactionId {
+    Utils.bytesToText(await P2tr.send_script_path(schnorr_canister_actor, NETWORK, p2trDerivationPaths(), KEY_NAME, request.destination_address, request.amount_in_satoshi));
   };
 
   func p2pkhDerivationPath() : [[Nat8]] {

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

@@ -245,7 +245,7 @@ module {
     /// Sends a key spend transaction with a non-empty MAST to the network that
     /// transfers the given amount to the given destination, where the source
     /// of the funds is the canister itself at the given derivation path.
-    public func send_key_spend(schnorr_canister_actor : SchnorrCanisterActor, network : Network, derivation_paths : P2trDerivationPaths, key_name : Text, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
+    public func send_key_path(schnorr_canister_actor : SchnorrCanisterActor, network : Network, derivation_paths : P2trDerivationPaths, key_name : Text, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
         let internal_bip340_public_key = await fetch_bip340_public_key(schnorr_canister_actor, key_name, derivation_paths.key_path_derivation_path);
         let script_bip340_public_key = await fetch_bip340_public_key(schnorr_canister_actor, key_name, derivation_paths.script_path_derivation_path);
         let { tweaked_address = own_tweaked_address } = internal_key_and_script_key_to_p2tr_address(internal_bip340_public_key, script_bip340_public_key, network);
@@ -256,13 +256,13 @@ module {
             merkle_root_hash = Blob.fromArray(leafHash(leaf_script));
         });
 
-        await send_key_spend_generic(schnorr_canister_actor, own_tweaked_address, network, derivation_paths.key_path_derivation_path, key_name, ?aux, dst_address, amount);
+        await send_key_path_generic(schnorr_canister_actor, own_tweaked_address, network, derivation_paths.key_path_derivation_path, key_name, ?aux, dst_address, amount);
     };
 
     /// Sends a key spend transaction to the network that transfers the given amount to the
     /// given destination, where the source of the funds is the canister itself
     /// at the given derivation path.
-    public func send_key_spend_generic(schnorr_canister_actor : SchnorrCanisterActor, own_address : BitcoinAddress, network : Network, signer_derivation_path : [[Nat8]], key_name : Text, aux : ?Types.SchnorrAux, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
+    public func send_key_path_generic(schnorr_canister_actor : SchnorrCanisterActor, own_address : BitcoinAddress, network : Network, signer_derivation_path : [[Nat8]], key_name : Text, aux : ?Types.SchnorrAux, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
         // Get fee percentiles from previous transactions to estimate our own fee.
         let fee_percentiles = await BitcoinApi.get_current_fee_percentiles(network);
 
@@ -313,7 +313,7 @@ module {
     /// Sends a script spend transaction to the network that transfers the given amount to the
     /// given destination, where the source of the funds is the canister itself
     /// at the given derivation path.
-    public func send_script_spend(schnorr_canister_actor : SchnorrCanisterActor, network : Network, derivation_paths : P2trDerivationPaths, key_name : Text, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
+    public func send_script_path(schnorr_canister_actor : SchnorrCanisterActor, network : Network, derivation_paths : P2trDerivationPaths, key_name : Text, dst_address : BitcoinAddress, amount : Satoshi) : async [Nat8] {
         // Get fee percentiles from previous transactions to estimate our own fee.
         let fee_percentiles = await BitcoinApi.get_current_fee_percentiles(network);
 

motoko/basic_bitcoin/src/basic_bitcoin/src/P2trKeyOnly.mo

@@ -41,7 +41,7 @@ module {
     #bip341({
       merkle_root_hash = Blob.fromArray(P2tr.unspendableMerkleRoot(untweaked_bip340_public_key_bytes));
     });
-    await P2tr.send_key_spend_generic(schnorr_canister_actor, own_address, network, derivation_path, key_name, ?aux, dst_address, amount);
+    await P2tr.send_key_path_generic(schnorr_canister_actor, own_address, network, derivation_path, key_name, ?aux, dst_address, amount);
   };
 
   /// Returns the P2TR key-only address of this canister at a specific