Escrow Guide

How blockchain-based escrow works in OFFER-HUB — fund locking, release flows, and dispute handling.

Note

This is the public API/SDK guide for integrators. For internal implementation detail (Orchestrator state machine, signer roles), see docs/guides/escrow.md in the repo.

Escrow is the core security mechanism in OFFER-HUB. When a buyer pays for a service, funds are locked in a Stellar smart contract until the work is delivered and approved. Neither party can unilaterally access the funds — the contract enforces fair resolution.

Tip

Make sure you understand the Order Lifecycle before diving into escrow mechanics.

How Escrow Works

OFFER-HUB uses Trustless Work smart contracts on the Stellar blockchain for non-custodial escrow. This means:

Funds are on-chain — Not in OFFER-HUB's database
Contract enforces rules — Release requires proper signatures
Transparent — Anyone can verify escrow state on Stellar
Non-custodial — OFFER-HUB cannot access funds without proper authorization

Escrow Participants

Role	Description
Buyer	Funds the escrow; approves milestones; signs fund-release transactions
Seller	Receives funds; marks milestones as completed (`serviceProvider` role)
Platform	OFFER-HUB's signer; acts as `disputeResolver` — required for any dispute resolution
Arbiter	Trustless Work's smart contract; enforces that `disputeResolver` ≠ `disputer` on-chain

Escrow Lifecycle

State Machine

The escrow contract follows the internal Escrow state machine below — the same canonical diagram used across the docs, matching docs/architecture/state-machines.md in the orchestrator repository exactly. The order around it follows the Order lifecycle.

Mermaid

Rendering diagram…

State Descriptions

State	Description
`CREATING`	Creating contract in Trustless Work
`CREATED`	Contract created, not funded
`FUNDING`	Funding contract
`FUNDED`	Funds locked in contract
`RELEASING`	Releasing funds to the seller
`RELEASED`	Funds released
`REFUNDING`	Returning funds to the buyer
`REFUNDED`	Funds returned
`DISPUTED`	Active dispute

Note

Order-level statuses (e.g. ESCROW_CREATING, ESCROW_FUNDING, ESCROW_FUNDED, IN_PROGRESS, CLOSED) belong to the Order state machine. The escrow machine above tracks the smart contract itself.

Creating Escrow

After reserving funds, create the escrow contract:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json"

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ESCROW_CREATING",
    "escrow": {
      "contractId": "CDLZFC...",
      "status": "creating"
    }
  }
}

The contract deployment happens asynchronously. Listen for events or poll the order status.

Funding Escrow

Once the contract is created, fund it with USDC:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_your_api_key"

This triggers an on-chain USDC transfer from the buyer's invisible wallet to the escrow contract.

What Happens During Funding

Debit buyer's balance — Reserved funds become locked
Sign transaction — Platform signs with buyer's encrypted key
Submit to Stellar — USDC sent to contract address
Confirm on-chain — Wait for ledger confirmation
Update status — Order becomes IN_PROGRESS

Note

Funding typically takes 5-10 seconds. The order status progresses through ESCROW_FUNDING → ESCROW_FUNDED → IN_PROGRESS.

Releasing Funds

When the buyer approves the work, release funds to the seller:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_buyer123"}'

The 3-Transaction Release Flow

Releasing funds requires three separate Stellar transactions signed by different parties:

Step	Contract call	Signer	Role in contract
1	`changeMilestoneStatus`	Seller	`serviceProvider`
2	`approveMilestone`	Buyer	`approver`
3	`releaseFunds`	Buyer	`releaseSigner`

Note

The seller signs first to mark the milestone as completed, then the buyer signs twice — once to approve and once to trigger the actual fund transfer. All signing happens server-side via the parties' invisible wallets.

Mermaid

Rendering diagram…

Release Response

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "CLOSED",
    "resolution": {
      "type": "released",
      "amount": "50.00",
      "recipient": "usr_seller456",
      "completedAt": "2026-02-25T14:00:00.000Z"
    }
  }
}

Refunding (Dispute Flow)

If there's a problem, the buyer can request a refund through the dispute process:

Step 1: Open Dispute

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Step 2: Platform Resolves

After review, the platform resolves the dispute:

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_REFUND",
    "note": "Seller did not deliver agreed work"
  }'

The 2-Transaction Refund Flow

Step	Contract call	Signer	Role in contract
1	`disputeEscrow`	Buyer	`approver` (disputer)
2	`resolveDispute` (100% to buyer)	Platform	`disputeResolver`

Warning

Disputes require platform intervention. The smart contract won't transfer funds until the platform signs the resolveDispute transaction as disputeResolver.

