Scaffolder (create-offer-hub-orchestrator)

Interactive setup wizard for OFFER-HUB Orchestrator — prompts, environment configuration, database migrations, and platform user bootstrapping.

The create-offer-hub-orchestrator package is the official interactive setup wizard for the OFFER-HUB Orchestrator. It automates environment configuration, cryptographic key generation, database migrations, and platform user bootstrapping into a guided terminal workflow.

Tip

For developers setting up a new Orchestrator instance, the scaffolder replaces manual .env file editing and multi-step terminal setup. Running npx create-offer-hub-orchestrator gets you a configured, fully bootstrapped instance in about two minutes.

Prerequisites

Before running the scaffolder, ensure your development or host environment has the following installed:

Requirement	Minimum Version	Purpose
Node.js	`20.x` or higher	Runtime for orchestrator and installer (`packages/create-offerhub/package.json`)
npm	`10.x` or higher	Package execution
PostgreSQL	`14+`	Primary database (Supabase, Railway, Docker, or self-hosted)
Redis	`6+`	Caching, idempotency store, and BullMQ queues (Upstash or Redis local)
Trustless Work Account	—	Escrow contract integration (dapp.trustlesswork.com)

The wizard must be executed inside the root directory of a cloned Orchestrator repository (OFFER-HUB/OFFER-HUB), where the root package.json resides.

Installation & Execution

To clone the Orchestrator and run the setup wizard:

bash

# 1. Clone the Orchestrator repository
git clone https://github.com/OFFER-HUB/OFFER-HUB.git
cd OFFER-HUB

# 2. Install workspace dependencies
npm install

# 3. Run the interactive setup wizard
npx create-offer-hub-orchestrator

Overwrite Protection

If an existing .env file is detected in the working directory, the wizard pauses and prompts:

typescript

.env file already exists. Overwrite? (y/N)

Selecting No immediately exits without mutating your existing configuration, safeguarding production credentials against accidental truncation.

Interactive Prompts

The scaffolder presents an interactive prompt sequence defined in packages/create-offerhub/src/index.ts. Each input is validated in real time:

Prompt	Type	Default Value	Validation & Details
API Port	Number	`4000`	Port must be an integer between `1` and `65535`.
PostgreSQL Database URL	String	`postgresql://postgres:postgres@localhost:5432/offerhub`	Must start with `postgres` or `postgresql://`. For Supabase, use the direct connection on port `5432` for initial migrations.
Redis URL	String	`redis://localhost:6379`	Must start with `redis://` or `rediss://` (TLS).
Payment Provider	List	`crypto`	Choice between `crypto` (Stellar invisible wallets, recommended) and `airtm` (fiat on/off-ramp, requires Enterprise credentials).
AirTM API Key (conditional)	String	—	Prompted only when `airtm` is selected. Required non-empty string.
AirTM API Secret (conditional)	Password	—	Prompted only when `airtm` is selected. Input is masked.
AirTM Webhook Secret (conditional)	Password	—	Prompted only when `airtm` is selected. Input is masked.
Stellar Network	List	`testnet`	Choice between `testnet` (development/staging) and `mainnet` (production).
Trustless Work API Key	String	`your_api_key_here`	API key from your Trustless Work dashboard (dapp.trustlesswork.com).
Trustless Work Webhook Secret	Password	`tw_whsec_...`	Webhook verification secret from Trustless Work. Input is masked.
Public URL	String	`http://localhost:<port>`	Public HTTPS URL of your Orchestrator instance, used for receiving webhook callbacks.
Run database migrations now?	Confirm	`true`	When confirmed, automatically generates the Prisma client and executes pending migrations.
Generate initial admin API key?	Confirm	`true`	When confirmed, attempts to mint an initial admin API key against the local API.

Automated Secret Generation

Before writing any configuration files, the wizard generates high-entropy cryptographic keys in memory using Node.js crypto.randomBytes:

1. `OFFERHUB_MASTER_KEY`

typescript

const masterKey = `ohk_master_${randomBytes(24).toString("hex")}`;

The master key is the administrative credential used to provision API keys. It gives full authority to call POST /api/v1/auth/api-keys.

2. `WALLET_ENCRYPTION_KEY` (Crypto Mode Only)

