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.

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

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_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md
• HYBX_BATCH_001_OPERATOR_CHECKLIST.md
• OMNL_TRANSACTION_SEQUENCE_FULL.md
• PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md
• FX_AND_VALUATION.md
• SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md