A library for interfacing with ckBTC on the Internet Computer.
You can use ckbtc-js by installing it in your project.
npm i @dfinity/ckbtcThe 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/utilsThe 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({});ckbtc-js implements following features:
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
- create
- getBtcAddress
- updateBalance
- getWithdrawalAccount
- retrieveBtc
- retrieveBtcWithApproval
- retrieveBtcStatus
- retrieveBtcStatusV2ByAccount
- estimateWithdrawalFee
- getMinterInfo
- getKnownUtxos
| Method | Type |
|---|---|
create |
(options: CkBTCMinterCanisterOptions<_SERVICE>) => CkBTCMinterCanister |
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, thecallerwill be use instead. -
params.subaccount: An optional subaccount to compute the address.
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, thecallerwill be use instead. -
params.subaccount: An optional subaccount of the address.
Returns the account to which the caller should deposit ckBTC before withdrawing BTC using the [retrieveBtc] endpoint.
| Method | Type |
|---|---|
getWithdrawalAccount |
() => Promise<Account> |
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.
Submits a request to convert ckBTC to BTC after making an ICRC-2 approval.
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.
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.
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
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.
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.
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
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, thecallerwould be used by the minter instead. -
params.subaccount: An optional subaccount.