ckbtc

What this skill does

# Chain-Key Bitcoin (ckBTC) Integration

## What This Is

ckBTC is a 1:1 BTC-backed token native to the Internet Computer. No bridges, no wrapping, no third-party custodians. The ckBTC minter canister holds real BTC and mints/burns ckBTC tokens. Transfers settle in 1-2 seconds with a 10 satoshi fee (versus minutes and thousands of satoshis on Bitcoin L1).

## Prerequisites

- For Motoko: `mops` package manager, `core = "2.0.0"` in mops.toml
- For Rust: `ic-cdk`, `icrc-ledger-types`, `candid`, `serde`

## Canister IDs

### Bitcoin Mainnet

| Canister | ID |
|---|---|
| ckBTC Ledger | `mxzaz-hqaaa-aaaar-qaada-cai` |
| ckBTC Minter | `mqygn-kiaaa-aaaar-qaadq-cai` |
| ckBTC Index | `n5wcd-faaaa-aaaar-qaaea-cai` |
| ckBTC Checker | `oltsj-fqaaa-aaaar-qal5q-cai` |

### Bitcoin Testnet4

| Canister | ID |
|---|---|
| ckBTC Ledger | `mc6ru-gyaaa-aaaar-qaaaq-cai` |
| ckBTC Minter | `ml52i-qqaaa-aaaar-qaaba-cai` |
| ckBTC Index | `mm444-5iaaa-aaaar-qaabq-cai` |

## How It Works

### Deposit Flow (BTC -> ckBTC)

1. Call `get_btc_address` on the minter with the user's principal + subaccount. This returns a unique Bitcoin address controlled by the minter.
2. User sends BTC to that address using any Bitcoin wallet.
3. Wait for Bitcoin confirmations (the minter requires confirmations before minting).
4. Call `update_balance` on the minter with the same principal + subaccount. The minter checks for new UTXOs and mints equivalent ckBTC to the user's ICRC-1 account.

### Transfer Flow (ckBTC -> ckBTC)

Call `icrc1_transfer` on the ckBTC ledger. Fee is 10 satoshis. Settles in 1-2 seconds.

### Withdrawal Flow (ckBTC -> BTC)

1. Call `icrc2_approve` on the ckBTC ledger to grant the minter canister an allowance to spend from your account.
2. Call `retrieve_btc_with_approval` on the minter with `{ address, amount, from_subaccount: null }`.
3. The minter uses the approval to burn the ckBTC and submits a Bitcoin transaction.
4. The BTC arrives at the destination address after Bitcoin confirmations.

### Subaccount Generation

Each user gets a unique deposit address derived from their principal + an optional 32-byte subaccount. To give each user a distinct deposit address within your canister, derive subaccounts from a user-specific identifier (their principal or a sequential ID).

## Mistakes That Break Your Build

1. **Using the wrong minter canister ID.** The minter ID is `mqygn-kiaaa-aaaar-qaadq-cai`. Do not confuse it with the ledger (`mxzaz-...`) or index (`n5wcd-...`).

2. **Forgetting the 10 satoshi transfer fee.** Every `icrc1_transfer` deducts 10 satoshis beyond the amount. If the user has exactly 1000 satoshis and you transfer 1000, it fails with `InsufficientFunds`. Transfer `balance - 10` instead.

3. **Not calling `update_balance` after a BTC deposit.** Sending BTC to the deposit address does nothing until you call `update_balance`. The minter does not auto-detect deposits. Your app must call this.

4. **Using Account Identifier instead of ICRC-1 Account.** ckBTC uses the ICRC-1 standard: `{ owner: Principal, subaccount: ?Blob }`. Do NOT use the legacy `AccountIdentifier` (hex string) from the ICP ledger.

5. **Subaccount must be exactly 32 bytes or null.** Passing a subaccount shorter or longer than 32 bytes causes a trap. Pad with leading zeros if deriving from a shorter value.

6. **Calling `retrieve_btc` with amount below the minimum.** The minter has a minimum withdrawal amount (currently 50,000 satoshis / 0.0005 BTC). Below this, you get `AmountTooLow`.

7. **Not checking the `retrieve_btc` response for errors.** The response is a variant: `Ok` contains `{ block_index }`, `Err` contains specific errors like `MalformedAddress`, `InsufficientFunds`, `TemporarilyUnavailable`. Always match both arms.

8. **Forgetting `owner` in `get_btc_address` args.** If you omit `owner`, Candid sub-typing assigns null, and the minter returns the deposit address of the caller (the canister) instead of the user.

## Implementation

### Motoko

#### mops.toml

```toml
[package]
name = "ckbtc-app"
version = "0.1.0"

[dependencies]
core = "2.0.0"
icrc2-types = "1.1.0"
```

