Add retrieveBtcStatus to ckbtc minter

CHANGELOG.md

@@ -5,6 +5,7 @@
 ## Features
 
 - Substitute `?` fields with `Option` fields in the converters related to NNS proposals.
+- Add retrieveBtcStatus to ckbtc minter canister.
 
 # Release.2023.11.21-1400Z
 

packages/ckbtc/README.md

@@ -78,7 +78,7 @@ Parameters:
 
 ### :factory: CkBTCMinterCanister
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L35)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L36)
 
 #### Methods
 
@@ -88,6 +88,7 @@ Parameters:
 - [getWithdrawalAccount](#gear-getwithdrawalaccount)
 - [retrieveBtc](#gear-retrievebtc)
 - [retrieveBtcWithApproval](#gear-retrievebtcwithapproval)
+- [retrieveBtcStatus](#gear-retrievebtcstatus)
 - [estimateWithdrawalFee](#gear-estimatewithdrawalfee)
 - [getMinterInfo](#gear-getminterinfo)
 
@@ -97,7 +98,7 @@ Parameters:
 | -------- | ------------------------------------------------------------------------ |
 | `create` | `(options: CkBTCMinterCanisterOptions<_SERVICE>) => CkBTCMinterCanister` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L36)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L37)
 
 ##### :gear: getBtcAddress
 
@@ -115,7 +116,7 @@ Parameters:
 - `params.owner`: The owner for which the BTC address should be generated. If not provided, the `caller` will be use instead.
 - `params.subaccount`: An optional subaccount to compute the address.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L57)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L58)
 
 ##### :gear: updateBalance
 
@@ -133,7 +134,7 @@ Parameters:
 - `params.owner`: The owner of the address. If not provided, the `caller` will be use instead.
 - `params.subaccount`: An optional subaccount of the address.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L76)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L77)
 
 ##### :gear: getWithdrawalAccount
 
@@ -143,7 +144,7 @@ Returns the account to which the caller should deposit ckBTC before withdrawing
 | ---------------------- | ------------------------ |
 | `getWithdrawalAccount` | `() => Promise<Account>` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L99)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L100)
 
 ##### :gear: retrieveBtc
 
@@ -167,7 +168,7 @@ Parameters:
 - `params.address`: The bitcoin address.
 - `params.amount`: The ckBTC amount.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L118)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L119)
 
 ##### :gear: retrieveBtcWithApproval
 
@@ -193,7 +194,23 @@ Parameters:
 - `params.fromSubaccount`: An optional subaccount from which
   the ckBTC should be transferred.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L148)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L149)
+
+##### :gear: retrieveBtcStatus
+
+Returns the status of a specific BTC withdrawal based on the transaction ID
+of the corresponding burn transaction.
+
+| Method              | Type                                                                                                            |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `retrieveBtcStatus` | `({ transactionId, certified, }: { transactionId: bigint; certified: boolean; }) => Promise<RetrieveBtcStatus>` |
+
+Parameters:
+
+- `transactionId`: The ID of the corresponding burn transaction.
+- `certified`: query or update call
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L180)
 
 ##### :gear: estimateWithdrawalFee
 
@@ -209,7 +226,7 @@ Parameters:
 - `params.certified`: query or update call
 - `params.amount`: The optional amount for which the fee should be estimated.
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L179)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L198)
 
 ##### :gear: getMinterInfo
 
@@ -224,7 +241,7 @@ Parameters:
 - `params`: The parameters to get the deposit fee.
 - `params.certified`: query or update call
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L193)
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ckbtc/src/minter.canister.ts#L212)
 
 <!-- TSDOC_END -->
 

packages/ckbtc/src/index.ts

@@ -2,6 +2,7 @@ export type {
   MinterInfo,
   PendingUtxo,
   RetrieveBtcOk,
+  RetrieveBtcStatus,
   Account as WithdrawalAccount,
 } from "../candid/minter";
 export * from "./enums/btc.enums";

packages/ckbtc/src/minter.canister.spec.ts

