feat(contracts): implement Soroban milestone escrow state machine (#189) - #211
Open
CodeNinjaStephen wants to merge 2 commits into
Open
Conversation
…mina-eX#189) - Add InProgress state to MilestoneStatus enum (Funded → InProgress → Submitted) - Add start_milestone() function (client-only, Funded → InProgress) - Update submit_milestone() to require InProgress state - Update refund() to allow both client and freelancer to initiate - Update dispute() to accept InProgress | Submitted | Approved states - Emit events for every state transition (init/fund/start/submt/aprov/cnfrm/relse/rfund/dispt/rslve/expir) - Add 48 contract tests covering all valid and invalid transition paths - Update docs/soroban-escrow-deployment.md with state diagram, function reference, authorization model, events table, and error codes
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
feat(contracts): Soroban Milestone Escrow State Machine (#189)
Summary
Implements a formal state machine inside the Soroban escrow contract to manage milestone-based
workflows, enforcing predictable transitions, role-based authorization, and secure fund
handling.
Changes
New state: InProgress
Added InProgress between Funded and Submitted, making the full happy path:
Pending → Funded → InProgress → Submitted → Approved → Released
New function: start_milestone(milestone_id)
Client-only call that transitions a milestone from Funded to InProgress, signalling that work
may begin. This prevents freelancers from submitting deliverables before the client has
formally started the milestone.
Updated refund()
Both the client and the freelancer can now initiate a refund (previously freelancer-only).
Valid from Funded or InProgress states only.
Updated dispute()
Disputes can now be raised from InProgress, Submitted, or Approved states. The old Funded entry
point has been removed — a dispute only makes sense once work has started.
Updated submit_milestone()
Now requires InProgress status. Submissions from Funded are rejected, enforcing the
start_milestone() step.
Events
Every state transition emits a Soroban event with a descriptive topic and relevant data
payload, visible in transaction logs.
Docs
docs/soroban-escrow-deployment.md updated with a full ASCII state diagram, function reference
table, authorization model, events table, and error code reference.
Tests
48 contract tests — all passing — covering:
Checklist
closes #189