security(contract): enforce supply-cap conservation on every stream mutation

[arisu6804]

Problem

A single overlooked top-up, cancellation, or recovery path can bypass the configured supply cap.

Objective

Deliver a production-quality improvement to global supply accounting and stream mutations that creates measurable value for correctness, security, reliability, performance, or maintainability.

Implementation scope

• Centralize supply checks and apply them to create, top-up, cancel, withdraw, and admin recovery; reject overflow.

Acceptance criteria

• Live stream commitments plus released amounts never exceed the cap; failed calls do not change supply; unauthorized paths cannot alter counters.

Required validation

• Invariant, overflow, authorization, concurrent-call, and rollback tests.
• Existing tests and CI remain passing.
• Add regression coverage for the original failure mode.
• Do not weaken, delete, or skip unrelated tests to obtain a green build.

PR quality bar

• Keep the PR focused and explain design tradeoffs, compatibility impact, and test evidence.
• Avoid typo-only, documentation-only, cosmetic-only, or unrelated refactor submissions.

Out of scope

• Broad rewrites not required by the acceptance criteria.
• Changes to unrelated services, contracts, or user flows.

[leocagli]

Hi, I would like to take this one. I also applied to #90, and the two are complementary: this defines the conservation rule, #90 generates the sequences that try to break it.

I am Leo Cagliero, from the Starmaker program, working on Cosmos LATAM and Open Stellar.

Why I am credible here specifically: in Disciplr-Contracts#416 I wrote exactly this property for another Soroban contract. Several escrows opened with deliberately different amounts, driven to three different terminal states, then asserting each destination received exactly its own amount and the contract retains exactly the escrow still open. The different amounts matter: with equal amounts a leak between escrows passes by coincidence, and the test proves nothing.

One design question before I write code.

"Enforce on every mutation" admits two readings and they produce very different diffs:

1. A guard called at the end of each entrypoint that recomputes the identity and rejects if it fails. Small diff, but it only catches the violation after the mutation, and a new entrypoint can forget to call it.
2. A single accounting module that owns every balance write, so no path can move value without going through it. Structurally stronger, since forgetting is impossible rather than merely discouraged, but it touches every entrypoint at once.

I lean toward the second because your phrasing is "on every path" rather than "on every call", but it is a bigger change and I would rather agree first than surprise you in review.

On overflow: I would use checked arithmetic returning a typed error rather than relying on overflow-checks. A trap aborts the invocation instead of producing the structured Result the rest of the contract returns. And the order matters: if the expression is (a + b) * c with caller-supplied values, the addition overflows before the multiplication you were guarding, so both operations need to be checked and in the right sequence.

Happy to answer anything before you assign.