The seam is
the architecture.

What the stack can actually do

Verified against live vendor documentation in August 2026, not from memory. This table is the reason the rest of the document is shaped the way it is.

Nothing talks to a provider directly

The RN app has exactly three outbound dependencies: the Privy SDK, a Base RPC for reads, and the Corridor API. It holds no provider credentials, computes no quotes, and cannot tell a mock provider from a real one.

Routes are a table, not a codebase

The Bridge gap stops being a defect the moment corridors are data. Adding USD→MXN is a row; it binds to a Bridge payout provider instead of the Turkish one and nothing else changes.

// corridor/routes.ts: the whole multi-corridor story, without building multi-corridor
type CorridorId = 'USD:TRY' | 'USD:MXN';

interface RouteBinding {
  onramp:     ProviderId;   // fiat in
  settlement: ChainId;      // value transport
  payout:     ProviderId;   // fiat out
  limits:     TierLimits;
}

const ROUTES: Record<CorridorId, RouteBinding> = {
  'USD:TRY': {
    onramp:     'bridge.usd.ach',
    settlement: 'base',
    payout:     'turkiye.try.bank',  // ← Bridge has no TRY route
    limits:     TIER_LIMITS.basic,
  },
  'USD:MXN': {
    onramp:     'bridge.usd.ach',
    settlement: 'base',
    payout:     'bridge.mxn.spei',  // ← same vendor, supported route
    limits:     TIER_LIMITS.basic,
  },
};

two corridors differ by one binding · a new destination is a row and a provider, not a release

Money, quotes, and the interfaces

Money is never a number

Minor units as bigint, currency-tagged, with the scale carried explicitly. The USD→USDC boundary is where the bugs live: USD has 2 decimals, USDC has 6, so every conversion crosses a factor of 10⁴ that a float would quietly corrupt.

// money.ts
type Currency = 'USD' | 'TRY' | 'USDC';

const SCALE: Record<Currency, number> = { USD: 2, TRY: 2, USDC: 6 };

interface Money {
  readonly currency: Currency;
  readonly minor: bigint;    // $500.00 → 50_000n   ·   500.00 USDC → 500_000_000n
}

// Rates are rationals. A float rate is an unreconcilable rate.
interface Rate {
  readonly pair: 'USD/TRY';
  readonly num: bigint;      // 5284n
  readonly den: bigint;      // 100n     → 52.84
  readonly source: 'mid_market';
  readonly observedAt: string;
}

// Rescaling is explicit and total. There is no implicit coercion anywhere.
function rescale(m: Money, to: Currency): Money {
  const d = SCALE[to] - SCALE[m.currency];
  return {
    currency: to,
    minor: d >= 0 ? m.minor * 10n ** BigInt(d)
                  : m.minor / 10n ** BigInt(-d),   // caller proves divisibility
  };
}

Quotes are signed server-side

Screen 03 submits a quoteId, never amounts. The client's numbers are a rendering of the quote, never the source of it, which is what stops a stale countdown or a patched binary from reaching settlement.

// quote.ts
interface Quote {
  readonly id: QuoteId;
  readonly corridor: CorridorId;
  readonly send: Money;          // USD 50_000n            → what the user typed
  readonly receive: Money;       // TRY 2_642_000n         → ₺26,420.00
  readonly totalCharged: Money;  // USD 50_375n            → $503.75
  readonly rate: Rate;
  readonly fees: readonly FeeLine[];
  readonly expiresAt: string;    // server clock, always
  readonly sig: string;          // HMAC over every field above
}

interface FeeLine {
  readonly kind: 'onramp' | 'network' | 'payout';
  readonly label: string;        // 'On-ramp · ACH → USDC'
  readonly amount: Money;        // USD 125n → $1.25
}

fees are named after the rail that consumes them; the breakdown on screen 03 is this array, rendered

The provider interfaces

Three interfaces, each implemented once per rail. validateDestination is where Türkiye's IBAN mod-97 check lives and where Mexico's CLABE check would; destination correctness is a property of the payout rail, not of the app.

// providers/contracts.ts

