feat: bitcoin balance and getUtxos support for queries only (#706)

# Motivation

As we learned this week, update calls to the Bitcoin canister for
`get_balance` and `get_utxos` are only possible when executed from a
canister. Therefore, we remove the support for certified calls regarding
those endpoints in `@dfinity/ckbtc`. In addition, to make the exception
more obvious and to reflects the actual IC API naming, we also add the
suffix `Query` to the functions.

# Documentation


https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-bitcoin_get_utxos

# Changes

- Remove `certified` option parameter for `getBalance` and `getUtxos`
- Rename `getBalance` and `getUtxos` to `getBalanceQuery` and
`getUtxosQuery`
- Add a warning in the documentation
- Update code to use only endpoints `_query`
- Add breaking change in changelog

---------

Signed-off-by: David Dal Busco <david.dalbusco@dfinity.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -5,12 +5,13 @@
 - Rename values of enum Topic and NnsFunction to match the backend values.
 - Use different request/response types for NNS Governance proposals, and different fields for `InstallCode` proposals.
 - The `getUtxos` parameter `filter.min_confirmations` has been renamed to `filter.minConfirmations` for consistency with the general naming conventions used in `@dfinity/ckbtc`.
+- Only queries to `getUtxos` of the Bitcoin canister can be executed by external users — i.e., update calls can only be performed by the canister. This is why `getUtxos` now only supports non-certified calls and has been renamed to `getUtxosQuery`.
 
 ## Features
 
 - Provide a new utility to convert Candid `Nat` to `BigInt`. This utility is useful for interpreting the fees provided by the SNS Aggregator.
 - Support conversion of `InstallCode`, `StopOrStartCanister` and `UpdateCanisterSettings` actions, `SetVisibility` neuron operation, and `Neuron::visibility` attribute.
-- Add function `getBalance` to `BitcoinCanister` object of package `@dfinity/ckbtc`, that implements the `bitcoin_get_balance` method of the IC Bitcoin API.
+- Add function `getBalanceQuery` to `BitcoinCanister` object of package `@dfinity/ckbtc`, that implements the `bitcoin_get_balance_query` method of the IC Bitcoin API.
 
 ## Build
 

packages/ckbtc/README.md

@@ -281,8 +281,8 @@ Parameters:
 #### Methods
 
 - [create](#gear-create)
-- [getUtxos](#gear-getutxos)
-- [getBalance](#gear-getbalance)
+- [getUtxosQuery](#gear-getutxosquery)
+- [getBalanceQuery](#gear-getbalancequery)
 
 ##### :gear: create
 
@@ -292,37 +292,39 @@ Parameters:
 
 [:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/bitcoin.canister.ts#L18)
 
-##### :gear: getUtxos
+##### :gear: getUtxosQuery
 
 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.
 
-| Method     | Type                                                                        |
-| ---------- | --------------------------------------------------------------------------- |
-| `getUtxos` | `({ certified, ...params }: GetUtxosParams) => Promise<get_utxos_response>` |
+⚠️ Note that this method does not support certified calls because only canisters are allowed to get UTXOs via update calls.
+
+| Method          | Type                                                             |
+| --------------- | ---------------------------------------------------------------- |
+| `getUtxosQuery` | `({ ...params }: GetUtxosParams) => Promise<get_utxos_response>` |
 
 Parameters:
 
 - `params.network`: Tesnet or mainnet.
 - `params.filter`: The optional filter parameter can be used to restrict the set of returned UTXOs, either providing a minimum number of confirmations or a page reference when pagination is used for addresses with many UTXOs.
 - `params.address`: A Bitcoin address.
-- `params.certified`: query or update call
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/bitcoin.canister.ts#L41)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/bitcoin.canister.ts#L42)
 
-##### :gear: getBalance
+##### :gear: getBalanceQuery
 
 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.
 
-| Method       | Type                                                              |
-| ------------ | ----------------------------------------------------------------- |
-| `getBalance` | `({ certified, ...params }: GetBalanceParams) => Promise<bigint>` |
+⚠️ Note that this method does not support certified calls because only canisters are allowed to get Bitcoin balance via update calls.
+
+| Method            | Type                                                   |
+| ----------------- | ------------------------------------------------------ |
+| `getBalanceQuery` | `({ ...params }: GetBalanceParams) => Promise<bigint>` |
 
 Parameters:
 
 - `params.network`: Tesnet or mainnet.
 - `params.min_confirmations`: The optional filter parameter can be used to limit the set of considered UTXOs for the calculation of the balance to those with at least the provided number of confirmations in the same manner as for the `bitcoin_get_utxos` call.
 - `params.address`: A Bitcoin address.
-- `params.certified`: query or update call
 
 [:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/bitcoin.canister.ts#L64)