docs(bitcoin): expand ckBTC CLI section into a step-by-step walkthrough#171
Merged
Conversation
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.
marc0olo
added a commit
that referenced
this pull request
Apr 29, 2026
## Summary
Adds a dedicated `### Transaction deduplication` section to
`docs/guides/digital-assets/ledgers.mdx`, immediately after `### Fee
handling`.
Previously, deduplication was a single sentence at the end of `### Fee
handling`: "Always set `created_at_time` to enable deduplication.
Without it, two identical transfers submitted within 24 hours both
execute." Fee handling and deduplication are separate concerns, and a
developer scanning the page for deduplication guidance would not find it
there.
The new section covers:
- **What it does**: the ledger tracks `(args, created_at_time)` pairs
and rejects exact duplicates within 24 hours with `Duplicate {
duplicate_of: block_index }`. The `duplicate_of` field lets you confirm
the original succeeded without re-submitting.
- **How to enable it**: references the existing `sendTokens` (Motoko:
`Nat64.fromNat(Int.abs(Time.now()))`) and `send_tokens` (Rust:
`ic_cdk::api::time()`) examples already on the page — no redundant code
tabs needed.
- **Boundary errors**: `TooOld` (timestamp older than 24h, window no
longer tracked) and `CreatedInFuture { ledger_time }` (timestamp ahead
of ledger time, `ledger_time` field helps diagnose clock drift).
- **When `null` is acceptable**: one-off manual CLI calls where
double-submission is not a concern.
Also updates the `bitcoin.mdx` CLI note to link to
`#transaction-deduplication` instead of the broader
`#transferring-assets-icrc-1` anchor.
## Related
- Surfaced while writing the ckBTC CLI walkthrough in PR #171
- Opened
[dfinity/icskills#178](dfinity/icskills#178)
to track updating the ckBTC skill's CLI examples
## Sync recommendation
Hand-written. Content is derived from the ICRC-1 specification
(`created_at_time` deduplication semantics) and verified against the
existing Motoko/Rust examples in this file.
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
Heading renamed from
### Interact with ckBTC using icp-clito### Deposit, mint, and transfer (icp-cli)— the old name described the tool, not the task. The section covers a full BTC deposit, ckBTC minting, and transfer flow.Five numbered steps with explanatory prose between each command, replacing the flat list of code blocks. Each step now tells the reader what they need to know before running the command, not just what the command does.
Step 2:
get_minter_infoadded beforeupdate_balance. The minter requires a minimum number of Bitcoin confirmations before minting (currently 6 on mainnet). Showing this call lets readers checkmin_confirmations,kyt_fee, andretrieve_btc_min_amountbefore waiting for confirmations, rather than discovering the requirement by getting aNoNewUtxoserror.update_balanceresponse explained: aMintedrecord confirms ckBTC was credited;Err(NoNewUtxos { current_confirmations = opt N })tells the reader exactly how many confirmations the transaction currently has, so they can see progress without guessing.Transfer command restructured:
export RECIPIENT=...is now shown as inline prose before the code block. Theicp canister callblock is a clean single operation, consistent with all other command blocks in the section.created_at_time = nullexplained: a sentence after the transfer block clarifies thatnullskips deduplication (running the command twice sends twice), and that production canister code should set this field to the current nanosecond timestamp. Links to Transferring assets (ICRC-1) where deduplication is documented.KYT terminology corrected: KYT stands for "Know Your Transaction", not "Know Your Token" — fixed in the
get_minter_inforesponse description.Correctness notes
min_confirmations = 6sourced from.sources/portal/docs/references/ckbtc-reference.mdxline 12.retrieve_btc_min_amount = 50,000 satoshissourced from the same file, line 10.kyt_feevalue is not hardcoded — it's governance-adjustable, so the prose describes the field rather than stating a value that could drift.update_balanceerror variant structure (NoNewUtxos { current_confirmations }) sourced from.sources/icskills/skills/ckbtc/SKILL.mdlines 177–186.Related
Opened dfinity/icskills#178 to track updating the ckBTC skill's CLI examples to recommend setting
created_at_timeinstead ofnull.Sync recommendation
Informed by
dfinity/icskills(skills/ckbtc/SKILL.md);dfinity/portal(docs/references/ckbtc-reference.mdx)