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

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

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`
- Pin `hyper-rustls` to v0.27.7 for MSRV

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).

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`.

luisschwab · 2026-04-18T18:49:44Z

@ValuedMammal rebased changing the commit messages and pinning hyper-rustls to fix MSRV

ValuedMammal · 2026-04-18T19:37:45Z

We need to fix the feerate conversion bug and the get_script_hash naming inconsistency. Besides that, I haven't done a thorough review.

luisschwab · 2026-04-18T20:02:38Z

the get_script_hash naming inconsistency

Oh this got lost on the last rebase

the feerate conversion bug

Right. I mixed it up with the deserialize_feerate below.

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. fix(api): use `.round()` on `sat_per_vbyte_to_feerate` 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' ```

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`

…ubmit_package`

Add `BlockSummary` and `get_blocks` with a deprecation warning. These should be removed for the v0.14.0 release.

luisschwab · 2026-04-25T15:46:29Z

I've opened a draft PR on bdk using this branch: bitcoindevkit/bdk#2189

cc @ValuedMammal

oleonardolima

I was trying to review commit-by-commit, but it's quite hard. There's multiple commits changing the same code multiple times, and some commits are mixing different scopes.

I'd suggest splitting strictly into feat, fix, refactor and docs and keep them to scope. As there's a lot LoC changed it'll make it easier and even could be splitted into smaller PRs.

oleonardolima · 2026-04-27T14:56:28Z

@@ -256,6 +260,7 @@ pub struct Utxo {
    /// The confirmation status of the [`TxOut`].
    pub status: UtxoStatus,
    /// The value of the [`TxOut`] as an [`Amount`].


nit: in order to keep the same style.

Suggested change

/// The value of the [`TxOut`] as an [`Amount`].

/// The value of the [`TxOut`], in satoshis.

luisschwab · 2026-04-27T15:35:37Z

@oleonardolima I'll make this PR a draft for reference and break it up into smaller PRs.

oleonardolima · 2026-04-27T22:04:23Z

@oleonardolima I'll make this PR a draft for reference and break it up into smaller PRs.

Awesome, thanks!

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

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).

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 removed the request for review from oleonardolima April 1, 2026 23:14

luisschwab force-pushed the chore/api-fixups branch from df3b306 to 754558c Compare April 17, 2026 14:50

luisschwab added 4 commits April 17, 2026 12:00

refactor(api)!: use bitcoin::Amount for all bitcoin amount fields

913774f

refactor(api)!: use bitcoin::Weight for all block/tx fields

a03bd4e

luisschwab force-pushed the chore/api-fixups branch from 754558c to 9a97e86 Compare April 17, 2026 15:01

luisschwab requested review from ValuedMammal and yan-pi and removed request for ValuedMammal and yan-pi April 17, 2026 15:02

luisschwab added 6 commits April 18, 2026 17:22

refactor(client)!: use Amount and FeeRate instead of f64 for `s…

224cb65

…ubmit_package`

fix(api)!: re-add BlockSummary and get_blocks

4db8311

Add `BlockSummary` and `get_blocks` with a deprecation warning. These should be removed for the v0.14.0 release.

fix: pin hyper-rustls to v0.27.7 for MSRV

3cf07f3

fix(client)!: rename get_script_hash_txs to get_scripthash_txs

39bf961

luisschwab force-pushed the chore/api-fixups branch from 9a97e86 to 39bf961 Compare April 18, 2026 20:23

luisschwab moved this from In Progress to Needs Review in BDK Chain Apr 20, 2026

notmandatory removed the chore label Apr 22, 2026

luisschwab mentioned this pull request Apr 22, 2026

Relicense to this crate to dual MIT OR Apache-2.0 #179

Closed

27 tasks

luisschwab mentioned this pull request Apr 25, 2026

Bump esplora-client to v0.13.0 bitcoindevkit/bdk#2189

Draft

oleonardolima reviewed Apr 27, 2026

View reviewed changes

luisschwab marked this pull request as draft April 27, 2026 15:35

	/// The value of the [`TxOut`] as an [`Amount`].
	/// The value of the [`TxOut`], in satoshis.

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 18, 2026

Uh oh!

ValuedMammal commented Apr 18, 2026

Uh oh!

luisschwab commented Apr 18, 2026

Uh oh!

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

Uh oh!

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

oleonardolima Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

luisschwab commented Apr 27, 2026

Uh oh!

oleonardolima commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

luisschwab commented Jan 7, 2026 •

edited

Loading

coveralls commented Jan 7, 2026 •

edited

Loading

luisschwab commented Apr 25, 2026 •

edited

Loading