docs: correct admin transfer, pausing and error tables

[thegreatfeez]

closes #305,
closes #304,
closes #303,
closes #301.

All four items from issues.md were implemented in streamgive-contracts.
The README now describes the shared admin handshake for both contracts, lists
every entry point's paused behaviour, and regenerates both error tables from
the actual Error enums. The donation vault gains a table-driven test for the
whole StreamStatus machine.

issues.md item	GitHub issue
Fix the admin transfer description	#305
Rewrite the Pausing section	#304
Correct the error code tables	#303
Cover the stream status state machine	#301

---

#305 — Admin transfer, both contracts

• Replaced the contradictory “either side can abort” paragraph with the
  behaviour in the code: the current admin proposes and cancels; the
  pending admin accepts. The active admin is unchanged until acceptance.
• Documented the same handshake for ngo-registry, which had been omitted.
• Noted that only donation-vault has renounce_admin; the registry does not.

#304 — Pausing section

• Rewrote the broken sentence and removed the claim that pause “only flips a
  flag” without consequence. The pause call itself still moves no funds, but it
  changes which entry points are accepted.
• Replaced the five-row table with one that covers every public entry point:
  rejected paths (create_stream, withdraw, withdraw_batch, top_up,
  modify_rate, transfer_stream), paths that stay open (cancel_stream,
  unpause, renounce_admin, extend_stream), pause-only rescue_stream,
  the admin/configuration surface, and all read-only views.
• Kept and clarified the accrual note: time-based accrual continues while
  paused and is claimable after unpause.

#303 — Error tables

• Regenerated both tables from contracts/*/src/lib.rs rather than copying the
  stale rows.
• donation-vault: all 23 variants, in numeric order, with every entry point
  that can surface each one (including errors raised through require_admin,
  require_not_paused, and settle/record_payout).
• ngo-registry: all 11 variants, including InvalidAdmin,
  ArithmeticOverflow and InvalidName, and the full list of paths that can
  return AlreadyVerified (unregister, update_name, approve_ngo).
• Removed the duplicated 9/10/11 rows and the wrong InvalidTreasury /
  SelfStream assignments.

#301 — Stream status state machine

• Added stream_status_state_machine_walks_each_transition, a table-driven
  test that creates a fresh stream and walks each case, asserting the stored
  status after every call:
  • Active → Drained → top-up → Cancelled;
  • Active → Drained → Cancelled;
  • Active → partial withdraw (still Active) → Cancelled;
  • Active → Drained → rate change (still Drained) → Cancelled.
• Added cancelling_a_drained_stream_makes_it_terminal, which checks the
  Drained → Cancelled transition and that withdraw, top_up, modify_rate
  and transfer_stream all treat the cancelled stream as terminal.
• The tests pin current behaviour: a top-up does not revive a Drained
  stream's stored status. See the judgement call below.

---

Verification

Check	Result
cargo fmt --all -- --check	✅
cargo clippy --workspace --all-targets -- -D warnings	✅
cargo test --workspace	✅ 160 tests passed
cargo doc --workspace --no-deps with RUSTDOCFLAGS=-D warnings	✅
cargo build --workspace --target wasm32v1-none --release	✅
bash scripts/check-wasm-size.sh	⚠️ local bash is 3.2 (no associative arrays); CI runs Ubuntu bash 5

Judgement calls

• Drained → Active on top-up (Add a test for the full stream status state machine #301). The issue summary names this
  transition, but the current contract deliberately does not recompute status
  on top_up; the existing test from Add tests for modify_rate and top_up on a drained stream #298/test: pin Stream layout and cover depletion, fee TTL, drained streams #321 asserts it remains Drained.
  This is a test-only issue, so the new state-machine test asserts the actual
  behaviour and keeps the prior contract semantics. Changing the contract would
  be a separate behavioural fix.
• Paused rescue_stream (README Pausing section is garbled and out of date #304). It is listed separately because it is the
  one entry point that requires the vault to be paused; cancel_stream is open
  during a pause, and the admin/config surface is not gated by pause at all.
• Clippy clean-up. The required cargo clippy -- -D warnings command was
  already red on main from unused imports/borrows and an unused loop
  variable. Those warning-only fixes are included so the PR's required checks
  can pass; no behaviour changed.
• Wasm size check. The release wasm build succeeds. The size script uses
  bash associative arrays, which macOS's system bash 3.2 cannot run; the CI
  runner uses bash 5, so the check remains unchanged.

[drips-wave]

@thegreatfeez Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits