Orchestrator

The Orchestrator is the central engine of OFFER-HUB. It coordinates every step of a transaction — from the moment a buyer deposits USDC to the moment a seller withdraws funds — enforcing rules, managing state, and communicating with the Stellar blockchain so your marketplace never has to.

What is the Orchestrator

The Orchestrator is a state machine-driven backend service that sits between your marketplace and the Stellar blockchain. It is responsible for:

• Managing buyer and seller internal balances
• Locking funds into Soroban smart contracts via Trustless Work
• Enforcing valid escrow state transitions
• Emitting real-time events on every state change
• Handling dispute resolution and refund flows

Your marketplace communicates with the Orchestrator via REST API. The Orchestrator handles everything on-chain.

API and background jobs

The API in apps/api serves the REST API and processes BullMQ background jobs in the same service. The separate apps/worker package is deprecated; do not deploy it as a second required process.

Architecture Overview

Marketplace requests enter the Orchestrator, which coordinates ledger, escrow, events, and idempotency work.

This view is verified against apps/api/src/modules/orders/orders.controller.ts, its dto/create-order.dto.ts, and apps/api/src/modules/events/event-catalog.ts in the Orchestrator repository; those files define the REST boundary, order input, and emitted domain events represented here.

Key Components

Balance Ledger — tracks available and reserved balances for every user. All operations are atomic to prevent double-spending.

Escrow Engine — manages the lifecycle of each escrow from creation to settlement or dispute, enforcing valid state transitions.

SSE Event Stream — emits a domain event on every state change so your marketplace can react in real time.

Idempotency Key Store — caches responses to prevent duplicate operations when requests are retried.

How it Processes Transactions

Every transaction follows the same linear flow:

1. Buyer Deposits

The buyer sends USDC to their assigned Stellar address. The Orchestrator detects the on-chain payment and credits the buyer's available balance.

2. Order Created

The buyer places an order. Funds move from available to reserved in the internal ledger — no longer spendable but not yet on-chain.

const order = await client.orders.create({
  buyer_id: "usr_123",
  seller_id: "usr_456",
  amount: "75.00",
  idempotency_key: "550e8400-e29b-41d4-a716-446655440004",
})

3. Escrow Funded On-Chain

The Orchestrator signs and submits a Stellar transaction that locks the USDC into a Soroban smart contract via Trustless Work. The escrow state moves to FUNDED.

4. Work is Delivered

Your marketplace manages communication, deliverables, and reviews. The Orchestrator waits.

5. Settlement

The buyer approves the delivery. The Orchestrator submits transactions to release USDC from the smart contract to the seller's Stellar address.

const release = await client.orders.release('ord_789', 'Work approved');

6. Seller Withdraws

The seller requests a withdrawal. The Orchestrator signs a Stellar payment transaction sending USDC to any Stellar address.

State Machines

The Orchestrator runs two distinct state machines: an Order state machine that tracks the order lifecycle, and an internal Escrow state machine that tracks the on-chain escrow contract. Invalid transitions are rejected with a 409 Conflict error. Both diagrams below match docs/architecture/state-machines.md in the orchestrator repository exactly.

Order State Machine

Escrow State Machine (internal)

The escrow contract moves through its own lifecycle inside the Orchestrator while the order machine advances in parallel.

Error Handling

The Orchestrator uses standard HTTP status codes and structured error responses.

Retrying Failed Requests

Always include an Idempotency-Key header on state-changing requests. Retrying with the same key is safe — the Orchestrator returns the cached result instead of processing twice.

const response = await fetch("/api/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440004",
  },
  body: JSON.stringify(orderPayload),
})

Configuration Options

# Blockchain
STELLAR_NETWORK=mainnet
STELLAR_HORIZON_URL=https://horizon.stellar.org

# Trustless Work (Escrow)
TRUSTLESS_API_URL=https://api.trustlesswork.com
TRUSTLESS_API_KEY=your-trustless-api-key
TRUSTLESS_WEBHOOK_SECRET=your-webhook-secret

# Payment Provider
PAYMENT_PROVIDER=crypto

# Security
WALLET_ENCRYPTION_KEY=your-aes-256-key

Stellar and USDC

The Orchestrator is built exclusively for USDC on Stellar. Stellar was chosen for its low fees (fractions of a cent), fast finality (3-5 seconds), and native USDC support via Circle. Smart contracts run on Soroban, managed through the Trustless Work protocol.

Switching to AirTM

PAYMENT_PROVIDER=airtm
AIRTM_API_KEY=your-airtm-key
AIRTM_WEBHOOK_SECRET=your-webhook-secret