@dfinity/ckbtc v3.1.2
ckbtc-js
A library for interfacing with ckBTC on the Internet Computer.
Table of contents
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
: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 parseparams.network
: Optional. Default BtcNetwork is Mainnet
:factory: CkBTCMinterCanister
Methods
- create
- getBtcAddress
- updateBalance
- getWithdrawalAccount
- retrieveBtc
- retrieveBtcWithApproval
- retrieveBtcStatus
- retrieveBtcStatusV2ByAccount
- estimateWithdrawalFee
- getMinterInfo
- getKnownUtxos
:gear: create
Method | Type |
---|---|
create | (options: CkBTCCanisterOptions<_SERVICE>) => CkBTCMinterCanister |
: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, thecaller
will be use instead.params.subaccount
: An optional subaccount to compute the address.
: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, thecaller
will be use instead.params.subaccount
: An optional subaccount of the address.
:gear: getWithdrawalAccount
Returns the account to which the caller should deposit ckBTC before withdrawing BTC using the retrieveBtc endpoint.
Method | Type |
---|---|
getWithdrawalAccount | () => Promise<Account> |
: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.
: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.
: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
: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 callaccount
: an optional account to retrieve the statuses. If not provided, statuses for the caller are retrieved.
: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 callparams.amount
: The optional amount for which the fee should be estimated.
: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
: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, thecaller
would be used by the minter instead.params.subaccount
: An optional subaccount.
:factory: BitcoinCanister
Methods
:gear: create
Method | Type |
---|---|
create | (options: CkBTCCanisterOptions<_SERVICE>) => BitcoinCanister |
:gear: getUtxosQuery
Given a get_utxos_request
, which must specify a Bitcoin address and a Bitcoin network (mainnet
, testnet
or regtest
), 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.
⚠️ 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.
:gear: getBalanceQuery
Given a get_balance_request
, which must specify a Bitcoin address and a Bitcoin network (mainnet
, testnet
or regtest
), the function returns the current balance of this address in Satoshi
(10^8 Satoshi = 1 Bitcoin) in the specified Bitcoin network.
⚠️ 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 thebitcoin_get_utxos
call.params.address
: A Bitcoin address.
Resources
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
6 months ago
7 months ago
4 months ago
5 months ago
5 months ago
4 months ago
5 months ago
4 months ago
4 months ago
7 months ago
7 months ago
4 months ago
4 months ago
4 months ago
4 months ago
7 months ago
6 months ago
7 months ago
7 months ago
7 months ago
5 months ago
7 months ago
7 months ago
6 months ago
6 months ago
7 months ago
7 months ago
4 months ago
6 months ago
4 months ago
6 months ago
6 months ago
6 months ago
7 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
5 months ago
5 months ago
6 months ago
6 months ago
5 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago