trustless-work-dev

Trustless Work Development Skill

View on skills.sh

This skill provides comprehensive guidance for integrating Trustless Work escrow contracts into applications. Use the reference files below for detailed implementation guides.

Quick Start

Installation

Install this skill using:

npx skills add trustless-work/trustlesswork-skill

Protocol version — read this first

Trustless Work has two protocol versions, and they are not interchangeable.

• V1 is production and the default. It is the only version deployed on mainnet. Build every normal integration from skills/protocol/v1.md.
• V2 is beta and testnet-only. It is deployed on testnet, so you can build on it there — contract semantics in skills/protocol/v2.md, REST endpoints in skills/api/v2/, React SDK in skills/react-sdk/v2/, JS SDK in skills/js-sdk/ — but never on mainnet while it is beta, and never as the recommended production path. Say it is beta every time.
• Explaining V2 is always in scope. Answer any V2 question; the restriction is which network you target, not whether the user said "beta".
• Never mix them. Roles, payload shapes, approval semantics and lifecycle rules belong to one version at a time.
• If the version is ambiguous, use V1 and state which version you are describing.

Escrow type (single-release or multi-release) and protocol version are independent: there is a V1 and a V2 of each. Always know both before writing code.

When working with Trustless Work:

1. Know the platform laws — Read constitution.md before designing any escrow flow: the universal laws and the version-selection rule, each tagged as contract-enforced, canonical workflow, security practice, or versioned fact. Then load the profile for the version you are targeting.
2. Configure MCP (recommended) — See MCP Integration below for live docs and escrow tools
3. Understand core concepts - See skills/api/core-concepts.md
4. Choose escrow type:

• Single-release: One payment after all milestones - See skills/api/single-release-escrow.md
• Multi-release: Payments per milestone - See skills/api/multi-release-escrow.md

1. Configure trustlines - See skills/api/trustlines.md
2. Choose integration method:

• REST API: Direct API calls - See skills/api/ folder
• React SDK: Custom hooks for React/Next.js - See skills/react-sdk/react-sdk.md
• Blocks SDK: Pre-built UI components - See skills/blocks/introduction.md

1. Implement workflow: Deploy → Fund → Complete → Approve → Release

Gotchas

These are the non-obvious facts that the agent will get wrong without being told:

• `amount` is always a `number`: Across the entire V1 integration — deploy, fund-escrow, milestone amounts, and React SDK's FundEscrowPayload — send 1000, never "1000".
• `milestoneIndex` is always a string: Pass "0" not 0 — even though it looks numeric.
• Don't include `status` or `approvedFlag` in single-release milestone objects when deploying: Only description is valid on V1 Single Release deploy. Adding those fields causes errors.
• Header is `x-api-key`: Not Authorization: Bearer for the V1 API-key requirement. This is the single most common auth mistake.
• Single-release requires ALL milestones approved before any release: You cannot call release-funds until every milestone is individually approved. Multi-release allows per-milestone releases.
• Dispute distribution rules differ by escrow type: Single-release resolve-dispute distributions must sum exactly to the current escrow balance. Multi-release resolve-milestone-dispute distributions must be positive, must not exceed that milestone's amount, and must not exceed the contract balance — they do not have to equal the full balance.
• Fees are deducted from the escrow amount at release, not funded upfront: platformFee is a fee-rate configuration, not an extra amount to deposit. At release the contract computes the platform fee and the 0.3% Trustless Work protocol fee (mainnet) from the configured release amount and sends the remainder to the receiver.
• After funding, existing escrow state is frozen and only new milestones can be appended: Roles, configured amounts, platform fee, and existing milestones cannot be changed once the escrow has funds. Existing approved milestones do not by themselves prevent appending new unapproved milestones.
• `trustline.address` is always the issuer address (starts with G), never the escrow Soroban contract address in the V1 API payload shape described by this skill. USDC Testnet: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 — USDC Mainnet: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN.
• Trustlines are needed to hold or receive the asset: The depositor needs the trustline to fund, and every address that will receive tokens (receiver(s), platformAddress for fees, dispute-distribution addresses) needs it before funds reach them. Authority-only signatures don't require holding the asset. The v2 API enforces this at deploy/update time (ESCROW_RECEIVER_TRUSTLINE_MISSING) and reports a funder without the trustline as TOKEN_TRUSTLINE_MISSING. Read skills/api/trustlines.md if trustline errors occur.
• Role addresses may intentionally overlap: V1 permits the same address to hold multiple roles. Its effective authority is the combination of those role assignments, except explicit contract prohibitions (for example, an address assigned as disputeResolver cannot raise a dispute). Use separate addresses when the product requires separation of duties; it is not a contract requirement.
• React SDK: `useSendTransaction` is required after every write hook: Hooks return an unsigned XDR only. You must sign it and call sendTransaction — without this, nothing reaches the blockchain.
• React SDK: the `type` parameter must match the payload type: "single-release" expects SingleRelease*Payload; "multi-release" expects MultiRelease*Payload. Mismatching causes runtime errors.
• Use `validateOnChain=true` when querying before critical operations: Without it you may receive stale cached data. Always use it before release, dispute, or resolve calls.
• `engagementId` is an external reference, not a global uniqueness key: Integrators can use it to link an escrow to their own contract, sale, invoice, order, grant, or serial number. V1 does not enforce global uniqueness of this field.

Reference Files

Load these on demand — only when the task requires them:

Platform Laws

