Refactor API and clean up house by luisschwab · Pull Request #157 · bitcoindevkit/rust-esplora-client

luisschwab · 2026-01-07T15:36:51Z

Closes #142.
Closes #146.
Closes #148.
Closes #150.

This PR does a bunch of cleanup, standardizes and adds missing documentation, fixes inconsistencies and redundancies in the API, and uses rust-bitcoin types where possible.

Changelog

# Added
- Add `impl From<EsploraTx> to Transaction` and `impl From<&EsploraTx> to Transaction`
- Add `sat_per_vbyte_to_feerate` utility function in `api.rs`
- Add `get_block_infos` (returns `Vec<BlockInfo>`)

# Breaking
- Rename `scripthash_txs` to `get_scripthash_txs`
- Remove `PrevOut` in favor of reusing `Vout`
- Rename `Tx` to `EsploraTx`
- Remove `EsploraTx::fee()` method (use `EsploraTx.fee` instead)
- Remove `EsploraTx::weight()` method (use `Esplora.weight` instead)
- Change `get_fee_estimates` to return `HashMap<u16, FeeRate>` instead of `HashMap<u16, f64>`
- Change `convert_fee_rate` to accept `HashMap<u16, FeeRate>` and return `Option<FeeRate>` instead of `Option<f32>`
- Change `submit_package` `maxfeerate` parameter from `Option<f64>` to `Option<FeeRate>`
- Change `submit_package` `maxburnamount` parameter from `Option<f64>` to `Option<Amount>`
- Change all bitcoin amount fields from `u64` to `Amount`
- Change all weight fields from `u64` to `Weight`

# Changed
- Deprecate `BlockSummary` and `get_blocks` (to be removed on v0.14.0)
- Replace `std::` with `core::` where applicable
- Reorder API structs into logical groups: transaction, block, address, script hash, UTXO, mempool
- Reorder client methods into logical groups: transaction, block, address, script hash, mempool
- Improve documentation for `api.rs`, `async.rs`, `blocking.rs`, and `lib.rs`
- Update copyright notice to `2020-2026`

coveralls · 2026-01-07T15:39:43Z

Pull Request Test Coverage Report for Build 22006096792

Details

21 of 22 (95.45%) changed or added relevant lines in 4 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.007%) to 87.257%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/api.rs	1	2	50.0%

Totals
Change from base Build 22002487177:	0.007%
Covered Lines:	1438
Relevant Lines:	1648

💛 - Coveralls

oleonardolima

cACK dbbe555

oleonardolima

utACK eccf30d

I'm also wondering on how disruptive it'll be on downstream, see VM's comment, though it'll be in a major release.

luisschwab · 2026-01-23T15:09:24Z

Makes sense. We can remove the deprecated function on v14.

oleonardolima

utACK 530ebea

luisschwab · 2026-03-05T14:28:46Z

I'll rebase this one since we decided to deprecate get_blocks instead of removing it outright.

Removes `BlockSummary`, as it omitted information returned by Esplora. This removes `get_blocks` and adds `get_block_infos` (`get_blocks` was deprecated in v0.12.3).

The `PrevOut` struct is identical to `Vout`.

luisschwab · 2026-04-01T23:19:06Z

Pushed 8337a89 completing the work. It's a big one, but mostly documentation and moving things around.

yan-pi

tACK 8337a89

…tcoin amount

…k/tx weight

This commit: - Renames `Tx` to `EsploraTx`: more explicit. `Tx` is not precise about what it is. - Remove `EsploraTx::fee`, since the field is already public. - Implements `From<EsploraTx>`/`From<&EsploraTx>` to `Transaction` conversions. - Reorders structs into logical groups: Transaction, Block, Address, ScriptHash, UTXO, and Mempool. - Improves documentation. - Updates copyright notice to `2020-2026`.

This commit: - Reorders methods into logical groups: transaction, block, address, script hash, and mempool. - Improves documentation throughout: clearer summaries, consistent style, and proper intra-doc links. - Moves `Sleeper`, `DefaultSleeper`, and `is_status_retryable` to the top of the file for better readability. - Updates return types from `Tx` to `EsploraTx` following the rename. - Removes unused `log` imports. - Updates copyright notice to `2020-2026`.

This commit: - Changes `get_fee_estimates` to return `HashMap<u16, FeeRate>` instead of `HashMap<u16, f64>`. - Changes `convert_fee_rate` to accept `HashMap<u16, FeeRate>` and return `Option<FeeRate>` instead of `Option<f32>`. - Adds `sat_per_vbyte_to_feerate` to `api.rs` to convert the raw `f64` sat/vbyte values returned by the Esplora API into `FeeRate`. - Updates the `feerate_parsing` test accordingly.

This commit: - Rewrites crate-level docs: - Cleaner structure - Usage examples for async and blocking clients - Feature table instead of a bullet list - Improves `Builder` documentation - Improves `Error` documentation - Replaces `std::` with `core::` where applicable - Updates copyright notice to `2020-2026`

…_package`

Re-add with a deprecation warning. These should be removed for the v0.14.0 release.

Only casting to `u64` would always round down. Rounding (`.round()`) and then casting to `u64` is more precise. Also updates the fee JSON on `test_feerate_parsing` with current values which include sub-1 sat fees: ``` curl https://mempool.space/api/fee-estimates | jq 'to_entries | sort_by(.key | tonumber) | from_entries' ```

yan-pi

tACK df3b306

ValuedMammal · 2026-04-16T18:32:54Z

I suggest reserving the "chore" label for tasks related to repo maintenance, not API or behavior changes. And changing the commits to refactor(api)!: ... or something. I bring it up because as a reviewer I look to the commit message to see at a glance the type and scope of the changes. chore doesn't really describe what amounts to a complete API overhaul.

