Refresh `docs/interfaces/vault.json` to match the real ABI and add a backend integration guide

[greatest0fallt1me]

Description

docs/interfaces/vault.json is described in README.md as the canonical, machine-readable reference for backend integrators using @stellar/stellar-sdk, but it has drifted from the implementation in contracts/vault/src/lib.rs. It documents string panics (e.g. "vault is paused", "amount must be positive") even though every entrypoint now returns typed VaultError codes; it is missing error code 29 (DuplicateRequestId); and it omits many public functions that exist in the contract. This makes the JSON misleading for integrators and out of sync with EVENT_SCHEMA.md.

Requirements and context

Functional — reconcile docs/interfaces/vault.json against contracts/vault/src/lib.rs:

• Replace string-panic panics arrays with the typed VaultError variant each entrypoint actually returns (the enum is at contracts/vault/src/lib.rs:42–:106; e.g. Paused (4), AmountNotPositive (6), ExceedsMaxDeduct (7), InsufficientBalance (5)).
• Add the missing error code { "code": 29, "name": "DuplicateRequestId" } to errors.codes.
• Add the missing public functions to the functions array, including: set_max_deduct (:479), set_price / get_price (:1035 / :1060), remove_metadata (:1103), set_revenue_pool (:956), get_revenue_pool (:350), get_contract_addresses (:366), clear_allowed_depositors (:526), get_allowed_depositors (:407), is_request_processed (:1188), upgrade (:1142), version (:1164), and the allowlist aliases add_address / clear_all / get_allowlist (:1251–:1286).
• Ensure each documented function's params, returns, access, and events match the source (e.g. deduct takes request_id: Option<Symbol>, returns i128).
• Remove the duplicated set_metadata / get_metadata / require_owner entries currently listed twice in the JSON.
• Add a short backend integration guide (Markdown) that walks an integrator through: init -> set_settlement -> set_authorized_caller -> deposit -> deduct(request_id) -> reading balances, built directly from the JSON interface and EVENT_SCHEMA.md. Cross-link it from README.md and docs/interfaces/README.md.

Non-functional / repo conventions

• Keep the JSON schema shape consistent with docs/interfaces/settlement.json and docs/interfaces/revenue_pool.json.
• This is a docs-only change — no contract code edits — but the JSON must be validated against the actual lib.rs symbols.

Acceptance criteria

• Every public function in contracts/vault/src/lib.rs appears exactly once in docs/interfaces/vault.json with correct params / returns / access.
• panics arrays reflect typed VaultError variants (not legacy string panics).
• Error code 29 (DuplicateRequestId) present in errors.codes.
• Duplicate set_metadata / get_metadata / require_owner entries removed.
• A new integration guide exists under docs/ and is linked from README.md and docs/interfaces/README.md.
• docs/interfaces/vault.json is valid JSON (cargo test --workspace and a JSON lint both pass).

Suggested execution

1. Fork the repo and create a branch

git checkout -b docs/vault-interface-refresh

2. Implement changes

• docs/interfaces/vault.json — reconcile errors, functions, params, and events against contracts/vault/src/lib.rs.
• New docs/INTEGRATION_GUIDE.md (or similar) — backend walkthrough.
• README.md, docs/interfaces/README.md — add cross-links.

3. Write/extend tests

• No contract tests required, but verify the JSON parses (e.g. python3 -m json.tool docs/interfaces/vault.json) and that every function name in the JSON corresponds to a pub fn in contracts/vault/src/lib.rs (a small grep cross-check is sufficient and should be noted in the PR).

4. Test and commit

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace
./scripts/check-wasm-size.sh
./scripts/coverage.sh

Example commit message

docs(vault): sync interface JSON with real ABI and add integration guide

Guidelines

• Coverage must stay >= 95% (scripts/coverage.sh), CI-enforced via .github/workflows/coverage.yml (unaffected by docs-only changes, but keep the gate green).
• Treat contracts/vault/src/lib.rs as the source of truth; keep docs/interfaces/vault.json and EVENT_SCHEMA.md mutually consistent.
• Timeframe: 96 hours.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!