> 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/dispute-resolution.md). # Dispute Resolution Understand how disputes are opened, scoped, and resolved in Trustless Work V2, including authorized disputers, Dispute Resolvers, and programmable fund distributions. Disputes provide an alternative settlement path when participants disagree about the outcome of an escrow. A dispute answers: > **Should the normal release path be stopped while this outcome is reviewed?** Resolution answers: > **How should the disputed funds ultimately be distributed?** These are deliberately separate actions performed by different authorities. ``` Dispute initiation = contest the settlement Dispute resolution = decide the economic outcome ``` *** ## Who can open a dispute? V2 allows several participants involved in the transaction to open a dispute. For **Single Release**, authorized disputers include: * Approvers * Service Providers * Platform * Release Signers * Receiver For **Multi Release**, authorized disputers include: * Approvers * Service Providers * Platform * Release Signers * the Receiver of the relevant milestone A milestone Receiver can only dispute milestones for which they are actually the Receiver. *** ## The Dispute Resolver cannot open disputes A **Dispute Resolver** is explicitly prevented from opening a dispute. This is an important authorization boundary: > **The role responsible for deciding the outcome cannot use that same role to create the dispute.** This separates: ``` Participant: "This settlement is contested." ``` from: ``` Dispute Resolver: "This is how the disputed funds should be distributed." ``` The same principle applies even when your application uses a platform team, arbitration service, governance system, or automated resolution mechanism. [Review Roles and Permissions](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work) *** ## A dispute requires a reason V2 requires the participant opening the dispute to provide a **reason**. For example: ``` Reason: "The delivered application does not include the authentication functionality defined in the agreement." ``` The reason becomes part of the dispute state. This gives participants and the Dispute Resolver context for understanding why the normal settlement path was interrupted. A dispute is therefore more than a boolean flag. Conceptually: ``` Dispute ├── is_disputed ├── reason └── resolved ``` *** ## When can a dispute be opened? A dispute can be raised while the relevant settlement remains unresolved. It does not require the milestone to have failed approval first. For example: ``` Work reported ↓ Dispute ``` or: ``` Work reported ↓ Approval collected ↓ Dispute ↓ Release blocked ``` The important boundary is settlement. A dispute cannot be opened after the relevant funds have already been released. A dispute also cannot be opened again once that dispute has already been resolved. *** ## What does a dispute block? The scope depends on the escrow type. ### Single Release A Single-Release dispute applies to the **entire escrow**. For example: ``` Milestone 1 → Approved Milestone 2 → Approved Milestone 3 → Approved Escrow → Disputed Normal final release → Blocked ``` Because Single Release has one economic settlement, the dispute affects that entire settlement. *** ### Multi Release A Multi-Release dispute applies to **specific milestones**. For example: ``` Milestone 1 Released Milestone 2 Disputed Milestone 3 Approved and eligible for release ``` The dispute on Milestone 2 does not automatically dispute Milestone 3. This preserves the independent settlement model of Multi Release. [Compare Escrow Types](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-types) *** ## Batch disputes Multi Release can dispute multiple milestones in one operation. For example: ``` Dispute milestones: [2, 4, 5] Reason: "Deliverables do not satisfy the agreed acceptance criteria." ``` Every selected milestone must be eligible for dispute. A milestone cannot be included if it has already been: * released * disputed * dispute-resolved If the signer is acting only because they are a milestone Receiver, every milestone in the batch must belong to that Receiver. *** ## A dispute does not freeze all informational activity Opening a dispute blocks the **normal release path**, but it does not make the escrow completely inactive. In V2, Service Providers can continue updating status and evidence while a dispute is open. For example: ``` Dispute opened ↓ Service Provider submits additional evidence ↓ Dispute Resolver reviews the updated information ↓ Resolution ``` This allows participants to add information that may help resolve the disagreement. Approval state also remains separate from dispute state. The critical economic restriction is that the disputed settlement cannot proceed through normal release. [Review Change Milestone Status](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/milestone-status-update) *** ## Who resolves the dispute? Only an address assigned to **Dispute Resolvers** can execute a resolution. V2 supports multiple Dispute Resolvers. For example: ``` Dispute Resolvers: Arbitrator A Arbitrator B Platform Resolution Service ``` An authorized resolver can execute the resolution transaction. The contract does not determine which party is morally or legally correct. It enforces the economic decision submitted by an authorized Dispute Resolver within the contract's resolution rules. For that reason, it is more accurate to think of the Dispute Resolver as a: > **designated resolution authority** rather than assuming that the role is inherently neutral. *** ## Resolution uses distributions V2 does not restrict dispute resolution to: ``` Pay Receiver ``` or: ``` Refund Funder ``` Instead, the Dispute Resolver provides a **distribution** containing addresses and amounts. For example: ``` Disputed amount: 1,000 USDC Resolution: 700 USDC → Service Provider 300 USDC → Client ``` Another outcome could be: ``` 500 USDC → Vendor A 300 USDC → Vendor B 200 USDC → Customer ``` This makes dispute resolution flexible enough to represent partial settlements and multi-party outcomes. *** ## Resolution amounts must fully account for the dispute Resolution is not an arbitrary partial withdrawal. The submitted distributions must account for the entire economic scope being resolved. ### Single Release The distribution total must equal the **entire current contract balance**. For example: ``` Contract balance: 10,000 USDC Distribution total required: 10,000 USDC ``` A resolution attempting to distribute only: ``` 8,000 USDC ``` would not satisfy the resolution requirement. Single Release resolves the economic outcome as one unit. *** ### Multi Release The distribution total must equal the combined amounts of the disputed milestones being resolved. For example: ``` Milestone 2: 2,000 USDC Milestone 4: 3,000 USDC Resolution scope: [2, 4] Required distribution total: 5,000 USDC ``` This resolves those milestones without requiring unrelated milestones to be settled at the same time. *** ## Fees still apply during dispute resolution Resolution does not bypass the escrow's fee model. The economic outcome still accounts for: * Trustless Work protocol fee * configured Platform Fee Conceptually: ``` Gross disputed amount - Trustless Work fee - Platform fee = Distributable amount ``` The current Trustless Work protocol fee is **0.30%**. The remaining amount is distributed proportionally according to the resolution submitted by the Dispute Resolver. This means a resolution distribution describes the intended allocation of the disputed economic value while the contract handles the applicable fees. *** ## Example: Single-Release dispute Consider a Single-Release Escrow: ``` Protected amount: 10,000 USDC Receiver: Development Studio ``` The client disputes the final delivery: ``` Reason: "Two required production integrations were not delivered." ``` Normal release is now blocked. After reviewing the agreement and evidence, the Dispute Resolver determines: ``` 7,000 USDC → Development Studio 3,000 USDC → Client ``` The resolution accounts for the entire disputed economic balance. After execution: ``` is_disputed = false resolved = true ``` The escrow has reached its dispute-resolution outcome. *** ## Example: Multi-Release dispute Consider a Multi-Release Escrow: | Milestone | Amount | State | | --------- | ---------: | ----------- | | Research | 1,000 USDC | Released | | Prototype | 2,000 USDC | Disputed | | Launch | 3,000 USDC | In progress | Only the Prototype milestone is disputed. The Dispute Resolver may decide: ``` Prototype amount: 2,000 USDC Resolution: 1,500 USDC → Development Team 500 USDC → Funder ``` After resolution: ``` Research → Released Prototype → Resolved Launch → Continues normally ``` The rest of the escrow does not need to be resolved as part of that dispute. *** ## Resolution is terminal for that settlement Once a dispute has been resolved, that economic obligation does not return to the normal release path. ### Single Release The escrow's dispute becomes resolved. The normal Single-Release payout cannot subsequently be executed. ### Multi Release The resolved milestone becomes terminal. That milestone cannot later be normally released as though no resolution had occurred. Other unresolved milestones continue independently. This prevents the same economic obligation from being settled twice. *** ## Resolution does not include a separate evidence field The V2 resolution transaction focuses on the economic outcome: * which disputed scope is being resolved * which addresses should receive value * how much is allocated to each address The dispute **reason** is recorded when the dispute is opened. Evidence can continue to be supplied through milestone evidence while the dispute remains open. The contract does not currently add a separate free-form resolution-evidence or reasoning field to the resolution transaction. If your application needs: * arbitrator notes * legal reasoning * case documents * attachments * supporting records those should be managed at the application layer and associated with the on-chain dispute or transaction. *** ## What happens on-chain? ### Opening a dispute When an authorized participant opens a dispute: 1. The contract verifies that the signer can dispute. 2. The relevant escrow or milestone state is validated. 3. The dispute reason is stored. 4. `is_disputed` becomes `true`. 5. A dispute event is emitted. 6. Normal release of that economic scope is blocked. *** ### Resolving a dispute When an authorized Dispute Resolver executes resolution: 1. The contract verifies the resolver. 2. The disputed scope is validated. 3. The distribution amounts are validated. 4. Applicable fees are calculated. 5. The dispute is marked resolved. 6. Funds are distributed according to the resolution. 7. A resolution event is emitted. The resulting transaction and distributions are publicly verifiable on Stellar. *** ## Leftover funds An escrow can sometimes contain funds after all of its economic obligations have already been processed. V2 includes a separate **withdraw remaining funds** mechanism for this situation. This is not the normal dispute-resolution operation. It is used only after the escrow has reached the required terminal state: * Single Release has been released or dispute-resolved, or * all Multi-Release milestones have been released or dispute-resolved An authorized Dispute Resolver can then distribute the remaining contract balance. This prevents surplus funds from becoming permanently stranded after the escrow's intended settlements are complete. *** ## Designing dispute resolution Before creating an escrow, decide: #### Who can contest? Which operational participants should be able to stop normal settlement? #### Who resolves? Who should have authority to determine the economic outcome? #### How independent should that authority be? Should the resolver be: * a platform team * a designated third party * an arbitration provider * a governance mechanism * another specialized resolution system #### What happens off-chain? The smart contract enforces the result. Your application may still need processes for: * collecting evidence * communicating between parties * setting review deadlines * documenting decisions * appeals or escalation * legal or compliance requirements Those are application-layer responsibilities unless explicitly encoded in the contract. *** ## Protocol resolution vs application arbitration Trustless Work provides the **settlement primitive** for disputes. It does not prescribe the entire arbitration system. The protocol provides: * explicit dispute authority * a required dispute reason * settlement blocking * designated resolution authority * programmable distributions * on-chain execution * auditable outcomes Your application determines: * how claims are reviewed * what evidence is required * how long review takes * whether humans or automated systems participate * what policies govern the decision A useful separation is: > **The application determines the resolution process. The escrow enforces the authorized economic outcome.** *** ## Output of Dispute Resolution After a dispute is successfully resolved: * the relevant dispute is no longer open * its state is marked resolved * the disputed economic value has been distributed * applicable fees have been applied * the resolution is recorded on-chain * that settlement cannot later execute through the normal release path For Multi Release, unaffected milestones can continue independently through their lifecycle. *** ### Related concepts [Escrow Lifecycle](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle) [Release Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/release-phase) [Approval Phase](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle/approval-phase) [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 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/dispute-resolution.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.