interface OnrampProvider {
  readonly id: ProviderId;
  supports(rail: FiatRail): boolean;                    // 'ach' | 'wire' | 'card'
  estimateSettlement(rail: FiatRail, at: Date): Date;   // → 'arrives Wed, Aug 5'
  createDeposit(req: DepositRequest, idem: IdempotencyKey): Promise<ProviderRef>;
  parseWebhook(raw: unknown, sig: string): OnrampEvent | null;
}

interface PayoutProvider {
  readonly id: ProviderId;
  supports(corridor: CorridorId): boolean;
  validateDestination(d: Destination): ValidationResult;  // local + synchronous
  submit(req: PayoutRequest, idem: IdempotencyKey): Promise<ProviderRef>;
  parseWebhook(raw: unknown, sig: string): PayoutEvent | null;
}

interface KycProvider {
  readonly id: ProviderId;
  createSession(userId: UserId): Promise<{ sessionId: string; uploadUrl: string }>;
  parseWebhook(raw: unknown, sig: string): KycEvent | null;
}

// Every provider normalises its own vendor payload into Corridor's event vocabulary.
// The orchestrator never sees a vendor-shaped object. This is the entire point:
// swapping turkiye.try.bank for a different partner touches one file.

One transfer, eleven states

State is a fold over an append-only event log, not a mutable column. Three providers with three clocks will deliver events out of order and more than once; a log makes that a non-event, and it means the in-flight screen can always be rebuilt exactly as the user saw it.

// transfer/events.ts: the log. State is fold(events).
type TransferEvent =
  | { t: 'quote_accepted';   quoteId: QuoteId }
  | { t: 'onramp_initiated'; ref: ProviderRef; rail: FiatRail }
  | { t: 'onramp_settled';   amount: Money }
  | { t: 'onramp_returned';  code: AchReturnCode }   // R01 | R08 | R10 …
  | { t: 'minted';           amount: Money }         // USD → USDC, at par
  | { t: 'chain_submitted';  txHash: Hex }
  | { t: 'chain_confirmed';  txHash: Hex; confirmations: number }
  | { t: 'payout_submitted'; ref: ProviderRef }
  | { t: 'payout_delivered'; at: string }
  | { t: 'payout_returned';  reason: PayoutReturnReason }
  | { t: 'refunded';         amount: Money };

// Every event carries these. seq is assigned by Corridor on ingress,
// never taken from the provider, whose ordering guarantees are its own business.
interface Envelope {
  readonly seq: number;
  readonly at: string;          // Corridor's clock
  readonly providerAt?: string;  // the vendor's clock, kept for forensics only
  readonly idem: IdempotencyKey;
}

The funded_held decision

Phase 2 asserted that Corridor holds the payout until ACH clears rather than fronting the funds. This is where that becomes a state, a cost, and an admission.

• Holding to settlement covers the common returns. R01 insufficient funds and R08 stop payment surface within roughly two banking days. Waiting for settlement before releasing the payout eliminates both, which is precisely why screen 09 shows "USD received" as a discrete, timestamped step instead of hiding a two-day wait inside a spinner.
• It does not cover R10. An unauthorised-debit return can arrive up to 60 days later. By then the lira has been spent. No holding period that a customer would tolerate closes this window, so it cannot be designed away.
• So it gets priced and bounded instead. Residual R10 exposure is carried in the $3.75 fee, and constrained by per-user velocity limits until an account has settled history: first transfer capped low, limit rising with successful settlements rather than with elapsed time.
• The alternative is a real product, not a mistake. Fronting the funds buys same-day delivery and needs working capital plus fraud scoring. It's the right call at scale and the wrong one for a first corridor, and a design doc that pretended the choice didn't exist would be the actual error.

Idempotency and reconciliation

• Keys are minted client-side when screen 08 mounts, not at submit. A user who taps through a flaky connection retries with the same key, and the second request returns the first result rather than a second transfer.
• Provider calls carry the transfer's key, scoped per leg: {transferId}:onramp, {transferId}:payout. A reorg-driven chain resubmit reuses {transferId}:chain, so a duplicate submission is impossible even across process restarts.
• Webhooks are the fast path; polling is the floor. Any transfer not in a terminal state is re-polled on exponential backoff. Dropped webhooks are normal, not exceptional; a design that only handles the push path is a design that stalls silently in production.
• Steps are monotonic in the UI. An out-of-order webhook that would move a step backwards is recorded in the log but not reflected on screen 09. A user watching a completed step un-complete has just learned not to trust the screen, and they're right to.

