> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fundwork.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Planned Escrow Design

> The intended smart-contract escrow lifecycle, state machine, and design principles for Fundwork's production payment architecture.

<Warning>
  Fundwork escrow is part of the planned production payment architecture. The alpha should not be interpreted as offering fully deployed non-custodial escrow unless explicitly stated. This page describes the intended design and the principles guiding it.
</Warning>

Escrow is one of the most sensitive components of any paid-work marketplace. Getting it wrong can lock funds, enable theft, or create resolution problems that can only be untangled by hand. This page lays out how Fundwork intends to approach escrow, what the state machine will look like, and the principles the contract design will follow.

## Intended Escrow Lifecycle

The planned high-level lifecycle for an escrow-backed opportunity is:

<Steps>
  <Step title="Client creates a funded opportunity">
    The client posts an opportunity that requires committed funds. The required USDC amount is deposited into an escrow contract.
  </Step>

  <Step title="Funds are associated with the opportunity">
    The deposited USDC becomes associated with a specific opportunity or milestone. The contract records which opportunity the funds are earmarked for.
  </Step>

  <Step title="Worker completes work">
    A worker is selected (contracts) or self-selects (bounties, campaigns) and completes the work.
  </Step>

  <Step title="Work is submitted">
    The worker submits the deliverable. The submission is recorded and, where applicable, the associated onchain state advances.
  </Step>

  <Step title="Client approves or challenges">
    The client approves the submission or opens a dispute. Approval triggers a release path; a dispute pauses release until the dispute is resolved.
  </Step>

  <Step title="Approved funds are released to the worker">
    On approval, the contract releases the earmarked USDC to the worker's payout address.
  </Step>

  <Step title="Platform fee is distributed">
    Any platform fee that applies is distributed according to protocol rules at release time.
  </Step>

  <Step title="Unused or refundable funds are handled">
    Unused, cancelled, or refundable funds are returned according to the opportunity's terms.
  </Step>
</Steps>

## Intended State Machine

The following states are the planned surface for an escrowed opportunity or milestone. Actual naming may change in the final contract implementation.

| State     | Meaning                                                                        |
| --------- | ------------------------------------------------------------------------------ |
| Created   | The opportunity exists but funds have not yet been committed.                  |
| Funded    | USDC has been deposited into escrow and earmarked.                             |
| Active    | Work is in progress.                                                           |
| Submitted | The worker has submitted a deliverable pending review.                         |
| Approved  | The client has approved. Release is authorized.                                |
| Disputed  | Either party has opened a dispute. Release is paused.                          |
| Released  | Funds have been paid out to the worker.                                        |
| Refunded  | Funds have been returned to the client.                                        |
| Cancelled | The opportunity was cancelled before completion, with fund handling per terms. |

State transitions will be explicit and constrained. There is no path, for example, from **Released** back to **Active**.

## Design Principles

The escrow contract will be designed against a set of principles. These are guardrails on how the system is allowed to behave.

### Fundwork should not be able to move funds arbitrarily

Release conditions must be defined by the contract, not by platform discretion. Fundwork operators should not have the ability to pull funds out of escrow for any reason not encoded in the contract's release logic.

### Release conditions should be explicit

Every way that funds leave escrow (release to worker, refund to client, fee distribution) will be a specific, named path with clearly defined preconditions.

### State transitions should be deterministic

For a given contract state and input, the resulting state is fully determined by the contract logic. There should be no code paths whose outcome depends on off-chain trust.

### Funds should not become permanently locked

Every reachable state must have at least one path out that eventually resolves funds to a legitimate party. "Stuck escrow" with no resolution path is a design failure.

### Emergency procedures should be narrowly scoped

Any emergency mechanism (for example, pausing new deposits during a discovered vulnerability) should have the smallest scope needed to address the problem, be time-bounded where possible, and be documented publicly.

### Admin capabilities should be minimized

Privileged roles should exist only where strictly necessary and should have the smallest possible surface. Multi-signature approval and time delays are appropriate for privileged actions that must exist.

### Upgradeability, if used, must be documented

If the contract uses any upgrade pattern, the pattern will be documented explicitly, including who can upgrade, under what constraints, and how users can verify the current implementation.

### Reentrancy protection

Release and refund paths that transfer tokens will use appropriate reentrancy protection so that a malicious recipient cannot re-enter and drain the contract.

### Stablecoin transfer edge cases

USDC is well-behaved, but the contract will still be designed to handle standard ERC-20 edge cases safely: return-value handling, allowance changes, and the possibility of transfer failure.

<Note>
  Fundwork does not claim any specific escrow implementation is finalized. The above are the design constraints the eventual implementation will be measured against.
</Note>

## Why Not Launch with Complicated Escrow Immediately?

A reasonable question is why Fundwork does not simply ship a full escrow contract on day one.

The answer is that direct settlement reduces smart-contract risk during alpha while core marketplace behavior is validated. Escrow contracts hold real user funds; every additional line of contract code is additional surface for bugs, misconfigurations, and economic edge cases.

Escrow should only be introduced once:

* The contract architecture has been designed against the principles above.
* The full state machine, including failure modes, has been reviewed.
* The dispute process that governs contested releases is defined.
* A comprehensive test suite is in place. See [Smart Contract Testing](/technical/smart-contract-testing).
* An independent security review of the contracts has been performed. See [Security](/technical/security).

Launching escrow before those conditions are met would trade a known small risk (marketplace behavior in alpha) for a much larger risk (unreviewed contracts holding user funds).

## Status

<CardGroup cols={2}>
  <Card title="Currently available" icon="circle-check">
    Direct settlement of approved work in USDC on Base, verified server-side. See [Payment Architecture](/technical/payment-architecture).
  </Card>

  <Card title="Planned before public launch" icon="clock">
    Escrow contract design, state machine specification, test suite, and independent security review before production deployment.
  </Card>

  <Card title="Under evaluation" icon="flask">
    Specific fee distribution mechanics, milestone-level escrow structuring, and emergency procedures.
  </Card>

  <Card title="Future" icon="telescope">
    Production escrow deployment and integration with dispute resolution paths.
  </Card>
</CardGroup>