Milestone lifecycle
Details of Milestone states and transitions
The following state machine illustrates the lifecycle of milestones. This guide provides additional context on the business rules, conditions, and actor responsibilities that govern these state transitions.
Key Concepts
Approval Pattern
Most critical operations require approval from the receiver (contractor) and funding from the payer (client). This ensures mutual consent and prevents unilateral actions that could harm either party. The approval process works asynchronously - receiver approves first, buyer funds, and the action executes.
Funds Locked
Funds are locked on the smart contract as milestones are funded. The funds can only flow in the direction of payer and receiver (minus the platform fees). Mutual consent to work having been done or resolving disputes, or having the admin resolve disputes are the only way to move funds.
States
PENDING
Initial state, milestone is not approved yet
DEPLOYED
Milestone escrow contract is deployed and ready for approval
APPROVED
Milestone is approved by receiver
FUNDED
Milestone is funded from the payer side - all funds are held on escrow contract
COMPLETED
Milestone work has been completed through happy path. Funds are distributed to receiver.
IN_DISPUTE
Either party has disputed (which will need to be RESOLVED, or reset to FUNDED by mutual consent or decision from the auditor).
PROPOSED_SPLIT
Either party has proposed a different payment split. Very similar to dispute but without mediators. Both parties can figure out an arrangement and fix any disagreements between them without anyone else's interference.
RESOLVED
Dispute or split has been resolved and funds distributed. Milestone is finished.
CANCELLED
The milestone is cancelled.
Details
Milestones can be controlled individually or in bulk. Per each agreement, milestones can be added, updated or cancelled. Only one side needs to dispute or propose a split for a milestone to pause and seek rectification.
Cancellation Rules
Milestone cancellation permissions vary by state:
PENDING: Unilateral cancellation (either party)
ACTIVE: Cannot be cancelled
FUNDED: Cannot be cancelled
IN_DISPUTE, PROPOSED_SPLIT, COMPLETED: Cannot be cancelled (must be resolved)
Value Update Capabilities
Milestone amounts and taxes can be updated in specific states by mutual consent:
PENDING, APPROVED: Simple value updates (no fund movement)
FUNDED: Smart fund adjustments (automatic transfers for increases/decreases)
Dispute Resolution Mechanisms
The system provides two-tier dispute resolution:
Tier 1 - Party Resolution:
Either party can dispute and propose a resolution percentage (0-100%), or revert back to FUNDED
The other party can approve the proposal
Dual-party resolution executes immediately when both agree
Reduces mediator workload for simple disagreements
Tier 2 - Mediator Resolution:
If both parties cannot agree on a resolution, a mediator will be responsible for resolving the dispute
Final authority on resolution percentage
Can choose resolution type: FINAL (which completes the milestone to RESOLVED) or CONTINUE (allow re-submission and puts state back to FUNDED)
Note that disputing a milestone will stop other interactions against that milestone until resolution.
Management
Following chart explains in details how to manage milestone states.
Last updated