docs(wallet): reword the next_unused_address doc

[oleonardolima]

Description

Adds an example on what used stands for, and make it explicit that it
has the same behavior as Wallet::reveal_next_address in the scenario
where all previously revealed addresses have been used.

Notes to the reviewers

Is there any other behavior of next_unused_address we'd need to make clear through documentation ?

Changelog notice

• Improve the Wallet::next_unused_address documentation to better describe expected behavior/usage.

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran cargo fmt and cargo clippy before committing

New Features:

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

Bugfixes:

• This pull request breaks the existing API
• I've added tests to reproduce the issue which are now passing
• I'm linking the issue being fixed by this PR

[notmandatory]

ACK 07b85ca

New name looks good to me.

[evanlinjin]

Okay thinking about it, this method actually returns the earliest unused...

[notmandatory]

lets make this a doc only change

[oleonardolima]

As per last call discussion, I'll repurpose this PR to keep next_unused_address API, focusing only on improving the current documentation.

Will re-review after new direction changes pushed.

[Ademan]

FWIW the docs tripped me up a bit, such that I was confused what the actual difference between next_unused_address() and reveal_next_address() was for a short while.

On subsequent readings it's perfectly clear, so I might have just been careless in my first reading...

But I think the distinction between "used" and "derived" was not in my mind on my first reading.

    /// This will attempt to derive and reveal a new address if no newly revealed addresses
    /// are available. See also [`reveal_next_address`](Self::reveal_next_address).

Maybe instead of "available" it could be "unused" ? ("available" sent my mind to the generated key pools of pre-HD wallet bitcoin core)

and/or at the risk of repeating nearly the same thing as the first and second lines, add something like

"If any previously derived addresses are unused, next_unused_address() returns the one with the lowest derivation index, otherwise it derives a new address."

[ValuedMammal]

@Ademan That's a great suggestion, thanks for weighing in on this. Here's another way we could word it as well:

    /// This will attempt to reveal a new address if all previously revealed addresses have
    /// been used, in which case the returned address will be the same as calling
    /// [`reveal_next_address`].

[Ademan]

@Ademan That's a great suggestion, thanks for weighing in on this. Here's another way we could word it as well:

    /// This will attempt to reveal a new address if all previously revealed addresses have
    /// been used, in which case the returned address will be the same as calling
    /// [`reveal_next_address`].

I like that! It directly contrasts the two calls.

As a side note, is there are reason why BDK uses the word "reveal" instead of "derive" in the API?

[ValuedMammal]

As a side note, is there are reason why BDK uses the word "reveal" instead of "derive" in the API?

When you create a wallet we first derive a number of addresses (script pubkeys) and store them internally. When you reveal an address, it comes from the pool of derived scripts. The concept of "revealing" exists for the purpose of keeping track of the highest index that we've uncovered. An address is considered "used" when you receive a transaction paying to that address.

[oleonardolima]

Thanks for the suggestions.

I repurposed the PR to have only the documentation change: i) added a statement on what used stands for, and ii) applied the VM's suggestion in the second section.

[thunderbiscuit]

ACK 7ece14a.

[oleonardolima]

@notmandatory @ValuedMammal do we want to get this one in for 1.0? Any other required changes?

[ValuedMammal]

self-ACK d051e73

[notmandatory]

@oleonardolima please just squash the commits and then we can merge this one.

[oleonardolima]

@oleonardolima please just squash the commits and then we can merge this one.

Done b39cf08, sorry for the typo.

[notmandatory]

ACK b39cf08

[ValuedMammal]

ACK b39cf08