Producing the proof artifact

One genuinely real transaction, end to end, signed by a wallet the user owns. Everything else in this build is a simulation and says so; this is the part that isn't.

// The only place the app itself moves value.
// Privy holds the key shards; the app never sees a private key.

const { wallets } = useEmbeddedEthereumWallet();
const provider = await wallets[0].getProvider();

// ERC-20 transfer(address,uint256) on Base Sepolia USDC
const USDC = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';  // 6 decimals

const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    to:   USDC,
    data: encodeFunctionData({
      abi: erc20Abi,
      functionName: 'transfer',
      args: [treasuryAddress, 500_000_000n],   // 500.00 USDC
    }),
  }],
});

// → surfaced on screen 09 the moment it exists, not held back for the receipt.
// → 0x551c···ba10  ·  verifiable on sepolia.basescan.org

• The hash appears mid-flight, not on success. Screen 09 shows it as soon as the transaction is submitted. Proof that is only revealed once everything worked is not proof of much.
• Testnet is disclosed everywhere it appears: the persistent demo strip on screen 02, and "Base Sepolia" next to the hash on screen 10. A testnet hash presented as mainnet would be the one genuinely dishonest thing in the project.
• Confirmations are read from the chain, not simulated. The 2 / 12 counter on screen 09 is a real subscription: it's the one number in the whole in-flight screen that nothing could fake.
• Funded from Circle's public faucet: 20 USDC per address every 2 hours, so the demo amount of 500.00 USDC needs either accumulation across intervals or a smaller headline figure for the recorded walkthrough.

The app cannot tell

A mock that the application knows about is a mock that hides integration bugs until the day you swap it. Corridor's simulated providers implement the same interfaces, emit the same events through the same webhook ingress, and are selected by configuration.

// providers/registry.ts
const PROVIDERS: Record<ProviderId, Provider> = {
  'bridge.usd.ach':  env.BRIDGE_KEY ? new BridgeOnramp(env)  : new SimulatedOnramp(fixtures.ach),
  'turkiye.try.bank': env.TRY_KEY    ? new TurkiyePayout(env)  : new SimulatedPayout(fixtures.try),
  'kyc.fixture':     env.KYC_KEY    ? new VendorKyc(env)     : new SimulatedKyc(fixtures.kyc),
};

// There is no `if (isMock)` anywhere above this line. Not in the orchestrator,
// not in the API layer, and certainly not in the app. The seam is the only
// place that knows, and it decides once, at boot, from the environment.

• Simulated providers advance on a timer and POST to the real webhook endpoint, signed with a local secret. The ingress path, the signature check, the parseWebhook normalisation, the ordering logic and the reconciler are all exercised identically. When a real key arrives, the untested surface is one adapter.
• Fixtures encode timing, not just payloads. The ACH fixture settles at T+2 in wall-clock terms, compressed for demos by an env-controlled factor. A mock that returns instantly would have hidden the entire funded_held design.
• Failure fixtures are first-class. fixtures.try.nameMismatch drives screen 11c end to end: payout rejected, USDC returned to balance, fees for the failed leg refunded. The unhappy paths are exercised on every run, not written once and left to rot.
• Disclosure is derived, not authored. The demo strip and the per-screen simulated badges read from the same registry that selects the providers, so a screen cannot claim a leg is real while the server is running a simulation. The honesty rule is enforced by construction rather than by remembering.

What lives where

What has to happen before phase 4

Two of these need an account created by hand. Everything else is code.

Screen → service map

Carried into the phase 5 failure-modes writeup: Bridge has no TRY route and why the seam absorbed that; ACH R10 exposure being bounded rather than eliminated, and the reserve it implies; rate-lock expiry and re-quote semantics; Turkish name-match rejection as an unpreventable failure made cheap; chain reorg resubmission under a stable idempotency key; KYC provider outage as a hard stop rather than a bypass; the faucet-versus-demo-amount constraint on the proof artifact; and that Privy's Expo SDK has no web target, so there is no browser fallback demo.