> 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/approval-phase.md). # Approval phase Validate milestone completion in Trustless Work V2 using multiple Approvers, threshold approvals, batch operations, and explicit authorization. The **Approval Phase** is where authorized Approvers validate that a milestone has satisfied its agreed conditions. Approval answers: > **Has this milestone met the conditions required for settlement?** It is different from both progress reporting and payment execution. ``` Status = communication Approval = validation Release = settlement ``` A Service Provider can report that work is complete. An Approver decides whether that work satisfies the agreement. A Release Signer executes settlement once the contract conditions allow it. *** ## V2 uses threshold approvals V1 represented milestone approval as a simple boolean: ``` approved = true ``` V2 replaces that model with an **approval structure**. Each milestone tracks: * **target** — how many approvals are required * **approval count** — how many authorized Approvers have approved * **approved by** — which addresses submitted those approvals For example: ``` Approvers: Alice Bob Carol Target: 2 Approved by: Alice Approval count: 1 / 2 ``` When Bob approves: ``` Approved by: Alice Bob Approval count: 2 / 2 ``` The milestone has now satisfied its approval requirement. *** ## Who can approve? Only addresses configured in the escrow's **Approvers** role can submit approvals. V2 supports multiple Approvers. For example: ``` Approvers: Alice Bob Carol David ``` A milestone can then define how many of those Approvers are required. Examples: * 1 of 1 * 1 of 4 * 2 of 3 * 3 of 5 The approval target cannot exceed the number of configured Approvers. [Review Roles and Permissions](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work) *** ## Each Approver can approve once An authorized Approver can contribute **one approval per milestone**. For example: ``` Target: 2 Alice approves → 1 / 2 ``` Alice cannot approve the same milestone again to produce: ``` Alice Alice → 2 / 2 ``` The contract records the Approver addresses that have already voted and rejects duplicate approval attempts. This means the threshold represents participation from distinct authorized addresses. *** ## Approval is irreversible Once an Approver has submitted an approval, V2 does not provide an `unapprove` operation. The approval becomes part of the milestone's state. For example: ``` Alice approves Bob approves 2 / 2 ``` The application should not later present that milestone as though those blockchain approvals never occurred. If the business workflow needs concepts such as: ``` Changes Requested Revision Required Reopened ``` those can exist at the application or milestone-status layer. They should not be represented as fake reversal of an on-chain approval. *** ## Status does not control approval Approval does not depend on a specific status string. For example: ``` Status: Ready for Review ``` can be followed by approval. But technically: ``` Status: In Progress ``` does not automatically prevent an authorized Approver from approving if they believe the agreed condition has already been satisfied. Trustless Work deliberately keeps: * status * approval * settlement authorization as separate concepts. This allows the application to define its own workflow while the contract enforces the economic permissions. [Review Change Milestone Status](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/milestone-status-update) *** ## Batch approvals V2 supports approving multiple milestones in a single operation. Instead of signing: ``` Approve Milestone 1 Approve Milestone 2 Approve Milestone 3 ``` as three separate operations, an authorized Approver can approve a set of milestone indices together. Conceptually: ``` Approve milestones: [1, 2, 3] ``` The Approver signs once, and their approval is recorded against each valid milestone in the batch. This is useful for: * grant programs * project reviews * bulk verification * operational dashboards * automated policies * agent-assisted workflows Each milestone still maintains its own approval count and approval target. *** ## Example: different milestones, same Approver set Assume the escrow has: ``` Approvers: Alice Bob Carol ``` #### Milestone 1 ``` Target: 1 Alice approves → 1 / 1 → Approval requirement satisfied ``` #### Milestone 2 ``` Target: 2 Alice approves → 1 / 2 Bob approves → 2 / 2 → Approval requirement satisfied ``` #### Milestone 3 ``` Target: 3 Alice approves Bob approves Carol approves → 3 / 3 → Approval requirement satisfied ``` The same escrow can therefore require different levels of consensus for different milestones. *** ## Approval in Single Release In a **Single-Release Escrow**, each milestone has its own approval requirement. But the escrow has one final settlement. For example: ``` Milestone 1 2 / 2 approvals Milestone 2 1 / 1 approval Milestone 3 2 / 2 approvals ``` Once **every required milestone has reached its approval target**, the escrow satisfies the approval condition for final release. The Release Signer can then execute the Single-Release payout, assuming the other contract conditions are also satisfied. A milestone reaching its own threshold does not release part of the funds. Single Release still produces **one settlement**. [Review Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) *** ## Approval in Multi Release In a **Multi-Release Escrow**, each milestone has its own settlement. Once a milestone reaches its approval target, that milestone becomes eligible for release independently of the others, subject to the remaining contract conditions. For example: ``` Milestone 1 2 / 2 → Ready for release Milestone 2 1 / 2 → Not yet ready Milestone 3 3 / 3 → Ready for release ``` Milestones 1 and 3 can move toward settlement without waiting for Milestone 2. Eligible milestones can also be released together in a batch. *** ## Approval does not release funds Reaching the approval threshold does not itself move funds. For example: ``` Approvals: 2 / 2 Released: false ``` This is a valid state. The milestone has satisfied its approval requirement, but a Release Signer must still execute settlement. This separation is intentional. The Approvers answer: > **Should this milestone be accepted?** The Release Signers answer: > **Should the authorized settlement now be executed?** Those responsibilities can be held by different participants. *** ## Approver + Release Signer V2 also supports workflows where the same address intentionally holds both roles. For example: ``` Alice: Approver + Release Signer ``` In that configuration, V2 provides an **approve-and-release** operation. This allows the authorized signer to combine: ``` Approve + Release ``` into one transaction when the contract requirements are satisfied. This is useful for workflows where separating the two signatures provides little additional value. For example: * simple marketplace transactions * automated settlement policies * trusted operational workflows * constrained agent execution The address must genuinely hold **both permissions**. Being an Approver alone does not grant release authority. Being a Release Signer alone does not grant approval authority. *** ## Approval and disputes remain separate Approval does not eliminate the dispute mechanism. A milestone can have approval activity while dispute state remains a separate contract concern. Most importantly: > **Approval cannot be used to bypass an active dispute during settlement.** Release logic still checks the relevant dispute state before funds can move. This separation is useful because approval history and dispute history represent different facts: ``` Approval: An authorized participant accepted the milestone. Dispute: An authorized participant contested the settlement. ``` Both can matter when understanding what happened in an agreement. *** ## Approval is an authorization signal, not a status label Applications should avoid treating strings like: ``` "Approved" "Accepted" "Complete" ``` as substitutes for actual approval state. For example: ``` status = "Approved" approval_count = 0 target = 2 ``` means the milestone is **not approved at the protocol level**. Conversely: ``` status = "Under Review" approval_count = 2 target = 2 ``` means the approval requirement **has** been satisfied, regardless of the status label. When deciding whether settlement is allowed, use the actual approval structure. *** ## What happens on-chain? When an authorized Approver submits an approval: 1. The contract verifies that the signer belongs to `approvers`. 2. The milestone indices are validated. 3. The contract verifies that the Approver has not already approved those milestones. 4. The Approver address is added to each milestone's `approved_by` list. 5. The approval count is updated. 6. The updated escrow state is stored. 7. An approval event is emitted. The event provides an auditable record of which Approver authorized which milestones. *** ## When is a milestone approved? The rule is simple: ``` approval_count >= target ``` If: ``` approval_count = 1 target = 2 ``` the requirement is not satisfied. If: ``` approval_count = 2 target = 2 ``` the requirement is satisfied. Applications should derive approval state from this relationship rather than recreating the old V1 boolean model. *** ## Example Consider a grant milestone. #### Configuration ``` Milestone: Deliver audited prototype Approvers: Foundation Technical Reviewer Program Manager Target: 2 ``` #### First approval The Technical Reviewer accepts the deliverable: ``` Approved by: Technical Reviewer Approval count: 1 / 2 ``` The milestone is not yet ready for settlement. #### Second approval The Program Manager approves: ``` Approved by: Technical Reviewer Program Manager Approval count: 2 / 2 ``` The milestone has now satisfied its approval requirement. If this is: * **Single Release** — all other milestones must also satisfy their requirements before final settlement. * **Multi Release** — this milestone can now move independently toward release. *** ## Output of the Approval Phase After the required approvals are collected: * authorized Approver signatures are recorded * the milestone's approval count reflects those approvals * the milestone has satisfied its configured threshold * approval history remains auditable * no funds have necessarily moved yet * release authority remains with the Release Signers The next phase is settlement. [Continue to the Release Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/release-phase) *** ### Related concepts [Escrow Lifecycle](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle) [Change Milestone Status](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/milestone-status-update) [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) [Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) --- # 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/approval-phase.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.