Skip to content

Escrow Lifecycle

Home · Top · Table of Contents

Table of Contents

Kevin K. Le (LinkedIn) — Founder, Founding Engineer, and Current Lead Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon.

Kellen Snider — Founding Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon. His vision, ideas, and dedication during TrustLedger's Ethereum development were invaluable to the codebase we build on today.

See CREDITS.md.

This document explains TrustLedger escrow state transitions. Read it when reviewing user flows, testing lifecycle behavior, or integrating a client with TrustLedger.sol.

Statuses

Home · Top · Table of Contents

Status Meaning
PENDING A proposal exists but escrow funds have not been deposited.
ACTIVE Escrow funds are deposited and the freelancer can work.
SUBMITTED The freelancer submitted proof of work.
APPROVED The client approved work; the holdback remains in warranty.
DISPUTED Arbitration owns the outcome.
RESOLVED Funds were released or an arbitration ruling executed.
CANCELLED The proposal or escrow was cancelled before completion.

Freelancer-Proposed Flow

Home · Top · Table of Contents

Use this flow when the freelancer writes the offer and the client decides whether to fund it.

proposeContract
      |
      v
PENDING -- acceptContract --> ACTIVE -- submitProofOfWork --> SUBMITTED
   |                              |                              |
   |                              |                              +-- approveWork --> APPROVED
   |                              |                              |
   |                              |                              +-- disputeWork --> DISPUTED
   |                              |                              |
   |                              |                              +-- claimAfterAcceptanceWindow
   |                              |                                  --> RESOLVED
   |                              |
   |                              +-- claimAfterDeadlineMiss --> CANCELLED
   |
   +-- cancelProposal --> CANCELLED
   |
   +-- rejectContract --> CANCELLED

Proposal

Home · Top · Table of Contents

The freelancer calls proposeContract with a client address, amount, project duration, warranty period, contract hash, contract URI, token address, and optional previous contract ID. The function does not escrow funds. Native-token escrows use the zero address. ERC-20 escrows require a token that allowedTokens[token] already marks as allowed.

The contract stores a buffered deadline using MIN_BUFFER_FACTOR, which is 1100 basis points. That gives the freelancer 110 percent of the estimated duration.

Funding

Home · Top · Table of Contents

The client calls acceptContract. For native-token escrows, msg.value must equal the contract amount. For ERC-20 escrows, msg.value must be zero and the client must approve TrustLedger to transfer the escrow amount before calling.

Cancellation

Home · Top · Table of Contents

Before funding, the freelancer can call cancelProposal and the client can call rejectContract. Both paths move the escrow to CANCELLED.

Client-Proposed Flow

Home · Top · Table of Contents

Use this flow when the client writes the offer and the freelancer decides whether to accept it.

proposeContractByClient
      |
      v
PENDING -- acceptContractByFreelancer --> PENDING -- fundContractByClient --> ACTIVE
   |                                           |
   |                                           +-- rejectContractByFreelancer --> CANCELLED
   |
   +-- withdrawClientProposal --> CANCELLED

The client-proposed path is two-step acceptance plus funding. acceptContractByFreelancer marks the freelancer as accepted but does not take funds. fundContractByClient deposits funds and moves the escrow to ACTIVE.

Work Submission

Home · Top · Table of Contents

The freelancer calls submitProofOfWork from ACTIVE. The proof hash and proof URI are stored, and the escrow moves to SUBMITTED. The contract then waits for client approval, dispute, or the acceptance-window claim path.

Approval And Holdback

Home · Top · Table of Contents

The client calls approveWork from SUBMITTED. The contract pays the freelancer the escrow amount minus the holdback and moves to APPROVED. The holdback remains in escrow until the warranty period expires.

After the warranty deadline, the freelancer calls claimWarrantyFunds. That pays the holdback and moves the escrow to RESOLVED.

Deadline Claims

Home · Top · Table of Contents

Claim Caller State Result
claimAfterDeadlineMiss Client ACTIVE after project deadline Refunds escrow funds and cancels the contract.
claimAfterAcceptanceWindow Freelancer SUBMITTED after acceptance window Pays the freelancer and resolves the contract.
claimWarrantyFunds Freelancer APPROVED after warranty deadline Pays holdback and resolves the contract.

Disputes

Home · Top · Table of Contents

Either the client or freelancer can call disputeWork when the escrow is in a disputable state. The escrow moves to DISPUTED, and TrustLedger opens an arbitration dispute.

Native-token escrows carve the juror fee pool from escrowed funds. ERC-20 escrows require the caller to provide the ETH juror fee separately because the escrowed asset is not ETH.

Read Arbitration for the dispute flow.

Ratings

Home · Top · Table of Contents

After completion paths, submitRating lets each party rate the counterparty from 1 to 100. When arbitration executes a ruling, TrustLedger also records automatic low-score ratings in extreme outcomes:

  • Completion at least 80 records a low client score.
  • Completion at most 20 records a low freelancer score.

Ratings are sent to ReputationRegistry only after initReputationRegistry has configured that registry.

Authors and Contributors

Home · Top · Table of Contents

  • Kevin K. Le — Founder, Founding Engineer, and Current Lead Engineer (LinkedIn)
  • Kellen Snider — Founding Engineer (LinkedIn)

See CREDITS.md for the complete acknowledgement list.

Home · Top · Table of Contents

This document is part of TrustLedger, an open-source decentralized escrow and arbitration protocol. Use of this software and documentation is subject to the Terms and Conditions, Privacy Policy, and Risk Disclosure. See LEGAL.md for the full compliance and licensing overview.