feat(chain): add ChainPosition::blocks_since_conf

[Dmenec]

Suggested by @nymius in #2246 (comment).

Description

Adds ChainPosition::blocks_since_conf(tip), which returns the number of blocks mined on top of a confirmed position's block, given the chain tip. Returns None if the position is unconfirmed, or if the confirmation height is above tip.

Changelog notice

• Added ChainPosition::blocks_since_conf, returning the number of blocks mined on top of a confirmed position's block given the chain tip.

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran just p before committing

New Features:

• I've added tests for the new feature
• I've added docs for the new feature

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.41%. Comparing base (456f9b7) to head (defff8e).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2263      +/-   ##
==========================================
+ Coverage   78.36%   78.41%   +0.04%     
==========================================
  Files          30       30              
  Lines        5945     5952       +7     
  Branches      281      282       +1     
==========================================
+ Hits         4659     4667       +8     
+ Misses       1210     1209       -1     
  Partials       76       76              

Flag	Coverage Δ
rust	78.41% <100.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[evanlinjin]

The concept that is more common is "confirmations". Would it be better to just have confirmations() -> Option<u32> and for callers that need "blocks since conf", it will be confirmations.and_then(|n| n.checked_sub(1))?

Edit: Note that it would be confirmations_lower_bound.

[nymius]

The concept that is more common is "confirmations". Would it be better to just have confirmations() -> Option<u32> and for callers that need "blocks since conf", it will be confirmations.and_then(|n| n.checked_sub(1))?

Edit: Note that it would be confirmations_lower_bound.

Agree, it is more familiar. Something I should have asked before suggesting this is, is it interesting from an API user perspective? Because I came up with this in the context of a test, but seems to be useful in other contexts.

[evanlinjin]

@nymius I think getting confirmations from chain position is definitely useful. It's what a wallet would want to show to the user.