typescript

const walletEncryptionKey = randomBytes(32).toString("hex");

In crypto mode, the Orchestrator manages invisible Stellar wallets for buyers, sellers, and the platform. Private keys are encrypted at rest using AES-256-GCM. The WALLET_ENCRYPTION_KEY is a 32-byte (64 hex character) key used for this cipher.

Warning

Back up WALLET_ENCRYPTION_KEY immediately. If this key is lost, all stored user and platform wallet private keys become permanently unrecoverable on-chain. Store it securely in a secrets manager (AWS Secrets Manager, Railway Variables, or 1Password).

Generated Environment Configuration (`.env`)

The wizard formats and writes the root .env file using packages/create-offerhub/src/env-generator.ts. The resulting file is organized into modular sections:

env

# ============================================
# OFFER-HUB Orchestrator Configuration
# Generated on 2026-09-27T22:00:00.000Z
# ============================================

# Server
NODE_ENV=development
PORT=4000
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/offerhub
REDIS_URL=redis://localhost:6379

# Payment Provider
PAYMENT_PROVIDER=crypto

# Wallet Encryption (AES-256-GCM)
WALLET_ENCRYPTION_KEY=1a2b3c4d...

# Marketplace Auth
OFFERHUB_MASTER_KEY=ohk_master_5e6f7a...

# Trustless Work
TRUSTLESS_API_KEY=tw_live_api_key_xxx
TRUSTLESS_API_URL=https://dev.api.trustlesswork.com
TRUSTLESS_WEBHOOK_SECRET=tw_whsec_xxx
TRUSTLESS_TIMEOUT_MS=60000

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_USDC_ASSET_CODE=USDC
STELLAR_USDC_ISSUER=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5

# Platform Identity (populated during bootstrap)
PLATFORM_USER_ID=usr_9a8b7c6d5e4f

# Public URL (for webhooks)
PUBLIC_BASE_URL=http://localhost:4000

Network-Specific Stellar Defaults

Depending on the stellarNetwork selection, the scaffolder automatically configures the appropriate Stellar Horizon and Trustless Work endpoints:

Setting	Testnet (`testnet`)	Mainnet (`mainnet`)
`STELLAR_HORIZON_URL`	`https://horizon-testnet.stellar.org`	`https://horizon.stellar.org`
`STELLAR_USDC_ISSUER`	`GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`	`GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`
`TRUSTLESS_API_URL`	`https://dev.api.trustlesswork.com`	`https://api.trustlesswork.com`

Automated Post-Setup Workflow

When the prompts complete, create-offer-hub-orchestrator executes the following sequence:

Mermaid

Rendering diagram…

Step 1 — Prisma Client Generation

The wizard runs:

npx prisma generate --schema packages/database/prisma/schema.prisma

This generates the type-safe Prisma Client with the database models (User, Balance, ApiKey, Order, Escrow, Wallet, etc.).

Step 2 — Database Migrations

When runMigrations is enabled, the wizard executes:

npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

This applies all pending migrations from packages/database/prisma/migrations/ to your PostgreSQL database without requiring manual interactive confirmation.

Step 3 — Platform User & Stellar Wallet Bootstrap

The Orchestrator requires a dedicated internal platform user (scripts/bootstrap.ts). This platform user holds the Stellar keypair that acts as platformAddress and disputeResolver in Soroban escrow smart contracts.

The scaffolder runs:

npm run bootstrap

The bootstrap script performs the following actions:

