Deprecating the Bitcoin API of the management canister (#354)

* Deprecating the Bitcoin API of the management canister.

* changelog

---------

Co-authored-by: Martin Raszyk <[email protected]>

Author: THLO

spec/_attachments/interface-spec-changelog.md

@@ -3,6 +3,7 @@
 ### ∞ (unreleased)
 * Allow anonymous query and read state requests with invalid `ingress_expiry`.
 * Add allowed viewers variant to canister log visibility.
+* Deprecate the Bitcoin API of the management canister.
 
 ### 0.28.0 (2024-10-11) {#0_28_0}
 * Add new management canister methods for canister snapshot support.

spec/index.md

@@ -2639,10 +2639,18 @@ Replica-signed queries may improve security because the recipient can verify the
 
 ## The IC Bitcoin API {#ic-bitcoin-api}
 
-The Bitcoin functionality is exposed via the management canister. Information about Bitcoin can be found in the [Bitcoin developer guides](https://developer.bitcoin.org/devguide/). Invoking the functions of the Bitcoin API will cost cycles. We refer the reader to the [Bitcoin documentation](https://internetcomputer.org/docs/current/developer-docs/integrations/bitcoin/bitcoin-how-it-works) for further relevant information and the [IC pricing page](https://internetcomputer.org/docs/current/developer-docs/gas-cost) for information on pricing for the Bitcoin mainnet and testnet.
+The Bitcoin API exposed by the management canister is DEPRECATED.
+Developers should interact with the Bitcoin canisters (`ghsi2-tqaaa-aaaan-aaaca-cai` for Bitcoin mainnet and `g4xu7-jiaaa-aaaan-aaaaq-cai` for Bitcoin testnet) directly.
+Information about Bitcoin and the IC Bitcoin integration can be found in the [Bitcoin developer guides](https://developer.bitcoin.org/devguide/) and  the [Bitcoin integration documentation](https://internetcomputer.org/docs/current/developer-docs/integrations/bitcoin/bitcoin-how-it-works).
 
 ### IC method `bitcoin_get_utxos` {#ic-bitcoin_get_utxos}
 
+:::note
+
+This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.
+
+:::
+
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
 
 Given a `get_utxos_request`, which must specify a Bitcoin address and a Bitcoin network (`mainnet` or `testnet`), the function returns all unspent transaction outputs (UTXOs) associated with the provided address in the specified Bitcoin network based on the current view of the Bitcoin blockchain available to the Bitcoin component. The UTXOs are returned sorted by block height in descending order.
@@ -2677,6 +2685,12 @@ The recommended workflow is to issue a request with the desired number of confir
 
 ### IC method `bitcoin_get_balance` {#ic-bitcoin_get_balance}
 
+:::note
+
+This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.
+
+:::
+
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
 
 Given a `get_balance_request`, which must specify a Bitcoin address and a Bitcoin network (`mainnet` or `testnet`), the function returns the current balance of this address in `Satoshi` (10^8 Satoshi = 1 Bitcoin) in the specified Bitcoin network. The same address formats as for [`bitcoin_get_utxos`](#ic-bitcoin_get_utxos) are supported.
@@ -2689,6 +2703,12 @@ Given an address and the optional `min_confirmations` parameter, `bitcoin_get_ba
 
 ### IC method `bitcoin_send_transaction` {#ic-bitcoin_send_transaction}
 
+:::note
+
+This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.
+
+:::
+
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
 
 Given a `send_transaction_request`, which must specify a `blob` of a Bitcoin transaction and a Bitcoin network (`mainnet` or `testnet`), several checks are performed:
@@ -2705,6 +2725,12 @@ If the transaction passes these tests, the transaction is forwarded to the speci
 
 ### IC method `bitcoin_get_current_fee_percentiles` {#ic-bitcoin_get_current_fee_percentiles}
 
+:::note
+
+This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.
+
+:::
+
 This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.
 
 The transaction fees in the Bitcoin network change dynamically based on the number of pending transactions. It must be possible for a canister to determine an adequate fee when creating a Bitcoin transaction.
@@ -2717,7 +2743,7 @@ The [standard nearest-rank estimation method](https://en.wikipedia.org/wiki/Perc
 
 :::note
 
-The `bitcoin_get_block_headers` endpoint is considered EXPERIMENTAL. Canister developers must be aware that this endpoint may evolve in a non-backward-compatible way.
+This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.
 
 :::