Welcome to the Smart Escrow Design section.

To simplify the design process, we have subdivided the escrow lifecycle into distinct phases. Click on any phase to learn more:

Initiation phase

Funding phase

Milestone Status Updates

Approval phase

Release phase

Dispute Resolution phase

Each phase plays a crucial role in the lifecycle, and each participating party has one or more defined roles.

To understand how roles interact accross the lifecycle, visit the Roles in Trustless Work

Figma Template for Escrow Design

Start designing your escrow configurations visually using our Figma template. Feel free to copy it and accelerate your Go To market by correctly planning your Trustless Work integration!

https://www.figma.com/community/file/1456840320155816764/trustless-design-framework

By having a clear understanding of the roles and their function throughout the escrow lifecycle, it will be way easier to adapt the flow to your use case.

Only addresses who have a role assigned to them will be able to write and update to escrow.

Reading the escrow configuration, status, and transaction history does not require an assigned role.

Roles, Parties, and Fees in Trustless Work

• Roles: Each role pays a clear functions or action within the escrow flow. (e.g., approving milestones, releasing payments).

• Parties: Parties are entities or individuals assigned to one or more roles (e.g., buyer, seller, platform). The parties interact through a stellar wallet, from which they will sign any interactions they have with the escrow.

• Platform: you can also set a platform addresss, which is the address that will receive the platform fee. This fee is configured in the contract and calculated at each payment release. This is an optional additional fee collected by a platform, distinct from the Trustless Work fee which is not optional (for now).

Roles:

1. Milestone Approver

• Function: Approves or disputes milestones marked as completed by the milestone marker.

• Examples:

  • Buyer in a freelance marketplace approves the deliverable marked as done by the freelancer.

  • Host in a security deposit scenario approves the checkout marked as done by the turist.

  • Platform in a crowdfunding campaign approves milestone marked as done by the company.

2. Milestone Marker

• Function: Delivers the product, service, or objective set on milestine. Marks milestones as completed and ready for approval.

• Examples:

  • Freelancer delivering a service and marking it as done.

  • Company updating crowdfunding milestones and marking as done.

  • Compliance department marking a withdraw complaince check as done.

  • Real Estate inspector maks the house inispections as done.

3. Release Signer

• Function: Approves the release of funds for the amount set.

• Examples:

  • Airbnb (platform) releasing a deposit.

  • eBay (platform) releasing payment to a seller.

  • DAO releasing a payment to a contributor

4. Dispute Resolver

• Function: Resolves disputes by adjusting milestone amounts, updating status, or canceling the contract.

• Examples:

  • Platform (eBay, Airbnb) acting as arbiter for a deposit because turist broke something redirecting deposit to host.

  • Independent third-party arbitrator setting a new milestone price for an project milestone.

  • Cenceling an escrow amount and redirecting funds back to Client.

5. Receiver

• Function: The final recipient of funds after conditions are met or disputes are resolved.

• Examples:

  • Freelancer receiving payment.

  • Turist receiving a security deposit.

  • Company receiving funds

6. Platform Address

• Function: An address designated to receive the platform fee, a percentage or fixed amount of the total funds processed through escrow.

• Examples:

  • Airbnb collecting platform fees.

  • Crowdfunding platform taking a fee from funds raised.

1. Trustline The contract address of the token being used on the escrow. Can be any asset issued on Stellar network.

The escrow lifecycle represents the structured flow of actions and responsibilities involved in securely managing a transaction. At Trustless Work, we break this lifecycle into clear, logical phases, ensuring transparency and adaptability for diverse use cases.PreviousRoles, Parties, and Fees in Trustless Work

Core Phases of the Escrow Lifecycle

1. Initiation Phase: The foundation of the process, where roles, responsibilities, and transaction terms are established, and the escrow contract is created. Learn More

2. Funding Phase: The phase where the funds are deposited into the escrow contract, securing the transaction and preparing for the next steps.

3. Milestone Updates Phase: As the transaction progresses, milestones are marked as completed by the designated party, providing visibility and enabling reviews.

4. Approval Phase: The phase where milestones are reviewed and approved (or disputed), moving the transaction closer to resolution.

5. Release Phase: Funds are released to the designated recipient based on milestone approvals or dispute resolutions, completing the financial component of the transaction.

6. Closure Phase: Marks the official end of the escrow process, ensuring all conditions are met, funds are distributed, and the contract is finalized.

Alternative Phases in the Escrow Lifecycle

In some scenarios, the lifecycle may include additional phases to address unique circumstances:

1. Dispute Resolution Phase: Engaged when there are disagreements between parties, this phase ensures fairness by resolving disputes and determining the final outcome.