Idempotency Check: Queries User where externalUserId = "offerhub-platform". If the platform user already exists, it skips creation and outputs the existing PLATFORM_USER_ID.
User & Balance Record Creation: In a single database transaction, creates the platform User entity (status: "ACTIVE", type: "BOTH") and initializes an associated Balance record (available: "0.00", reserved: "0.00", currency: "USD").
Stellar Keypair & Wallet Encryption: Generates a cryptographically random Stellar keypair (Keypair.random()), encrypts the secret key using AES-256-GCM with WALLET_ENCRYPTION_KEY, and persists the wallet record in PostgreSQL.
Testnet Account Funding: On testnet, automatically requests test XLM from Stellar Friendbot (https://friendbot.stellar.org?addr=<publicKey>).
USDC Trustline Setup: Submits a changeTrust transaction to Stellar Horizon establishing a trustline for the configured USDC asset and issuer.
Environment Update: Emits PLATFORM_USER_ID=usr_<id>. The scaffolder captures this value and updates the PLATFORM_USER_ID= line in .env.

Note

If you run the scaffolder with runMigrations: false, you can run the bootstrap step manually at any time after deploying your migrations:

bash

npm run bootstrap

Then paste the emitted PLATFORM_USER_ID=usr_... into your .env file.

Step 4 — Initial Admin API Key Generation

If generateApiKey is selected and the local API is accessible, the wizard issues a request to create an initial administrative API key:

bash

curl -X POST http://localhost:4000/api/v1/auth/api-keys \
  -H "Authorization: Bearer <OFFERHUB_MASTER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin Key",
    "scopes": ["orders", "users", "balance", "withdrawals", "topups", "support"]
  }'

If the API server is not yet running, the scaffolder prints the exact curl command with your master key so you can mint your initial key as soon as the server boots.

Starting the Orchestrator

After the scaffolder finishes, launch the API:

bash

# Development mode with hot-reload
npm run dev

# Or build and run for production
npm run build
node apps/api/dist/main.js

Verify that the API and background workers are healthy:

curl http://localhost:4000/api/v1/health

Expected response:

json

