on_before_asset_added_to_account and on_before_asset_added_to_note callbacks are missing a formal invariant specification

[giwaov]

Background

Protocol v0.14.0 added two new asset callback hooks:

• on_before_asset_added_to_account (feat: implement asset callbacks #2571)
• on_before_asset_added_to_note (feat: implement on_before_asset_added_to_note callback #2595)

These hooks let custom account components run MASM procedures whenever an asset is about to be added. The NetworkFungibleFaucet already implements one such callback (distribute).

The gap

The CHANGELOG and PR descriptions document what the callbacks do, but the protocol specification does not define the contract they must uphold for implementors. Four specific invariants are currently unspecified:

1. Invocation ordering when a single note adds multiple assets, are hooks fired asset-by-asset in declaration order, all-or-nothing per note, or in some other order? A callback that reads the vault to check an issuance cap needs this guarantee to reason about intermediate state correctness.

2. Abort semantics can a callback trap to veto an asset addition? If it does, does the whole transaction fail or only the current note? Is partial rollback possible?

3. State visibility can a callback observe vault mutations committed by an earlier callback in the same transaction? This is a re-entrancy-adjacent question that allows callbacks to interact non-locally, which could be exploited in multi-component accounts.

4. Recursive invocation can a callback itself call add_asset, thereby triggering recursive callback invocations? If so, what bounds recursion depth and prevents stack exhaustion?

Impact

Without these invariants, third-party components implementing these hooks including the NetworkFungibleFaucet already shipped in v0.14.0 cannot formally verify their correctness. This is a gap in the v0.14.0 security model for composable account components.

Proposed deliverable

A documentation section in the account-component spec titled "Asset Callback Guarantees" that covers:

• Invocation count: exactly once per asset addition, before the asset is written to the vault
• Ordering: sequential, in component declaration order, for each asset in turn
• Abort: a trap inside a callback propagates as TransactionError and fails the entire transaction; no partial-note state is committed
• Re-entrancy: callbacks must not call add_asset directly or indirectly; if they do, behavior is defined (error, panic, or explicitly permitted with bounded depth)

[bobbinth]

Thank you for opening the issue. We should probably add a section on callbacks to the docs (and probably update the whole section on assets/faucets), but I'd do it after the structure is solidified more. Also, we already have #1827 that covers this more broadly. So, I'll just add a comment there about documenting callbacks.