> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/architecture-and-design-strategy.md). # Architecture & Design Strategy Understand how Trustless Work V2 fits into your application architecture, from SDKs and APIs to wallet signatures, Soroban contracts, indexing, and operational tools. Trustless Work is designed to be embedded into existing products. You do not need to move your entire application on-chain. Instead, Trustless Work provides a specialized settlement layer for the parts of your workflow that benefit from explicit authorization and programmable escrow: * holding protected funds * tracking settlement conditions * validating approvals * enforcing role permissions * handling disputes * executing releases Your application continues to own the surrounding product experience. > **Your application owns the workflow. Trustless Work enforces the escrow and settlement rules.** *** ## V2 is a hybrid architecture A typical Trustless Work integration combines: * your application or agent * Trustless Work SDKs or REST API * a user-controlled wallet * the Core API * Stellar and Soroban smart contracts * automatic indexing * your own application database and business logic Conceptually: ``` Your Application / Agent ↓ React SDK / JS SDK / REST / Blocks ↓ Trustless Work Core API v2 ↓ Unsigned Stellar Transaction ↓ Authorized Wallet Signs ↓ Stellar / Soroban ↓ Trustless Work Escrow Contract ↓ On-chain Events ↓ Automatic Indexer ↓ Core API Read Model ↓ Your Application ``` This separation lets you integrate blockchain settlement without turning your entire product into a blockchain application. *** ## Current V2 status Trustless Work Version 2 is currently: * **Beta** * **Stellar Testnet only** * **Not yet externally audited** The V2 Core API runs at: ``` https://beta.api.trustlesswork.com ``` Version 1 remains the current production/mainnet path. V2 integrations should therefore be treated as beta integrations until the production migration path is announced. [Open the V2 Developer Guide](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources) *** ## Architecture layers Trustless Work separates responsibilities across several layers. | Layer | Responsibility | | ------------------------ | ------------------------------------------------------------------------------------------------ | | **Your Application** | UX, business workflow, users, permissions outside the escrow, evidence collection, notifications | | **SDK / REST Layer** | Developer interface for creating and operating escrows | | **Core API v2** | Authentication, transaction construction, transaction submission, indexed reads | | **Wallet Layer** | Signs actions using the address authorized by the escrow | | **Smart Contract Layer** | Enforces escrow roles, approvals, disputes, release rules, and settlement | | **Indexer / Read Model** | Converts on-chain activity into application-friendly queryable data | | **Operational Tools** | Backoffice, Viewer, and supporting interfaces | Each layer has a different responsibility. Understanding those boundaries is important when designing an integration. *** ## Your application owns the workflow Trustless Work does not need to know your entire business process. For example, your application might manage: ``` Order Created ↓ Vendor Assigned ↓ Shipment Created ↓ Customs Cleared ↓ Delivery Confirmed ↓ Customer Review ``` The escrow may only need to represent: ``` Milestone status ↓ Approval ↓ Release ``` Your application can remain responsible for: * onboarding * identity * permissions outside the escrow * customer communication * internal workflow * evidence presentation * deadlines * notifications * analytics * compliance processes * dispute case management The smart contract should only own the economic rules that need deterministic enforcement. This is a core Trustless Work design principle: > **Keep the smart-contract primitive narrow. Build the business workflow above it.** *** ## Smart contracts own settlement enforcement The Soroban escrow contracts enforce the rules that determine how protected funds can move. These include: * authorized roles * milestone approval thresholds * release authorization * dispute state * dispute resolution authority * settlement amounts * Receivers * fees The contract does not determine whether a real-world delivery is good or bad. It determines whether the **authorized actions required for settlement have occurred**. For example: ``` Application determines: "Was the shipment actually delivered?" Approver determines: "I accept that delivery." Contract determines: "Has the required approval threshold been satisfied?" Release Signer determines: "Execute the eligible settlement." Contract executes: "Transfer funds according to the escrow rules." ``` This separation makes Trustless Work reusable across many industries without encoding industry-specific business logic into the escrow contracts. *** ## Core API v2 The Core API is the orchestration layer between applications and the escrow contracts. For write operations, the basic model is: ``` Application ↓ Core API builds transaction ↓ Wallet signs locally ↓ Transaction submitted ↓ Soroban executes ``` The Core API **does not sign escrow actions for the user**. It is a transaction builder and orchestration layer, not the holder of user signing authority. This preserves the non-custodial authorization model. [Explore the V2 REST API](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest) *** ## Wallet authority remains explicit An API key gives an application access to the Trustless Work developer infrastructure. It does **not** give that application permission to impersonate escrow roles. These are separate forms of authority: ``` API Key = access to integration infrastructure Wallet Signature = authorization to perform an escrow action ``` For example, an application may successfully authenticate with the Core API but still be unable to approve a milestone if the signing wallet is not one of the configured Approvers. The contract remains the final authority over role-based actions. [Get an API Key](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources/request-api-key) *** ## SDKs and integration surfaces V2 provides several ways to integrate the same underlying escrow infrastructure. ### React SDK Package: ``` @trustless-work/escrow ``` The React SDK provides hooks and client utilities for React and TypeScript applications. Use it when your product already has a React-based frontend and you want Trustless Work operations integrated directly into the application experience. [Explore the Escrow React SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-react-sdk) *** ### JavaScript SDK Package: ``` @trustless-work/escrow-js ``` The JS SDK is framework-agnostic. It is useful for: * Node.js services * backend integrations * scripts * non-React frontend applications * automation * agent systems [Explore the Escrow JS SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-js-sdk) *** ### REST API Applications can integrate directly with Core API v2 without using an SDK. This is appropriate when: * you use another language or framework * you want direct control over HTTP orchestration * you are building your own client abstraction * an agent or backend service needs direct API access [Explore the V2 REST API](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest) *** ### Escrow Blocks Escrow Blocks provide reusable UI components built on top of the React integration stack. They are useful when you want to accelerate implementation without building every escrow interface from scratch. Use Blocks when the provided components fit your application. Use the React SDK or JS SDK directly when you need deeper control over the UX. [Explore the Escrow Blocks SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-blocks-sdk) *** ## Reads and writes are different paths V2 deliberately separates operations from querying. ### Write path Actions that change escrow state use the transaction flow: ``` REST / SDK ↓ Unsigned transaction ↓ Wallet signature ↓ Stellar submission ↓ Contract execution ``` Examples include: * create * fund * update milestone status * approve * dispute * resolve * release *** ### Read path Applications can query escrow state through: * REST * GraphQL * supporting application interfaces Core API v2 automatically indexes on-chain escrow activity into its read model. Applications do not need the V1 manual `update-from-txHash` indexing flow. [Explore GraphQL](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/graphql) *** ## The blockchain and the read model The blockchain is the authoritative execution layer. The Core API read model is an indexed representation optimized for applications. That means there can be a short period where: ``` Transaction confirmed on Stellar ↓ Indexer processing ↓ API read model updated ``` Applications should expect this **eventual consistency**. A transaction succeeding on-chain before the API reflects the latest state does not necessarily mean the operation failed. *** ## Backoffice The **Backoffice** is an operational interface for interacting with Trustless Work without building every management screen yourself. It can support workflows such as: * developer configuration * API key management * escrow operations * testing * operational support A platform can use Trustless Work programmatically while still allowing internal teams to use Backoffice for selected operational tasks. For example: ``` Customer-facing application → creates escrows through SDK Operations team → handles exceptions through Backoffice ``` This can be useful during pilots and early integrations before every operational workflow has been built into the platform. [Explore Backoffice](https://docs.trustlesswork.com/trustless-work/v2-en/oss-dapps/backoffice) *** ## Escrow Viewer The **Escrow Viewer** provides a read-only way to inspect escrow state. The Viewer is intentionally independent from the Core API indexed read model and can inspect contract state through Stellar infrastructure. This makes it useful as a separate transparency and verification surface. Potential uses include: * transaction participants reviewing an escrow * support teams investigating state * partners verifying funds and roles * external stakeholders inspecting settlement * debugging indexed state against on-chain state [Explore the Escrow Viewer](https://docs.trustlesswork.com/trustless-work/v2-en/oss-dapps/escrow-viewer) *** ## Integration patterns There is no single required Trustless Work architecture. Different products can adopt different levels of integration. *** ### 1. Backoffice-assisted pilot Use Trustless Work operational tools before building a full product integration. For example: ``` Existing business process + Backoffice + Escrow contracts ``` Useful for: * validating a use case * running a pilot * learning the escrow lifecycle * testing role configurations * understanding operational requirements The goal should be to learn what actually needs to be automated before investing in deeper integration. *** ### 2. SDK-first application Integrate escrow directly into your product using the React or JS SDK. ``` Your Product ↓ Trustless Work SDK ↓ Core API ↓ Wallet ↓ Escrow Contract ``` Your users remain inside your application while Trustless Work handles the escrow infrastructure underneath. This is the typical path for product integrations. *** ### 3. Direct REST integration Integrate directly with Core API v2. ``` Your Backend / Agent ↓ REST API ↓ Wallet signing flow ↓ Soroban ``` This is useful when you need: * framework independence * custom infrastructure * server-side orchestration * agent integrations * another programming language *** ### 4. Hybrid application + Backoffice Use your application for the common user journey while using Backoffice for exceptional or internal workflows. For example: ``` Your Application Create Fund Status Approve Release + Backoffice Operations Support Exception handling ``` This often reduces MVP complexity. You do not need to build every administrative interface before proving the core user flow. *** ### 5. Application + Viewer Your application can expose escrow transparency without rebuilding a separate blockchain inspection interface. For example: ``` Marketplace order page ↓ "View escrow" ↓ Escrow Viewer ``` Your product owns the customer experience. The Viewer provides an independent inspection surface for the underlying escrow. *** ## Agents use the same authorization model An agent can interact with Trustless Work through the same infrastructure used by applications. For example: ``` Agent ↓ JS SDK / REST / MCP ↓ Transaction construction ↓ Authorized signing boundary ↓ Escrow Contract ``` Using an agent does not remove the contract's authorization requirements. An agent should only be able to perform actions for which it has been deliberately granted authority through the surrounding wallet and application architecture. For example, an agent might: * monitor evidence * update milestone status * prepare approval transactions * trigger settlement under predefined authority But the underlying escrow permissions remain the same. > **Automation changes who initiates the workflow. It does not bypass the trust model.** *** ## What Trustless Work does not replace Integrating Trustless Work does not eliminate every responsibility from your application. Depending on your product, you may still need to handle: * identity and authentication * KYC / KYB * sanctions screening * business-specific compliance * tax reporting * evidence storage * dispute operations * customer support * notifications * fiat on/off ramps * wallet UX * application permissions * analytics Trustless Work provides escrow infrastructure. It should not be treated as a replacement for every operational, compliance, or application-layer system surrounding a transaction. *** ## Security boundary Trustless Work reduces the amount of custom settlement infrastructure an integrator needs to build. That does **not** mean an integration has no security responsibilities. Integrators should still evaluate: * wallet security * role assignment * approval thresholds * signing flows * API credential management * application authorization * evidence integrity * dispute operations * contract version and network * production readiness V2 is currently beta and testnet-only. Do not treat beta deployment as equivalent to an audited production settlement environment. *** ## Design principle: keep responsibilities separate A robust integration keeps each responsibility in the layer best suited to enforce it. | Concern | Best layer | | ------------------------------- | ------------------------------ | | User experience | Application | | Business process | Application | | Off-chain evidence | Application / external storage | | Escrow roles | Smart contract | | Approval thresholds | Smart contract | | Release authorization | Smart contract | | Settlement | Smart contract | | Transaction construction | Core API / SDK | | Transaction signing | Authorized wallet | | Indexed reads | Core API | | Independent contract inspection | Viewer | | Operational support | Application / Backoffice | Avoid putting business complexity into the smart contract simply because it can be encoded on-chain. Likewise, avoid relying only on application permissions for actions that affect protected funds when the escrow contract can enforce those permissions directly. *** ## Example: marketplace integration Consider a marketplace that wants to add milestone-based stablecoin payments. The marketplace might own: ``` User accounts Job listings Messaging Delivery workflow Notifications Reviews ``` Trustless Work might own: ``` Escrow Roles Milestones Approval thresholds Dispute state Release authorization Settlement ``` The integration could be: ``` Marketplace UI ↓ React SDK ↓ Core API v2 ↓ Buyer / Operator wallet signature ↓ Soroban escrow ↓ Automatic indexing ↓ Marketplace UI ``` Internal operations could still use Backoffice when needed. Users could inspect the underlying escrow through the Viewer. The marketplace does not need to build its own escrow contracts, contract indexer, or settlement state machine. It still owns its product, business process, and security decisions around the integration. *** ## Core principle Trustless Work is infrastructure for embedding conditional settlement into applications. The architecture works best when you separate: ``` Business workflow ↓ Your application Transaction orchestration ↓ Trustless Work API / SDK Authorization ↓ Role wallet signatures Settlement enforcement ↓ Soroban escrow contracts Application-readable state ↓ Automatic indexing ``` The result is not a fully on-chain application. It is an application that uses **on-chain escrow where deterministic economic enforcement adds value**. *** ### Continue building [Open the Developer Guide](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/developer-resources) [Explore the V2 REST API](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest) [Explore the Escrow React SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-react-sdk) [Explore the Escrow JS SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-js-sdk) [Explore the Escrow Blocks SDK](https://docs.trustlesswork.com/trustless-work/v2-en/escrow-blocks-sdk) [Review Escrow Design](https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.trustlesswork.com/trustless-work/v2-en/introduction/technology-overview/architecture-and-design-strategy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.