{
  "status": "healthy",
  "timestamp": "2026-09-27T22:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

Next Steps

Installation Guide — Complete overview of setup options (wizard vs. manual Docker)
Configuration Reference — Comprehensive guide to all environment variables
CLI Tool Guide — Manage API keys and configuration from the terminal
Quick Start — Make your first authenticated payment and escrow call
Self-Hosting Guide — Production deployment with Docker and monitoring

Edit this page on GitHub

Scaffolder (create-offer-hub-orchestrator)

Interactive setup wizard for OFFER-HUB Orchestrator — prompts, environment configuration, database migrations, and platform user bootstrapping.

Tip

Prerequisites

Before running the scaffolder, ensure your development or host environment has the following installed:

Requirement	Minimum Version	Purpose
Node.js	`20.x` or higher	Runtime for orchestrator and installer (`packages/create-offerhub/package.json`)
npm	`10.x` or higher	Package execution
PostgreSQL	`14+`	Primary database (Supabase, Railway, Docker, or self-hosted)
Redis	`6+`	Caching, idempotency store, and BullMQ queues (Upstash or Redis local)
Trustless Work Account	—	Escrow contract integration (dapp.trustlesswork.com)

The wizard must be executed inside the root directory of a cloned Orchestrator repository (OFFER-HUB/OFFER-HUB), where the root package.json resides.

Installation & Execution

To clone the Orchestrator and run the setup wizard:

bash

# 1. Clone the Orchestrator repository
git clone https://github.com/OFFER-HUB/OFFER-HUB.git
cd OFFER-HUB

# 2. Install workspace dependencies
npm install

# 3. Run the interactive setup wizard
npx create-offer-hub-orchestrator

Overwrite Protection

If an existing .env file is detected in the working directory, the wizard pauses and prompts:

typescript

.env file already exists. Overwrite? (y/N)

Selecting No immediately exits without mutating your existing configuration, safeguarding production credentials against accidental truncation.

Interactive Prompts

The scaffolder presents an interactive prompt sequence defined in packages/create-offerhub/src/index.ts. Each input is validated in real time:

Prompt	Type	Default Value	Validation & Details
API Port	Number	`4000`	Port must be an integer between `1` and `65535`.
PostgreSQL Database URL	String	`postgresql://postgres:postgres@localhost:5432/offerhub`	Must start with `postgres` or `postgresql://`. For Supabase, use the direct connection on port `5432` for initial migrations.
Redis URL	String	`redis://localhost:6379`	Must start with `redis://` or `rediss://` (TLS).
Payment Provider	List	`crypto`	Choice between `crypto` (Stellar invisible wallets, recommended) and `airtm` (fiat on/off-ramp, requires Enterprise credentials).
AirTM API Key (conditional)	String	—	Prompted only when `airtm` is selected. Required non-empty string.
AirTM API Secret (conditional)	Password	—	Prompted only when `airtm` is selected. Input is masked.
AirTM Webhook Secret (conditional)	Password	—	Prompted only when `airtm` is selected. Input is masked.
Stellar Network	List	`testnet`	Choice between `testnet` (development/staging) and `mainnet` (production).
Trustless Work API Key	String	`your_api_key_here`	API key from your Trustless Work dashboard (dapp.trustlesswork.com).
Trustless Work Webhook Secret	Password	`tw_whsec_...`	Webhook verification secret from Trustless Work. Input is masked.
Public URL	String	`http://localhost:<port>`	Public HTTPS URL of your Orchestrator instance, used for receiving webhook callbacks.
Run database migrations now?	Confirm	`true`	When confirmed, automatically generates the Prisma client and executes pending migrations.
Generate initial admin API key?	Confirm	`true`	When confirmed, attempts to mint an initial admin API key against the local API.

Automated Secret Generation

Before writing any configuration files, the wizard generates high-entropy cryptographic keys in memory using Node.js crypto.randomBytes:

1. `OFFERHUB_MASTER_KEY`

typescript

const masterKey = `ohk_master_${randomBytes(24).toString("hex")}`;

The master key is the administrative credential used to provision API keys. It gives full authority to call POST /api/v1/auth/api-keys.

2. `WALLET_ENCRYPTION_KEY` (Crypto Mode Only)

typescript

const walletEncryptionKey = randomBytes(32).toString("hex");

Warning

Generated Environment Configuration (`.env`)

The wizard formats and writes the root .env file using packages/create-offerhub/src/env-generator.ts. The resulting file is organized into modular sections:

env

# ============================================
# OFFER-HUB Orchestrator Configuration
# Generated on 2026-09-27T22:00:00.000Z
# ============================================

# Server
NODE_ENV=development
PORT=4000
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/offerhub
REDIS_URL=redis://localhost:6379

# Payment Provider
PAYMENT_PROVIDER=crypto

# Wallet Encryption (AES-256-GCM)
WALLET_ENCRYPTION_KEY=1a2b3c4d...

# Marketplace Auth
OFFERHUB_MASTER_KEY=ohk_master_5e6f7a...

# Trustless Work
TRUSTLESS_API_KEY=tw_live_api_key_xxx
TRUSTLESS_API_URL=https://dev.api.trustlesswork.com
TRUSTLESS_WEBHOOK_SECRET=tw_whsec_xxx
TRUSTLESS_TIMEOUT_MS=60000

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_USDC_ASSET_CODE=USDC
STELLAR_USDC_ISSUER=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5

# Platform Identity (populated during bootstrap)
PLATFORM_USER_ID=usr_9a8b7c6d5e4f

# Public URL (for webhooks)
PUBLIC_BASE_URL=http://localhost:4000

Network-Specific Stellar Defaults

Depending on the stellarNetwork selection, the scaffolder automatically configures the appropriate Stellar Horizon and Trustless Work endpoints:

Setting	Testnet (`testnet`)	Mainnet (`mainnet`)
`STELLAR_HORIZON_URL`	`https://horizon-testnet.stellar.org`	`https://horizon.stellar.org`
`STELLAR_USDC_ISSUER`	`GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`	`GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`
`TRUSTLESS_API_URL`	`https://dev.api.trustlesswork.com`	`https://api.trustlesswork.com`

Automated Post-Setup Workflow

When the prompts complete, create-offer-hub-orchestrator executes the following sequence:

Mermaid

Rendering diagram…

Step 1 — Prisma Client Generation

The wizard runs:

npx prisma generate --schema packages/database/prisma/schema.prisma

This generates the type-safe Prisma Client with the database models (User, Balance, ApiKey, Order, Escrow, Wallet, etc.).

Step 2 — Database Migrations

When runMigrations is enabled, the wizard executes:

npx prisma migrate deploy --schema packages/database/prisma/schema.prisma

This applies all pending migrations from packages/database/prisma/migrations/ to your PostgreSQL database without requiring manual interactive confirmation.

Step 3 — Platform User & Stellar Wallet Bootstrap

The scaffolder runs:

npm run bootstrap

The bootstrap script performs the following actions:

Idempotency Check: Queries User where externalUserId = "offerhub-platform". If the platform user already exists, it skips creation and outputs the existing PLATFORM_USER_ID.
User & Balance Record Creation: In a single database transaction, creates the platform User entity (status: "ACTIVE", type: "BOTH") and initializes an associated Balance record (available: "0.00", reserved: "0.00", currency: "USD").
Stellar Keypair & Wallet Encryption: Generates a cryptographically random Stellar keypair (Keypair.random()), encrypts the secret key using AES-256-GCM with WALLET_ENCRYPTION_KEY, and persists the wallet record in PostgreSQL.
Testnet Account Funding: On testnet, automatically requests test XLM from Stellar Friendbot (https://friendbot.stellar.org?addr=<publicKey>).
USDC Trustline Setup: Submits a changeTrust transaction to Stellar Horizon establishing a trustline for the configured USDC asset and issuer.
Environment Update: Emits PLATFORM_USER_ID=usr_<id>. The scaffolder captures this value and updates the PLATFORM_USER_ID= line in .env.

Note

If you run the scaffolder with runMigrations: false, you can run the bootstrap step manually at any time after deploying your migrations:

bash

npm run bootstrap

Then paste the emitted PLATFORM_USER_ID=usr_... into your .env file.

Step 4 — Initial Admin API Key Generation

If generateApiKey is selected and the local API is accessible, the wizard issues a request to create an initial administrative API key:

bash

curl -X POST http://localhost:4000/api/v1/auth/api-keys \
  -H "Authorization: Bearer <OFFERHUB_MASTER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin Key",
    "scopes": ["orders", "users", "balance", "withdrawals", "topups", "support"]
  }'

If the API server is not yet running, the scaffolder prints the exact curl command with your master key so you can mint your initial key as soon as the server boots.

Starting the Orchestrator

After the scaffolder finishes, launch the API:

bash

# Development mode with hot-reload
npm run dev

# Or build and run for production
npm run build
node apps/api/dist/main.js

Verify that the API and background workers are healthy:

curl http://localhost:4000/api/v1/health

Expected response:

json

{
  "status": "healthy",
  "timestamp": "2026-09-27T22:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

Next Steps

Installation Guide — Complete overview of setup options (wizard vs. manual Docker)
Configuration Reference — Comprehensive guide to all environment variables
CLI Tool Guide — Manage API keys and configuration from the terminal
Quick Start — Make your first authenticated payment and escrow call
Self-Hosting Guide — Production deployment with Docker and monitoring

Edit this page on GitHub

Scaffolder (create-offer-hub-orchestrator)

Prerequisites

Installation & Execution

Overwrite Protection

Interactive Prompts

Automated Secret Generation

1. OFFERHUB_MASTER_KEY

2. WALLET_ENCRYPTION_KEY (Crypto Mode Only)

Generated Environment Configuration (.env)

Network-Specific Stellar Defaults

Automated Post-Setup Workflow

Step 1 — Prisma Client Generation

Step 2 — Database Migrations

Step 3 — Platform User & Stellar Wallet Bootstrap

Step 4 — Initial Admin API Key Generation

Starting the Orchestrator

Next Steps

Scaffolder (create-offer-hub-orchestrator)

Prerequisites

Installation & Execution

Overwrite Protection

Interactive Prompts

Automated Secret Generation

1. OFFERHUB_MASTER_KEY

2. WALLET_ENCRYPTION_KEY (Crypto Mode Only)

Generated Environment Configuration (.env)

Network-Specific Stellar Defaults

Automated Post-Setup Workflow

Step 1 — Prisma Client Generation

Step 2 — Database Migrations

Step 3 — Platform User & Stellar Wallet Bootstrap

Step 4 — Initial Admin API Key Generation

Starting the Orchestrator

Next Steps

1. `OFFERHUB_MASTER_KEY`

2. `WALLET_ENCRYPTION_KEY` (Crypto Mode Only)

Generated Environment Configuration (`.env`)

1. `OFFERHUB_MASTER_KEY`

2. `WALLET_ENCRYPTION_KEY` (Crypto Mode Only)

Generated Environment Configuration (`.env`)