Documentation chevron_right Architecture Specs

Mesa Protocol Architecture & Technical Specifications

Mesa Protocol provides a type-safe, durable state machine runtime for complex financial transactions on Stellar and Soroban. It replaces imperative SDK boilerplate with declarative workflow definitions that survive server restarts, network congestion, and compliance delays.

lightbulb Technical Core: Why Durable Orchestration Matters

Web3 payment pipelines combine synchronous blockchain operations with asynchronous external dependencies (e.g., SEP-24 Anchor deposit callbacks, KYC manual sign-offs, and Soroban WASM contract execution). If a Node.js process crashes or experiences HTTP timeouts mid-pipeline, traditional in-memory try/catch blocks leave user funds stuck in inconsistent states.

close Raw Stellar SDK (Imperative)

State lost on process crash or restart
Sequence number collisions on retry
No built-in compensation / refund mechanism
Requires 150+ lines of custom glue code per endpoint

check Mesa Protocol Runtime (Durable)

Every step transition checkpointed to database
Resumes seamlessly at exact step after server reboot
Automated Saga pattern compensating refunds
Declarative JSON AST generated from TypeScript SDK

layers 3-Tier System Architecture Blueprint

Tier 1: Developer SDK & Studio Canvas (@mesaprotocol/sdk & @mesaprotocol/codegen)

Fluent method-chaining builder that validates steps against canonical Zod schemas and generates immutable JSON Flow Definitions.

↓ JSON AST Flow Definition (id, version, steps) ↓

Tier 2: Durable Runtime Engine & Store (@mesaprotocol/runtime)

Postgres / InMemoryPool state store, 2-second polling scheduler, webhook HMAC verification, and Saga rollback compensator.

↓ Signed Transactions & RPC Payloads ↓

Tier 3: Stellar Blockchain Infrastructure

Stellar Horizon RPC (on-chain XLM / token payments), Soroban RPC (WASM smart contracts), SEP-10 Auth, and SEP-24 Anchors.

Documentation chevron_right Quickstart

Quickstart & Environment Setup

Set up Mesa Protocol in your backend Node.js application in under 3 minutes.

1. Install NPM Workspace Packages

bash

npm install @mesaprotocol/sdk @mesaprotocol/runtime @mesaprotocol/schema dotenv

2. Environment Configuration Reference (.env)

Variable	Type	Default	Description
SENDER_SECRET	SecretRef	Required	Stellar secret key (S-address) used for signingHorizon transactions.
HORIZON_URL	URL	https://horizon-testnet.stellar.org	Horizon RPC endpoint (switch to horizon.stellar.org for Mainnet).
STELLAR_NETWORK	String	TESTNET	Stellar Network passphrase identifier (`TESTNET` or `PUBLIC`).
PORT	Number	3001	HTTP Port for Mesa Runtime REST API server.
DATABASE_URL	URI / mock	mock	Postgres connection URI. Set to `mock` for zero-dependency in-memory testing.
WEBHOOK_HMAC_SECRET	String	Optional	Secret key for verifying incoming webhook HMAC signatures (`X-Mesa-Signature`).

3. Complete Server Entrypoint (mesa-server.ts)

mesa-server.ts

import 'dotenv/config';
import { startServer } from '@mesaprotocol/runtime';
import { Mesa } from '@mesaprotocol/sdk';

// Define Workflow using Mesa Fluent Builder
const flow = Mesa.flow('Remittance Payment', 'remittance-flow')
  .sep10Auth({ domain: 'anchor.stellar.org' })
  .delay({ seconds: 2 })
  .payment({ asset: 'XLM', amount: 50, to: 'GA7IL52JSHMHWCP6HEPYE6IXIR5IZGDEISUFSJVPKCAU7NE7A6EJOFMN' })
  .build();

const port = Number(process.env.PORT || 3001);

async function main() {
  // 1. Initialize Runtime HTTP Server & DB Pool
  await startServer(port);

  // 2. Auto-Register Workflow Definition
  await Mesa.register(flow);

  console.log(`🚀 Mesa Server running on http://localhost:${port}`);
}

main().catch(console.error);

Documentation chevron_right Providers Reference

9 Built-in Execution Providers

Detailed technical specifications, parameter schemas, and output states for all 9 Mesa execution primitives.

1. Provider: sep10 (SEP-10 Web Auth)

STELLAR AUTH

Executes SEP-10 challenge transaction request, signs with private key secret reference, submits challenge back to anchor auth server, and returns cached JWT token.

SDK Builder Method: .sep10Auth({ domain: 'anchor.stellar.org', accountSecretRef: 'SENDER_SECRET' })

Emitted Context Output: { sep10Auth: true, authenticatedDomain: "anchor.stellar.org", jwtToken: "sep10_jwt_..." }

2. Provider: anchor (SEP-24 Webview)

SEP-24 ANCHOR

Initiates interactive SEP-24 deposit or withdrawal flow, returns interactive webview URL, and suspends execution until anchor callback notifies successful funding.

SDK Builder Method: .anchorDeposit({ anchorDomain: 'anchor.stellar.org', assetCode: 'USDC', amount: 100 })

Resumed Output State: { depositedAmount: 100, depositTxHash: "7590ce43...", depositStatus: "COMPLETED" }

3. Provider: soroban (Smart Contracts)

SOROBAN WASM

Invokes methods on deployed Soroban WASM smart contracts using Soroban RPC. Automatically serializes typed XDR contract parameters.

SDK Builder Method: .invoke({ contractId: 'CAKJYFD...', method: 'transfer', args: '{"amount": 100}' })

4. Provider: stellar (Payments & Swaps)

HORIZON PRIMITIVES

