Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

feat(bitcoin): add region markers to basic_bitcoin examples for stable developer workflow embeds

オープン
  • 何か問題がありますか？
#168 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
52/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
静か
技術スタック
rust
領域
documentation

調査の方向性

dfinity/examples にある一覧の Rust ファイルと、src/basic_bitcoin 配下の Motoko ファイルから始め、要求された領域と既存の workflow 関数を比較します。指定された実装に安定したマーカーを追加し、明示されている Motoko の UTXO 選択に関するリクエストに対応します。その後 bitcoin.mdx を確認し、Developer workflow がそれらの領域を参照できることを確認します。

索引モデルが issue の本文から書いたものです。

説明

enhancement

Background

docs/guides/chain-fusion/bitcoin.mdx has a Developer workflow section that lists 5 steps for building a Bitcoin send transaction. Step 3 (UTXO selection, fee estimation, transaction construction) is currently described with no code — the section says "see the examples." A developer recently searched for a UTXO selection algorithm and couldn't find it because the old portal docs that referenced it are gone.

The authoritative implementations already exist in the basic_bitcoin examples. The blocker is that the code is not annotated with stable named regions, so docs can't embed slices without fragile line-number references that break when files change.

This issue tracks the work needed on both sides: region annotations in the examples repo, and the docs expansion that follows.

What are region markers

Named anchor comments that mark stable, embeddable slices of code regardless of line numbers. Convention (mdBook-style, widely understood by tooling and scripts):

// ANCHOR: select-utxos-greedy
pub fn select_utxos_greedy(...) { ... }
// ANCHOR_END: select-utxos-greedy

// ANCHOR: get-utxos
public func get_utxos(...) { ... }
// ANCHOR_END: get-utxos

Scope: Rust basic_bitcoin

The 5-step workflow maps to these files and regions:

src/common.rs
Region name Content
select-utxos-greedy Greedy UTXO selection: iterate in reverse (oldest first), accumulate until sum >= amount + fee. General-purpose payment flow.
select-one-utxo Single-UTXO selection: find first UTXO that alone covers amount + fee. Required for Ordinals/Runes/BRC-20 where asset must be tied to specific satoshis.
get-fee-per-byte Query bitcoin_get_current_fee_percentiles, return 50th percentile; fall back to 2000 msat/vB on regtest.
build-transaction-with-fee Construct unsigned transaction from selected UTXOs, primary output (address or OP_RETURN), change output, dust threshold.
src/p2pkh.rs
Region name Content
build-transaction Iterative fee-size loop: start with fee=0, build + mock-sign, measure vsize, recalculate fee until stable. Calls select_utxos_greedy + build_transaction_with_fee.
sign-transaction P2PKH signing: compute SIGHASH_ALL per input, call sign_with_ecdsa, encode DER signature, set script_sig.
src/service/get_p2pkh_address.rs
Region name Content
get-p2pkh-address Whole function: derive ECDSA public key at BIP-44 path, convert to P2PKH address. Step 1 of the workflow.
src/service/get_utxos.rs
Region name Content
get-utxos Whole function: call bitcoin_get_utxos. Step 2 of the workflow. Pagination note is important (current implementation assumes all UTXOs fit in one response).
src/service/send_from_p2pkh_address.rs
Region name Content
send-end-to-end Full orchestration (steps 2–5): get UTXOs, get fee, build transaction, sign, submit, return txid. Best overview of the complete flow.

Scope: Motoko basic_bitcoin

src/basic_bitcoin/src/BitcoinApi.mo
Region name Content
get-utxos get_utxos function. Step 2 of the workflow.
get-current-fee-percentiles get_current_fee_percentiles function.
src/basic_bitcoin/src/P2pkh.mo
Region name Content
get-address get_address function. Step 1.
build-transaction build_transaction function: iterative fee-size loop using Bitcoin.buildTransaction from mo:bitcoin. Step 3.
sign-transaction sign_transaction function. Step 4.
send-end-to-end send function: full flow orchestration (steps 2–5).
Gap: Motoko has no explicit UTXO selection function

In Rust, select_utxos_greedy and select_one_utxo are explicit, documented, documentable functions. In Motoko, UTXO selection is delegated to Bitcoin.buildTransaction from mo:bitcoin, which handles it internally. This means:

  • There is no Motoko equivalent to show alongside the Rust algorithm
  • Developers reading the Motoko example cannot learn or adapt the selection strategy
  • The single-UTXO variant (for Ordinals/inscriptions) has no Motoko equivalent at all

Request: add an explicit selectUtxosGreedy (and optionally selectOneUtxo) function to the Motoko basic_bitcoin example, parallel to the Rust implementation in common.rs. This would be called before Bitcoin.buildTransaction rather than relying on the library's internal selection.

Docs follow-up (this repo)

Once region markers exist in the examples, we can:

  1. Expand ### Developer workflow in bitcoin.mdx to inline the UTXO selection step (both variants) for both languages, directly from the examples source.
  2. Optionally inline the other steps (address generation, UTXOs, fee estimation, signing, submission) with stable embeds rather than links to line numbers that drift.
  3. This requires either a custom Astro/rehype plugin for region embedding, or a pre-build script that materializes the regions into the MDX source. That tooling decision is tracked separately.

The immediate value even without tooling: stable region names give docs maintainers a reliable copy target that doesn't break when surrounding code changes.

Files NOT needing regions for this workflow

  • src/runes.rs, src/ordinals.rs, src/brc20.rs — asset-specific flows, not part of the core workflow
  • src/p2wpkh.rs, src/p2tr.rs — alternative address types; share common.rs utilities but have their own signing logic. Worth separate region treatment once P2PKH is done.
  • src/ecdsa.rs, src/schnorr.rs — key derivation internals; documented elsewhere

Related

  • Closes the navigational gap from the retired https://docs.internetcomputer.org/current/developer-docs/integrations/bitcoin/ URL path
  • Refs: dfinity/examples — rust/basic_bitcoin/src/common.rs, motoko/basic_bitcoin/src/basic_bitcoin/src/P2pkh.mo
主要言語
JavaScript
スター
4
フォーク
5
平均マージ
21時間 49分
マージ済み PR（30日）
28

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

dfinity/developer-docs のほかの issue

dfinity/developer-docs の issue をすべて見る

似ている issue

JavaScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。