Improve docs in terms of persistence with Wallet

[evanlinjin]

Describe the enhancement

• Explain and give examples of implementing PersistWith<CustomDb> for Wallet.
• Explain when to call .persist on Wallet.

cc. @tnull

[tnull]

Thank you! Preferably, this wouldn't only be reflected in docs, but also in the API, e.g, either allowing us to get notified when persistence needs to happen or by returning a corresponding enum PersistenceNeeded or similar.

Also, please add guidance how to deal with persistence failures. Do we need to abort the current operation? Can we retry? Until when? Are there circumstances under which we need to panic as continuing without persistence would be considered highly unsafe?

[evanlinjin]

When persist needs to happen

Isn't this up to the caller to decide? We just need to inform the caller which methods would reveal a new address/spk (since if we don't persist immediately, it will result in address reuse). Everything else, can be delayed (with no catastrophic consequences) if changes are not persisted.

Also, please add guidance how to deal with persistence failures.

The persistence backend is responsible for returning errors which are informative and hopefully it can be dealt with.

Are there circumstances under which we need to panic as continuing without persistence would be considered highly unsafe?

Unsafe in what regard? The database is left corrupted? The database data is left in an inconsistent state? -> There are all persistence-backend-specific right?

Determining whether data not being persisted would lead to something disastrous, isn't this dependent on the application?

[tnull]

Isn't this up to the caller to decide? We just need to inform the caller which methods would reveal a new address/spk (since if we don't persist immediately, it will result in address reuse). Everything else, can be delayed (with no catastrophic consequences) if changes are not persisted.

The persistence backend is responsible for returning errors which are informative and hopefully it can be dealt with.

Determining whether data not being persisted would lead to something disastrous, isn't this dependent on the application?

I mean yes, I mostly agree with all three of these points, but the API docs should still highlight what the consequences of address reuse (or, FWIW, any other edge cases arising from BDK's state not being immediately/correctly persisted) might be. Yes, it's application-specific, but it still would be important to make the API as safe as possible and the docs as accommodating to users with different knowledge levels as possible (without becoming overly verbose, of course).