docs: explain Stellar network selection and deposit preparation

[Obaara293]

Overview

This PR documents the end-to-end deposit preparation flow for frontend integrators: vault registration prerequisites, the POST /api/vault/deposit/prepare request/response contract, network selection rules enforced by DepositController, fee/timeout environment variables, simulation diagnostics redaction, and signing responsibilities. It is a documentation-only change — no runtime behaviour, validation, or safeguards are modified.

Related Issue

Changes

📄 Deposit transaction builder docs

• [MODIFY] docs/deposit-transaction-builder.md
  • Documents the full deposit flow: vault registration first, then POST /api/vault/deposit/prepare.
  • Adds the request body schema matching DepositPrepareRequest (vault id, amount, asset, destination, and related fields).
  • Adds the response schema matching DepositPrepareResponse, including the returned XDR fields and their meaning.
  • Describes network mismatch behaviour: requests whose network differs from config.stellar.network are rejected by DepositController with INVALID_NETWORK.
  • Describes the vault-not-found failure mode and why vaults must exist before preparation.
  • Lists the environment variables that supply fees and timeouts.
  • Explains simulation diagnostics redaction and what the caller can and cannot see.
  • States signing responsibilities: the backend returns an unsigned XDR and the client signs it.
  • Includes an example XDR signing snippet.

🌐 Network configuration docs

• [MODIFY] docs/network-configuration.md
  • Clarifies how config.stellar.network is resolved and how it governs deposit preparation.
  • Cross-references the network mismatch behaviour and the relevant env variables for fee and timeout.
  • Links the two documents so integrators can follow the flow from configuration to request.

Verification Results

npm test -- src/controllers/depositController.test.ts

Examples in the docs were checked against src/controllers/depositController.ts and the DepositPrepareRequest / DepositPrepareResponse schemas so the documented fields, error codes (INVALID_NETWORK, vault-not-found), and env variable names match the implementation. No test files were added or modified by this PR.

Acceptance Criteria	Status
The request and response schemas match DepositPrepareRequest/Response	✅ Documented field-by-field from the controller schemas
Network mismatch behaviour is described	✅ INVALID_NETWORK rejection when network ≠ config.stellar.network
Env variables for fee and timeout are listed	✅ Fee and timeout env vars enumerated with their roles
An example XDR signing snippet is included	✅ Client-side signing example for the returned XDR

Security and Failure Modes

• Documents that simulation diagnostics are redacted, so integrators do not assume raw diagnostic payloads are available.
• Makes explicit that the backend never signs on the caller's behalf — the returned XDR is unsigned and signing is the client's responsibility.
• Calls out the two most common integrator failures (INVALID_NETWORK, vault-not-found) and their causes so they are not mistaken for transient errors.
• No safeguards or validation were weakened; this PR only adds documentation.

Compatibility

Documentation-only. No API, schema, or configuration changes, so existing integrators are unaffected.

Closes #1347

[drips-wave]

@Obaara293 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits