docs(soroban): add per-contract API reference and consolidated error table

[dev-fani]

What this resolves

soroban/src/ has ~35 contract modules with no unified reference for their public entry points or error codes, so contributors and integrators had to read each source file directly to understand what's callable, what auth it requires, or what a given error code means (#12).

Approach

• soroban/docs/API_REFERENCE.md — every public function under soroban/src/: signature, arguments, authorization requirement, and emitted events. Descriptions are derived from each function's /// doc comment where one exists (most modules already had good rustdoc-style comments); where a module had none (alert_system, analytics_aggregator, circuit_breaker, operator_rotation, report_hash, source_blessing, threshold_window, version_migration_helper, plus gaps in governance, bridge_reserve_verifier, insurance_pool), the description was written by reading the function body.

  While mapping this out, it became clear soroban/src/ mixes three very different compilation states that aren't documented anywhere:

  • Deployed contract — BridgeWatchContract (lib.rs) plus EmergencyFundRecovery, the only two #[contract] types unconditionally compiled into the release wasm32-unknown-unknown build.
  • cfg(test)-only standalone contracts — 11 modules (governance, insurance_pool, asset_registry, rate_limiter, etc.) each define their own #[contract] type but are gated to avoid wasm symbol collisions with BridgeWatchContract, per the existing comment in lib.rs. They're compiled and tested by cargo test, but excluded from the release wasm artifact.
  • Unreferenced files — 10 files (alert_system.rs, fee_distribution.rs, bridge_reserve_verifier.rs, etc.) have no mod declaration or #[path] include anywhere in the workspace, so they're never compiled by any build target and their inline test suites never run in CI.

  The reference is organized around this so nobody mistakes a cfg(test)-only or unreferenced module for something that's actually live.

• soroban/docs/ERRORS.md — every #[contracterror] numeric code (8 enums, ~100 codes total) grouped by originating contract, plus a verification that each contract's own codes are contiguous starting at 1 with no gaps or duplicates. Also flags that migration.rs and version_migration_helper.rs both define a MigrationError type (different, non-colliding Rust types, since they're #[contracttype] result variants rather than numeric error codes — but same name, worth knowing).

• README.md — links to both new docs.

Scope note: per the issue's own "Where to look" pointers, this covers soroban/src/ and soroban/docs/ only, not escrow_contract/ or transfer_state_machine/.

How this was tested

• Verified the error-code uniqueness/contiguity claims programmatically against the actual #[contracterror] enum discriminants in source.
• Verified every internal anchor link (table of contents, cross-references between API_REFERENCE.md and ERRORS.md) resolves against a real heading using GitHub's heading-slug algorithm.
• This is a docs-only change (no .rs files touched), but ran the full CI checklist locally to confirm nothing regressed:
  • cargo fmt --all -- --check — pass
  • cargo clippy --all-targets --all-features -- -D warnings — pass
  • cargo build --release --target wasm32-unknown-unknown — pass
  • cargo test (full workspace) — 506+ tests pass, 0 failed

Closes #12