[Quality] Make vault lifecycle transitions an explicit invariant

[1nonlypiece]

Problem

Vault state transitions can become difficult to reason about when release, failure, cancellation, and validation paths overlap.

This issue requires a meaningful production implementation. Typo-only, documentation-only, formatting-only, dependency-only, or cosmetic changes do not satisfy the scope.

Objective

Encode the lifecycle transition table in the contract and reject every invalid edge deterministically.

Scope

Review all entrypoints, centralize transition validation, preserve terminal-state monotonicity, and add event assertions.

Acceptance criteria

• Every valid transition is represented and tested.
• Terminal states cannot transition to active or pending states.
• Invalid transitions leave all storage unchanged.
• Tests cover each edge, repeated calls, authorization, and event ordering.
• Existing CI/CD checks remain green.
• The PR explains the design, tradeoffs, test evidence, and any remaining limitations.
• The PR references this issue with Closes #{issue-number} or Fixes #{issue-number}.

Implementation notes

Implement only the stated behavior; keep unrelated refactors out of the PR.

Non-goals

• Do not remove tests merely to make CI pass.
• Do not introduce secrets, private keys, credentials, or mainnet-only values.
• Do not change unrelated APIs, UI surfaces, contract behavior, or deployment configuration.

Contributor application

Before starting, comment with relevant experience, a 1–4 bullet implementation approach, and an estimate for opening the first draft PR. Wait for maintainer assignment before coding. Only the assigned contributor is eligible for reward consideration.

Submission requirements

• Use PR title format [#<issue-number>] <short summary>.
• Check off each completed acceptance criterion.
• Include focused automated tests for success, failure, authorization, and boundary behavior where applicable.
• Include the validation commands and results in the PR description.
• Address maintainer review feedback before merge.

GrantFox reward consideration is based on the original scope, implementation quality, tests, security review, CI/CD results, review feedback, and follow-up stability; completion or merge alone is not a guarantee.

[safal207]

Hi — this is directly aligned with my recent escrow lifecycle verification work.

Relevant experience:
In a recent independent escrow assessment, function-level tests passed, but state-transition analysis exposed a material liveness failure: a funded terminal-like state had no contract-level path to release or refund.

Approach for #419:

• model the complete vault lifecycle as an explicit transition table;
• verify every valid and invalid edge, including repeated calls;
• preserve terminal-state monotonicity and unchanged storage on rejected transitions;
• add regression coverage for authorization, event ordering, and recovery paths.

First draft PR: within 1 day after maintainer assignment.

I’ll wait for assignment before implementation.

[guptakumarranjeet150]

Hello! I'd like to work on this issue.

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement [Quality] Make vault lifecycle transitions an explicit invariant with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Testing & Verification: Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.
• Delivery: Ready to ship a thoroughly tested PR within 12–24 hours with passing CI.

Happy to pick this up today—please assign to me!

[shobhamerabacha-star]

Hi maintainers,

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement [Quality] Make vault lifecycle transitions an explicit invariant with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Testing & Verification: Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.
• Delivery: Ready to ship a thoroughly tested PR within 12–24 hours with passing CI.

Ready to deliver a clean, tested PR within 12–24 hours. Please assign!

[ranjeet150]

Hi everyone,

I would love to take this on. My planned approach:

• Implement [Quality] Make vault lifecycle transitions an explicit invariant with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.

I am ready to start immediately—please assign this to me!