Quickstart

Corridor is a TypeScript monorepo (pnpm workspaces). The ledger runs on embedded Postgres (PGlite) locally, so there is no database to install, and testnet keys are generated and funded from Friendbot on first run.

Prerequisites

• Node.js 22 or later and pnpm 9
• Nothing else. The test suite touches no network, and the Stellar scripts need only a testnet account, which they create.

Run it

Clone and install

cd corridorHub
pnpm install

Verify

pnpm typecheck
pnpm test

298 tests cover Ramp and its SDK, the Stellar venue (references on real transaction shapes, issuer identity, the Horizon quirks that would otherwise lose every memo), the reference codec, routing and hub enforcement, ledger invariants, the saga engine (forced failures, compensation order, lease fencing), the SEP anchor adapter, the partner adapters and webhooks, signers, read-only matching and vault accounting.

Create two testnet vaults

pnpm stellar:wallets

Generates keys into .env.local on first run and funds them from Friendbot. Keys stay local and the file is gitignored.

A first payment carrying the reference

pnpm stellar:smoke

Sends a payment from the treasury vault to the escrow vault with a Corridor Reference as its MEMO_HASH, then asks Horizon for that account’s payments and finds the movement again by its memo — the join reconciliation uses, with no indexer in the path. It prints the reference, the decoded fields, the explorer link and the ledger sequence.

A whole payout through the saga engine

pnpm stellar:payout

Plans a EUR → KES route, reserves the customer’s balance, opens an anchor order, funds it exactly once with a real Stellar payment, books every movement double-entry and prints the ledger invariants. The anchor is MockPartner, so no local currency moves; the route, the saga, the payment and every ledger entry are the real ones.

Against a real SEP server

./examples/anchor/up.sh
CORRIDOR_ANCHOR_BASE_URL=http://localhost:8080 \
CORRIDOR_ANCHOR_PLATFORM_URL=http://localhost:8085/ \
CORRIDOR_PAYOUT_CURRENCY=USD pnpm stellar:payout

The same payout against Stellar’s own Anchor Platform, brought up locally as a receiving SEP-31 anchor: SEP-1, SEP-10, SEP-38, SEP-31 and a funding payment carrying the anchor’s own memo. Needs Docker. See examples/anchor.

Both Stellar scripts move XLM, because a funded testnet USDC trustline needs an issuer faucet. The USDC path is the same call with a different asset.

Scripts

Command	What it does
pnpm test	298 tests, no network
pnpm typecheck	tsc -b across every package
pnpm stellar:wallets	Create or inspect the testnet vaults (keys stay local)
pnpm stellar:smoke	A real payment, with the reference read back off Horizon and decoded
pnpm stellar:payout	The whole saga: route, reserve, fund the anchor, book it, check invariants
CORRIDOR_WATCH=G…,G… pnpm watch:report	Read-only reconciliation of Stellar accounts you already run

Configuration

Variable	What it does
CORRIDOR_NETWORK	testnet (default) or mainnet
CORRIDOR_HORIZON_URL	Point at a private Horizon instance instead of the public one
CORRIDOR_WATCH	Comma-separated Stellar account ids for read-only mode
CORRIDOR_SIGNER	aws-kms or turnkey; the default is a local key from .env.local
CORRIDOR_TAG_SECRET	Key for the reference’s customer tag, so a public memo never identifies the customer
CORRIDOR_STELLAR_ISSUER_<CODE>_<NETWORK>	Supply an issuer Corridor does not ship (ADR 0007)
CORRIDOR_ANCHOR_BASE_URL	Run the payout against a real SEP server instead of the stand-in
CORRIDOR_PAYOUT_CURRENCY	The corridor’s destination currency; KES by default
CORRIDOR_FUNDING_ASSET	What the anchor is funded in; XLM on testnet
CORRIDOR_ANCHOR_TIMEOUT_MS	How long to wait for the anchor to complete an order

Private keys are written to .env.local, which is gitignored. Never commit it.

Repository layout

packages/
  core/            Venues, currencies, money at 7 dp, the Corridor Reference codec
  chain-stellar/   The hub: client, asset registry, payments with references, Horizon observer
  routing/         Route graph and planner; the hub is enforced here
  saga/            Durable saga engine: leases, fencing, reverse-order compensation
  ledger/          Double-entry ledger with invariants (PGlite / Postgres)
  partners/        The anchor interface, the SEP-10/12/31/38 adapter, off-Stellar partners
  legs/            The leg implementations the saga executes
  recon/           Reconciliation, read-only mode and vault checks
  signer/          Signer interfaces: local, AWS KMS, Turnkey
  webhooks/        Partner event store and webhook verification
  chain-solana/    The cross-chain spoke for currencies no Stellar anchor serves yet
  chain-evm/       Base, for USDC inflows
apps/
  site/            Public website
  docs/            This documentation
scripts/           stellar-wallets · stellar-smoke · stellar-payout · watch-report
examples/
  anchor/          A local receiving SEP-31 anchor: Stellar's Anchor Platform
  watch/           Sample read-only configurations