Danger

Role separation is enforced on-chain. The disputeResolver must be a different party from the disputer. Because the buyer opens the dispute (step 1), only the platform wallet — never the buyer or seller — can sign the resolution (step 2). This prevents either party from unilaterally reclaiming funds.

Using the SDK

The SDK simplifies escrow operations:

typescript

import { OfferHubSDK } from '@offerhub/sdk';

const sdk = new OfferHubSDK({
  apiUrl: 'http://localhost:4000',
  apiKey: 'ohk_live_your_api_key'
});

// Create and fund escrow in sequence
const order = await sdk.orders.get('ord_xyz789');

// Create escrow contract
await sdk.orders.createEscrow(order.id);

// Wait for contract creation (or use events) — the order advances to
// ESCROW_FUNDING once Trustless Work confirms the deployment
await sdk.orders.waitForStatus(order.id, 'ESCROW_FUNDING');

// Fund the escrow
await sdk.orders.fundEscrow(order.id);

// Wait for funding confirmation
await sdk.orders.waitForStatus(order.id, 'IN_PROGRESS');

// Later: release to seller
await sdk.orders.release(order.id, 'Buyer approved release');

Listening to Escrow Events

typescript

const events = sdk.events.subscribe();

events.on('order.escrow_creating', (data) => {
  console.log('Contract deploying:', data.contractId);
});

events.on('order.escrow_funded', (data) => {
  console.log('Funds locked:', data.amount);
});

events.on('order.released', (data) => {
  console.log('Funds released to seller');
});

events.on('order.disputed', (data) => {
  console.log('Dispute opened:', data.reason);
});

On-Chain vs Off-Chain Balance

OFFER-HUB tracks two types of balances:

Off-Chain Balance

Stored in the database for fast operations:

json

{
  "available": "100.00",
  "reserved": "50.00"
}

Available — Can be used for new orders or withdrawn
Reserved — Locked for pending orders (before escrow funding)

On-Chain Balance

Actual USDC in the user's Stellar wallet:

json

{
  "stellar_address": "GCV24WNJ...",
  "usdc_balance": "150.00"
}

Balance Flow During Escrow

Stage	Available	Reserved	On-Chain
Initial	100.00	0.00	100.00
After reserve	50.00	50.00	100.00
After funding	50.00	0.00	50.00 (in escrow)
After release	50.00	0.00	50.00

Note

When escrow is funded, the reserved amount leaves both the off-chain balance AND the on-chain wallet. It's now in the smart contract.

Platform Wallet

The platform wallet is a special Stellar account that:

Co-signs transactions — Required for release/refund
Collects fees — Platform fees are sent here
Never holds user funds — Only signs, doesn't custody

Configure it in your environment:

env

PLATFORM_USER_ID=usr_platform

Error Handling

Common Escrow Errors

Error	Cause	Solution
`ESCROW_ALREADY_EXISTS`	Duplicate creation attempt	Check order status first
`ESCROW_NOT_FUNDED`	Trying to release unfunded escrow	Fund the escrow first
`INVALID_STATE_TRANSITION`	Wrong order state	Follow the state machine
`INSUFFICIENT_FUNDS`	Wallet doesn't have enough USDC	Check balance before funding
`CONTRACT_ERROR`	Stellar contract failure	Check Trustless Work status

Handling Timeouts

Blockchain transactions can take time. Handle timeouts gracefully:

typescript

try {
  await sdk.orders.fundEscrow(orderId);
} catch (error) {
  if (error.code === 'FUNDING_TIMEOUT') {
    // Check if transaction was actually submitted
    const order = await sdk.orders.get(orderId);
    if (order.status === 'ESCROW_FUNDING') {
      // Transaction pending — wait for the order.escrow_funded SSE event or poll
      console.log('Funding in progress, waiting for confirmation...');
    }
  }
}

Real-Time Escrow Events (SSE)

Escrow lifecycle events are delivered over the SSE event stream at GET /api/v1/events — there is no outbound webhook API:

bash

curl -N "http://localhost:4000/api/v1/events?types=order.escrow_creating,order.escrow_funded,order.released,order.refunded" \
  -H "Authorization: Bearer ohk_live_your_api_key"

Or with the SDK:

typescript

const events = sdk.events.subscribe();

events.on('order.escrow_funded', (data) => {
  console.log('Escrow funded:', data.fundedAt);
});

events.on('order.released', (data) => {
  console.log('Released to seller:', data.amount);
});

See Events (SSE) for the full event catalog, connection parameters, and replay support.

Security Considerations

