docs: Bitcoin integration guide

[marc0olo]

Summary

• Two-approach structure: ckBTC (recommended) and Direct Bitcoin API (advanced)
• ckBTC integration: deposit flow, transfers, withdrawals with Motoko/Rust tabbed code examples
• CLI examples for interacting with ckBTC canisters
• Common mistakes section (6 pitfalls)
• Direct Bitcoin API: available endpoints, get_blockchain_info example using the new ic-cdk-bitcoin-canister crate
• Cycle costs table including per-byte costs for bitcoin_send_transaction (8M/20M cycles per byte)
• Development setup: bitcoin-starter template, local regtest with Docker, multi-environment icp.yaml
• Deploy to testnet and mainnet

Sync recommendation

Informed by dfinity/portal — docs/build-on-btc/*, docs/references/bitcoin-how-it-works.mdx, docs/references/cycles-cost-formulas.mdx; dfinity/icskills — skills/ckbtc/SKILL.md; dfinity/icp-cli-templates — bitcoin-starter/; dfinity/cdk-rs — ic-cdk-bitcoin-canister 0.2

[marc0olo]

Review: Bitcoin integration guide

Must fix

• --template flag doesn't exist for icp new (line 597): Uses icp new my-bitcoin-app --template bitcoin-starter. The correct flag is --subfolder: icp new my-bitcoin-app --subfolder bitcoin-starter. Verified against .sources/icp-cli/docs/reference/cli.md.
• --env flag doesn't exist for icp deploy (lines 688-695): Uses --env staging and --env production. The correct flag is -e / --environment: icp deploy -e staging and icp deploy -e production.
• -e ic wrong for canister calls by principal ID (lines 394-420): Uses -e ic for direct canister calls like icp canister call mxzaz-hqaaa-aaaar-qaada-cai .... The -e flag refers to --environment which expects an environment name from icp.yaml. When calling canisters by principal ID (not by name), the correct flag is -n ic (--network ic).

Suggestions

• Content brief gap — missing threshold signing details: The brief asks for the full signing workflow (generating addresses, creating transactions, signing with chain-key, submitting). The page defers transaction construction/signing/submission to external examples (>30 lines rule). Showing the sign_with_ecdsa / sign_with_schnorr call signature inline (~10 lines) would help developers understand the API shape.
• Missing ckBTC Checker canister from the table: The ckBTC skill lists a "ckBTC Checker" canister (oltsj-fqaaa-aaaar-qal5q-cai) for mainnet. It's omitted from the canister ID table. This canister validates BTC addresses and is part of the production ckBTC flow.
• Regtest cycle cost discrepancy: CDK source shows regtest uses mainnet costs for bitcoin_get_balance (100,000,000), but the page's cycle cost table groups "Testnet / Regtest" together implying they share the same (lower) costs. Consider verifying all cost rows.
• Motoko <system> capability (line 484): private func getNetwork<system>() : Network uses the <system> capability for Runtime.envVar. Readers unfamiliar with this pattern may be confused. A brief inline comment explaining why <system> is needed would help.
• Missing prerequisites section: Before jumping into ckBTC integration, noting that readers need familiarity with ICRC-1/ICRC-2 token standards, or linking to the token standards reference page, would help orient newcomers.
• Bitcoin API canister ID table (line 441): The table suggests these are canisters you call directly, but bitcoin_get_balance etc. are management canister methods routed via the Bitcoin canister. The CDK handles routing automatically. This could confuse advanced developers.

Verified

• All internal links resolve: chain-fusion.md, chain-key-cryptography.md, chain-key-tokens.md, ethereum.md, management-canister.md
• External example links verified: basic_bitcoin exists in both .sources/examples/motoko/ and .sources/examples/rust/
• Bitcoin-starter template exists at .sources/icp-cli-templates/bitcoin-starter/ with matching icp.yaml
• ckBTC canister IDs match skill: Ledger (mxzaz-...), Minter (mqygn-...), Index (n5wcd-...)
• Bitcoin canister IDs match CDK source: Mainnet ghsi2-tqaaa-aaaan-aaaca-cai, testnet/regtest g4xu7-jiaaa-aaaan-aaaaq-cai
• Cycle costs match CDK constants (with regtest caveat noted above)
• Rust CDK API patterns correct: Call::unbounded_wait, .with_arg(), .candid_tuple(), ic_cdk::api::msg_caller(), ic_cdk::api::canister_self()
• Motoko syntax verified: persistent actor, transient let, (with cycles = ...), Runtime.envVar, Runtime.trap, Principal.isAnonymous, Principal.fromActor
• No dfx references — uses icp/icp-cli exclusively
• Old .md stub deleted, .mdx format correct with proper imports
• Tab order correct (Motoko first), syncKey="lang", no headings in TabItem
• Upstream comment present listing portal, icskills, and icp-cli-templates
• Frontmatter complete
• Build passes
• Diataxis how-to compliance confirmed

[marc0olo]

cdk-rs was bumped to b8dab03. One optional addition to consider:

• New get_blockchain_info API (ic-cdk-bitcoin-canister v0.2.0, #702): the ic_cdk::bitcoin_canister module now exposes get_blockchain_info() to query the current state of the Bitcoin blockchain (height, chain tip, etc.). The PR already covers the core Bitcoin integration APIs — this is an additive method worth mentioning if the guide has a section on querying blockchain state.

No breaking changes. Please review before merging.

[marc0olo]

Feedback addressed:

• Fixed --template → --subfolder for icp new (verified from icp-cli source)
• Fixed --env → -e/--environment for icp deploy (verified from icp-cli source)
• Fixed -e ic → -n ic for direct canister calls by principal ID (verified from icp-cli source)
• Added ckBTC Checker canister (oltsj-fqaaa-aaaar-qal5q-cai) to canister ID table
• Added <system> capability comment to Motoko getNetwork function
• Added note on new get_blockchain_info() API from cdk-rs bump

[marc0olo]

Feedback addressed:

• Updated Rust imports from ic_cdk::bitcoin_canister to ic_cdk_bitcoin_canister (new dedicated ic-cdk-bitcoin-canister = "0.2" crate)
• Replaced commented-out get_blockchain_info stub with a working example using the new crate, including Cargo.toml dependency note
• Expanded cycle costs table to show bitcoin_send_transaction per-byte costs (8M/20M cycles per byte for testnet/mainnet)
• Fixed ckBTC skill link to point directly to the skill page
• Added inline comment explaining amount + Nat::from(10u64) in Rust withdraw function (covers ICRC-2 transfer fee)
• Updated Upstream comment to include dfinity/cdk-rs and portal cost reference pages