2. Escrow Cancellation Phase: Allows for the early termination of the escrow contract under specific conditions, ensuring any funds or fees are appropriately handled.

The Milestone Status Update Phase is where the Milestone Marker signals progress by marking a milestone as completed. This step is critical for keeping all participants informed about the transaction's progress and prepares the milestone for review by the Milestone Approver in the subsequent Approval Phase.

Key Actions

1. Milestone Marker Updates Milestone Status

• The Milestone Marker logs into the platform or uses the Trustless Work API to update the milestone status to For Review, he signs the transaction, signaling the completion of the deliverable.

2. Escrow Contract Updates

• Upon the signed update, the escrow contract:

  • Changes the milestone status to For Review.

  • Retains the Approved Flag as False until explicitly approved or disputed by the Milestone Approver.

3. Notification to Milestone Approver

• The platform detects the status update and notifies the Milestone Approver that the milestone is ready for review.

4. Transparency for All Participants

• All participants, including the Milestone Marker, Release Signer, and Platform Address, can view the updated milestone status:

  • On-chain via the transaction ID or Stellar block explorer.

  • Through the Escrow Viewer or by querying the Trustless Work API.

Key Metadata

1. Milestone Status:

   • For Review: Indicates the milestone is ready for approval or dispute.

2. Approved Flag:

   • Default = False: Remains unchanged until explicitly approved or disputed by the client.

3. Progress Details (to be added):

   • Optional fields can include:

     • Delivery notes.

     • Evidence of completion (e.g., reference IDs or uploaded documentation).

Key Notes

• Blockchain Visibility: All participants can view the updated milestone status on-chain, ensuring transparency and traceability of progress.

• Platform Notifications: The platform plays a key role in notifying the client (Alice) about the milestone update, facilitating smooth communication.

• Optional Progress Details: The service provider can add supporting details or documentation (e.g., delivery receipts, tracking numbers) to enhance transparency.

Phase Outcomes

1. Milestone Progress Recorded:

   • The service provider’s update is recorded on-chain, ensuring transparency and traceability.

2. Client Notified for Review:

   • The client (Alice) is notified to review the milestone and take action in the next phase.

3. Escrow Contract Reflects Progress:

   • The escrow contract’s milestone status is updated, preparing the transaction for the Approval Phase.

The Funding Phase is where funds are deposited into the escrow smart contract, signaling the formal commitment of all parties to the transaction. This phase ensures the financial security of the agreement, builds trust among participants, and sets the stage for the remaining phases.

Key Actions

1. Depositing Funds

• Anyone with a Stellar wallet and funds in the configured currency can deposit to the escrow smart contract.

• The escrow contract address is the Escrow ID (Contract ID) generated during the Initiation Phase.

2. Escrow Contract Updates

• Upon deposit, the escrow contract:

  • Updates the balance to reflect the deposited amount.

  • Emits a blockchain Deposit Event, notifying all participants of the successful funding.

3. Verification by Participants

• All participants, including the Milestone Marker, Release Signer, and Platform Address, can independently verify the transaction using:

  • The transaction ID (e.g., tx123abc) on the Stellar network and Stellar block explorer.

  • The Escrow Viewer provided by Trustless Work.

  • A direct request to the Trustless Work API using the Escrow ID.

Key Notes

• Blockchain Transparency: All participants can independently verify the funding status using the transaction ID on-chain.

• Stellar Integration Flexibility: Any Stellar Anchor (on/off-ramp) can be seamlessly integrated to fund the escrow, allowing for global accessibility and currency flexibility.

• Escrow Balance Updates: Participants calculate funding status off-chain by comparing the balance with the agreed amount.

• Platform's Role: The platform provides updates to participants.

Outcomes of the Funding Phase

1. Funds Held On-Chain:

   • The deposited amount is securely held in the escrow smart contract, ensuring safety and transparency.

2. Participant Verification:

   • All participants can verify the funding details using the on-chain transaction ID, building trust and confidence.

3. Trust Reinforced:

   • The client’s deposit demonstrates their commitment to the transaction, fostering trust with the service provider.

The Initiation Phase is the foundation of the escrow process. It ensures that all necessary details are captured, roles are assigned, and conditions are clearly defined. This phase lays the groundwork for a secure, transparent, and efficient transaction.

Participants and Roles

In the initiation phase key roles are assigned to specific parties. These roles determine responsibilities and actions throughout the transaction.

The roles are:

1. Milestone Approver: Approves or disputes milestones.

2. Milestone Marker: Marks milestones as completed and ready for approval.

3. Release Signer: Approves the release of funds for completed milestones.

4. Dispute Resolver: Resolves disputes and adjusts milestone statuses if necessary.

