Document RTGS FX and Indonesia banking integration

2026-03-29 00:41:48 -07:00
parent d513ac35c0
commit e70964ef2d
5 changed files with 799 additions and 1 deletions
--- a/dbis_chain_138_technical_master_plan.md
+++ b/dbis_chain_138_technical_master_plan.md
@@ -469,6 +469,8 @@ Executable counterparts in this repository:
 | Phase 3 liveness wrapper | `scripts/verify/run-dbis-phase3-e2e-simulation.sh`, `docs/03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md` |
 | Production gate | `docs/03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md` |
 | RTGS E2E requirements matrix | `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` |
+| RTGS FX transaction catalog | `docs/03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md` |
+| Indonesia / BNI E2E integration blueprint | `docs/03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md` |
 | RTGS first-slice architecture | `docs/03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md` |
 | RTGS first-slice deployment checklist | `docs/03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md` |
 | Caliper hook | `docs/03-deployment/CALIPER_CHAIN138_PERF_HOOK.md`, `scripts/verify/print-caliper-chain138-stub.sh` |
--- a/docs/00-meta/ROOT_DIRTY_WORK_REVIEW_2026-03-29.md
+++ b/docs/00-meta/ROOT_DIRTY_WORK_REVIEW_2026-03-29.md
@@ -0,0 +1,117 @@
+# Root Dirty Work Review — 2026-03-29
+
+**Purpose:** Separate unrelated root-repo dirty work from the DBIS RTGS tranche so operators can review risk and merge intent without conflating changes.
+
+## Scope reviewed
+
+From `git status --short` in the root repo:
+
+- modified:
+  - `docs/04-configuration/GITEA_ACT_RUNNER_SETUP.md`
+  - `pnpm-lock.yaml`
+  - `scripts/dev-vm/setup-act-runner.sh`
+  - `scripts/lib/load-project-env.sh`
+  - `smom-dbis-138` submodule pointer dirty
+- untracked:
+  - `scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh`
+  - `scripts/dev-vm/install-act-runner-systemd.sh`
+
+## Findings
+
+### 1. Gitea act-runner lane
+
+**Files**
+- [GITEA_ACT_RUNNER_SETUP.md](../04-configuration/GITEA_ACT_RUNNER_SETUP.md)
+- [setup-act-runner.sh](/home/intlc/projects/proxmox/scripts/dev-vm/setup-act-runner.sh)
+- [bootstrap-gitea-act-runner-site-wide.sh](/home/intlc/projects/proxmox/scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh)
+- [install-act-runner-systemd.sh](/home/intlc/projects/proxmox/scripts/dev-vm/install-act-runner-systemd.sh)
+
+**What changed**
+- docs now describe a site-wide bootstrap path
+- setup defaults now target `http://127.0.0.1:3000`
+- runner labels default to `ubuntu-latest`
+- new scripts appear intended to:
+  - fetch a registration token via admin API
+  - install and daemonize the runner under systemd
+
+**Assessment**
+- This is a coherent feature lane, not random drift.
+- It should be reviewed and committed as a dedicated `act_runner bootstrap` tranche.
+- It is unrelated to the RTGS sidecar work.
+
+**Risk**
+- low to medium if kept isolated
+- medium to high if accidentally bundled with RTGS or infra-truth updates
+
+### 2. `scripts/lib/load-project-env.sh`
+
+**What changed**
+- VMID `5700` was added to the `r630-02` host mapping set.
+
+**Assessment**
+- This appears to be a small support fix for the act-runner / dev-vm lane.
+- It is logically related to the act-runner work above.
+- It should ship with that lane, not with unrelated RTGS work.
+
+**Risk**
+- low if correct
+- moderate if `5700` is mobile and the mapping is treated as permanently canonical
+
+### 3. `pnpm-lock.yaml`
+
+**What changed**
+- substantial additions for a root importer named `smom-dbis-138`
+- many Hardhat / TypeChain / changesets and related packages
+
+**Assessment**
+- this is a generated artifact from a package-manager operation
+- it likely belongs to a separate `smom-dbis-138` JavaScript / Hardhat tooling lane
+- it is not tied to the RTGS docs/deployment tranche
+
+**Risk**
+- medium if committed without the matching `package.json` / workspace intent
+- high if it accidentally lands in the root repo without the team intending to manage `smom-dbis-138` from the root PNPM workspace
+
+### 4. `smom-dbis-138` submodule dirty state
+
+**Observed**
+- deleted contract files:
+  - `contracts/emoney/BridgeVault138.sol`
+  - `contracts/emoney/ComplianceRegistry.sol`
+  - `contracts/emoney/PolicyManager.sol`
+  - `contracts/emoney/TokenFactory138.sol`
+  - several `contracts/emoney/interfaces/*`
+- modified:
+  - `package.json`
+  - `package-lock.json`
+- untracked:
+  - `playwright-report/`
+
+**Assessment**
+- this is high-risk and should be treated as a separate active refactor or deletion lane
+- the deleted contracts are core-emoney-surface files, not cosmetic churn
+- do not bundle or auto-commit this with unrelated infra/docs work
+
+**Risk**
+- high
+
+## Recommended split
+
+1. **Act-runner tranche**
+   - docs
+   - setup script
+   - bootstrap script
+   - systemd install script
+   - `load-project-env.sh` mapping
+
+2. **Root JS / lockfile tranche**
+   - `pnpm-lock.yaml`
+   - only if intentionally paired with a matching workspace/package change
+
+3. **`smom-dbis-138` contract/package tranche**
+   - separate review required
+   - verify whether the deletions are intentional refactor, move, or accidental loss
+
+## Rule
+
+Until these lanes are reviewed and intentionally grouped, they should remain excluded from RTGS-sidecar, explorer, and DBIS master-plan commits.
--- a/docs/03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md
+++ b/docs/03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md
@@ -0,0 +1,394 @@
+# DBIS OMNL → Indonesia / BNI E2E Integration Blueprint
+
+**Last updated:** 2026-03-29  
+**Purpose:** Detailed end-to-end integration blueprint for moving value from OMNL as central-bank / settlement authority to Indonesian beneficiary banks, with FX, correspondent banking, messaging, reconciliation, and optional Chain 138 settlement augmentation.
+
+## 1. Scope
+
+This blueprint covers the full production path for:
+
+- OMNL as settlement and banking ledger authority
+- Indonesian beneficiary institutions such as Bank Kanaya and BNI-connected flows
+- FX conversion and revaluation
+- domestic and correspondent-bank settlement
+- HYBX sidecar orchestration
+- optional Chain 138 anchoring / settlement confirmation
+
+This document is intentionally broader than the current deployed slice. It defines everything required to make the system fully production-complete.
+
+## 2. Participant model
+
+### Mandatory participant classes
+
+1. **OMNL / central bank rail**
+   - source of settlement authority
+   - operator of Fineract ledger
+   - owner of reserve, treasury, and reporting policy
+
+2. **HYBX / sidecar integration layer**
+   - compliance
+   - posting
+   - settlement orchestration
+   - reconciliation
+   - audit package generation
+
+3. **Indonesian beneficiary bank**
+   - Bank Kanaya in current repo-backed materials
+   - BNI or BNI-connected domestic banking path for broader production rollout
+
+4. **Global correspondent / liquidity banks**
+   - USD / EUR / multicurrency correspondents
+   - nostro / vostro counterparties
+   - statement and confirmation providers
+
+5. **Chain 138 settlement lane**
+   - optional but strategically important if on-ledger finality is part of the regulated operating model
+
+## 3. Full end-to-end stages
+
+### Stage 0 — Static setup
+
+Required before live value movement:
+
+- OMNL tenant and credentials frozen
+- participant offices created
+- beneficiary offices mapped
+- GL chart complete
+- FX reserve / revaluation accounts complete
+- payment types and maker-checker policy frozen
+- sidecar-to-Fineract auth contract frozen
+- external bank routing matrix frozen
+- regulatory package template frozen
+
+### Stage 1 — Payment or settlement initiation
+
+Possible initiators:
+
+- OMNL treasury operator
+- HYBX sidecar
+- external banking system
+- Mojaloop switch if later included
+- ISO 20022 or MT gateway
+
+Required artifacts:
+
+- instruction id
+- end-to-end id
+- message id
+- correlation id
+- counterparty and beneficiary identifiers
+- amount, currency, value date
+- purpose / regulatory narrative
+
+### Stage 2 — Compliance and sanctions controls
+
+Required checks:
+
+- KYC / KYB status
+- sanctions and watchlist screening
+- limit checks
+- liquidity and prefunding check
+- market conduct / rate authorization check
+- jurisdictional eligibility
+
+Required outputs:
+
+- compliance decision
+- reason codes
+- approval / rejection metadata
+- audit payload hash
+
+### Stage 3 — FX pricing and trade capture
+
+Required capabilities:
+
+- direct or triangulated rate determination
+- XAU-based triangulation where required by current OMNL methodology
+- rate-source reference
+- trade timestamp and value date
+- spread / fee logic
+- approved trader / operator identity
+
+Required records:
+
+- source currency
+- destination currency
+- quoted amount
+- settlement amount
+- rate
+- fee / spread component
+- realized vs unrealized P&L handling
+
+### Stage 4 — OMNL accounting and posting
+
+Required journal-entry families:
+
+1. source debit
+2. beneficiary or settlement credit
+3. due-to / due-from interoffice leg where applicable
+4. FX reserve / treasury leg where applicable
+5. realized FX gain/loss leg where applicable
+6. accrued fee leg where applicable
+
+Mandatory OMNL data points:
+
+- `officeId`
+- `glAccountId`
+- `transactionDate`
+- `currencyCode`
+- `comments`
+- transaction reference
+
+### Stage 5 — External banking message exchange
+
+#### 5.1 Domestic Indonesia path
+
+For Bank Kanaya / BNI-style domestic beneficiary credit:
+
+- payment or settlement instruction generated
+- local beneficiary validation completed
+- beneficiary account / institution reference resolved
+- domestic reporting obligations attached
+
+#### 5.2 Correspondent-bank path
+
+For global-bank and cross-border settlement:
+
+- route to correspondent or settlement bank selected
+- nostro / vostro account chosen
+- prefunding / cover logic confirmed
+- message dispatched and acknowledged
+
+### Stage 6 — Funds movement and settlement confirmation
+
+Required evidence:
+
+- bank acceptance / status message
+- credit confirmation or rejection
+- statement extract or advice
+- confirmation of beneficiary-bank receipt
+- unresolved exception queue if delayed
+
+### Stage 7 — Reconciliation and package generation
+
+Required reconciliations:
+
+1. sidecar request vs OMNL journal
+2. OMNL journal vs office balances
+3. FX trade blotter vs accounting postings
+4. external bank confirmations vs OMNL settlement state
+5. on-chain event vs OMNL event where chain leg exists
+
+Required evidence outputs:
+
+- transaction package snapshot
+- journal detail
+- recent journal entries
+- computed balances
+- payload hash files
+- ISO / SWIFT message archive references
+- prudential and BI/OJK crosswalks
+
+## 4. Required message families
+
+### ISO 20022
+
+| Message | Role in flow |
+|--------|---------------|
+| `pain.001` | customer or enterprise initiation |
+| `pacs.008` | FI-to-FI customer credit transfer |
+| `pacs.009` | interbank settlement |
+| `pacs.002` | status |
+| `camt.052` | intraday report |
+| `camt.053` | statement |
+| `camt.054` | debit/credit notification |
+
+### SWIFT Fin / legacy
+
+| Message | Role in flow |
+|--------|---------------|
+| `MT103` | customer transfer |
+| `MT202` / `MT202 COV` | bank transfer / cover |
+| `MT910` | credit confirmation where needed |
+| `MT950` | statement where legacy paths require it |
+
+### Internal / platform-specific
+
+| Message | Role |
+|--------|------|
+| sidecar transfer envelope | canonical business payload |
+| OMNL journal response | accounting confirmation |
+| settlement reference manifest | cross-system correlation |
+| chain settlement event | optional on-ledger finality evidence |
+
+## 5. BNI-specific and Indonesia-specific requirements
+
+### What must exist for a BNI-connected production path
+
+1. **BNI counterparty profile**
+   - institution identifiers
+   - beneficiary validation rules
+   - account structure
+   - allowed currency pairs
+   - reporting obligations
+
+2. **Domestic payment / settlement route definition**
+   - whether BNI is:
+     - direct beneficiary bank
+     - intermediary settlement bank
+     - correspondent / nostro bank
+   - final message set per route
+
+3. **Indonesia regulatory obligations**
+   - BI reporting crosswalk
+   - OJK prudential bridge
+   - FX reporting obligations
+   - large exposure / related-party handling
+   - settlement finality memo
+
+4. **Operational controls**
+   - cut-off times
+   - business dates / value dates
+   - holiday calendars
+   - exception and return handling
+   - maker-checker approvals
+
+### Current state
+
+- Bank Kanaya path is documented in repo-backed material.
+- BNI-specific live endpoint, auth, and correspondent contract are not yet evidenced in this workspace.
+- Therefore the BNI lane is a required integration blueprint item, not a completed deployment.
+
+## 6. Required funds-movement model
+
+### 6.1 OMNL-only book transfer
+
+Used when both parties settle on OMNL books.
+
+Required:
+- interoffice mapping
+- due-to / due-from treatment
+- no external correspondent required
+
+### 6.2 OMNL to domestic beneficiary bank
+
+Required:
+- beneficiary institution mapping
+- outbound settlement message
+- inbound confirmation
+- domestic regulatory reference
+
+### 6.3 OMNL to global correspondent / global bank
+
+Required:
+- nostro selection
+- cover / prefunding policy
+- message dispatch
+- statement reconciliation
+- confirmation of receipt / finality
+
+## 7. Required sidecar integrations
+
+### `mifos-fineract-sidecar`
+
+Required responsibilities:
+- canonical transfer ingest
+- compliance check invocation
+- OMNL posting
+- transaction status tracking
+- audit payload preservation
+
+### `server-funds-sidecar`
+
+Required responsibilities:
+- treasury approval and release
+- limit checks
+- prefunding and source-of-funds orchestration
+- status / approval / exception workflow
+
+### `off-ledger-2-on-ledger-sidecar`
+
+Required responsibilities:
+- translate approved off-ledger event into on-ledger settlement action
+- attach rates, conversion basis, and settlement refs
+- record chain transaction linkage
+
+### Optional or later
+
+- `mt103-hardcopy-sidecar`
+- `card-networks-sidecar`
+- `securitization-engine-sidecar`
+- Mojaloop connector
+
+## 8. Required Chain 138 integration
+
+If on-ledger settlement is in scope, the following must be true:
+
+1. settlement contract path is frozen
+2. instrument selection is frozen
+3. reserve / oracle dependencies are frozen
+4. sidecar correlation id maps to chain tx hash
+5. evidence package includes chain settlement proof
+
+## 9. Reconciliation requirements
+
+### Mandatory reconciliation layers
+
+1. **Accounting reconciliation**
+   - OMNL JEs vs intended posting matrix
+
+2. **FX reconciliation**
+   - rate source vs booked rate
+   - realized / unrealized P&L correctness
+
+3. **Bank reconciliation**
+   - statement / advice vs OMNL settlement state
+
+4. **Operational reconciliation**
+   - sidecar correlation IDs vs journal refs vs package refs
+
+5. **On-ledger reconciliation**
+   - chain tx vs off-ledger settlement event
+
+## 10. Full production-complete gate
+
+The OMNL → Indonesia / BNI → global-bank flow is only fully complete when:
+
+1. one domestic Indonesia beneficiary flow is live and repeatable
+2. one BNI-connected path is live and repeatable
+3. one global correspondent-bank flow is live and repeatable
+4. FX pricing, accounting, and revaluation are frozen and audited
+5. all required ISO/SWIFT messages are archived and correlated
+6. reconciliation package is reproducible
+7. if chain settlement is in scope, the chain leg is included in the same evidence package
+
+## 11. Current blockers
+
+- no live BNI endpoint/auth contract captured in repo-backed state
+- no live global correspondent-bank endpoint/auth contract captured in repo-backed state
+- treasury / funds sidecar lane not yet validated end to end
+- on-ledger settlement leg not yet included in the canonical transaction
+- participant / office / treasury model not yet frozen across all counterparties
+
+## 12. Execution order
+
+1. freeze participant / office / GL / nostro-vostro model
+2. freeze OMNL operator runbook
+3. validate `server-funds-sidecar`
+4. validate `off-ledger-2-on-ledger-sidecar`
+5. acquire and document BNI / correspondent-bank endpoint and auth contracts
+6. run one domestic Indonesia beneficiary-bank flow
+7. run one correspondent-bank flow
+8. add Chain 138 settlement leg if in scope
+9. generate and sign the final evidence package
+
+## Related artifacts
+
+- [DBIS_RTGS_FX_TRANSACTION_CATALOG.md](DBIS_RTGS_FX_TRANSACTION_CATALOG.md)
+- [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)
+- [HYBX_BATCH_001_OPERATOR_CHECKLIST.md](../04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md)
+- [BANK_KANAYA_OFFICE_RUNBOOK.md](../04-configuration/mifos-omnl-central-bank/BANK_KANAYA_OFFICE_RUNBOOK.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)
+- [INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](../04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md)
+- [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](../04-configuration/SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md)
--- a/docs/03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md
+++ b/docs/03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md
@@ -0,0 +1,285 @@
+# 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](../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)
--- a/docs/MASTER_INDEX.md
+++ b/docs/MASTER_INDEX.md
@@ -58,7 +58,7 @@
 |------|-----------------|
 | **00-meta** (tasks, next steps, phases) | [00-meta/NEXT_STEPS_INDEX.md](00-meta/NEXT_STEPS_INDEX.md), [00-meta/PHASES_AND_TASKS_MASTER.md](00-meta/PHASES_AND_TASKS_MASTER.md) |
 | **02-architecture** | [02-architecture/](02-architecture/) — **Public sector + Phoenix catalog baseline:** [02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md](02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md); **non-goals (incl. catalog vs marketing §9):** [02-architecture/NON_GOALS.md](02-architecture/NON_GOALS.md); **DBIS Chain 138:** [dbis_chain_138_technical_master_plan.md](../dbis_chain_138_technical_master_plan.md), [02-architecture/DBIS_NODE_ROLE_MATRIX.md](02-architecture/DBIS_NODE_ROLE_MATRIX.md), [02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md](02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md) |
