proxmox/docs/03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md

# DBIS RTGS FX Transaction Catalog

**Last updated:** 2026-03-29  
**Purpose:** Canonical transaction catalog for FX, cross-border banking, and RTGS-adjacent settlement flows across OMNL, HYBX sidecars, Chain 138, and Indonesia-facing beneficiary banks such as Bank Kanaya and BNI-connected correspondent paths.

## Scope

This document describes the full transaction families required for a production-grade FX and cross-border RTGS stack:

- OMNL / Fineract journal-entry flows
- HYBX sidecar business flows
- ISO 20022 and SWIFT Fin message flows
- FX valuation and revaluation flows
- correspondent-banking and nostro / vostro flows
- Chain 138 settlement augmentation where on-ledger finality is in scope

This document is not a statement that every flow is already deployed. It is the execution catalog for what must exist to call the stack fully end to end.

**Canonical integration map (OMNL API, DBIS Core, Chain 138 Smart Vaults, fiat wallet binding, external RTGS, correlation IDs, ISO-20022 on-chain, DID/eIDAS, FX/token-aggregation):** [OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md](OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md) (see section 14).

## Status legend

- `Implemented now`
- `Partially implemented`
- `Required next`

## 1. Core transaction families

| Family | Description | Current status | Primary systems |
|--------|-------------|----------------|-----------------|
| Opening balance / reserve migration | Initial OMNL funding and reserve booking | Implemented now | OMNL / Fineract |
| M0 to M1 conversion | Central-bank style monetary conversion and allocation | Implemented now | OMNL / Fineract |
| Interoffice settlement | HO to branch / institution due-to / due-from settlement | Implemented now | OMNL / Fineract |
| PvP multilateral net settlement | Beneficiary office receives net cleared position | Partially implemented | OMNL / Fineract |
| Sidecar-initiated RTGS posting | Business-side RTGS transfer posted into OMNL via sidecar | Partially implemented | `mifos-fineract-sidecar`, OMNL |
| Treasury / funding orchestration | Treasury approval, prefunding, limits, release | Required next | `server-funds-sidecar`, OMNL |
| Off-ledger to on-ledger conversion | External event to Chain 138 settlement leg | Required next | `off-ledger-2-on-ledger-sidecar`, Chain 138 |
| FX valuation / revaluation | Spot, triangulated, and end-of-day revaluation | Required next | OMNL, rate feeds |
| Correspondent-bank settlement | Nostro / vostro reconciliation with domestic / global banks | Required next | OMNL, bank APIs, ISO/SWIFT rails |
| Regulatory evidence package | Indonesia / institution-ready package and submission | Partially implemented | OMNL scripts, evidence tooling |

## 2. Full FX transaction classes

### 2.1 Internal treasury FX conversion

**Purpose**
- Convert between currencies inside OMNL treasury books.
- Support central treasury reserve management and internal balance-sheet positioning.

**Required legs**
1. Debit source currency reserve / treasury account.
2. Credit target currency reserve / treasury account.
3. Post realized or unrealized FX P&L where applicable.
4. Update revaluation basis and audit trail.

**Key GL patterns**
- `12010` / `12020` / `12090` — FX reserve detail
- `13010` — FX settlement nostro
- `42000` / `51000` — realized FX gain / loss
- `42100` / `52100` — unrealized FX gain / loss

**Required messages / records**
- Internal treasury instruction
- Rate source reference
- value date / trade date
- dealing reference
- settlement reference

**Status**
- GL and valuation framework are documented.
- End-to-end booked treasury FX conversion flow is not yet proven in production.

### 2.2 Domestic beneficiary settlement in Indonesia

**Purpose**
- Credit Indonesian beneficiary institutions such as Bank Kanaya on OMNL books.
- Support domestic regulatory reporting and beneficiary balance confirmation.

**Required legs**
1. Clear multilateral or bilateral obligation.
2. Post OMNL journal entries to beneficiary office.
3. Attach settlement reference and supporting evidence.
4. Reconcile beneficiary office balances and produce regulator-facing package.

**Current repo-backed example**
- `HYBX-BATCH-001`
- beneficiary office `22` Bank Kanaya
- `USD 1,000,000,000.00`
- PvP multilateral net narrative in [PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md](../04-configuration/mifos-omnl-central-bank/PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md)

**Status**
- Repo-backed posting and package path exists.
- Live authenticated sidecar-to-OMNL posting now exists.
- Full production beneficiary-bank operating model is still not frozen.

### 2.3 Cross-border commercial-bank FX payment

**Purpose**
- Move value from OMNL / central-bank context through a domestic or correspondent bank path to an external bank.

**Required legs**
1. Payment initiation or settlement instruction received.
2. FX quote / rate locked.
3. Compliance and sanctions checks.
4. Nostro / vostro and prefunding checks.
5. Debit source balance / reserve.
6. Credit beneficiary bank or correspondent account.
7. Reconcile statement and confirmation messages.
8. Produce audit and regulatory evidence.

