proxmox/docs/03-deployment/DBIS_RTGS_FX_AND_LIQUIDITY_OPERATING_MODEL.md

DBIS RTGS FX and Liquidity Operating Model

Last updated: 2026-03-29
Purpose: Implementation-grade operating model for the FX pricing / dealing engine, liquidity pooling and aggregation engine, and liquidity source adapters referenced by the DBIS RTGS canonical production checklist.

1. Scope

This document freezes the intended runtime boundaries for:

• FX pricing / dealing engine
• Liquidity pooling and aggregation engine
• Liquidity source adapters

It defines the minimum behavior required before these layers can be promoted from architecture intent into a validated production lane.

2. Canonical role split

FX pricing / dealing engine

Owns:

• quote generation or approved rate ingest
• source hierarchy for rates
• spread / fee policy application
• quote locking, expiry, and value-date semantics
• booking references for OMNL and settlement

Does not own:

• final accounting ledger
• final liquidity-source selection
• final settlement transport

Liquidity pooling and aggregation engine

Owns:

• evaluate available liquidity sources
• prioritize and allocate funding
• enforce eligibility and operator override rules
• emit the canonical funding decision reference

Does not own:

• FX quote formation
• bank-message transport
• settlement evidence packaging

Liquidity source adapters

Owns:

• normalize access to internal treasury pools
• normalize access to bank lines and correspondent-bank sources
• normalize access to optional on-chain liquidity
• return funding availability, hold, release, and failure states

Does not own:

• aggregate funding decisions
• journal posting
• orchestration state

3. Canonical business objects

Object	Primary owner	Required downstream link
fx_quote	FX engine	OMNL booking, settlement refs
fx_booking_reference	FX engine	journal refs, evidence package
funding_request	Liquidity engine	source adapter calls
funding_decision	Liquidity engine	OMNL posting, settlement rail, evidence package
liquidity_adapter_result	Source adapter	funding decision
rate_source_reference	FX engine	FX reconciliation

4. Required source classes

Mandatory source classes to model:

1. internal treasury pools
2. bank credit / liquidity lines
3. correspondent-bank liquidity
4. optional on-chain liquidity if it remains in the target production path

Each class must have:

• auth model
• request contract
• response contract
• failure code mapping
• hold/release semantics

5. Canonical flow

flowchart LR
    REQ["Payment / Settlement Request"] --> ORCH["RTGS Orchestrator"]
    ORCH --> FX["FX Pricing / Dealing Engine"]
    FX -->|"locked quote"| ORCH
    ORCH --> LQE["Liquidity Pooling / Aggregation Engine"]
    LQE --> AD1["Internal Treasury Adapter"]
    LQE --> AD2["Bank Line Adapter"]
    LQE --> AD3["Correspondent Adapter"]
    LQE --> AD4["Optional On-Chain Adapter"]
    AD1 --> LQE
    AD2 --> LQE
    AD3 --> LQE
    AD4 --> LQE
    LQE -->|"funding decision"| ORCH
    ORCH --> OMNL["OMNL / Fineract"]
    ORCH --> SETTLE["Settlement Rail"]

6. Minimum interface contract

FX quote/pricing/booking contract

• Input:
  • source currency
  • destination currency
  • amount
  • value date
  • participant / route context
• Output:
  • quote id
  • rate
  • spread / fee
  • expiry
  • booking reference
• Failure contract:
  • reject quote with explicit reason and no booking reference

Liquidity-engine source-selection and allocation contract

• Input:
  • funding request id
  • route context
  • required amount / currency
  • value date
  • constraints / policy flags
• Output:
  • funding decision id
  • selected source set
  • allocation amounts
  • operator action requirement if needed
• Failure contract:
  • insufficient-liquidity or policy-rejected state

Liquidity source adapter contract

• Input:
  • funding request
  • hold/release action
  • source account or line reference
• Output:
  • adapter result id
  • availability / hold / release confirmation
  • failure code
• Failure contract:
  • adapter error with retriable vs terminal distinction

7. Reconciliation requirements

Required reconciliations:

1. rate source vs booked rate
2. quote id vs OMNL posting reference
3. funding decision vs selected source confirmations
4. source holds/releases vs actual settlement usage
5. FX gain/loss and fee treatment vs final accounting outputs

8. Deployment expectations

Before these layers can be considered active:

1. the canonical rate hierarchy must be frozen
2. the canonical funding-source priority model must be frozen
3. mandatory source adapters must be enumerated and assigned
4. one canonical FX-backed transfer must run end to end with quote and funding references preserved

9. Production gate

This operating model is complete only when:

1. one canonical FX transaction completes with frozen pricing inputs
2. one canonical funding decision is emitted and reconciled
3. mandatory liquidity source adapters are validated
4. the canonical production checklist rows for these layers can move from Planned to Partial or Complete with evidence