> 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.md).

# Escrow Design

Understand how Trustless Work V2 escrows combine roles, milestones, approvals, assets, and release conditions.

Trustless Work escrows are **programmable, non-custodial agreements**.

The smart contract does not decide whether work is good, whether a delivery is acceptable, or who should be trusted. Instead, it enforces the rules you configure:

* who can report progress
* who can approve milestones
* who can release funds
* who can manage the escrow configuration
* who can raise and resolve disputes
* where released funds go

A useful question when designing any escrow is:

> **Who must do what before money can move?**

This section describes **Trustless Work V2 contract semantics**. V2 introduces multi-address roles, threshold approvals, a dedicated Admin role, Observers, structured disputes, and batch milestone operations.

***

### Roles and permissions

Every escrow defines the addresses that are allowed to perform specific actions.

V2 separates these responsibilities deliberately.

#### Operational roles

* **Service Providers** report progress by updating milestone status and evidence.
* **Approvers** validate milestones by submitting approvals.
* **Release Signers** execute fund releases once the required conditions are satisfied.

These roles can contain **multiple addresses**, allowing applications to distribute authority instead of depending on a single wallet.

#### Administration

* **Admin** manages allowed escrow configuration changes and milestone configuration according to the contract rules.

The Admin role is separate from the economic role of the Platform.

#### Economic roles

* **Platform** represents the integrating platform, receives the optional platform fee, and can participate in specific protocol actions such as raising a dispute.
* **Receiver** is the final destination of released funds.

In a **Single-Release Escrow**, the receiver belongs to the escrow.

In a **Multi-Release Escrow**, each milestone can define its own receiver.

#### Dispute resolution

* **Dispute Resolvers** determine how disputed funds are distributed after a dispute has been opened.

Dispute Resolvers are intentionally **resolution-only authorities**. They cannot open the disputes they are responsible for resolving.

#### Visibility

* **Observers** are read-only addresses associated with an escrow for tracking and visibility. They do not receive execution authority.

Funding is different from holding a role. A funder can provide assets to an escrow without automatically becoming an Approver, Release Signer, or other operational participant.

[Learn more about Roles and Permissions](/trustless-work/v2-en/introduction/technology-overview/roles-in-trustless-work.md)

***

### What an escrow contains

Roles are only one part of the escrow configuration.

A V2 escrow combines several pieces of information:

* **Escrow ID / Contract ID** — the Soroban contract address identifying the escrow on-chain.
* **Engagement ID** — an external reference that connects the escrow to an order, invoice, project, agreement, or other application record.
* **Title and Description** — human-readable context for the agreement.
* **Roles** — the addresses authorized to perform specific actions.
* **Milestones** — the conditions, deliverables, or checkpoints being tracked.
* **Approvals** — the approval requirements and votes associated with each milestone.
* **Amount and Receivers** — how much can be released and where funds go.
* **Asset / Trustline** — the Stellar asset held by the escrow.
* **Platform Fee** — an optional fee configured by the integrating platform.
* **Release State** — whether funds have already been released.
* **Dispute State** — whether a dispute exists, why it was opened, and whether it has been resolved.

#### Threshold approvals

A key V2 change is that milestone approval is **not a simple true/false flag**.

Each milestone defines how many approvals it requires.

For example:

```
Approvers: Alice, Bob, Carol
Required approvals: 2

Alice approves → 1 / 2
Bob approves   → 2 / 2 → approval requirement satisfied
```

This allows applications to implement approval policies such as:

* 1 of 1
* 1 of 3
* 2 of 3
* 3 of 5

without changing the underlying escrow model.

[Learn more about Escrow Properties](/trustless-work/v2-en/introduction/technology-overview/what-does-a-smart-escrow-look-like.md)

***

### Two escrow types

Trustless Work supports two settlement patterns.

#### Single-Release Escrow

A Single-Release Escrow can contain multiple milestones, but funds are released in **one final payout**.

All required milestone approval conditions must be satisfied before the protected amount can be released.

