Reconcile the deposit-to-release state gap that leaves Funded contracts unreleasable

[mikewheeleer]

Reconcile the deposit-to-release state gap that leaves Funded contracts unreleasable

Description

deposit::deposit_funds_impl in contracts/escrow/src/deposit.rs promotes a contract to ContractStatus::Funded once funded_amount >= total_amount. But release_milestone in contracts/escrow/src/lib.rs guards with if contract.status != ContractStatus::Accepted { panic InvalidState }. There is no entrypoint anywhere in the contract that transitions a contract from Funded to Accepted. The consequence is a hard dead-end: a fully funded contract can never have any milestone released, because the only status release_milestone accepts is unreachable through the normal lifecycle.

This issue reconciles the two ends of the state machine so that a funded contract is releasable. Pick one canonical contract: either have release_milestone accept Funded (and Accepted) contracts, or wire a real Funded → Accepted transition into the lifecycle and document it as the required pre-release step.

Requirements and context

• Repository scope: Talenttrust/Talenttrust-Contracts only.
• Audit which statuses each money-flow entrypoint expects (deposit_funds, release_milestone, raise_dispute, refund_unreleased_milestones) and converge on a single documented progression.
• If release_milestone is changed to accept Funded, keep all other gates (approvals, per-milestone funding, pause/emergency, finalization) intact.
• Ensure the chosen path does not silently allow releases on Created, Disputed, Cancelled, Refunded, or Completed contracts.
• Update the ContractStatus doc comments and any README/docs state-machine description to match the reconciled flow.

Suggested execution

• Fork the repo and create a branch
• git checkout -b enhancement/contracts-deposit-release-state-gap
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — adjust the release_milestone status gate (and/or add the missing transition) so funded contracts are releasable.
  • Write comprehensive tests in: contracts/escrow/src/test/release.rs — assert a deposit-then-release happy path end to end, and that disallowed statuses still reject.
  • Add documentation: update the ContractStatus state-machine docs to show the canonical funded-to-release path.
  • Include NatSpec-style doc comments (///) describing the accepted statuses on release_milestone.
  • Validate security assumptions: no release from a never-funded or terminal contract, no bypass of approval checks.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: release attempt on Created, Disputed, Cancelled, and Completed contracts.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

fix: reconcile deposit-to-release status gate so funded contracts are releasable

Guidelines

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

Community & contribution rewards

• 💬 Join the TalentTrust community on Discord for questions, reviews, and faster merges: https://discord.gg/WqnGpcPx
• ⭐ 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.

[GBOYEE]

Hey — took a look at the state machine here and the gap is clear: deposit_funds_impl flips to Funded, but release_milestone only accepts Accepted, and nothing ever bridges that.

The simplest fix is widening release_milestone's guard in contracts/escrow/src/lib.rs to accept both Accepted and Funded — that's the natural lifecycle since funding always precedes the first release. I'd keep every other gate intact (approvals, milestone funding thresholds, pause/emergency, finalization) and add a regression test in contracts/escrow/src/test/release.rs covering the deposit→release happy path. Then a couple negative cases to make sure Created, Disputed, Cancelled and Completed all still reject.

Mind if I take this on? Should have it done in a day or so.