Add a reconciliation view comparing the live token balance against outstanding liabilities

[mikewheeleer]

Add a reconciliation view comparing the live token balance against outstanding liabilities

Description

The contract exposes get_token_balance(env) (the live SEP-41 balance held by the contract) and get_distributed_principal(env) (principal already returned), but offers no single view that tells an operator whether the contract is solvent for its remaining obligations. Reconciliation tooling must fetch the balance, the funded amount, the distributed principal, and the settlement state separately and compute the surplus/deficit off-chain, duplicating the exact liability arithmetic that sweep_terminal_dust already encodes internally.

This issue adds a read-only view returning the contract's reconciliation position: live balance, outstanding investor liability, and the resulting surplus (sweepable dust) or deficit.

Requirements and context

• Repository scope: Liquifact/Liquifact-contracts only.
• Add a ReconciliationView struct (token_balance, outstanding_liability, surplus) and get_reconciliation(env) -> ReconciliationView.
• Compute outstanding_liability using the same formula sweep_terminal_dust relies on (funded_amount - distributed_principal, floored at zero), so the two never disagree.
• Use saturating/checked arithmetic; the view must never panic on extreme values.
• Keep it a pure read with no auth and no storage writes.
• Cross-reference sweep_terminal_dust's liability floor in the doc comment.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-reconciliation-view
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — add the struct and get_reconciliation reusing the liability formula.
  • Write comprehensive tests in: contracts/escrow/src/tests/external_calls.rs — assert surplus equals sweepable dust before and after partial refunds.
  • Add documentation: add the view to the read-API surface and reconciliation guide in README.md and docs/.
  • Include NatSpec-style doc comments (///) on the struct fields and the surplus definition.
  • Validate security assumptions: surplus never exceeds what sweep_terminal_dust would permit.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: zero balance, over-funded balance, fully-distributed, and partial-refund states.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

feat: add get_reconciliation view comparing token balance to outstanding liability

Guidelines

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

Community & contribution rewards

• 💬 Join the Liquifact community on Discord for questions, reviews, and faster merges: https://discord.gg/JrGPH4V3
• ⭐ 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 — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Hassanmovic98]

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

I will implement the get_reconciliation read-only view to track contract solvency.I will define the ReconciliationView struct returning balance, outstanding liability, and surplus.I will integrate this view cleanly within contracts/escrow/src/lib.rs.The calculation will mirror the exact liability arithmetic found in sweep_terminal_dust.I will use safe, saturating math blocks to ensure the function never panics.The new endpoint will remain a pure read requiring no user authorization headers.I will write focused unit tests inside contracts/escrow/src/tests/external_calls.rs.These tests will aggressively verify edge cases like zero balance and over-funded scenarios.I will document this view and its security definitions within the project README.md.Finally, I will run the cargo test runner to lock in 95%+ coverage.

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

[Spagero763]

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

i would like to take up this issue

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

[drips-wave]

Congratulations, @Spagero763! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Spagero763: 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 🌊