diff --git a/CHANGELOG.md b/CHANGELOG.md index 41841f1c3..5e2a55ef3 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/packages/ckbtc/README.md b/packages/ckbtc/README.md index 5583b61fc..f736642c7 100644 --- a/packages/ckbtc/README.md +++ b/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` | -[: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` | + +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) diff --git a/packages/ckbtc/src/index.ts b/packages/ckbtc/src/index.ts index d6c7dde39..079888cf7 100644 --- a/packages/ckbtc/src/index.ts +++ b/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"; diff --git a/packages/ckbtc/src/minter.canister.spec.ts b/packages/ckbtc/src/minter.canister.spec.ts index 6c3330a73..387ded729 100644 --- a/packages/ckbtc/src/minter.canister.spec.ts +++ b/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, + ): CkBTCMinterCanister => + CkBTCMinterCanister.create({ + canisterId: minterCanisterIdMock, + serviceOverride: service, + }); + describe("BTC address", () => { it("should return the BTC address of main account", async () => { const service = mock>(); @@ -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>(); + 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>(); + 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 }; diff --git a/packages/ckbtc/src/minter.canister.ts b/packages/ckbtc/src/minter.canister.ts index ddf2c6ce9..178e5c19d 100644 --- a/packages/ckbtc/src/minter.canister.ts +++ b/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 { 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 => + 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. *