> 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/milestone-status-update.md). # Change Milestone Status Report milestone progress and evidence in a Trustless Work V2 escrow without confusing status updates with approval or settlement. The **Change Milestone Status** phase is how Service Providers communicate progress. A milestone can represent work, delivery, compliance, verification, or any other condition your application needs to track. Status updates answer: > **What is happening with this milestone right now?** They do **not** answer: > Has the milestone been approved? And they do **not** move funds. That separation is fundamental to the Trustless Work lifecycle: ``` Status = communication Approval = validation Release = settlement ``` *** ## Who can update milestone status? Only an address assigned to the escrow's **Service Providers** role can update milestone status. V2 supports multiple Service Providers. For example: ``` Service Providers: Alice Bob Automation Service ``` Any authorized Service Provider can submit a valid milestone status update. Other roles do not gain this permission automatically. Being an: * Approver * Release Signer * Platform * Admin * Observer * Dispute Resolver does not by itself grant permission to change milestone status. [Review Roles and Permissions](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work) *** ## Status is application-defined Trustless Work does not impose a fixed list of statuses. Your application decides what the status means. A development workflow might use: ``` Not Started ↓ In Progress ↓ Ready for Review ↓ Delivered ``` A logistics workflow might use: ``` Order Received ↓ Packed ↓ In Transit ↓ Delivered ``` A grant program might use: ``` Not Started ↓ Evidence Submitted ↓ Under Review ↓ Completed ``` The contract enforces **who can update the status**. Your application defines **what the status means**. *** ## Status does not control approval A status string is not an approval condition. For example: ``` status = "Completed" ``` does not mean: ``` approval requirement satisfied ``` An Approver must still submit an actual approval through the approval operation. Likewise: ``` status = "Ready for Review" ``` does not prevent an Approver from approving if they are already satisfied that the milestone conditions have been met. Status and approval intentionally remain independent. This gives applications freedom to design their own workflow without turning every application state into a protocol rule. *** ## Adding evidence A milestone status update can also include **evidence**. Evidence gives the Service Provider a way to associate proof or context with the progress being reported. Examples include: * pull request URL * delivery receipt * shipment tracking link * audit result * IPFS reference * transaction reference * external application record * signed document reference For example: ``` Status: Ready for Review Evidence: https://example.com/deliverables/final-build ``` Trustless Work stores the evidence value as part of the milestone state. The application decides what that value represents and how users should interpret it. *** ### Updating status without replacing evidence Evidence is optional during an update. A Service Provider can change the status while leaving the existing evidence unchanged. Conceptually: ``` Existing: Status: In Progress Evidence: https://example.com/work-v1 ``` Then: ``` Update: Status: Ready for Review Evidence: unchanged ``` This lets applications update workflow state without repeatedly submitting the same evidence. *** ## Batch milestone updates V2 supports updating multiple milestones in a single operation. Instead of: ``` Update Milestone 1 Sign Update Milestone 2 Sign Update Milestone 3 Sign ``` an application can submit several milestone updates together: ``` Update: Milestone 1 → Ready for Review Milestone 2 → Delivered Milestone 3 → In Progress ``` The authorized Service Provider signs the batch as one operation. This is useful for: * project management workflows * automated integrations * grant programs * bulk delivery verification * agent-driven workflows Each update still identifies the milestone being changed and its new status. *** ## Funding and status are separate concepts Funding is the normal lifecycle step before work begins, but V2 does not define milestone status as a balance condition. The contract's status-update authorization is based on: * the Service Provider role * the milestone being valid * the milestone's current terminal state This means applications should not use status as a substitute for determining whether an escrow is funded. If your workflow requires: > “Do not allow work to begin until the escrow is fully funded” that rule should be enforced by your application using the escrow's funding state. The protocol concepts remain separate: ``` Funding = capital committed Status = progress reported ``` [Review the Funding Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/funding-phase) *** ## Status can continue after approval Approval does not automatically freeze milestone status. A milestone may already satisfy its approval threshold while additional workflow information is still useful. For example: ``` Status: Delivery Accepted Approvals: 2 / 2 Later status: Preparing Final Handoff ``` The important settlement condition remains the actual approval state, not the status text. This is another reason applications should avoid treating values such as `"Approved"` or `"Completed"` as protocol authorization. *** ## Status and evidence during a dispute V2 deliberately allows status and evidence updates while a dispute is still open. This can be important because new information may help resolve the disagreement. For example: ``` Milestone disputed ↓ Service Provider adds new evidence ↓ Dispute Resolver reviews updated information ↓ Resolution ``` Opening a dispute therefore does not automatically freeze the milestone's informational state. The terminal boundary comes later. *** ## When updates become frozen Status and evidence cannot remain editable forever. Once settlement reaches a terminal outcome, the relevant state becomes frozen. ### Single Release In a Single-Release Escrow, milestone status and evidence can no longer be changed once: * the escrow has been released, or * the escrow's dispute has been resolved Because Single Release has one economic outcome, the terminal state applies to the escrow as a whole. *** ### Multi Release In a Multi-Release Escrow, the restriction is milestone-specific. A milestone can no longer have its status or evidence changed once that milestone: * has been released, or * has had its dispute resolved Other milestones can continue through their own lifecycle independently. For example: ``` Milestone 1 Released → status frozen Milestone 2 Dispute open → evidence can still be updated Milestone 3 In Progress → status can still be updated ``` This matches the independent settlement model of Multi Release. [Compare Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) *** ## What happens on-chain? When an authorized Service Provider submits a valid update: 1. The contract verifies the Service Provider's authorization. 2. The requested milestone indices are validated. 3. The new status is stored. 4. Evidence is updated when new evidence is provided. 5. The updated escrow state is stored on-chain. 6. A milestone status event is emitted. The event records which milestone changed and its new status. When evidence changes, V2 events include a cryptographic hash of the evidence value, allowing the event history to prove which evidence content was associated with the update without duplicating the full text in the event payload. *** ## Application workflow vs protocol state Your product will often need richer workflow states than the escrow itself. For example: ``` Draft ↓ Assigned ↓ Work Started ↓ Revision Requested ↓ Resubmitted ↓ Accepted ``` Not every state needs to become a new smart-contract primitive. Trustless Work gives you: * configurable status * evidence * approval * dispute * release Your application can build richer workflows above those primitives. A useful design rule is: > **Keep application workflow in the application unless it needs to affect economic authorization.** *** ## Example Consider a software development milestone. #### Initial state ``` Description: Deploy production application Status: In Progress Evidence: None Approvals: 0 / 2 ``` The Service Provider deploys the application and updates the milestone: ``` Status: Ready for Review Evidence: https://github.com/example/project/releases/v1.0 ``` The escrow now communicates: > The Service Provider says the deliverable is ready and has provided supporting evidence. It does **not** yet communicate: > The deliverable has been accepted. That happens in the Approval Phase. *** ## Output of this phase After a milestone status update: * the escrow reflects the latest reported progress * optional evidence can support that progress * the update is authorized by a Service Provider * the change is recorded on-chain * approval state remains independent * no funds have moved The milestone can now move toward validation by its Approvers. [Continue to the Approval Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/approval-phase) *** ### Related concepts [Escrow Lifecycle](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle) [Funding Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/funding-phase) [Roles and Permissions](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work) [Escrow Properties](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/what-does-a-smart-escrow-look-like) --- # 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/milestone-status-update.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.