[CONTRACT-04] Soroban Contract Documentation & ABI Reference

[mftee]

⚠️ Depends on: [CONTRACT-01], [CONTRACT-02], [CONTRACT-03] — contracts must be tested and deployed before documentation is finalized.

Overview

The five Soroban contracts have no external documentation. Contributors integrating the backend with the contracts (see [BE-28], [BE-29]) must read the raw Rust source to understand function signatures, error codes, and storage layout. This issue creates clear documentation for all five contracts.

Technical Details

1. Per-Contract Documentation Files

For each contract, create a contracts/{contract-name}/README.md with the following structure:

Template:

# [Contract Name] Contract

## Overview
[One paragraph: what this contract does, who calls it, and what state it manages]

## Storage Layout
[Table: key name, type, description, TTL policy]

## Functions

### function_name(param1: Type, param2: Type) → ReturnType
**Authorization:** [Who can call this — any, owner, admin, carrier]
**Description:** [What it does]
**Errors:** [List of panic conditions with the error name from the Error enum]
**Example call (Soroban CLI):**
```bash
soroban contract invoke --id  --network testnet -- function_name --param1 value

Error Codes

[Table of all Error enum variants: name, u32 value, description]

Events Emitted

[Table of all events: name, topics, data fields]

Apply this template to all five contracts:
- `contracts/identity/README.md`
- `contracts/shipment/README.md`
- `contracts/escrow/README.md`
- `contracts/document/README.md`
- `contracts/reputation/README.md`

### 2. Workspace-Level Documentation (`contracts/README.md`)
Create or update `contracts/README.md`:
- Introduction: what this workspace contains and why Soroban/Stellar was chosen
- Contract dependency map (which contracts interact with each other and in what order)
- Setup: how to install Soroban CLI, configure a testnet account, and fund it with Friendbot
- Build: `cargo build --target wasm32-unknown-unknown --release`
- Test: `cargo test`
- Deploy: link to `scripts/deploy-all.sh` from **[CONTRACT-03]**
- Deployed addresses table: link to `deployed-addresses.md`

### 3. Backend Integration Reference (`contracts/INTEGRATION.md`)
Create a guide specifically for backend developers (NestJS) integrating with the contracts:
- How to construct a Soroban invocation using `stellar-sdk` (TypeScript examples)
- How to decode XDR response values for each contract's return types
- How to handle the platform keypair for admin-only calls (escrow refund, dispute)
- Common pitfalls: TTL expiry, insufficient fee, contract not initialized
- Example: invoking `escrow::fund()` from NestJS end-to-end

### 4. ABI JSON Export
For each contract, generate a JSON ABI file using the Soroban CLI:
```bash
soroban contract bindings json --wasm target/wasm32-unknown-unknown/release/{name}.wasm > contracts/{name}/abi.json

Commit the abi.json files alongside each contract. These can be consumed by frontend code or SDK generators.

Acceptance Criteria

• Each of the 5 contracts has a README.md following the template
• Every public function is documented with its authorization level, description, and error conditions
• contracts/README.md covers setup, build, test, and deploy steps
• contracts/INTEGRATION.md includes a working TypeScript example of invoking an escrow function
• ABI JSON files are generated and committed for all 5 contracts
• Documentation is clear enough that a developer new to Soroban can successfully call a contract using the Soroban CLI following only the README instructions