5. Receiver: The final recipient of funds once conditions are met.

6. Platform Address: An address designated to receive the platform fee.

Parties: Parties are entities (e.g., buyer, seller, platform) assigned to fulfill one or more roles based on the use case. You can learn more about how this can work for different use cases later on.

Other escrow properties configuredin this phase:

• Engagement ID

  • Definition: A customizable identifier that links the escrow to an external system or reference, such as a UUID, Order ID, or Invoice ID.

• Amount: The total funds to be held in escrow.

• Platform Fee: A fixed or percentage-based fee for the platform’s services, in bps.

• Milestones: Defined deliverables or outcomes that are tracked and verified throughout the process.

• Trustline: The Contract address of the Token used for the escrow.

Process Steps

Step 1: Configuring Terms

• Parties and Address are configured at a platform level. All parties agree on the transaction terms, including:

  • Deliverables or milestones.

  • Payment amounts and structure.

  • Roles and responsibilities.

Step 2: Recording Metadata

• The platform records escrow details, assigns an Engagement ID for their own tracking, platform fee, platform address, trustline, and prepares to deploy the escrow contract.

Step 3: Initializing the Escrow

• Using the Trustless Work API, the platform deploys the escrow contract with the configured terms.

• Upon deployment:

  • A unique Escrow ID (Contract ID) is generated and returned to all parties for reference. Funds of the approved trustline can be deposited to the escrow ID.

Example Scenario: Freelance Marketplace (e.g., Upwork)

• Engagement ID: Order_12345 links the escrow to the platform's order system.

• Escrow ID: Generated by the Soroban network as 0xABC123....

• Roles Assigned:

  • Milestone Approver: Client.

  • Milestone Marker: Freelancer.

  • Release Signer: Upwork.

  • Dispute Resolver: Upwork.

  • Receiver: Freelancer.

  • Platform Address: Upwork (receiving platform fees).

• Outcome: The escrow contract is initialized with:

  • Clear roles and responsibilities.

  • Transparent milestone and payment structures.

  • A shared understanding among all parties.

Outcome of the Initiation Phase

1. A smart escrow contract is successfully created and ready for the transaction.

2. Roles, parties, and conditions are clearly defined and documented.

3. Engagement and Escrow IDs provide traceability and clarity.

4. All participants have full visibility, fostering trust and reducing potential disputes.

Escrow ID (Contract ID)

The escrow ID is what we are going to use as address to deposit funds in the next phase. Anyone can send funds to an escrow, as long as it is the accepted token (Trustline is set).

• Definition: A unique identifier automatically generated by the Soroban network when the escrow smart contract is deployed.

• Purpose: Serves as the primary identifier for the escrow contract on the blockchain.

The Approval Phase is where the Milestone Approver evaluates the milestone marked as For Review by the Milestone Marker. This critical step determines whether the milestone is approved or disputed, dictating the next steps in the escrow process and transitioning the transaction toward completion or resolution.

Key Actions

1. Milestone Approver Reviews the Milestone

• The Milestone Approver evaluates the deliverable or service associated with the milestone, referencing any supporting evidence or details provided by the Milestone Marker.

2. Decision: Approve or Dispute

• Approve:

  • If satisfied, the Milestone Approver approves the milestone.

  • The Approved Flag is updated to True, signaling that the transaction can proceed toward the Release Phase.

• Dispute:

  • If concerns arise, the Milestone Approver disputes the milestone.

  • The Approved Flag is updated to On Dispute, pausing the transaction and escalating it to the Dispute Resolver.

Next Steps: the approved / dispute flag determines what Next step on the excrow lifecycle is enabled.

If the milestone is approved, the Release is possible,

If a dispute is raised, the dispute resolver must set a resolution and either update the amount, or cancel the milestone.

Key Metadata

1. Milestone Status

• For Review: Indicates the milestone is under review by the Milestone Approver.

• On Dispute: Set when the milestone is disputed, triggering resolution by the Dispute Resolver.

2. Approved Flag

• True: Set when the Milestone Approver approves the milestone.

Key Notes

• Milestone Approver Authority: The Milestone Approver has sole authority to approve or dispute milestones, ensuring their satisfaction with the deliverable.

• Platform's Role: The platform facilitates the review process by providing tools and notifications to assist the Milestone Approver.

• On-Chain Transparency: All participants, including the Milestone Marker, Release Signer, and Platform Address, can track the milestone’s status and associated decisions on-chain.

• Dispute Escalation: Disputes trigger the transaction to enter the Dispute Resolution Phase, ensuring fair and transparent resolution before proceeding.

