The fact that the Wallet.transactions() API can return more than wallet-related txs is not explicit

[thunderbiscuit]

One might expect that the Wallet.transactions() method replaced the Wallet.list_transactions() and will return similar transactions (the transactions related to the descriptors the wallet tracks). This is not the case, as the method returns an iterator that traverses the entire TxGraph. If I understand this TxGraph correctly, any number of transactions can be added to it, even conflicting and never mined txs. The API docs are simply: Iterate over the transactions in the wallet.

For typical use, a wallet will likely want to see transactions related to itself, and I assume the user is expected to then filter the transactions in the iterator using the is_mine() method. Let me know if I misunderstand the intended use of the API!

But if the above is correct, I find the API more cumbersome than it needs to be for the most typical uses and what one might expect of something like a Wallet.transactions() method. Here are a few thoughts I have to maybe make the API simpler/more explicit. Would love to hear what others think:

1. The transactions() method could take an argument mine_only: bool that would ensure the method returns only wallet-related txs, or maybe the opposite, an argument full_tx_graph: bool that would return what it currently returns.
2. The transactions() method could be renamed entirely to imply its more complex nature, and a new, simpler transactions() method could take its place and return a more filtered list of transactions that relate to the wallet.

Let me know if there is more to this that I haven't understood well!

[thunderbiscuit]

Connecting this to bitcoindevkit/bdk-ffi#432

[LLFourn]

One might expect that the Wallet.transactions() method replaced the Wallet.list_transactions() and will return similar transactions (the transactions related to the descriptors the wallet tracks). This is not the case, as the method returns an iterator that traverses the entire TxGraph. If I understand this TxGraph correctly, any number of transactions can be added to it, even conflicting and never mined txs. The API docs are simply: Iterate over the transactions in the wallet.

I think it should actually return similar things than before. To be specific it returns transactions in the chain that have been inserted into the wallet. Most likely this will be only relevant transactions (but applications can always insert irrelevant ones if they want!).

The documentation should explain this nuance. You could make this method more restrictive or add another one which made sure it was only relevant transactions (i.e. sent or received some bitcoin in the wallet) which should be easy to check.