Skip to content

feat(bitcoin): Maestro data provider and first-class coin selection#10

Open
jinglescode wants to merge 6 commits into
mainfrom
feature/bitcoin-maestro-provider
Open

feat(bitcoin): Maestro data provider and first-class coin selection#10
jinglescode wants to merge 6 commits into
mainfrom
feature/bitcoin-maestro-provider

Conversation

@jinglescode

Copy link
Copy Markdown
Member

Milestone: standard headless wallet on Bitcoin

Closes the remaining gap for the Bitcoin headless wallet milestone: the wallet, coin selection, and signTransfer already existed in src/, but no concrete data provider did. This PR adds the Maestro provider and promotes coin selection to a first-class, tested module.

A1 — UTXO querying via Maestro

  • MaestroProvider (src/bitcoin/providers/maestro.ts) implements the existing IBitcoinProvider interface against Maestro's Esplora-compatible Bitcoin API: address info/UTXOs, per-tx unspent outputs (via /outspends), paginated tx history, tx status, sat/vB fee estimates (closest-target selection, testnet fallback), and raw-tx broadcast.
  • Uses the platform fetch — zero new runtime dependencies. Shared plumbing in src/bitcoin/providers/common.ts with a typed ProviderHttpError.

A2 — Coin selection on queried UTXOs

  • Extracted the largest-first selector into src/bitcoin/utils/coin-selection.ts and exported it (selectUtxosLargestFirst, DUST_THRESHOLD_P2WPKH). Behavior unchanged: BIP-141 vbyte fee model, 546-sat dust absorption. BitcoinHeadlessWallet.signTransfer now delegates to it.

A3 — Send transfer

  • The existing signTransfer flow (query → select → PSBT → sign → broadcast) runs end-to-end on the Maestro provider; covered by the existing wallet regression tests.

Tests & docs

  • 20 new provider tests (mocked HTTP) + 12 coin-selection tests; full suite green on this branch (231 tests, 19 suites), tsup CJS/ESM/DTS build passes.
  • README "Bitcoin Headless Wallet" section and bitcoin-milestone.md mapping acceptance criteria to code.

🤖 Generated with Claude Code

jinglescode and others added 3 commits July 6, 2026 19:56
Milestone: standard headless wallet on Bitcoin.

- MaestroProvider implements IBitcoinProvider against Maestro's
  Esplora-compatible Bitcoin API using platform fetch (no new deps):
  address info/UTXOs/txs, per-tx unspent outputs via outspends,
  tx status, sat/vB fee estimates with closest-target selection,
  and raw-tx broadcast.
- Extract largest-first coin selection from BitcoinHeadlessWallet
  into src/bitcoin/utils/coin-selection.ts and export it; behavior
  unchanged (BIP-141 vbyte model, 546-sat dust handling).
- Unit tests for provider (mocked HTTP) and coin selection.
- README Bitcoin section and bitcoin-milestone.md evidence doc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@Temasar1

Temasar1 commented Jul 13, 2026

Copy link
Copy Markdown
Member

✅ Bitcoin Provider Integration Demo

Tested using the new BlockstreamBitcoinProvider on Bitcoin Testnet.

> tsx bitcoin-run.ts

⚡  Bitcoin playground  [testnet]

────────────────────────────────────────────────────────────
Payment address : tb1qj6jl9g9c0j4qcwcxz4nn27c6rerz5xv30yprvs
Public key (hex): 02b628626f6dd36dabdd973a4e5d150c0b8b203a6f838ee2accaf9abe187fbaa11
────────────────────────────────────────────────────────────
Fetching balance…
  confirmed  : 0 sats
  unconfirmed: 5,000 sats
  total      : 5,000 sats
────────────────────────────────────────────────────────────
Fetching UTxOs…
  [0] 0b08ac6d03d87445060aed42451cec736c75fd1775511762e143e97b4670070a:1  5,000 sats  confirmed=false
────────────────────────────────────────────────────────────
Signing transfer (coin selection is automatic)…
  recipient : tb1qj6jl9g9c0j4qcwcxz4nn27c6rerz5xv30yprvs
  amount    : 4,000 sats
  ✓ Transaction submitted!
  txid: 007db8cdf25306f2d942c9367874a0e663f22a9b0ad80d8b62fed701df311ad4
────────────────────────────────────────────────────────────
Fetching tx history…
  [0] 0b08ac6d03d87445060aed42451cec736c75fd1775511762e143e97b4670070a  confirmed=false
  [1] 007db8cdf25306f2d942c9367874a0e663f22a9b0ad80d8b62fed701df311ad4  confirmed=false
────────────────────────────────────────────────────────────
✓ Done

https://mempool.space/testnet4/tx/007db8cdf25306f2d942c9367874a0e663f22a9b0ad80d8b62fed701df311ad4

Verified Functionality

  • ✅ Generated a Bitcoin testnet wallet from a mnemonic
  • ✅ Retrieved payment address and compressed public key
  • ✅ Queried wallet balance
  • ✅ Fetched available UTxOs using the @MeshJS/mesh-core provider package
  • ✅ Automatically performed coin selection
  • ✅ Built and signed a Bitcoin transaction
  • ✅ Successfully submitted the transaction to the Bitcoin testnet
  • ✅ Retrieved transaction history including the newly submitted transaction

This validates the end-to-end functionality of the new Bitcoin provider implementation, including read operations, transaction construction, signing, and broadcasting.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants