Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Architecture

This page describes the technical architecture of the Madhouse Wallet off-ramp platform.

System Components

Partner / API Key Caller
        ↓
  API Gateway (TLS 1.2+)
        ↓
  withExternalAuth — JWT or API key validation
        ↓
  Rate Limiter (per-key, sliding window)
        ↓
  Handler Logic
        ↓
  ┌─────────────────────────┐
  │  MongoDB (UserSession,  │
  │  PayoutTransaction,     │
  │  RecipientOwnership)    │
  └─────────────────────────┘
        ↓
  FX & Routing Infrastructure
        ↓
  On-chain USDC detection (multi-chain)
        ↓
  Outgoing fiat transfer (local rails / SWIFT / SEPA)

Request Authentication

Every API request passes through withExternalAuth, which:

  1. Detects whether the Authorization header carries a JWT (dashboard session) or API key (mw_live_...)

  2. For API keys: looks up the SHA-256 hash in MongoDB, stamps lastUsedAt, checks wallet requirement, enforces IP restriction if enabled

  3. For JWTs: verifies ES256 signature against the app's own ECDSA keypair, checks MongoDB session record

  4. Applies per-key rate limits before the handler runs

Transfer Pipeline

Each transfer follows an immutable state machine:

Every state transition is written atomically to MongoDB. The deposit address is unique per transfer — on-chain deposits are matched to the correct PayoutTransaction record via the deposit address, not scanned from a shared pool.

On-Chain Detection

The platform monitors deposits across all supported chains simultaneously:

  • Arbitrum, Base, Optimism, Polygon (EVM-compatible)

  • Ethereum Mainnet

  • Solana

When a USDC transfer to a deposit address is confirmed on-chain, the associated transfer record is updated and the conversion pipeline begins.

FX Conversion

Conversion uses institutional FX liquidity with real-time mid-market rates. Rates are locked at quote time for 5 minutes. No rate changes occur after a quote is accepted.

Outgoing Settlement

The outgoing fiat transfer is created and funded automatically after conversion. Settlement rails used depend on the recipient's currency:

  • Local bank transfer — instant to same-day (most currencies)

  • SEPA/IBAN — same day (EUR, GBP, and other European currencies)

  • M-PESA — instant (KES)

  • UPI — instant (INR)

  • CLABE — local (MXN)

  • ACH — 1–2 business days (USD)

  • SWIFT — 5–7 business days (global fallback)

Data Storage

All transfer records, recipient ownership, and session data are stored in MongoDB hosted on AWS (us-east-1), with controls designed to meet GDPR and CCPA requirements for the protection of customer data and personally identifiable information (PII).

Encryption

Layer
Method

Data at rest

AES-256-GCM encryption applied to all stored records

Data in transit

TLS 1.2 or higher enforced on all connections

API keys

SHA-256 hashed before storage — plaintext is never persisted

Dashboard session responses

AES-256-GCM encrypted per-session

Signing keys

Held in AWS KMS; keys are generated and used within HSMs and never exported

PII Handling

Recipient banking details (account numbers, routing numbers, IBAN, and similar fields) are treated as PII and are:

  • Encrypted at rest using AES-256-GCM

  • Never logged in plaintext

  • Accessible only to the authenticated partner or user who submitted them

  • Not shared with third parties beyond the settlement rail required to complete the transfer

Data Minimisation and Retention

Only data necessary to execute and audit a transfer is collected. Short-lived records (OTP codes, deposit challenges) are automatically purged using TTL indexes. Partners subject to GDPR may request deletion of personal data via the account dashboard or the support channel; requests are processed within the timeframes required by applicable law.

Access Controls and Audit Trail

  • Sparse indexes ensure per-user data is isolated and fast to retrieve without cross-tenant exposure

  • Atomic findOneAndUpdate operations enforce state-machine transitions and prevent double-processing or race conditions that could expose stale data

  • Every state change is written with a timestamp, creating an immutable audit trail for each transfer

  • Access to production data stores is restricted to authorised personnel via IAM policies and is logged

Smart Account Infrastructure

For dashboard users initiating transfers from the Madhouse Wallet UI, the platform uses ERC-4337 smart accounts (Safe v1.4.1 on Base). Signing keys are held in AWS KMS and never exposed. Gas is paid in USDC via an audited paymaster — no ETH balance required.

Component
Audit

Safe v1.4.1

Audit report

Pimlico ERC-20 Paymaster

Quantstamp certificate

USDC

Circle transparency reports

PreviousSecurity
NextEncryption & Key Management

Last updated

Was this helpful?