Never expose private keys — All signing happens server-side
Use the SSE stream — Real-time updates arrive over GET /api/v1/events; there is no outbound webhook API
Use idempotency keys — Prevent duplicate funding
Monitor contract state — Cross-check with Stellar explorer

Next Steps

Disputes Guide — Handle disagreements
Withdrawals Guide — Move funds off-platform
SDK Reference — Full SDK documentation

Edit this page on GitHub

Escrow Guide

How blockchain-based escrow works in OFFER-HUB — fund locking, release flows, and dispute handling.

Note

This is the public API/SDK guide for integrators. For internal implementation detail (Orchestrator state machine, signer roles), see docs/guides/escrow.md in the repo.

Tip

Make sure you understand the Order Lifecycle before diving into escrow mechanics.

How Escrow Works

OFFER-HUB uses Trustless Work smart contracts on the Stellar blockchain for non-custodial escrow. This means:

Funds are on-chain — Not in OFFER-HUB's database
Contract enforces rules — Release requires proper signatures
Transparent — Anyone can verify escrow state on Stellar
Non-custodial — OFFER-HUB cannot access funds without proper authorization

Escrow Participants

Role	Description
Buyer	Funds the escrow; approves milestones; signs fund-release transactions
Seller	Receives funds; marks milestones as completed (`serviceProvider` role)
Platform	OFFER-HUB's signer; acts as `disputeResolver` — required for any dispute resolution
Arbiter	Trustless Work's smart contract; enforces that `disputeResolver` ≠ `disputer` on-chain

Escrow Lifecycle

State Machine

Mermaid

Rendering diagram…

State Descriptions

State	Description
`CREATING`	Creating contract in Trustless Work
`CREATED`	Contract created, not funded
`FUNDING`	Funding contract
`FUNDED`	Funds locked in contract
`RELEASING`	Releasing funds to the seller
`RELEASED`	Funds released
`REFUNDING`	Returning funds to the buyer
`REFUNDED`	Funds returned
`DISPUTED`	Active dispute

Note

Order-level statuses (e.g. ESCROW_CREATING, ESCROW_FUNDING, ESCROW_FUNDED, IN_PROGRESS, CLOSED) belong to the Order state machine. The escrow machine above tracks the smart contract itself.

Creating Escrow

After reserving funds, create the escrow contract:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json"

Response:

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ESCROW_CREATING",
    "escrow": {
      "contractId": "CDLZFC...",
      "status": "creating"
    }
  }
}

The contract deployment happens asynchronously. Listen for events or poll the order status.

Funding Escrow

Once the contract is created, fund it with USDC:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_your_api_key"

This triggers an on-chain USDC transfer from the buyer's invisible wallet to the escrow contract.

What Happens During Funding

Debit buyer's balance — Reserved funds become locked
Sign transaction — Platform signs with buyer's encrypted key
Submit to Stellar — USDC sent to contract address
Confirm on-chain — Wait for ledger confirmation
Update status — Order becomes IN_PROGRESS

Note

Funding typically takes 5-10 seconds. The order status progresses through ESCROW_FUNDING → ESCROW_FUNDED → IN_PROGRESS.

Releasing Funds

When the buyer approves the work, release funds to the seller:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_buyer123"}'

The 3-Transaction Release Flow

Releasing funds requires three separate Stellar transactions signed by different parties:

Step	Contract call	Signer	Role in contract
1	`changeMilestoneStatus`	Seller	`serviceProvider`
2	`approveMilestone`	Buyer	`approver`
3	`releaseFunds`	Buyer	`releaseSigner`

Note

Mermaid

Rendering diagram…

Release Response

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "CLOSED",
    "resolution": {
      "type": "released",
      "amount": "50.00",
      "recipient": "usr_seller456",
      "completedAt": "2026-02-25T14:00:00.000Z"
    }
  }
}

Refunding (Dispute Flow)

If there's a problem, the buyer can request a refund through the dispute process:

Step 1: Open Dispute

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Step 2: Platform Resolves

After review, the platform resolves the dispute:

bash

curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "FULL_REFUND",
    "note": "Seller did not deliver agreed work"
  }'

The 2-Transaction Refund Flow

Step	Contract call	Signer	Role in contract
1	`disputeEscrow`	Buyer	`approver` (disputer)
2	`resolveDispute` (100% to buyer)	Platform	`disputeResolver`

Warning

Disputes require platform intervention. The smart contract won't transfer funds until the platform signs the resolveDispute transaction as disputeResolver.

Danger

Using the SDK

The SDK simplifies escrow operations:

typescript

import { OfferHubSDK } from '@offerhub/sdk';

