From 733893277aed4d7ac93eb205560e7048d81ad840 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 29 Apr 2026 22:41:00 +0200 Subject: [PATCH 1/2] docs(bitcoin): expand ckBTC CLI section into a step-by-step walkthrough Renamed the section from "Interact with ckBTC using icp-cli" to "Deposit, mint, and transfer (icp-cli)" to reflect what the section actually covers. Restructured into five numbered steps with explanatory prose between each command. Added a get_minter_info call in step 2 so readers can check min_confirmations (currently 6 on mainnet), kyt_fee, and retrieve_btc_min_amount before waiting. Clarified the update_balance response: a Minted record confirms success; Err(NoNewUtxos) with current_confirmations tells you where you stand if confirmations are not yet reached. Moved the RECIPIENT setup to inline prose before the transfer code block so the command block is a single clean operation. Added a note explaining that created_at_time = null skips deduplication and that production canister code should set this field to the current nanosecond timestamp. --- docs/guides/chain-fusion/bitcoin.mdx | 33 +++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/guides/chain-fusion/bitcoin.mdx b/docs/guides/chain-fusion/bitcoin.mdx index 0c00d185..ae9e4057 100644 --- a/docs/guides/chain-fusion/bitcoin.mdx +++ b/docs/guides/chain-fusion/bitcoin.mdx @@ -388,7 +388,9 @@ async fn withdraw(btc_address: String, amount: u64) -> RetrieveBtcResult { -### Interact with ckBTC using icp-cli +### Deposit, mint, and transfer (icp-cli) + +This walkthrough covers the full ckBTC deposit flow: getting a deposit address, checking the confirmation requirement, minting ckBTC, and transferring to another principal. First, export your principal from your active identity (every command below reuses it): @@ -396,7 +398,7 @@ First, export your principal from your active identity (every command below reus export MY_PRINCIPAL=$(icp identity principal) ``` -Get a deposit address: +**Step 1: Get a deposit address** ```bash icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_btc_address \ @@ -404,7 +406,21 @@ icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_btc_address \ -n ic ``` -Check for new deposits and mint ckBTC: +Send BTC to the returned address from any Bitcoin wallet. + +**Step 2: Check the confirmation requirement** + +The minter does not mint ckBTC until the depositing Bitcoin transaction reaches a minimum number of confirmations. Query the current threshold before waiting: + +```bash +icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_minter_info '()' -n ic +``` + +The response includes `min_confirmations` (how many Bitcoin confirmations are required before minting, currently 6 on mainnet), `kyt_fee` (the know-your-token check fee charged per deposit, in satoshis), and `retrieve_btc_min_amount` (the minimum withdrawal amount, currently 50,000 satoshis). + +**Step 3: Mint ckBTC** + +Once the Bitcoin transaction has the required confirmations, call `update_balance` to trigger minting: ```bash icp canister call mqygn-kiaaa-aaaar-qaadq-cai update_balance \ @@ -412,7 +428,9 @@ icp canister call mqygn-kiaaa-aaaar-qaadq-cai update_balance \ -n ic ``` -Check ckBTC balance (amount in satoshis): +A `Minted` record in the response confirms that ckBTC was credited to your account. If the response is `Err(NoNewUtxos { current_confirmations = opt N })`, the transaction exists but has not yet reached the required count. + +**Step 4: Check your balance** ```bash icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \ @@ -420,10 +438,11 @@ icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \ -n ic ``` -Transfer ckBTC (10 satoshi fee, amount in satoshis): +**Step 5: Transfer ckBTC** + +Set the recipient principal: `export RECIPIENT=""`. The 10 satoshi fee is charged in addition to the `amount`. ```bash -export RECIPIENT="" icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \ "(record { to = record { owner = principal \"$RECIPIENT\"; subaccount = null }; @@ -435,6 +454,8 @@ icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \ })" -n ic ``` +`created_at_time = null` skips deduplication: if you run this command twice, both transfers execute. In production canister code, set this field to the current nanosecond timestamp so that retried calls are rejected as duplicates rather than sending twice. + ### Common mistakes - **Not calling `update_balance` after a BTC deposit.** The minter does not auto-detect deposits. Your application must call `update_balance` to trigger minting. From 63661b51304c6bdc48fc71e78abd6fff853f6814 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 29 Apr 2026 22:46:02 +0200 Subject: [PATCH 2/2] fix(bitcoin): KYT = Know Your Transaction, link deduplication docs --- docs/guides/chain-fusion/bitcoin.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/chain-fusion/bitcoin.mdx b/docs/guides/chain-fusion/bitcoin.mdx index ae9e4057..fa9eeb6c 100644 --- a/docs/guides/chain-fusion/bitcoin.mdx +++ b/docs/guides/chain-fusion/bitcoin.mdx @@ -416,7 +416,7 @@ The minter does not mint ckBTC until the depositing Bitcoin transaction reaches icp canister call mqygn-kiaaa-aaaar-qaadq-cai get_minter_info '()' -n ic ``` -The response includes `min_confirmations` (how many Bitcoin confirmations are required before minting, currently 6 on mainnet), `kyt_fee` (the know-your-token check fee charged per deposit, in satoshis), and `retrieve_btc_min_amount` (the minimum withdrawal amount, currently 50,000 satoshis). +The response includes `min_confirmations` (how many Bitcoin confirmations are required before minting, currently 6 on mainnet), `kyt_fee` (the know-your-transaction check fee charged per deposit, in satoshis), and `retrieve_btc_min_amount` (the minimum withdrawal amount, currently 50,000 satoshis). **Step 3: Mint ckBTC** @@ -454,7 +454,7 @@ icp canister call mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \ })" -n ic ``` -`created_at_time = null` skips deduplication: if you run this command twice, both transfers execute. In production canister code, set this field to the current nanosecond timestamp so that retried calls are rejected as duplicates rather than sending twice. +`created_at_time = null` skips deduplication: if you run this command twice, both transfers execute. In production canister code, set this field to the current nanosecond timestamp so that retried calls are rejected as duplicates rather than sending twice. See [Transferring assets (ICRC-1)](../digital-assets/ledgers.md#transferring-assets-icrc-1) for details. ### Common mistakes