-| **03-deployment** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md), [03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md](03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md), **Public sector live checklist:** [03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md](03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md), **Proxmox VE ops template:** [03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md](03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md) · [`config/proxmox-operational-template.json`](config/proxmox-operational-template.json); **DBIS Phase 1–3:** [03-deployment/PHASE1_DISCOVERY_RUNBOOK.md](03-deployment/PHASE1_DISCOVERY_RUNBOOK.md), [03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md](03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md), [03-deployment/CALIPER_CHAIN138_PERF_HOOK.md](03-deployment/CALIPER_CHAIN138_PERF_HOOK.md), [03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md](03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md), [03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md](03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md), [03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md](03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md](03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md), [03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md](03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md), [03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md](03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md), [03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md](03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md) |
+| **03-deployment** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md), [03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md](03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md), **Public sector live checklist:** [03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md](03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md), **Proxmox VE ops template:** [03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md](03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md) · [`config/proxmox-operational-template.json`](config/proxmox-operational-template.json); **DBIS Phase 1–3:** [03-deployment/PHASE1_DISCOVERY_RUNBOOK.md](03-deployment/PHASE1_DISCOVERY_RUNBOOK.md), [03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md](03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md), [03-deployment/CALIPER_CHAIN138_PERF_HOOK.md](03-deployment/CALIPER_CHAIN138_PERF_HOOK.md), [03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md](03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md), [03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md](03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md), [03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md), [03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md](03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md), [03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md](03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md](03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md](03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md), [03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md](03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md), [03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md](03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md), [03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md](03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md) |
 | **04-configuration** | [04-configuration/README.md](04-configuration/README.md), [04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md](04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md) (paths, registry, token-mapping, LiFi/Jumper); **Chain 138 wallets:** [04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md); **Chain 2138 testnet wallets:** [04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md); **OMNL Indonesia / HYBX-BATCH-001:** [04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md](04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md), [04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md) |
 | **06-besu** | [06-besu/MASTER_INDEX.md](06-besu/MASTER_INDEX.md) |
 | **Testnet (2138)** | [testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md](testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md), [testnet/TESTNET_DEPLOYMENT.md](testnet/TESTNET_DEPLOYMENT.md) |