const sdk = new OfferHubSDK({
  apiUrl: 'http://localhost:4000',
  apiKey: 'ohk_live_your_api_key'
});

// Create and fund escrow in sequence
const order = await sdk.orders.get('ord_xyz789');

// Create escrow contract
await sdk.orders.createEscrow(order.id);

// Wait for contract creation (or use events) — the order advances to
// ESCROW_FUNDING once Trustless Work confirms the deployment
await sdk.orders.waitForStatus(order.id, 'ESCROW_FUNDING');

// Fund the escrow
await sdk.orders.fundEscrow(order.id);

// Wait for funding confirmation
await sdk.orders.waitForStatus(order.id, 'IN_PROGRESS');

// Later: release to seller
await sdk.orders.release(order.id, 'Buyer approved release');

Listening to Escrow Events

typescript

const events = sdk.events.subscribe();

events.on('order.escrow_creating', (data) => {
  console.log('Contract deploying:', data.contractId);
});

events.on('order.escrow_funded', (data) => {
  console.log('Funds locked:', data.amount);
});

events.on('order.released', (data) => {
  console.log('Funds released to seller');
});

events.on('order.disputed', (data) => {
  console.log('Dispute opened:', data.reason);
});

On-Chain vs Off-Chain Balance

OFFER-HUB tracks two types of balances:

Off-Chain Balance

Stored in the database for fast operations:

json

{
  "available": "100.00",
  "reserved": "50.00"
}

Available — Can be used for new orders or withdrawn
Reserved — Locked for pending orders (before escrow funding)

On-Chain Balance

Actual USDC in the user's Stellar wallet:

json

{
  "stellar_address": "GCV24WNJ...",
  "usdc_balance": "150.00"
}

Balance Flow During Escrow

Stage	Available	Reserved	On-Chain
Initial	100.00	0.00	100.00
After reserve	50.00	50.00	100.00
After funding	50.00	0.00	50.00 (in escrow)
After release	50.00	0.00	50.00

Note

When escrow is funded, the reserved amount leaves both the off-chain balance AND the on-chain wallet. It's now in the smart contract.

Platform Wallet

The platform wallet is a special Stellar account that:

Co-signs transactions — Required for release/refund
Collects fees — Platform fees are sent here
Never holds user funds — Only signs, doesn't custody

Configure it in your environment:

env

PLATFORM_USER_ID=usr_platform

Error Handling

Common Escrow Errors

Error	Cause	Solution
`ESCROW_ALREADY_EXISTS`	Duplicate creation attempt	Check order status first
`ESCROW_NOT_FUNDED`	Trying to release unfunded escrow	Fund the escrow first
`INVALID_STATE_TRANSITION`	Wrong order state	Follow the state machine
`INSUFFICIENT_FUNDS`	Wallet doesn't have enough USDC	Check balance before funding
`CONTRACT_ERROR`	Stellar contract failure	Check Trustless Work status

Handling Timeouts

Blockchain transactions can take time. Handle timeouts gracefully:

typescript

try {
  await sdk.orders.fundEscrow(orderId);
} catch (error) {
  if (error.code === 'FUNDING_TIMEOUT') {
    // Check if transaction was actually submitted
    const order = await sdk.orders.get(orderId);
    if (order.status === 'ESCROW_FUNDING') {
      // Transaction pending — wait for the order.escrow_funded SSE event or poll
      console.log('Funding in progress, waiting for confirmation...');
    }
  }
}

Real-Time Escrow Events (SSE)

Escrow lifecycle events are delivered over the SSE event stream at GET /api/v1/events — there is no outbound webhook API:

bash

curl -N "http://localhost:4000/api/v1/events?types=order.escrow_creating,order.escrow_funded,order.released,order.refunded" \
  -H "Authorization: Bearer ohk_live_your_api_key"

Or with the SDK:

typescript

const events = sdk.events.subscribe();

events.on('order.escrow_funded', (data) => {
  console.log('Escrow funded:', data.fundedAt);
});

events.on('order.released', (data) => {
  console.log('Released to seller:', data.amount);
});

See Events (SSE) for the full event catalog, connection parameters, and replay support.

Security Considerations

Never expose private keys — All signing happens server-side
Use the SSE stream — Real-time updates arrive over GET /api/v1/events; there is no outbound webhook API
Use idempotency keys — Prevent duplicate funding
Monitor contract state — Cross-check with Stellar explorer

Next Steps

Disputes Guide — Handle disagreements
Withdrawals Guide — Move funds off-platform
SDK Reference — Full SDK documentation

Edit this page on GitHub