I believe many aspects of how callbacks or notifications work are not well-documented, particularly the user-facing behaviors (like the various -*notify behaviors, zmq interface, and synchronization guarantees between the wallet/mempool/validation). Along with a lack of documentation, I believe there’s likely a lack of regression testing to ensure that our software continues to enforce whatever implicit guarantees users may have come to expect. And it makes changes to the behavior more difficult, as it is hard to reason about changes to behavior without some context for what expectations might be.
I think it’d be a great project for someone to pick some of these interfaces and document exactly how they work. I imagine this would uncover some oversights that will be a jumping off point for making improvements as well.
As an example here are a few questions that show the kinds of things that I think are missing documentation:
- What are the ordering guarantees of eg
-blocknotifycallbacks, and what should they be? (#14275 highlights that there is a discrepancy between our own python tests and the behavior in our software) - Exactly which transactions are announced via the zmq interface – for instance during a reorg, or a transaction being evicted, a transaction being replaced due to conflict, etc?
- What ordering guarantees exist (if any) between notifications received via zmq and when the rest of our software (wallet/mempool/validation) reflecting the same underlying event via our RPC interface?
- What should the synchronization be between RPC calls that affect validation-level information (like
getbestblockhashand RPC calls that touch the mempool? (eg see #14193 for a reasonable-looking change that IMO should be evaluated in a larger context about how our interfaces should work).
etc.