Skip to main content

PRD : Forsyt Broker Service

Instant Settlement | iFrame-Based Exchange Execution | USDC on Solana​

1. Objective​

Design and implement an event-driven architecture that enables:

  • Exchange trading via embedded iFrame
  • User funds held in USDC (Solana)
  • Exchange execution, matching, and hedge routing handled entirely by the iFrame
  • Instant settlement to users post-market resolution
  • Weekly exchange cash settlement
  • Strong capital, FX, and risk controls

This PRD covers:

  • User flows
  • System boundaries
  • Services
  • Events
  • State transitions
  • Failure handling

2. Core Architectural Principles​

  1. Execution is external (iFrame), economics are internal (Forsyt)
  2. Event-first, not API-first
  3. Single source of truth per domain
  4. No synchronous coupling between trading and money
  5. All irreversible actions are event-backed
  6. Ledgers are append-only

3. High-Level System View​

User
 ↓
Forsyt Frontend
 ↓
API Gateway
 ↓
Event Bus (Kafka / Redpanda / NATS)
 ↓
Domain Services

Execution path:

User → iFrame → Exchange → iFrame → Forsyt

Forsyt never places trades directly.

4. Domain Services (Mandatory)​

4.1 Identity & Session Service​

  • User authentication
  • Session token generation
  • Mapping Forsyt user ↔ exchange session

4.2 Wallet Service (USDC – Solana)​

Source of truth for user funds

Responsibilities:

  • Track deposits
  • Track available / locked / withdrawable balances
  • Execute locks and unlocks
  • Emit wallet events only (never pull)

4.3 Ledger Service (Critical)​

Double-entry, append-only

Responsibilities:

  • User ledger
  • Settlement receivable ledger
  • FX ledger
  • Treasury ledger

No business logic.

Only validates and records events.

4.4 Exchange Gateway Service (iFrame / Sevens)​

Single integration point with the exchange

Responsibilities:

  • Create iFrame sessions
  • Receive exchange callbacks
  • Normalize exchange lifecycle events
  • Emit exchange domain events

Important:

  • Does NOT place or hedge bets
  • Execution is already handled upstream

4.5 Risk Engine​

Stateless, event-driven decision engine

Responsibilities:

  • Capital utilization checks
  • Exposure caps (per user, per market)
  • Margin sufficiency checks
  • Instant settlement eligibility
  • System kill-switch triggers

4.6 Settlement Service​

User-facing settlement authority

Responsibilities:

  • Apply exchange PnL to users
  • Decide instant vs delayed settlement
  • Record exchange receivables
  • Maintain settlement state

4.7 FX & Treasury Service​

Balance-sheet management

Responsibilities:

  • Track EUR/GBP exposure
  • Maintain FX inventory
  • Convert fiat ↔ USDC
  • Track settlement inflows

4.8 Withdrawal Service​

Final cash-out authority

Responsibilities:

  • Enforce withdrawal limits
  • Validate withdrawable balance
  • Execute on-chain USDC transfers
  • Apply emergency restrictions

5. Event Bus​

Single shared bus, topic-segmented.

wallet.*
exchange.*
risk.*
settlement.*
treasury.*
withdrawal.*

Rules:

  • Services consume events
  • Services emit events
  • No service mutates another service’s state

6. User Flow – End-to-End (Event View)​

6.1 User Deposit (USDC on Solana)​

Flow​

  1. User transfers USDC to Forsyt vault
  2. Chain watcher confirms transaction

Events​

WalletDepositDetected {
  userId,
  amount,
  txHash,
  chain: "SOLANA"
}

WalletBalanceUpdated {
  userId,
  availableDelta: +amount,
  lockedDelta: 0
}

Ledger entry recorded.

6.2 User Opens Exchange​

Flow​

  1. Frontend requests exchange session
  2. Exchange Gateway calls /frame-url
  3. iFrame URL returned

Events​

ExchangeSessionCreated {
  userId,
  sessionToken,
  iframeUrl
}

No balance changes.

6.3 User Places Bet (Inside iFrame)​