Typical uses include:

* security deposits
* one-time service agreements
* final-delivery payments
* transactions where several checkpoints lead to one settlement

#### Multi-Release Escrow

A Multi-Release Escrow associates payments with individual milestones.

Each milestone can define its own:

* amount
* receiver
* approval state
* release state
* dispute state

Approved milestones can therefore be released independently or in batches without waiting for the entire agreement to finish.

Typical uses include:

* grants
* project phases
* milestone-based contracts
* progressive vendor payments
* multi-party payouts

|                     | Single Release           | Multi Release                     |
| ------------------- | ------------------------ | --------------------------------- |
| **Payment pattern** | One final payout         | Progressive payouts               |
| **Amount**          | Escrow-level             | Per milestone                     |
| **Receiver**        | Escrow-level             | Per milestone                     |
| **Release**         | Entire escrow            | Selected milestones               |
| **Dispute scope**   | Entire escrow            | Individual milestones             |
| **Best fit**        | One protected settlement | Staged or distributed settlements |

[Learn more about Escrow Types](/trustless-work/v2-en/introduction/technology-overview/escrow-types.md)

***

### Status, approval, and release are different

Trustless Work deliberately separates three concepts that applications often combine.

#### Status = communication

A Service Provider communicates what is happening.

Examples:

* In progress
* Ready for review
* Delivered
* PR merged
* Shipment received

A status is application-defined information. It does not authorize payment.

#### Approval = validation

An Approver confirms that an agreed condition has been satisfied.

In V2, multiple Approvers can participate and the milestone can require a configurable approval threshold.

Approval does not itself move funds.

#### Release = settlement

A Release Signer executes the movement of funds after the contract's approval and dispute conditions have been satisfied.

This separation lets applications build their own workflows while keeping economic authority explicit.

***

### Escrow lifecycle

A typical escrow follows five main phases:

1. **Design & Initiation** — define the agreement, roles, milestones, approval requirements, fees, asset, and receivers.
2. **Funding** — assets are deposited into the escrow.
3. **Milestone Updates** — Service Providers report progress and can attach evidence.
4. **Approval** — Approvers submit votes until the required threshold is reached.
5. **Release** — an authorized Release Signer executes settlement.

A dispute creates an alternative path before settlement:

```mermaid
flowchart TD
    A[Design & Initialize] --> B[Fund]
    B --> C[Update Milestones]
    C --> D[Submit Approvals]
    D --> E{Approval threshold met?}
    E -->|No| H[Dispute]
    E -->|Yes| F[Releasable]
    F --> G[Release]
    H --> I[Resolve Dispute]
```

Funding is an important boundary in the lifecycle.

While the escrow has no funds, the Admin can perform the configuration changes permitted by the contract. Once the escrow is funded, roles and key economic configuration are effectively frozen.

That makes configuration review **before funding** an important part of escrow design.

[Learn more about the Escrow Lifecycle](/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle.md)

***

### Design an escrow in four steps

Before integrating the API or SDK, work through these questions:

1. **Who has authority?**\
   Define the Service Providers, Approvers, Release Signers, Admin, Platform, Dispute Resolvers, Observers, and Receivers.
2. **What is being protected?**\
   Define the asset, amount, milestones, acceptance conditions, and fees.
3. **How should settlement happen?**\
   Choose between Single Release and Multi Release.
4. **What must happen before money moves?**\
   Define milestone progress, approval thresholds, release authority, and dispute behavior.

Then continue with:

* [Roles and Permissions](/trustless-work/v2-en/oss-dapps/offerhub-marketplace/roles-and-permissions.md)
* [Escrow Properties](/trustless-work/v2-en/introduction/technology-overview/what-does-a-smart-escrow-look-like.md)
* [Escrow Types](/trustless-work/v2-en/introduction/technology-overview/escrow-types.md)
* [Escrow Lifecycle](/trustless-work/v2-en/introduction/technology-overview/escrow-lifecycle.md)


---

# 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.md?ask=<question>&goal=<user_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.