The Dispute Resolution Phase is triggered when the client (e.g., Alice) raises a dispute during the Approval Phase. This phase involves a thorough review by the designated dispute resolver (e.g., the platform, Marketplace) to determine how the funds should be allocated. The escrow contract remains in a locked state, with no funds released, until the dispute is resolved.

Key Actions

1. Raising a Dispute:

   • The client (Alice) identifies issues with the milestone deliverable and raises a dispute.

   • Evidence or supporting documentation (e.g., screenshots, contracts, delivery notes) is submitted to the dispute resolver.

   • The escrow contract updates:

     • Milestone Status: Set to In Dispute.

     • Approved Flag: Updated to reflect the dispute status.

2. Dispute Resolver Review:

   • The dispute resolver (Marketplace) reviews the case, including:

     • Evidence provided by the client.

     • Responses or counter-evidence from the service provider (Bob).

   • The resolver makes a decision on fund allocation (e.g., full refund to client, partial payment to service provider).

3. Escrow Contract Updates:

   • Based on the resolver’s decision, the escrow contract is updated with:

     • Resolver Decision: Details of the resolution.

     • Updated Amounts: Adjustments to the escrowed funds (e.g., splitting funds, issuing a refund).

4. Final Approval and Resolution:

   • The resolver sets the Final Approval Flag to True, enabling the transaction to proceed to the Release Phase.

   • The escrow emits an event, notifying all participants of the resolution.

Key Metadata

1. Milestone Status:

   • In Dispute: Indicates the milestone is under review by the dispute resolver.

2. Dispute Details:

   • Captures the client’s reason for raising the dispute, supported by evidence.

3. Resolver Decision:

   • Contains the final decision, including updated allocations of funds.

4. Updated Amounts:

   • Reflects any changes to the original escrowed amount based on the resolution.

5. Final Approval Flag:

   • Set to True once the dispute is resolved, enabling the transition to the Release Phase.

Key Notes

• Transparency and Fairness: The dispute resolver ensures a neutral and unbiased resolution process, with all decisions recorded on-chain.

• Evidence-Based Decisions: Supporting documentation and evidence are critical to the resolution process, providing clarity for all parties involved.

• Locked State: While in dispute, the escrow contract prevents any unauthorized release of funds, safeguarding all participants.

Phase Outcomes

1. Resolution Achieved:

   • Funds are allocated according to the dispute resolver’s decision, ensuring a fair outcome for both parties.

2. Escrow Prepared for Release:

   • The Final Approval Flag is set, enabling the transaction to transition to the Release Phase.

3. Dispute Transparency Ensured:

   • All resolution details, including fund adjustments and final decisions, are recorded and visible to participants.

The Release Phase is initiated when the Release Signer approves the release of funds. This triggers the escrow smart contract to perform verification checks, deduct fees, and securely disburse funds to the Receiver. The escrow is then marked as completed, concluding the transaction.

Key Actions

1. Triggering the Release

• The Release Signer signs the release transaction, signaling the intent to disburse funds.

• The escrow smart contract initiates the release process.

2. Verification of Milestones

• The escrow smart contract verifies:

  • All milestones have their Approved Flag set to True.

  • No milestones are in a disputed state (Approved Flag ≠ On Dispute).

3. Fee Deductions

• Upon successful verification, the escrow contract calculates and deducts:

  • The Platform Fee (e.g., Marketplace fee%) as configured during the Initiation Phase.

  • The Trustless Work Fee (e.g., 0.3%).

4. Funds Disbursement

• The remaining funds are transferred to the Receiver Address designated during the Initiation Phase

5. Completion

• The escrow contract is marked as Completed, signaling the successful conclusion of the transaction.

Key Metadata

1. Release Signer

• The entity responsible for triggering the release by signing the transaction.

2. Milestone Approval Check

• Confirms that:

  • All milestones are approved (Approved Flag = True).

  • No unresolved disputes exist.

3. Fee Deductions

• Platform Fee Deduction: Calculated and deducted from the total escrowed amount.

• Trustless Work Fee Deduction: A fixed percentage (e.g., 0.3%) is deducted for using the Trustless Work infrastructure.

4. Receiver Address

• The blockchain address of the Receiver, who will receive the funds (e.g., Freelancer, Host, Company).

5. Release Transaction ID

• A blockchain reference (e.g., tx456def) for the release action, ensuring traceability and transparency.

Phase Outcomes

1. Funds Transferred Securely

• The Receiver (e.g., Freelancer, Host) receives the funds, minus the Platform Fee and Trustless Work Fee.

2. Escrow Marked as Completed

• The escrow status is updated to Completed, reflecting the transaction's successful conclusion.

3. Transparency Maintained

• All participants can trace the release process on-chain using the Release Transaction ID, ensuring full visibility and trust.