**Required message families**
- ISO 20022:
  - `pain.001`
  - `pacs.008`
  - `pacs.009`
  - `pacs.002`
  - `camt.052`
  - `camt.053`
  - `camt.054`
- SWIFT Fin where needed:
  - `MT103`
  - `MT202` / `MT202 COV`
  - optionally statement or advice equivalents off-platform

**Status**
- Message methodology is documented.
- A production cross-border message rail is not yet fully deployed in this workspace.

### 2.4 Chain-anchored RTGS settlement

**Purpose**
- Add on-ledger finality or settlement confirmation on Chain 138 after OMNL-side accounting.

**Required legs**
1. Off-ledger business event finalized in OMNL.
2. Canonical settlement event created with stable identifiers.
3. Chain 138 contract path selected.
4. Settlement token / registry / escrow action executed.
5. On-chain transaction hash captured in evidence package.
6. Reconciliation ties OMNL transaction, sidecar correlation ID, and chain tx hash together.

**Likely on-chain components**
- `MerchantSettlementRegistry`
- `WithdrawalEscrow`
- compliant settlement token set
- reserve / oracle controls where minting or conversion is involved

**Status**
- Contract inventory exists.
- Canonical RTGS chain leg is not yet frozen end to end.

## 3. Message-by-message transaction detail

### 3.1 `pain.001` customer initiation

**Used for**
- bank or enterprise payment initiation into the RTGS workflow

**Minimum mapped fields**
- debtor / creditor
- debtor account / creditor account
- amount
- currency
- end-to-end id
- purpose

**Downstream**
- mapped into canonical payload
- feeds compliance and posting workflow

### 3.2 `pacs.008` FI-to-FI customer credit transfer

**Used for**
- primary credit-settlement instruction between institutions

**Required downstream records**
- instructionId
- MsgId
- UETR if available
- amount / currency
- settlement method
- account references

**Expected system impacts**
- OMNL posting
- sidecar audit event
- optional chain settlement event

### 3.3 `pacs.009` interbank settlement

**Used for**
- bank-to-bank settlement leg
- high-value RTGS interbank flow

**Indonesia / correspondent context**
- preferred for institution-facing settlement instruction where OMNL to beneficiary bank mapping exists

### 3.4 `pacs.002` status reporting

**Used for**
- accept / reject / pending / completed status

**Required use**
- update business workflow state
- feed operator dashboards and evidence package

### 3.5 `camt.053` / `camt.054`

**Used for**
- statement and debit/credit advice reconciliation

**Required use**
- external-bank and nostro/vostro reconciliation
- proof of receipt / settlement confirmation

### 3.6 `MT103` / `MT202`

**Used for**
- legacy correspondent banking or hybrid gateway participation

**Required use**
- normalize into the same canonical struct as MX messages
- preserve raw message hash and field mapping in the evidence chain

## 4. Required reconciliation outputs

Every production FX / RTGS transaction family must produce:

1. business request payload
2. authenticated API request / response evidence
3. OMNL journal-entry ids and journal-entry payload
4. sidecar correlation id / message id / idempotency key
5. rate source and value date
6. beneficiary / counterparty office and account mapping
7. statement / confirmation artifact where external banks are involved
8. on-chain tx hash where Chain 138 is involved
9. package-ready manifest entry

## 5. Required identifiers

The following identifiers must be stable across systems:

- `instructionId`
- `messageId`
- `correlationId`
- `idempotencyKey`
- `settlementRef`
- `transactionId` (OMNL / Fineract)
- `UETR` where applicable
- chain transaction hash where applicable

## 6. Minimum production-complete FX criteria

The FX stack is not production-complete until all of the following are true:

1. rate source and valuation policy are frozen
2. participant / office / treasury / GL model is frozen
3. domestic beneficiary-bank flow is repeatable
4. correspondent-bank flow is documented and tested
5. reconciliation captures all identifiers and statement evidence
6. regulatory package includes FX-specific reporting and prudential mapping
7. chain settlement leg is either fully implemented or explicitly out of scope

## 7. Current truth

### Proven now

- OMNL tenant/auth is live and usable
- `mifos-fineract-sidecar` has completed an authenticated live OMNL posting
- the accounting side of a canonical business transfer can be initiated from a deployed sidecar on Proxmox VE

### Still open

- full treasury / funds orchestration
- off-ledger to Chain 138 settlement leg
- correspondent-bank and BNI-specific external settlement path
- full evidence package covering banking message + accounting + on-chain finality in one run

## Related artifacts

- [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)
- [DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md](DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md)
- [HYBX_BATCH_001_OPERATOR_CHECKLIST.md](../04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md)
- [OMNL_TRANSACTION_SEQUENCE_FULL.md](../04-configuration/mifos-omnl-central-bank/OMNL_TRANSACTION_SEQUENCE_FULL.md)
- [PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md](../04-configuration/mifos-omnl-central-bank/PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md)
- [FX_AND_VALUATION.md](../04-configuration/mifos-omnl-central-bank/FX_AND_VALUATION.md)
- [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](../04-configuration/SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md)