@@ -6,6 +6,7 @@ import type { Account, _SERVICE as CkBTCMinterService } from "../candid/minter";
 import {
   RetrieveBtcError,
   RetrieveBtcOk,
+  RetrieveBtcStatus,
   UpdateBalanceError,
 } from "../candid/minter";
 import {
@@ -33,6 +34,14 @@ describe("ckBTC minter canister", () => {
       certifiedServiceOverride: service,
     });
 
+  const nonCertifiedMinter = (
+    service: ActorSubclass<CkBTCMinterService>,
+  ): CkBTCMinterCanister =>
+    CkBTCMinterCanister.create({
+      canisterId: minterCanisterIdMock,
+      serviceOverride: service,
+    });
+
   describe("BTC address", () => {
     it("should return the BTC address of main account", async () => {
       const service = mock<ActorSubclass<CkBTCMinterService>>();
@@ -632,6 +641,54 @@ describe("ckBTC minter canister", () => {
     });
   });
 
+  describe("Retrieve BTC status", () => {
+    it("should return status", async () => {
+      const submittedStatus = {
+        Submitted: { txid: new Uint8Array([3, 2, 6]) },
+      } as RetrieveBtcStatus;
+
+      const service = mock<ActorSubclass<CkBTCMinterService>>();
+      service.retrieve_btc_status.mockResolvedValue(submittedStatus);
+      const transactionId = 481n;
+
+      const canister = minter(service);
+
+      const res = await canister.retrieveBtcStatus({
+        transactionId,
+        certified: true,
+      });
+
+      expect(service.retrieve_btc_status).toBeCalledTimes(1);
+      expect(service.retrieve_btc_status).toBeCalledWith({
+        block_index: transactionId,
+      });
+      expect(res).toEqual(submittedStatus);
+    });
+
+    it("should use non-certified service", async () => {
+      const submittedStatus = {
+        Submitted: { txid: new Uint8Array([9, 7, 5]) },
+      } as RetrieveBtcStatus;
+
+      const service = mock<ActorSubclass<CkBTCMinterService>>();
+      service.retrieve_btc_status.mockResolvedValue(submittedStatus);
+      const transactionId = 382n;
+
+      const canister = nonCertifiedMinter(service);
+
+      const res = await canister.retrieveBtcStatus({
+        transactionId,
+        certified: false,
+      });
+
+      expect(service.retrieve_btc_status).toBeCalledTimes(1);
+      expect(service.retrieve_btc_status).toBeCalledWith({
+        block_index: transactionId,
+      });
+      expect(res).toEqual(submittedStatus);
+    });
+  });
+
   describe("Estimate Withdrawal Fee", () => {
     it("should return estimated fee", async () => {
       const result = { minter_fee: 123n, bitcoin_fee: 456n };

packages/ckbtc/src/minter.canister.ts

@@ -8,6 +8,7 @@ import type {
   _SERVICE as CkBTCMinterService,
   MinterInfo,
   RetrieveBtcOk,
+  RetrieveBtcStatus,
   Account as WithdrawalAccount,
 } from "../candid/minter";
 import { idlFactory as certifiedIdlFactory } from "../candid/minter.certified.idl";
@@ -169,6 +170,24 @@ export class CkBTCMinterCanister extends Canister<CkBTCMinterService> {
     return response.Ok;
   };
 
+  /**
+   * Returns the status of a specific BTC withdrawal based on the transaction ID
+   * of the corresponding burn transaction.
+   *
+   * @param {bigint} transactionId The ID of the corresponding burn transaction.
+   * @param {boolean} certified query or update call
+   */
+  retrieveBtcStatus = async ({
+    transactionId,
+    certified,
+  }: {
+    transactionId: bigint;
+    certified: boolean;
+  }): Promise<RetrieveBtcStatus> =>
+    this.caller({
+      certified,
+    }).retrieve_btc_status({ block_index: transactionId });
+
   /**
    * Returns an estimation of the user's fee (in Satoshi) for a retrieve_btc request based on the current status of the Bitcoin network and the fee related to the minter.
    *