Handles native XLM payments, custom asset token transfers, and path payment strict receive/send operations on Stellar Horizon RPC.

SDK Builder Methods: .payment({ to: 'GA7IL...', amount: 50, asset: 'XLM' }) .pathPayment({ sendAsset: 'USDC', destAsset: 'XLM', sendAmount: 10, destMinAmount: 45, destination: 'GA7IL...' })

5. Provider: approval (Compliance Gate)

MANUAL COMPLIANCE

Suspends workflow execution and waits for an operator or compliance officer to manually approve or reject the transaction via dashboard/webhook.

SDK Builder Method: .manualApproval({ approverRole: 'compliance-officer', timeoutSeconds: 86400 })

6. Provider: condition (Branch Router)

DIRECTED BRANCHING

Evaluates dynamic boolean expressions over context variables (depositedAmount >= 100, status == APPROVED) and routes execution to ifTrueStep or ifFalseStep.

SDK Builder Method: .condition({ expression: 'depositedAmount >= 100', ifTrueStep: 3, ifFalseStep: 5 })

7. Provider: delay (Sanctions Timer)

NON-BLOCKING TIMER

Schedules a non-blocking timer delay (e.g. 5-second sanctions hold) using durable scheduler timestamps.

.delay({ seconds: 5 })

8. Provider: webhook (External Callback)

EXTERNAL CALLBACK

Parks execution and exposes a suspension key until an external system POSTs to /webhooks/resume.

.webhook({ url: 'https://api.myapp.com/callback' })

9. Provider: compensation (Saga Rollback)

SAGA REFUND

Executes distributed Saga compensating transactions to refund users if downstream steps fail permanently.

.compensate({ refundAddress: 'GBHTYH2...', refundAsset: 'USDC' })

Documentation chevron_right Code Recipes

Production Code Recipes

End-to-end runnable TypeScript code examples for real-world Stellar financial applications.

payments Recipe A: Cross-Border Remittance Corridor

import { Mesa } from '@mesaprotocol/sdk';

export const remittanceFlow = Mesa.flow('USDC to XLM Remittance', 'remittance-corridor')
  // 1. Authenticate with Anchor via SEP-10
  .sep10Auth({ domain: 'anchor.stellar.org' })
  // 2. Trigger SEP-24 Interactive Deposit
  .anchorDeposit({ anchorDomain: 'anchor.stellar.org', assetCode: 'USDC', amount: 100 })
  // 3. Compliance Hold (5 seconds)
  .delay({ seconds: 5 })
  // 4. Operator Manual Sign-Off Gate
  .manualApproval({ approverRole: 'compliance-officer' })
  // 5. Execute On-Chain XLM Payout
  .payment({
    asset: 'XLM',
    amount: 50,
    to: 'GA7IL52JSHMHWCP6HEPYE6IXIR5IZGDEISUFSJVPKCAU7NE7A6EJOFMN',
    senderSecretRef: 'SENDER_SECRET'
  })
  .build();

security Recipe B: Soroban Smart Contract Escrow Vault

import { Mesa } from '@mesaprotocol/sdk';

export const escrowVaultFlow = Mesa.flow('Soroban Escrow Vault', 'soroban-escrow-vault')
  // 1. Listen for Incoming Escrow Deposit
  .receive({ asset: 'USDC', minAmount: 100, toAddress: 'GD3ZJ3A4VSYJL3CEUDICCBFCMSTSFXDFBRKPZCKV5G25VSKP23XTKAOV' })
  // 2. Invoke Soroban WASM Vault Contract
  .invoke({
    contractId: 'CAKJYFDJIISEM453OFET4EWOVETS7F4YEWXDZVAFFMEJQKYFYUSGDKWE',
    method: 'lock_funds'
  })
  // 3. Automatic Saga Refund Compensation on Failure
  .compensate({
    refundAddress: 'GD3ZJ3A4VSYJL3CEUDICCBFCMSTSFXDFBRKPZCKV5G25VSKP23XTKAOV',
    refundAsset: 'USDC'
  })
  .build();

Documentation chevron_right API Specifications

Mesa Runtime REST API & Webhooks

HTTP Endpoint specifications and cryptographic webhook verification requirements.

Method	Endpoint	Description
POST	/flows	Register or update a Flow Definition JSON object.
GET	/flows/:id	Retrieve registered flow metadata and definition AST.
POST	/executions	Trigger new workflow execution with context payload.
GET	/executions/:id	Fetch execution status, current step, and step audit events.
POST	/webhooks/resume	Resume suspended workflow step via suspension key.
GET	/providers	List registered provider metadata and health check status.

Cryptographic Webhook Headers & HMAC Verification

POST /webhooks/resume Headers: X-Mesa-Signature: 7f8a9... (HMAC-SHA256 of timestamp.rawBody) X-Mesa-Timestamp: 1784984210 X-Mesa-Event-Id: evt-9821a-unique

{
  "suspensionKey": "anchor:sep24:exec-1234",
  "payload": {
    "amount": 100,
    "depositTxHash": "7590ce4389968b1d8f96ad2beaf72622d32d5477d10b36a5cd79d8669a9b78d5"
  }
}

Documentation chevron_right Error Codes

Error Codes & Saga Rollback Matrix

Canonical error code references and Saga compensation failure states.

Error Code	HTTP Status	Description
ERR_FLOW_NOT_FOUND	404	The requested flowId is not registered in store.
ERR_HMAC_INVALID	401	Webhook HMAC signature mismatch or invalid secret.
ERR_HMAC_EXPIRED	400	Webhook timestamp drift exceeds 300 seconds threshold.
ERR_STEP_PERMANENTLY_FAILED	500	Step exceeded max retries (5). Saga rollback triggered.