feat: implement missing methods

[luisschwab]

This PR implements the missing methods needed to be feature complete with the Esplora API specification, except for POST /txs/package.

Also adds Bitcoin Dev Kit Developers to authors on Cargo.toml.

Changelog

• Add OutputSpendStatus struct
• Add ScriptHashTxsSummary and ScriptHashStats structs
• Add BlockInformation struct
• Add MempoolStats struct
• Add MempoolRecentTxs struct
• Add InvalidStartIndexValue error variant
• Add get_tx_outspends method (GET /tx/:txid/outspends)
• Add get_scripthash_stats method (GET /scripthash/:hash)
• Add get_mempool_address_txs method (GET /address/:address/txs/mempool)
• Add get_mempool_scripthash_txs method (GET /scripthash/:hash/txs/mempool)
• Add get_scripthash_utxos method (GET /scripthash/:hash/utxo)
• Add get_block method (GET /block/:hash)
• Add get_block_txids method (GET /block/:hash/txids)
• Add get_block_txs method (GET /block/:hash/txs[/:start_index])
• Add get_mempool_stats method (GET /mempool)
• Add get_mempool_txids method (GET /mempool/txids)
• Add get_mempool_recent_txids method (GET /mempool/recent)

[coveralls]

Pull Request Test Coverage Report for Build 19713332546

Details

• 341 of 343 (99.42%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+3.3%) to 90.635%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/async.rs	51	52	98.08%
src/blocking.rs	50	51	98.04%

Totals
Change from base Build 19620365463:	3.3%
Covered Lines:	1384
Relevant Lines:	1527

---

💛 - Coveralls

[oleonardolima]

As it has a couple of commits, I'd check first if it is in the final state, ready for review ?

[oleonardolima]

FWIW, supersedes the methods from #127.

[luisschwab]

As it has a couple of commits, I'd check first if it is in the final state, ready for review ?

Yes, it's ready.

[ValuedMammal]

I'm about half way done reviewing this, will follow up soon with the rest.

[ValuedMammal]

• I verified that the endpoints exist and the types match the responses from esplora. Verified the code is the same for both async and blocking.
• I tested the new APIs on a fork of esplora-cli.
• I ran the tests locally

Additional thoughts:

• There's some cargo doc warnings due to unresolved rustdoc links
• We could eventually change or deprecate get_blocks which currently returns Vec<BlockSummary> to return a list of BlockInformation which is the more complete block summary.
• The tests feel a bit heavy. As a client library we should only care that the request succeeds and we can parse the response - not necessarily the values returned from the server. Also, since all of the tests share the same BITCOIND instance, some tests seem to rely on the output of other tests making it hard to run a single test in isolation (e.g. test_get_block_txs). This can make ongoing maintenance harder in the future.
• You could consider combining the mempool-related tests into one test and avoid having the "sleep 5 seconds" logic in multiple places.

[luisschwab]

There's some cargo doc warnings due to unresolved rustdoc links

I'll open a follow up PR that fixes these, adds all the missing documentation, adds #![warn(missing_docs)] to lib.rs and add cargo doc to CI.

You could consider combining the mempool-related tests into one test and avoid having the "sleep 5 seconds" logic in multiple places.

Indeed, this is a better approach

We could eventually change or deprecate get_blocks which currently returns Vec to return a list of BlockInformation which is the more complete block summary.

Yes, but we have to do it after the next release cc @oleonardolima

The tests feel a bit heavy. As a client library we should only care that the request succeeds and we can parse the response - not necessarily the values returned from the server. Also, since all of the tests share the same BITCOIND instance, some tests seem to rely on the output of other tests making it hard to run a single test in isolation (e.g. test_get_block_txs). This can make ongoing maintenance harder in the future.

I was trying to check if the start_index offset behavior was correct, but I agree this shouldn't be the client's concern. I'll cut back on that

[luisschwab]

@ValuedMammal rebased with your suggestions: tests now only focus on verifying that the returned value parses to the correct type, and condensed tests for the mempool methods into a single one.

[ValuedMammal]

Thanks I'll give it another review.

[ValuedMammal]

cargo doc is showing some unresolved links.

warning: unresolved link to `Block`
  --> src/api.rs:91:27
   |
91 | /// Information about a [`Block`].
   |                           ^^^^^ no item named `Block` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

warning: unresolved link to `Script`
   --> src/api.rs:181:37
    |
181 | /// Statistics about a particular [`Script`] hash's confirmed and mempool transactions.
    |                                     ^^^^^^ no item named `Script` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `Script`
   --> src/api.rs:184:58
    |
184 |     /// The summary of confirmed transactions for this [`Script`] hash.
    |                                                          ^^^^^^ no item named `Script` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `Script`
   --> src/api.rs:186:56
    |
186 |     /// The summary of mempool transactions for this [`Script`] hash.
    |                                                        ^^^^^^ no item named `Script` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `Script`
   --> src/api.rs:190:63
    |
190 | /// Contains a summary of the transactions for a particular [`Script`] hash.
    |                                                               ^^^^^^ no item named `Script` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `TxOut`
   --> src/async.rs:535:19
    |
535 |     /// Get all [`TxOut`]s locked to a [`Script`] hash.
    |                   ^^^^^ no item named `TxOut` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: unresolved link to `TxOut`
   --> src/blocking.rs:463:19
    |
463 |     /// Get all [`TxOut`]s locked to a [`Script`] hash.
    |                   ^^^^^ no item named `TxOut` in scope
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: `esplora-client` (lib doc) generated 7 warnings

[ValuedMammal]

Thanks for putting together a well organized patch set. I'm requesting that we fixup the test_get_block_txids test as well as the cargo doc warnings.

[luisschwab]

cargo doc is showing some unresolved links.

I proposed fixing these on a follow-up PR that also documents the rest of the crate, a few comments above.

I'll address these reviews in a few minutes.