• Read [constitution.md](constitution.md) before designing any escrow flow or answering questions about what a role can or cannot do — the universal laws, the version-selection rule, API and network rules, with each statement tagged ENFORCED / CANONICAL / SECURITY / FACT and a source-of-truth hierarchy on top.

Protocol Profiles

• Read [skills/protocol/v1.md](skills/protocol/v1.md) for roles, lifecycle, payload rules and economics — the default for every integration.
• Read [skills/protocol/v2.md](skills/protocol/v2.md) only when the user explicitly asks for V2 or beta behavior.

REST API

• Read [skills/api/core-concepts.md](skills/api/core-concepts.md) for roles, lifecycle, flags, and auth details.
• Read [skills/api/types.md](skills/api/types.md) when you need TypeScript type definitions for payloads, responses, or errors.
• Read [skills/api/single-release-escrow.md](skills/api/single-release-escrow.md) when implementing any single-release endpoint (deploy, fund, approve, release, dispute, resolve, update).
• Read [skills/api/multi-release-escrow.md](skills/api/multi-release-escrow.md) when implementing any multi-release endpoint.
• Read [skills/api/trustlines.md](skills/api/trustlines.md) when trustline errors occur, when setting up new accounts, or when the user asks about tokens/assets.

REST API — V2 (beta, testnet only)

• Read [skills/api/v2/core-concepts.md](skills/api/v2/core-concepts.md) first for the v2 role model, trustline forms, type rules and what changed from V1.
• Read [skills/api/v2/single-release.md](skills/api/v2/single-release.md) when implementing any single-release v2 endpoint.
• Read [skills/api/v2/multi-release.md](skills/api/v2/multi-release.md) when implementing any multi-release v2 endpoint.

React SDK — V2 (beta, testnet only)

• Read [skills/react-sdk/v2/react-sdk.md](skills/react-sdk/v2/react-sdk.md) when integrating @trustless-work/escrow 5.x: provider setup, the build/sign/submit loop, every hook, and the new GraphQL hooks.

JavaScript SDK — V2 (beta)

• Read [skills/js-sdk/js-sdk.md](skills/js-sdk/js-sdk.md) when the integration is not React — Node, NestJS, Angular, browser, scripts. @trustless-work/escrow-js is framework-agnostic, zero-dependency, and V2-only.

React SDK

• Read [skills/react-sdk/react-sdk.md](skills/react-sdk/react-sdk.md) for SDK setup, provider config, and hook overview.
• Read [skills/react-sdk/hooks-reference.md](skills/react-sdk/hooks-reference.md) for complete parameter docs and examples of any specific hook (useInitializeEscrow, useFundEscrow, useApproveMilestone, useReleaseFunds, useStartDispute, useResolveDispute, useUpdateEscrow, useChangeMilestoneStatus, useWithdrawRemainingFunds, useSendTransaction).
• Read [skills/react-sdk/vibe-coding.md](skills/react-sdk/vibe-coding.md) when scaffolding a full React/Next.js integration from scratch (contains global rules, step-by-step guides, and AI workflow context).

Blocks SDK (pre-built UI)

• Read [skills/blocks/introduction.md](skills/blocks/introduction.md) for installation and SDK overview.
• Read [skills/blocks/vibe-coding.md](skills/blocks/vibe-coding.md) when scaffolding a Blocks integration from scratch.
• Read [skills/blocks/components.md](skills/blocks/components.md) for available UI components.
• Read [skills/blocks/providers.md](skills/blocks/providers.md) for provider setup and context API.
• Read [skills/blocks/hooks.md](skills/blocks/hooks.md) for TanStack Query hooks.

API Base URLs

• Mainnet: https://api.trustlesswork.com
• Testnet: https://dev.api.trustlesswork.com
• Swagger (Mainnet): https://api.trustlesswork.com/docs
• Swagger (Testnet): https://dev.api.trustlesswork.com/docs

All endpoints require: x-api-key: YOUR_API_KEY header

Rate limit: 50 requests per 60 seconds

Common Transaction Flow

1. Call API endpoint → Get unsigned XDR transaction
2. Sign with the signer authorized for that operation → Create signed XDR
3. Submit via /helper/send-transaction → Broadcast to Stellar
4. Verify on-chain → Query with validateOnChain=true

MCP Integration

Pair this skill with the Trustless Work MCP servers for live documentation and escrow operations. Setup guide: https://docs.trustlesswork.com/trustless-work/ai/mcp

Add both servers to mcp.json in the project root (Cursor → Settings → MCP → Add New MCP Server):

{
  "mcpServers": {
    "trustlesswork-docs": {
      "type": "streamable-http",
      "url": "https://docs.trustlesswork.com/trustless-work/~gitbook/mcp",
      "headers": {}
    },
    "trustlesswork": {
      "type": "streamable-http",
      "url": "https://mcp.trustlesswork.com/mcp",
      "headers": {}
    }
  }
}

Docs MCP tools (use in Agent Mode when reference files don't cover a topic):

• mcp__trustless-work__searchDocumentation — search documentation for any topic
• mcp__trustless-work__getPage — retrieve a specific documentation page

Prefer local reference files in skills/ first; fall back to MCP when you need the latest docs or a topic not covered here.

If MCP tools are unavailable, remind the user to install both servers, enable Agent Mode, and confirm Connected status under Settings → MCP.

Resources

• Trustless Work Documentation
• MCP Setup Guide
• Backoffice
• Escrow Lab
• Escrow Blocks
• Swagger (Mainnet)