docs(bitcoin): expand Direct Bitcoin API section#169
Merged
Conversation
Resolves #159. Substantial expansion of the Direct Bitcoin API section to cover the full developer workflow and common pitfalls.
marc0olo
added a commit
that referenced
this pull request
Apr 29, 2026
…API sections (#170) ## Summary ### CLI copy-paste UX The `### Interact with ckBTC using icp-cli` section previously had a single monolithic code block with `YOUR-PRINCIPAL` literals that required manual editing before every command. The section now: - Exports `MY_PRINCIPAL` from the active identity in one setup block (`icp identity get-principal`) so it never needs to be typed or edited. - Splits each operation into its own copy-paste block with `$MY_PRINCIPAL` interpolated via double-quote shell expansion. - The transfer command includes `export RECIPIENT="<paste-recipient-principal>"` at the top of the same block, keeping it a single copy-paste operation while making the placeholder explicit. ### Direct Bitcoin API section reordering Previous order mixed monitoring utilities in with core read operations and placed `### Blockchain info` immediately after `### Available endpoints`, before the developer's first instinct (`get_balance`, `get_utxos`). New order groups sections by purpose: | Before | After | |---|---| | Bitcoin API canister IDs | Bitcoin API canister IDs | | Available endpoints | Available endpoints | | **Blockchain info** | **Read Bitcoin balance** | | Read Bitcoin balance | **Read UTXOs** | | Read UTXOs | **Get fee percentiles** | | Get fee percentiles | **Blockchain info** | | Developer workflow | Developer workflow | | (UTXO selection as h4) | **UTXO selection (h3)** | | Common mistakes | Common mistakes | | Cycle costs | Cycle costs | `Blockchain info` is a monitoring/diagnostics call — it belongs after the core transaction-building reads, not before them. ### Developer workflow heading structure `#### UTXO selection` was the only h4 in the entire file, sitting as a lone child under `### Developer workflow`. This: - Created a structurally awkward section (a heading with a single subheading implies the parent section exists only to contain one thing). - Buried the UTXO selection anchor below the fold of the workflow section. The fix promotes `#### UTXO selection` to `### UTXO selection` as a sibling of `### Developer workflow`. The `### Developer workflow` section now closes with the working-example links (which cover the full flow, not just UTXO selection), and step 3 in the numbered list links directly to `#utxo-selection` for readers who want to jump there. ### Em-dash cleanup The previous PR (#169) introduced several em-dashes in new prose. All instances outside code blocks are replaced with colons, semicolons, or parentheses per the project's banned-terms rule. ## Sync recommendation Informed by `dfinity/examples` — no source changes, documentation improvements only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Resolves #159.
get_blockchain_infodocumented (fixes docs(bitcoin): document get_blockchain_info endpoint in bitcoin guide #159): new### Blockchain infosection with a response field table, Motoko and Rust tabs, cycle cost row in the existing table, and a link to the Rust example. IncludesCargo.tomlsnippet foric-cdk-bitcoin-canister = "0.2".### Read UTXOssection added: Motoko and Rust tabs showingbitcoin_get_utxoswith a pagination note explaining how to follownext_page.### Get fee percentilessection added: Motoko and Rust tabs, fallback for regtest (empty response), andMillisatoshiPerBytetype note.### Developer workflowsection added: numbered end-to-end steps (address generation → UTXOs → fee → build → sign → submit) plus a#### UTXO selectionsubsection covering greedy (standard payments) and single-UTXO (Ordinals/Runes/BRC-20) strategies with working Motoko and Rust implementations.### Common mistakessection added: five actionable items — UTXO pagination, immature/unconfirmed UTXOs, missing iterative fee calculation, dust change outputs, and concurrent UTXO spending.### Available endpointsexpanded: added threshold signature methods and a forward-reference to cycle costs.### Bitcoin API canister IDssection added: table with mainnet and testnet/regtest canister IDs, extracted from the inline text.Bug fixes (caught in review)
label loop→label donein Motoko UTXO selection:loopis a reserved keyword and would have caused a compile error.UtxosFilterInRequest::Page→UtxosFilter::Pagein two prose locations: the type does not exist;UtxosFilter(fromic_cdk_bitcoin_canister) is correct.#[update]+use ic_cdk::update;→#[ic_cdk::update]in the blockchain info Rust tab: matches the style used in every other Rust tab.get_network().into()→get_network()in the UTXOs Rust tab:get_network()already returnsNetwork; the.into()was a no-op.Relation to issue #168
Issue #168 tracks adding mdBook region markers to the
basic_bitcoinexample source files so that docs can embed stable, line-number-independent code snippets directly from the examples repo. Until those markers land, the UTXO selection code in### Developer workflowis written inline in the docs (adapted fromcommon.rs). Once #168 is resolved, these snippets can be replaced with direct region embeds pointing at the upstream source — no content change required, only the embed syntax.Sync recommendation
Informed by
dfinity/examples—rust/basic_bitcoin/src/common.rs,rust/basic_bitcoin/src/service/get_utxos.rs,rust/basic_bitcoin/src/service/get_blockchain_info.rs,rust/basic_bitcoin/basic_bitcoin.did,motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo;dfinity/cdk-rs—ic-cdk-bitcoin-canister 0.2;dfinity/icskills—skills/ckbtc/SKILL.md