> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle.md). # 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: 1. **Initiation** 2. **Funding** 3. **Milestone Updates** 4. **Approval** 5. **Release** A dispute creates an alternative path before settlement: 6. **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. [Read the Initiation Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/initiation-phase) *** ## 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. [Read the Funding Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/funding-phase) *** ## 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: ``` In Progress ↓ Ready for Review ``` Or: ``` Order Packed ↓ Shipped ↓ Delivered ``` 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. [Read Change Milestone Status](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/milestone-status-update) *** ## 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: ``` Approvers: Alice Bob Carol Required approvals: 2 Alice approves → 1 / 2 Bob approves → 2 / 2 ``` 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. [Read the Approval Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/approval-phase) *** ## 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. [Read the Release Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/release-phase) *** ## Alternative path: Dispute The happy path is: ``` Initiation → Funding → Progress → Approval → Release ``` 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: ``` Pay Receiver or Refund Funder ``` The resolver can define a distribution of the disputed amount among valid recipient addresses. For example: ``` 70% → Service Provider 30% → Client ``` 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: ``` Milestone 1 → Released Milestone 2 → Disputed Milestone 3 → In Progress ``` without treating the entire escrow as one disputed settlement. [Read Dispute Resolution](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/dispute-resolution) *** ## Lifecycle by escrow type | Phase | Single Release | Multi Release | | -------------- | ------------------------------------ | ---------------------------------------- | | **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: ``` Draft Awaiting Delivery Under Review Changes Requested Accepted Paid ``` 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 [Review Roles and Permissions](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work) [Review Escrow Properties](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/what-does-a-smart-escrow-look-like) [Compare Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) *** ### Next Start with the first phase: [Continue to Initiation](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/initiation-phase) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.