@dfinity/ckbtc

ckbtc-js

A library for interfacing with ckBTC on the Internet Computer.

Table of contents

• Installation
• Usage
• Features

Installation

You can use ckbtc-js by installing it in your project.

npm i @dfinity/ckbtc

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils

Usage

The features are available through the class CkBTCMinterCanister. It has to be instantiated with a canister ID.

import { CkBTCMinterCanister } from "@dfinity/ckbtc";
import { createAgent } from "@dfinity/utils";

const agent = await createAgent({
  identity,
  host: HOST,
});

const { getBtcAddress } = CkBTCMinterCanister.create({
  agent,
  canisterId: MY_CKBTC_MINTER_CANISTER_ID,
});

const btcAddress = await getBtcAddress({});

Features

ckbtc-js implements following features:

:toolbox: Functions

• parseBtcAddress

:gear: parseBtcAddress

Parse a Bitcoin address.

Parse implementation follows strategy implemented in Minter canister.

Credits: Parts of JavaScript code and test values from bitcoin-address-validation.

Function	Type
parseBtcAddress	({ address, network, }: BtcAddress) => BtcAddressInfo

Parameters:

• params: The Bitcoin address and network to parse
• params.network: Optional. Default BtcNetwork is Mainnet

:link: Source

:factory: CkBTCMinterCanister

:link: Source

Methods

• create
• getBtcAddress
• updateBalance
• getWithdrawalAccount
• retrieveBtc
• retrieveBtcWithApproval
• retrieveBtcStatus
• retrieveBtcStatusV2ByAccount
• estimateWithdrawalFee
• getMinterInfo
• getKnownUtxos

:gear: create

Method	Type
create	(options: CkBTCMinterCanisterOptions<_SERVICE>) => CkBTCMinterCanister

:link: Source

:gear: getBtcAddress

Returns a BTC address for a given account.

Note: an update call is required by the Minter canister.

Method	Type
getBtcAddress	({ owner, subaccount, }: MinterParams) => Promise<string>

Parameters:

• params: The parameters for which a BTC address should be resolved.
• 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

:gear: updateBalance

Notify the minter about the bitcoin transfer.

Upon successful notification, new ckBTC should be available on the targeted address.

Method	Type
updateBalance	({ owner, subaccount, }: MinterParams) => Promise<UpdateBalanceOk>

Parameters:

• params: The parameters are the address to which bitcoin where transferred.
• 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

:gear: getWithdrawalAccount

Returns the account to which the caller should deposit ckBTC before withdrawing BTC using the [retrieveBtc] endpoint.

Method	Type
getWithdrawalAccount	() => Promise<Account>

:link: Source

:gear: retrieveBtc

Submits a request to convert ckBTC to BTC.

Note:

The BTC retrieval process is slow. Instead of synchronously waiting for a BTC transaction to settle, this method returns a request ([block_index]) that the caller can use to query the request status.

Preconditions:

The caller deposited the requested amount in ckBTC to the account that the [getWithdrawalAccount] endpoint returns.

Method	Type
retrieveBtc	(params: RetrieveBtcParams) => Promise<RetrieveBtcOk>

Parameters:

• params: The parameters are the bitcoin address and amount to convert.
• params.address: The bitcoin address.
• params.amount: The ckBTC amount.

:link: Source

:gear: retrieveBtcWithApproval

Submits a request to convert ckBTC to BTC after making an ICRC-2 approval.

Note

The BTC retrieval process is slow. Instead of synchronously waiting for a BTC transaction to settle, this method returns a request ([block_index]) that the caller can use to query the request status.

Preconditions

The caller allowed the minter's principal to spend its funds using [icrc2_approve] on the ckBTC ledger.

Method	Type
retrieveBtcWithApproval	({ address, amount, fromSubaccount, }: { address: string; amount: bigint; fromSubaccount?: Uint8Array or undefined; }) => Promise<RetrieveBtcOk>

Parameters:

• params.address: The bitcoin address.
• params.amount: The ckBTC amount.
• params.fromSubaccount: An optional subaccount from which the ckBTC should be transferred.

:link: Source

: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

:gear: retrieveBtcStatusV2ByAccount

Returns the status of all BTC withdrawals for an account.

Method	Type
retrieveBtcStatusV2ByAccount	({ account, certified, }: RetrieveBtcStatusV2ByAccountParams) => Promise<RetrieveBtcStatusV2WithId[]>

Parameters:

• certified: query or update call
• account: an optional account to retrieve the statuses. If not provided, statuses for the caller are retrieved.

:link: Source

:gear: estimateWithdrawalFee

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.

Method	Type
estimateWithdrawalFee	({ certified, amount, }: EstimateWithdrawalFeeParams) => Promise<EstimateWithdrawalFee>

Parameters:

• params: The parameters to estimate the fee.
• params.certified: query or update call
• params.amount: The optional amount for which the fee should be estimated.

:link: Source

:gear: getMinterInfo

Returns internal minter parameters such as the minimal amount to retrieve BTC, minimal number of confirmations or KYT fee.

Method	Type
getMinterInfo	({ certified }: QueryParams) => Promise<MinterInfo>

Parameters:

• params: The parameters to get the minter info.
• params.certified: query or update call

:link: Source

:gear: getKnownUtxos

Returns UTXOs of the given account known by the minter.

Method	Type
getKnownUtxos	({ owner, subaccount, certified, }: GetKnownUtxosParams) => Promise<Utxo[]>

Parameters:

• params: The parameters for which the known utxos should be resolved.
• params.owner: The owner of the account. Note that if not provided, the caller would be used by the minter instead.
• params.subaccount: An optional subaccount.

:link: Source

Resources

• Bitcoin integration
• ckBTC Minter