Document the settlement model and its invariants

[mikewheeleer]

Document the settlement model

Description

The settlement model and its invariants are undocumented, making audits harder. This issue documents them.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Add docs/settlement.md describing the settlement data model, its invariants, and the entrypoints that touch it.
• Cross-reference the code with a worked example; keep it accurate.
• Read the relevant module first.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/settlement-01-model
• Implement changes
  • Write code in: the relevant module.
  • Write comprehensive tests in: cover the new behaviour and edge cases.
• Test and commit

Test and commit

• Run cargo fmt, cargo clippy --all-targets -- -D warnings, and cargo test.
• Cover edge cases: n/a — verify invariants against source.
• Include the full test output in the PR description.

Example commit message

docs(settlement): document the model and invariants

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — a 5-star rating is much appreciated.