[huangji6693-max]

Summary

Adds docs/TROUBLESHOOTING.md, a comprehensive troubleshooting guide, diagnostic command reference, complete error catalog, and FAQ for StellarSplit (contracts/split and contracts/invoice-escrow).

Closes #1035

What's Included

1. Quick Diagnostic Triage Flowchart:
   • Decision tree for triaging Error(Contract, #N) vs. Soroban HostError (Auth, Budget, Storage) and stuck invoice states.
2. Diagnostic Tools & On-Chain Inspection Commands:
   • Ready-to-run stellar contract invoke commands for get_error_description, get_recovery_suggestion, is_invoice_releasable, simulate_release, run_contract_audit, run_invoice_audit, verify_invoice_invariant, get_monitoring_dashboard, get_pause_state, and get_rate_limit_status.
3. Step-by-Step Troubleshooting by Category:
   • Build, Rust toolchain (rustc >= 1.91.0), and storage_snapshot XDR baseline regeneration.
   • Invoice creation, recipient/split validation, and deadline errors.
   • Payment, SAC token allowance/balance, FX oracle staleness/slippage, and Ed25519 meta-transaction (PaymentIntent) issues.
   • Release, refund, milestone, and dispute freeze locks.
   • Sliding-window rate limiting (#70), emergency pause (#23), and circuit breaker blocks.
   • Staged contract upgrades, version monotonicity, and rollback windows.
4. Complete Error Code Reference:
   • All 77 contracts/split ContractError variants (#1–#77) with category, root cause, and actionable recovery steps, plus the contracts/invoice-escrow error code ranges (1–505).
5. Comprehensive FAQ:
   • Answers common questions around auto-release vs. conditional release, permissionless settlement cranks, partial funding refunds, pull-payment escrow recovery, and invariant verification.