Escrow Lifecycle
Understand the lifecycle of a Trustless Work V2 escrow, from configuration and funding through milestone updates, approval, release, or dispute resolution.
A Trustless Work escrow moves through a sequence of authorized actions.
The lifecycle separates three things that are often mixed together in payment workflows:
progress — what is happening
approval — whether agreed conditions have been satisfied
settlement — when funds are actually released
The core lifecycle is:
Initiation
Funding
Milestone Updates
Approval
Release
A dispute creates an alternative path before settlement:
Dispute Resolution
1. Initiation
The escrow is configured and created.
During initiation, you define:
escrow type
title and description
Engagement ID
asset / Trustline
roles
milestones
approval targets
amount and Receiver structure
Platform Fee
Admin
Observers
For Single Release, the protected amount and Receiver belong to the escrow.
For Multi Release, amounts and Receivers belong to individual milestones.
This phase establishes the agreement's authorization and settlement rules before funds are committed.
An important V2 principle is:
Configure first. Fund second.
Once funds are deposited, key roles and economic configuration become restricted.
2. Funding
Once created, the escrow can receive the configured asset.
Funding moves capital into the smart contract, where it remains protected by the escrow rules.
Funding can happen:
in one deposit
across multiple deposits
from a participant who does not hold an operational escrow role
The Funder does not automatically become:
an Approver
a Service Provider
a Release Signer
an Admin
a Receiver
Funding provides capital.
It does not authorize settlement.
3. Milestone Updates
Once work or another off-chain process is underway, authorized Service Providers can report progress.
They can update:
milestone status
milestone evidence
For example:
Or:
Status values are application-defined.
Trustless Work does not require a fixed workflow vocabulary.
The important distinction is:
A milestone status communicates progress. It does not approve payment.
V2 also supports updating multiple milestone statuses in one operation.
4. Approval
Approvers validate whether a milestone has satisfied its agreed condition.
V2 uses threshold approvals.
Each milestone defines:
which addresses may approve
how many approvals are required
which addresses have already approved
the current approval count
For example:
At that point, the milestone's approval requirement is satisfied.
Approval does not automatically move funds.
It makes the milestone eligible for the next settlement action when the rest of the contract conditions are satisfied.
V2 also supports approving multiple milestones in a batch.
5. Release
Release is the action that actually moves funds out of the escrow.
An authorized Release Signer executes settlement after the required approval and dispute conditions have been satisfied.
The behavior depends on the escrow type.
Single Release
All required milestones must satisfy their approval thresholds.
Then the protected amount is released as one settlement to the escrow Receiver.
Multi Release
Eligible milestones can be released independently.
A Release Signer can release:
one milestone
several eligible milestones in a batch
Each released milestone pays its configured Receiver.
Applicable Trustless Work and Platform fees are calculated during settlement.
Alternative path: Dispute
The happy path is:
But an authorized participant can open a dispute before settlement when the agreement is contested.
A V2 dispute includes a reason explaining why the dispute was opened.
Roles that may open disputes include authorized operational and economic participants, depending on the escrow type.
The Dispute Resolver cannot open the dispute.
That separation is intentional:
The party deciding the outcome should not also be the party initiating the dispute through the resolver role.
6. Dispute Resolution
Once a dispute exists, an authorized Dispute Resolver can determine how the disputed funds should be distributed.
Resolution is not limited to a binary outcome such as:
The resolver can define a distribution of the disputed amount among valid recipient addresses.
For example:
or another distribution representing the agreed resolution.
The dispute scope depends on the escrow type.
Single Release
The dispute applies to the entire escrow settlement.
Multi Release
Disputes apply to specific milestones.
That means a Multi-Release escrow can conceptually have:
without treating the entire escrow as one disputed settlement.
Lifecycle by escrow type
Initiation
Define one amount and Receiver
Define amount and Receiver per milestone
Funding
Fund protected settlement
Fund milestone-based settlement pool
Status
Update milestone progress
Update milestone progress
Approval
Each milestone reaches its threshold
Each milestone reaches its threshold
Release
One final payout
Independent or batched milestone payouts
Dispute
Escrow-wide
Milestone-specific
Resolution
Resolve protected settlement
Resolve selected disputed milestones
The lifecycle is not a rigid application workflow
Trustless Work enforces authorization and settlement conditions.
It does not require your application to expose these phases exactly as written.
For example, your application might have states such as:
Those can exist in your application while the underlying escrow only records the protocol state needed for settlement.
A useful rule is:
Do not confuse application workflow state with on-chain authorization state.
Your interface can be as simple or sophisticated as your use case requires, while the escrow remains responsible for the economic rules.
Core lifecycle principles
Keep these distinctions clear when designing an integration:
Funding ≠ control
Depositing assets does not automatically assign an operational role.
Status ≠ approval
Reporting that something is complete does not validate it.
Approval ≠ release
Accepting a milestone does not itself transfer funds.
Release ≠ arbitrary transfer
A Release Signer can only execute settlement when the contract's conditions are satisfied.
Dispute initiation ≠ resolution
The parties that can contest an outcome are deliberately separated from the role responsible for resolving it.
Related concepts
Next
Start with the first phase:
Last updated