Execution:

  • iFrame places bet
  • iFrame routes execution to exchange
  • Exchange computes required margin

Exchange → Forsyt callback​

ExchangeMarginRequested {
  userId,
  betId,
  amount,
  currency,
  marketId
}

6.4 Risk Check & Fund Lock​

Risk Engine consumes margin request​

Validates:

  • User available balance
  • Market exposure limits
  • Capital utilization thresholds

If approved​

RiskApproved {
  betId,
  userId
}

Wallet Service consumes approval​

WalletFundsLocked {
  userId,
  amount,
  reason: "EXCHANGE_MARGIN",
  betId
}

Ledger updated.

If rejected → compensating event sent to exchange.

6.5 Bet Lifecycle Updates​

Handled entirely by iFrame / exchange.

Forsyt receives informational events:

ExchangeBetMatched
ExchangeBetUpdated
ExchangeBetCancelled

Used for:

  • Exposure tracking
  • Risk recalculation

6.6 Market Settlement (Critical Point)​

ExchangeMarketSettled {
  marketId,
  outcome
}

Followed by:

ExchangeBetSettled {
  betId,
  pnl,
  currency
}

Outcome is now final.

7. Instant Settlement Flow​

7.1 Settlement Eligibility Check​

Settlement Service validates:

  • Market is settled
  • Exchange PnL is final
  • Risk Engine allows instant settlement

7.2 User Settlement Applied​

UserSettlementApplied {
  userId,
  betId,
  pnlUSDC
}

Wallet updates:

WalletFundsUnlocked {
  userId,
  lockedDelta: -stake,
  availableDelta: stake + pnl
}

User funds are now withdrawable immediately.

7.3 Exchange Receivable Recorded​

SettlementReceivableRecorded {
  counterparty: "EXCHANGE",
  amount,
  currency,
  expectedSettlementDate
}

This represents Forsyt’s float.

8. Withdrawal Flow​

8.1 User Requests Withdrawal​

WithdrawalRequested {
  userId,
  amountUSDC
}

8.2 Risk & Liquidity Validation​

Risk Engine checks:

  • Withdrawable balance
  • Global liquidity thresholds
  • Rate limits

8.3 Execute Withdrawal​

WithdrawalExecuted {
  userId,
  amountUSDC,
  txHash
}

Ledger updated.

9. Weekly Exchange Settlement​

ExchangeSettlementReceived {
  amount,
  currency,
  settlementPeriod
}

Treasury Service:

  • Updates balances
  • Clears receivable
  • Executes FX conversion if required

10. Failure & Rollback Model​

Principles​

  • No deletes
  • All rollbacks are compensating events
  • Exchange is authoritative on trade state

Examples:

RiskRejected
WalletLockReverted
SettlementDelayed
InstantSettlementDisabled

11. Kill Switches (Mandatory)​

Triggered by Risk Engine:

SystemRestrictionApplied {
  restrictionType,
  reason
}

Types:

  • Disable new exchange bets
  • Disable instant settlement
  • Throttle withdrawals
  • Freeze system

12. POC Scope (Strict)​

MUST​

  • Event bus
  • Wallet + Ledger
  • Exchange Gateway
  • Risk Engine
  • Settlement Service

NOT REQUIRED​

  • Full FX automation
  • Advanced treasury strategies
  • Analytics dashboards

13. Architectural Truths (Non-Negotiable)​

  • iFrame handles execution and hedging
  • Forsyt handles money, timing, and guarantees
  • Instant settlement is a capital decision
  • Net exposure matters, not gross volume
  • Event-driven design is mandatory

14. Final Statement​

This architecture:

  • Eliminates duplicate execution logic
  • Correctly assigns responsibility boundaries
  • Is capital-aware and risk-bounded
  • Is defensible in front of engineering, risk, and finance

This is the final PRD.

If you want next, I can:

  • Turn this into Kafka topic + schema specs
  • Produce sequence diagrams
  • Run capital stress simulations
  • Generate an engineering task breakdown

But structurally and conceptually — this document is now clean, correct, and safe.