#### icp.yaml

Your backend canister calls the ckBTC ledger and minter by principal directly — no local ckBTC canister deployment needed.

```yaml
canisters:
  - name: backend
    recipe:
      type: "@dfinity/[email protected]"
      configuration:
        main: src/backend/main.mo
```

#### src/backend/main.mo

```motoko
import Principal "mo:core/Principal";
import Blob "mo:core/Blob";
import Nat "mo:core/Nat";
import Nat8 "mo:core/Nat8";
import Nat64 "mo:core/Nat64";
import Array "mo:core/Array";
import Result "mo:core/Result";
import Error "mo:core/Error";
import Runtime "mo:core/Runtime";

persistent actor Self {

  // -- Types --

  type Account = {
    owner : Principal;
    subaccount : ?Blob;
  };

  type TransferArgs = {
    from_subaccount : ?Blob;
    to : Account;
    amount : Nat;
    fee : ?Nat;
    memo : ?Blob;
    created_at_time : ?Nat64;
  };

  type TransferResult = {
    #Ok : Nat; // block index
    #Err : TransferError;
  };

  type TransferError = {
    #BadFee : { expected_fee : Nat };
    #BadBurn : { min_burn_amount : Nat };
    #InsufficientFunds : { balance : Nat };
    #TooOld;
    #CreatedInFuture : { ledger_time : Nat64 };
    #Duplicate : { duplicate_of : Nat };
    #TemporarilyUnavailable;
    #GenericError : { error_code : Nat; message : Text };
  };

  type UpdateBalanceResult = {
    #Ok : [UtxoStatus];
    #Err : UpdateBalanceError;
  };

  type UtxoStatus = {
    #ValueTooSmall : Utxo;
    #Tainted : Utxo;
    #Checked : Utxo;
    #Minted : { block_index : Nat64; minted_amount : Nat64; utxo : Utxo };
  };

  type Utxo = {
    outpoint : { txid : Blob; vout : Nat32 };
    value : Nat64;
    height : Nat32;
  };

  type UpdateBalanceError = {
    #NoNewUtxos : {
      required_confirmations : Nat32;
      pending_utxos : ?[PendingUtxo];
      current_confirmations : ?Nat32;
    };
    #AlreadyProcessing;
    #TemporarilyUnavailable : Text;
    #GenericError : { error_code : Nat64; error_message : Text };
  };

  type PendingUtxo = {
    outpoint : { txid : Blob; vout : Nat32 };
    value : Nat64;
    confirmations : Nat32;
  };

  type ApproveArgs = {
    from_subaccount : ?Blob;
    spender : Account;
    amount : Nat;
    expected_allowance : ?Nat;
    expires_at : ?Nat64;
    fee : ?Nat;
    memo : ?Blob;
    created_at_time : ?Nat64;
  };

  type ApproveError = {
    #BadFee : { expected_fee : Nat };
    #InsufficientFunds : { balance : Nat };
    #AllowanceChanged : { current_allowance : Nat };
    #Expired : { ledger_time : Nat64 };
    #TooOld;
    #CreatedInFuture : { ledger_time : Nat64 };
    #Duplicate : { duplicate_of : Nat };
    #TemporarilyUnavailable;
    #GenericError : { error_code : Nat; message : Text };
  };

  type RetrieveBtcWithApprovalArgs = {
    address : Text;
    amount : Nat64;
    from_subaccount : ?Blob;
  };

  type RetrieveBtcResult = {
    #Ok : { block_index : Nat64 };
    #Err : RetrieveBtcError;
  };

  type RetrieveBtcError = {
    #MalformedAddress : Text;
    #AlreadyProcessing;
    #AmountTooLow : Nat64;
    #InsufficientFunds : { balance : Nat64 };
    #InsufficientAllowance : { allowance : Nat64 };
    #TemporarilyUnavailable : Text;
    #GenericError : { error_code : Nat64; error_message : Text };
  };

  // -- Remote canister references (mainnet) --

  transient let ckbtcLedger : actor {
    icrc1_transfer : shared (TransferArgs) -> async TransferResult;
    icrc1_balance_of : shared query (Account) -> async Nat;
    icrc1_fee : shared query () -> async Nat;
    icrc2_approve : shared (ApproveArgs) -> async { #Ok : Nat; #Err : ApproveError };
  } = actor "mxzaz-hqaaa-aaaar-qaada-cai";

  transient let ckbtcMinter : actor {
    get_btc_address : shared ({
      owner : ?Principal;
      subaccount : ?Blob;
    }) -> async Text;
    update_balance : shared ({
      owner : ?Principal;
      subaccount : ?Blob;
    }) -> async Upd