Panic containment policy doc

[nanaf6203-bit]

Problem Statement
Every state-changing function panics on errors rather than returning
Result. There is no documentation for: (a) when a function panics
vs when it succeeds silently, (b) what clients should expect when a
panicked call's transaction is rolled back.

Why it matters
Soroban treats panic as a transaction failure — rolled back storage
and emitted events. Clients that "fire-and-forget" tips without waiting
for confirmation may double-spend if they re-call after a panic.

Expected Outcome
docs/panic-policy.md documenting the contract's panics and the
TX-rollback semantics, with worked examples for each error variant.

Acceptance Criteria

• Doc walks through each TipError variant, the function it can be
  raised from, and the recovery recommended for the client.
• Linked from each public function's rustdoc.

Files/Modules Likely Affected

• docs/panic-policy.md (new)
• src/lib.rs — add /// # Errors rustdoc sections

Difficulty Easy. Estimated Effort S.

Labels
area:documentation, area:smart-contract-safety,
priority:medium

---

Imported from docs/open-issues-draft.md as draft issue #26 (commit 7becd4b). Original draft-order cross-references in this body have been remapped to current GitHub issue numbers at import time.

[GBOYEE]

Hi team — I'd like to take this on as part of the GrantFox campaign. I'll write the documentation and open a PR referencing this issue shortly.