Skip to content

SKILL.md

Latest commit

 

History

History
217 lines (180 loc) · 7.51 KB

SKILL.md

File metadata and controls

217 lines (180 loc) · 7.51 KB
Error in user YAML: (<unknown>): did not find expected key while parsing a block mapping at line 1 column 1
---
name: trustless-work
description: Integrate Trustless Work Escrow-as-a-Service (EaaS) for stablecoin escrow on Stellar. Use when building escrow flows, marketplace payments, milestone-based funding, freelance platforms, grant disbursements, or implementing non-custodial payment systems with USDC.
argument-hint: [action] [escrow-type]
allowed-tools: Read, WebFetch, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs
---

Trustless Work - Escrow-as-a-Service Integration

Build non-custodial escrow flows with milestones, approvals, and disputes on Stellar (Soroban).

Quick Start

What is Trustless Work?

  • Escrow-as-a-Service (EaaS) for stablecoin escrow (primarily USDC on Stellar)
  • Non-custodial smart contracts with programmable release logic
  • Role-based permissions and milestone tracking
  • REST API and React SDK available

Key Resources:

Core Concepts

Escrow Types

  1. Single-Release: Multiple milestones, one payout (best for simple jobs, deposits)
  2. Multi-Release: Multiple milestones, multiple payouts (best for grants, staged projects)

See escrow-types.md for detailed comparison.

Roles System

Every escrow assigns these roles to specific addresses:

  • Service Provider: Delivers work, marks milestones complete
  • Approver: Validates milestone completion
  • Release Signer: Executes fund releases
  • Dispute Resolver: Arbitrates conflicts, can re-route funds
  • Receiver: Final destination of funds
  • Platform Address: Platform itself, collects fees, configures escrow

See roles-reference.md for full permissions matrix.

Escrow Lifecycle

  1. Initiation → Define schema, roles, amounts, milestones
  2. Funding → Lock assets via Stellar trustline
  3. Milestone Updates → Service provider marks progress
  4. Approval → Approver signs off on milestones
  5. Release → Release signer triggers transfer
  6. (Optional) Dispute Resolution → Resolver steps in if needed

See lifecycle-guide.md for detailed phase breakdown.

Common Use Cases

When to use Trustless Work:

  • Building a freelance/gig marketplace with milestone payments
  • Implementing escrow for e-commerce or service platforms
  • Creating grant platforms with staged funding
  • Security deposits for rentals/bookings
  • Crowdfunding with conditional payouts
  • B2B tools using USDC for global settlement

Integration Options

REST API

Base URLs:

Key endpoints:

  • POST /escrow/single-release - Create single-release escrow
  • POST /escrow/multi-release - Create multi-release escrow
  • POST /escrow/{escrowId}/fund - Fund an escrow
  • POST /escrow/{escrowId}/milestone/{milestoneId}/update - Update milestone
  • POST /escrow/{escrowId}/approve - Approve milestones
  • POST /escrow/{escrowId}/release - Release funds
  • GET /escrow/{escrowId} - Get escrow details

See api-reference.md for complete endpoint documentation.

React SDK

npm install @trustless-work/react-sdk

Key hooks:

  • useCreateEscrow() - Create new escrow
  • useFundEscrow() - Fund an escrow
  • useUpdateMilestone() - Update milestone status
  • useApproveEscrow() - Approve milestones
  • useReleaseEscrow() - Release funds

Escrow Blocks SDK

Pre-built UI components for common escrow flows.

Quick Examples

Create Single-Release Escrow

const escrow = {
  engagementId: "order-123",
  title: "Website Development",
  description: "Build marketing website",
  roles: {
    approver: "G...CLIENT",
    serviceProvider: "G...FREELANCER",
    releaseSigner: "G...PLATFORM",
    platformAddress: "G...PLATFORM",
    disputeResolver: "G...RESOLVER",
    receiver: "G...FREELANCER"
  },
  amount: 1000,
  platformFee: 0.5, // 0.5% platform fee
  milestones: [
    { description: "Homepage design", status: "Pending", approved: false },
    { description: "Full website deployment", status: "Pending", approved: false }
  ],
  trustline: {
    address: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5" // USDC
  }
};

Create Multi-Release Escrow

const escrow = {
  engagementId: "grant-456",
  title: "Research Grant",
  description: "Funding in two phases",
  roles: {
    approver: "G...FUNDER",
    serviceProvider: "G...RESEARCHER",
    releaseSigner: "G...PLATFORM",
    platformAddress: "G...PLATFORM",
    disputeResolver: "G...RESOLVER"
  },
  platformFee: 0.5,
  milestones: [
    {
      description: "Interim report",
      amount: 500,
      status: "Pending",
      flags: { approved: false, released: false, disputed: false, resolved: false },
      receiver: "G...RESEARCHER"
    },
    {
      description: "Final report",
      amount: 500,
      status: "Pending",
      flags: { approved: false, released: false, disputed: false, resolved: false },
      receiver: "G...RESEARCHER"
    }
  ],
  trustline: {
    address: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
  }
};

See examples.md for more complete code examples.

Important Notes

Stellar Trustlines

  • All participants must have the trustline enabled for the asset (e.g., USDC)
  • USDC on Stellar: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
  • Without trustline, transactions will fail

Fees

  • Trustless Work Protocol Fee: 0.3% (automatic)
  • Platform Fee: Configurable percentage (set by you)
  • Total deduction: Protocol fee + Platform fee

Wallet Compatibility

  • Recommended: Freighter (non-custodial)
  • Supported: Any Stellar wallet with trustline support
  • Not supported: Some custodial exchanges (e.g., Binance) can't send to contract addresses

Testing

Task Instructions for $ARGUMENTS

When user requests help with Trustless Work:

  1. Understand the use case: What type of escrow flow do they need?
  2. Choose escrow type: Single-Release or Multi-Release?
  3. Define roles: Which addresses will have which permissions?
  4. Design milestones: What needs to be completed? How many stages?
  5. Select trustline: USDC or another Stellar asset?
  6. Set platform fee: What percentage should the platform earn?
  7. Provide code examples: Use the API or SDK based on their stack
  8. Guide through lifecycle: Explain what happens at each phase
  9. Reference supporting docs: Point to specific guides as needed

Additional Resources

Support

For questions or feature requests: