DX-087: Document the OrderVault contract

[IbrahimIjai]

Context

OrderVault custodies collateral between order submission and execution. Users
ask where their funds are during that window, and integrators need to know the
lifecycle to handle stuck or cancelled orders correctly.

Scope

• The contract's role and the custody lifecycle: deposit, execution, refund on
  cancellation.
• Every public function with parameters, authorisation, and errors, following
  the DX-084 template.
• What happens to collateral when an order fails, expires, or is cancelled —
  including who may trigger a refund and when.
• The events emitted, and how the indexer consumes them.
• A worked example tracing collateral through a cancelled order.

Acceptance criteria

• Function coverage asserted against the generated bindings.
• The custody lifecycle is verified against contract source, with the file
  and function named in the PR.
• Emitted events match what the indexer actually handles.
• The cancelled-order example was executed on testnet.

Out of scope

• Keeper and executor operation.

---

Spec: docs/dx_1/003_content_map.md §2 · Depends on: DX-086

[xtep103]

@xtep103 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer, I’d like to work on this issue. I’ve handled similar tasks before and can get started right away.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @xtep103 to this issue.

[Oluwatomilola]

@Oluwatomilola has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can fix this, kindly assign.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Oluwatomilola to this issue.

[drips-wave]

Congratulations, @Oluwatomilola! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Oluwatomilola: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