Add RTGS custody and liquidity operating models
All checks were successful
Deploy to Phoenix / deploy (push) Successful in 5s
All checks were successful
Deploy to Phoenix / deploy (push) Successful in 5s
This commit is contained in:
defiQUG
@@ -0,0 +1,162 @@
|
||||
# DBIS RTGS Depository and Custody Operating Model
|
||||
|
||||
**Last updated:** 2026-03-29
|
||||
**Purpose:** Implementation-grade operating model for the depository / CSD, global custodian, and custody / safekeeping / asset-servicing layers referenced by the DBIS RTGS canonical production checklist.
|
||||
|
||||
## 1. Scope
|
||||
|
||||
This document freezes the intended runtime boundaries for:
|
||||
|
||||
- `Depository / CSD layer`
|
||||
- `Global custodian layer`
|
||||
- `Custody / safekeeping / asset servicing flow`
|
||||
|
||||
It does not claim these layers are already deployed. It defines the operating contract they must satisfy before they can be marked `Complete` in the canonical checklist.
|
||||
|
||||
## 2. Canonical role split
|
||||
|
||||
### Depository / CSD layer
|
||||
|
||||
Owns:
|
||||
|
||||
- authoritative asset register for in-scope instruments
|
||||
- issuance, transfer, pledge, lien, and release semantics
|
||||
- linkage between asset ownership state and RTGS settlement-touch state
|
||||
|
||||
Does not own:
|
||||
|
||||
- cash ledger posting
|
||||
- bank-message transport
|
||||
- treasury funding decisions
|
||||
|
||||
### Global custodian layer
|
||||
|
||||
Owns:
|
||||
|
||||
- safekeeping account hierarchy
|
||||
- sub-custody and global-bank/correspondent custody relationships
|
||||
- statements, confirmations, and servicing references
|
||||
|
||||
Does not own:
|
||||
|
||||
- canonical cash settlement
|
||||
- pricing or liquidity decisions
|
||||
- on-chain anchoring
|
||||
|
||||
### Custody / safekeeping / asset servicing flow
|
||||
|
||||
Owns:
|
||||
|
||||
- holdings lifecycle from registration to reporting
|
||||
- statement generation and custody evidence references
|
||||
- servicing events such as entitlement, transfer instruction, and post-settlement reporting
|
||||
|
||||
Does not own:
|
||||
|
||||
- participant master data
|
||||
- FX price formation
|
||||
- liquidity source selection
|
||||
|
||||
## 3. Canonical business objects
|
||||
|
||||
| Object | Primary owner | Required downstream link |
|
||||
|--------|---------------|--------------------------|
|
||||
| `asset_position` | Depository / CSD | custody statement, settlement-touch reference |
|
||||
| `transfer_instruction` | Depository / CSD | RTGS orchestrator, OMNL posting reference |
|
||||
| `custody_account` | Global custodian | participant / office / account mapping |
|
||||
| `custody_statement` | Global custodian | reconciliation package, audit evidence |
|
||||
| `servicing_event` | Custody flow | holdings state, evidence package |
|
||||
| `settlement_touch_reference` | Depository / CSD | chain/off-ledger settlement evidence |
|
||||
|
||||
## 4. Required integrations
|
||||
|
||||
### Upstream
|
||||
|
||||
- OMNL participant / office / treasury model
|
||||
- RTGS orchestrator correlation IDs
|
||||
- external institution master data
|
||||
|
||||
### Downstream
|
||||
|
||||
- OMNL / Fineract postings
|
||||
- external bank statements or confirmations
|
||||
- Chain 138 settlement evidence where on-ledger finality is in scope
|
||||
- ISO 20022 / institutional evidence package
|
||||
|
||||
## 5. Canonical flow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
REQUEST["Transfer / Asset Instruction"] --> CSD["Depository / CSD"]
|
||||
CSD -->|"asset ownership update"| CUST["Global Custodian"]
|
||||
CSD -->|"settlement touch reference"| ORCH["RTGS Orchestrator"]
|
||||
ORCH -->|"cash posting"| OMNL["OMNL / Fineract"]
|
||||
ORCH -->|"bank or chain settlement"| SETTLE["Settlement Rail"]
|
||||
CUST -->|"statement / servicing output"| EVIDENCE["Evidence / Reconciliation"]
|
||||
OMNL --> EVIDENCE
|
||||
SETTLE --> EVIDENCE
|
||||
```
|
||||
|
||||
## 6. Minimum interface contract
|
||||
|
||||
### Depository asset-register and settlement-touch contract
|
||||
|
||||
- Input:
|
||||
- participant reference
|
||||
- instrument reference
|
||||
- action type: issue / transfer / pledge / release
|
||||
- quantity / amount
|
||||
- correlation id
|
||||
- Output:
|
||||
- asset position id
|
||||
- settlement-touch reference
|
||||
- depository state
|
||||
- Failure contract:
|
||||
- reject with reason code and no settlement-touch reference
|
||||
|
||||
### Global custodian account/reporting contract
|
||||
|
||||
- Input:
|
||||
- participant or sub-custody account reference
|
||||
- position or servicing reference
|
||||
- reporting period or event type
|
||||
- Output:
|
||||
- custody statement reference
|
||||
- servicing reference
|
||||
- reconciliation reference
|
||||
- Failure contract:
|
||||
- produce exception state with unresolved custody item
|
||||
|
||||
### Custody lifecycle contract
|
||||
|
||||
- Input:
|
||||
- custody account reference
|
||||
- position reference
|
||||
- servicing action
|
||||
- correlation id
|
||||
- Output:
|
||||
- custody lifecycle state
|
||||
- statement/evidence reference
|
||||
- Failure contract:
|
||||
- unresolved servicing queue with operator-visible reason
|
||||
|
||||
## 7. Deployment expectations
|
||||
|
||||
Before these layers can be considered active:
|
||||
|
||||
1. one implementation boundary must be selected for the depository role:
|
||||
- on-ledger
|
||||
- off-ledger
|
||||
- hybrid
|
||||
2. one implementation boundary must be selected for the global custodian role
|
||||
3. one canonical custody flow must be bound to OMNL and RTGS settlement
|
||||
4. reconciliation outputs must include holdings and statement references
|
||||
|
||||
## 8. Production gate
|
||||
|
||||
This operating model is complete only when:
|
||||
|
||||
1. one canonical asset flow uses the depository touch point
|
||||
2. one canonical custody flow generates statements/evidence
|
||||
3. holdings, settlement, and accounting reconcile in the same package
|
||||
4. the canonical production checklist rows for these layers can move from `Planned` to `Partial` or `Complete` with evidence
|
||||
187
docs/03-deployment/DBIS_RTGS_FX_AND_LIQUIDITY_OPERATING_MODEL.md
Normal file
187
docs/03-deployment/DBIS_RTGS_FX_AND_LIQUIDITY_OPERATING_MODEL.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user