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

```mermaid
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