luisschwab requested a review from oleonardolima January 7, 2026 15:37

luisschwab force-pushed the chore/api-fixups branch from 1872024 to dbbe555 Compare January 7, 2026 15:37

luisschwab changed the title ~~chore(api): remove BlockSummary and PrevOut, rename scripthash_txs to get_scripthash_txs~~ chore(api)!: remove BlockSummary and PrevOut, rename scripthash_txs to get_scripthash_txs Jan 7, 2026

oleonardolima reviewed Jan 7, 2026

View reviewed changes

oleonardolima assigned luisschwab Jan 7, 2026

oleonardolima added this to BDK Chain Jan 7, 2026

oleonardolima moved this to In Progress in BDK Chain Jan 7, 2026

luisschwab marked this pull request as ready for review January 20, 2026 20:11

luisschwab requested review from ValuedMammal and oleonardolima January 20, 2026 20:11

oleonardolima reviewed Jan 20, 2026

View reviewed changes

luisschwab force-pushed the chore/api-fixups branch from eccf30d to 530ebea Compare February 13, 2026 23:14

luisschwab requested a review from oleonardolima February 13, 2026 23:31

oleonardolima reviewed Feb 14, 2026

View reviewed changes

luisschwab changed the title ~~chore(api)!: remove BlockSummary and PrevOut, rename scripthash_txs to get_scripthash_txs~~ Refactor API structs Feb 14, 2026

luisschwab changed the title ~~Refactor API structs~~ Refactor API Feb 18, 2026

luisschwab mentioned this pull request Feb 19, 2026

chore(release): esplora-client v0.13.0 #156

Open

13 tasks

luisschwab mentioned this pull request Mar 5, 2026

feat!: get_blocks now returns BlockInfo instead of BlockSummary #175

Closed

oleonardolima self-requested a review March 5, 2026 15:55

oleonardolima added enhancement New feature or request api A breaking API change labels Mar 5, 2026

luisschwab added 2 commits April 1, 2026 15:12

chore(api)!: remove BlockSummary in favor of BlockInfo

13734cc

Removes `BlockSummary`, as it omitted information returned by Esplora. This removes `get_blocks` and adds `get_block_infos` (`get_blocks` was deprecated in v0.12.3).

chore(api)!: remove PrevOut in favor of Vout

4089ab8

The `PrevOut` struct is identical to `Vout`.

luisschwab force-pushed the chore/api-fixups branch from 530ebea to 35c42b7 Compare April 1, 2026 23:02

luisschwab changed the title ~~Refactor API~~ Refactor API and clean up house Apr 1, 2026

luisschwab force-pushed the chore/api-fixups branch 2 times, most recently from f2a2a16 to 8337a89 Compare April 1, 2026 23:10

luisschwab requested review from oleonardolima and removed request for oleonardolima April 1, 2026 23:14

luisschwab requested a review from notmandatory April 2, 2026 16:40

yan-pi reviewed Apr 9, 2026

View reviewed changes

Comment thread src/lib.rs Outdated

yan-pi approved these changes Apr 9, 2026

View reviewed changes

Comment thread src/async.rs

Comment thread src/api.rs Outdated

luisschwab force-pushed the chore/api-fixups branch from 8337a89 to ab5ea70 Compare April 10, 2026 14:56

luisschwab added 8 commits April 10, 2026 11:57

chore(api)!: rename scripthash_txs to get_scripthash_txs

4e650e4

chore(api)!: use bitcoin::Amount for all fields that represent a bi…

36eb9ce

…tcoin amount

chore(api)!: use bitcoin::Weight for all fields that represent bloc…

e725cf0

…k/tx weight

fix(client)!: use Amount and FeeRate instead of f64 for `submit…

fe686f0

…_package`

luisschwab force-pushed the chore/api-fixups branch from ab5ea70 to fe686f0 Compare April 10, 2026 14:57

fix: re-add BlockSummary and get_blocks

f6a114b

Re-add with a deprecation warning. These should be removed for the v0.14.0 release.

luisschwab requested a review from yan-pi April 10, 2026 15:23

luisschwab added documentation Improvements or additions to documentation chore labels Apr 10, 2026

yan-pi reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor API and clean up house#157

Refactor API and clean up house#157
luisschwab wants to merge 12 commits intobitcoindevkit:masterfrom
luisschwab:chore/api-fixups

luisschwab commented Jan 7, 2026 •

edited

Loading

Uh oh!

coveralls commented Jan 7, 2026 •

edited

Loading

Uh oh!

oleonardolima left a comment

Uh oh!

oleonardolima left a comment

Uh oh!

luisschwab commented Jan 23, 2026

Uh oh!

oleonardolima left a comment

Uh oh!

luisschwab commented Mar 5, 2026

Uh oh!

luisschwab commented Apr 1, 2026

Uh oh!

Uh oh!

yan-pi left a comment

Uh oh!

Uh oh!

Uh oh!

yan-pi left a comment

Uh oh!

ValuedMammal commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

luisschwab commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Uh oh!

coveralls commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 22006096792

Details

💛 - Coveralls

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

luisschwab commented Jan 23, 2026

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

luisschwab commented Mar 5, 2026

Uh oh!

luisschwab commented Apr 1, 2026

Uh oh!

Uh oh!

yan-pi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yan-pi left a comment

Choose a reason for hiding this comment

Uh oh!

ValuedMammal commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

luisschwab commented Jan 7, 2026 •

edited

Loading

coveralls commented Jan 7, 2026 •

edited

Loading