Docs and examples: CHANGELOG, README, API_REFERENCE, RECOMMENDATIONS, OMNL/transfer examples

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-23 03:48:39 -08:00
parent 8df772fab0
commit 439a5d9e51
8 changed files with 529 additions and 8 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ All notable changes to the FQBM project are documented here.
 - **CBDC in state**: `FQBMState.cbdc_liability`; workbook sets it on CBDC shift; IPSAS statement of financial position (CB/consolidated) shows CBDC liability; dashboard snapshot includes cbdc_liability.
 - **Repo multiplier in workbook/dashboard**: `run_workbook(shadow_params=ShadowBankingParams(...))` optional; repo_multiplier always computed and included in `result["dashboard"]["repo_multiplier"]` and `result["repo_multiplier"]`.
 - **Real data pipelines**: `fqbm.data.pipelines` — `fetch_fed_h41()`, `fetch_bis_series()` (BIS bulk CSV), `fetch_imf_series()` (IMF API with optional api_key).
- Documentation: RECOMMENDATIONS.md (consolidated list); framework_summary one sentence per Part; REFERENCES weblinks (IPSASB Handbook, BIS bulk, IMF Data, Fed Data Download); IPSAS_COMPLIANCE and GAPS_AND_MISSING reference RECOMMENDATIONS; CONTRIBUTING links RECOMMENDATIONS; USER_GUIDE and DATA_DICTIONARY mention pipelines extension and RECOMMENDATIONS; MISSING_COMPONENTS 2.2 status updated; docstrings: Part X and Required columns in regressions, Part XII in capital_stress.
+- Documentation: RECOMMENDATIONS.md (consolidated list); framework_summary one sentence per Part; REFERENCES weblinks (IPSASB Handbook, BIS bulk, IMF Data, Fed Data Download); IPSAS_COMPLIANCE and GAPS_AND_MISSING reference RECOMMENDATIONS; CONTRIBUTING links RECOMMENDATIONS; USER_GUIDE and DATA_DICTIONARY mention pipelines extension and RECOMMENDATIONS; MISSING_COMPONENTS 2.2 table completed (all rows updated, duplicate removed); RECOMMENDATIONS Inline docstrings row updated; docstrings: Part X and Required columns in regressions, Part XII in capital_stress.
 - IPSAS: structures for IPSAS 3, 5, 9/47, 10, 14, 19, 20, 23, 29/41, 38, 46, 48; cash-basis; RPG 2; functional/presentation currency.
 - budget_actual_from_state() for IPSAS 24 from state + budget dict.
 - State: functional_currency, presentation_currency.
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ The framework includes an **IPSAS-aligned presentation layer** (IPSAS 1 statemen

 ## Submodule (SWIFT DOT-FIN)

-This repo includes **SWIFT_DOT-FIN** as a submodule (ledger entries and payloads, creation to transfers). Clone with submodules: `git clone --recurse-submodules <repo>`, or after clone run `git submodule update --init --recursive`. The submodule lives at `SWIFT_DOT-FIN/`; its source path is `/home/intlc/projects/SWIFT_DOT-FIN` (or `../SWIFT_DOT-FIN` relative to this project).
+This repo includes **SWIFT_DOT-FIN** as a submodule (ledger entries and payloads, creation to transfers). Clone with submodules: `git clone --recurse-submodules <repo>`, or after clone run `git submodule update --init --recursive`. The submodule lives at `SWIFT_DOT-FIN/`. For required components and how DOT-FIN integrates with the matrix ledger (state, quadrants, identities), see [SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md](SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md).

 ## Framework and docs

@@ -81,3 +81,4 @@ This repo includes **SWIFT_DOT-FIN** as a submodule (ledger entries and payloads
 - [docs/DATA_DICTIONARY.md](docs/DATA_DICTIONARY.md) — State variables, sheet I/O, regression columns
 - [docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md](docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md) — Consolidated gap list and documentation checklist
 - [docs/RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md) — Additional recommendations and suggestions
+- [docs/examples/](docs/examples/README.md) — **Stored example**: due diligence PDF, MT-103, OMNL M1 creation, 15-entity distribution, DOT-FIN/ISO 20022 transmission, and **FQBM → MIFOS/Fineract via API** ([full example doc](docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md))
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -38,3 +38,7 @@ Statement of financial position; budget_vs_actual_structure; budget_actual_from_
 **fqbm.system.differential_model**: DifferentialParams; solve_trajectory(x0, t_span, params); check_stability(params).

 **fqbm.empirical.regressions**: generate_synthetic_inflation, run_inflation_pass_through; generate_synthetic_spread, run_sovereign_spread; generate_synthetic_capital_flow, run_capital_flow_sensitivity. Required columns: see [DATA_DICTIONARY.md](DATA_DICTIONARY.md). Further suggestions: [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
+
+## Integrations (reference docs)
+
+- **FQBM → MIFOS/Fineract via API**: For proper entries from the Quadrant Balance Sheet Matrix to Apache Fineract (GL journal entries, mapping FQBM state to Fineract chart of accounts), see the stored example [docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md](examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md) §5 and [docs/examples/README.md](examples/README.md).
--- a/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md
+++ b/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md
@@ -62,13 +62,12 @@ Consolidated list of **missing components** (code/IPSAS/FQBM) and **documentatio

 | Document | Status / remaining gap |
 |----------|------------------------|
-| **README.md** | No “Quick start” example with copy-paste code; no table of contents; Streamlit and scenarios could be in a single “Optional features” section. |
+| **README.md** | Quick start, table of contents, and single Optional features section in place. |
 | **docs/framework_summary.md** | One sentence per Part (I–XVI) and module mapping in place. |
-| **docs/IPSAS_COMPLIANCE.md** | Section 3 still says “L_cb not in state” – should say L_cb is in state. Compliance checklist could reference new helpers (comparative, notes, maturity/risk). |
-| **docs/GAPS_AND_MISSING.md** | B.3 table says “repo multiplier not modeled” but `repo_multiplier()` exists – could say “repo multiplier implemented; not in dashboard”. |
+| **docs/IPSAS_COMPLIANCE.md** | L_cb in state; checklist references comparative, notes, maturity/risk, budget_actual_from_state; links to RECOMMENDATIONS. |
+| **docs/GAPS_AND_MISSING.md** | Repo multiplier and dashboard noted; full CCP reference in RECOMMENDATIONS. |
 | **docs/REFERENCES.md** | Weblinks added (IPSASB, Handbook, BIS, BIS bulk, IMF, Fed H.4.1, Fed Data Download). |
-| **docs/RECOMMENDATIONS.md** | Created: consolidated list of recommendations and suggestions. |
-| **Inline docstrings** | Some modules lack “Part X” references or “Required columns” for regression DataFrames. |
+| **Inline docstrings** | Part X and Required columns added to empirical regressions; Part XII to capital_stress. |

 ---

--- a/docs/RECOMMENDATIONS.md
+++ b/docs/RECOMMENDATIONS.md
@@ -28,7 +28,7 @@ Consolidated list of **additional recommendations and suggestions** for the FQBM
 | **README** | Quick start and table of contents in place; Optional features in a single section. |
 | **framework_summary** | One sentence per Part (I–XVI) and module mapping in place; can be expanded. |
 | **REFERENCES weblinks** | IPSASB, IPSASB Handbook, BIS, BIS bulk, IMF, IMF Data, Fed H.4.1, Fed Data Download linked in [REFERENCES.md](REFERENCES.md). |
-| **Inline docstrings** | Add “Part X” references and “Required columns” for regression DataFrames where missing. |
+| **Inline docstrings** | Part X and Required columns added to empirical regressions; Part XII to capital_stress. |

 ---

--- a/docs/examples/OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md
+++ b/docs/examples/OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md
@@ -0,0 +1,298 @@
+# OMNL Central Bank — Detailed Transactional Ledger
+
+## GRU Monetary Policy Conversion & M1 Allocations
+
+**Document type:** Central bank operational ledger (OMNL)  
+**Compliance:** Aligned with FQBM (Four-Quadrant Balance Sheet Matrix); double-entry throughout; suitable for FQBM → MIFOS/Fineract API posting.  
+**Reference:** [TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md](TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md) (stored example).
+
+---
+
+## 0. Document control and compliance summary
+
+| Field | Value |
+|-------|--------|
+| Ledger scope | OMNL Central Bank (GRU Monetary Policy) |
+| Currency | USD (amounts in full units) |
+| Double-entry | All entries balanced (Debit = Credit) |
+| FQBM identities | Central bank identity preserved; see §6 |
+| Idempotency | Each entry has unique reference for API posting |
+| Client mapping | Client 1 = Head Office / Treasury; Clients 2–8 = allocated entities; Client 7 sub-entities 7A–7D (see §5) |
+
+---
+
+## 1. Chart of accounts (GL structure)
+
+### 1.1 FQBM quadrant and state-variable mapping
+
+| GL code | Name | FQBM quadrant | FQBM state variable (conceptual) |
+|---------|------|----------------|-----------------------------------|
+| **1000-USD-RESERVE-ASSETS** | Fiat USD Reserve Assets (M0) | Assets (Dr) | R (reserve asset side) / base money |
+| **2000-M0-CENTRAL-DEPOSITS** | Central Bank Deposit Liabilities (M0) | Liabilities (Dr) | R (reserve balances) |
+| **2100-M1-CENTRAL-LIABILITIES** | M1 General Liabilities | Liabilities (Dr) | Deposits (M1) |
+| **2200-M1-RESTRICTED-LIABILITIES** | M1 Restricted / Held Liabilities | Liabilities (Dr) | Deposits (M1, restricted) |
+| **3000-TREASURY-CONVERSION-RESERVE (M0)** | Segregated M0 backing for M1 issuance | Control (internal) | Reserve backing for M1 |
+| **3100-OPENING-BALANCE-CONTROL** | Migration balancing account | Control (internal) | Migration / balancing only |
+
+*Central bank identity (FQBM):* Assets (Dr) = Liabilities (Dr) + Liabilities (Cr). Here, 1000 = 2000 + 2100 + 2200 + equity (control accounts are internal and net to zero in conversion).
+
+### 1.2 GL structure (by type)
+
+**ASSETS**
+
+- **1000-USD-RESERVE-ASSETS** — Fiat USD Reserve Assets (M0)
+
+**LIABILITIES – M0**
+
+- **2000-M0-CENTRAL-DEPOSITS** — Central Bank Deposit Liabilities (M0)
+
+**LIABILITIES – M1**
+
+- **2100-M1-CENTRAL-LIABILITIES** — M1 General Liabilities  
+- **2200-M1-RESTRICTED-LIABILITIES** — M1 Restricted / Held Liabilities
+
+**CONTROL / RESERVE ACCOUNTS**
+
+- **3000-TREASURY-CONVERSION-RESERVE (M0)** — Segregated M0 backing for M1 issuance  
+- **3100-OPENING-BALANCE-CONTROL** — Migration balancing account (not used in entries below)
+
+---
+
+## 2. Section A — Opening balance (pre-existing fiat)
+
+### Entry T-001 — Opening balance recognition (migration)
+
+| Field | Value |
+|-------|--------|
+| **Reference** | OMNL-T-001 (idempotency key for API) |
+| **Type** | Migration / opening balance |
+
+**Debit:** 1000-USD-RESERVE-ASSETS ............................ **900,000,000,000**  
+**Credit:** 2000-M0-CENTRAL-DEPOSITS (Client 1 – Head Office) .. **900,000,000,000**
+
+**Check:** Debit = Credit = 900,000,000,000 ✓
+
+**Memo:** Recognition of pre-existing fiat USD reserves booked December 2023. Migration entry only. No new funding event.
+
+---
+
+## 3. Section B — Treasury denomination conversion (M0 → M1)
+
+### Entry T-100 — Segregate M0 for conversion
+
+| Field | Value |
+|-------|--------|
+| **Reference** | OMNL-T-100 |
+
+**Debit:** 2000-M0-CENTRAL-DEPOSITS (Client 1) ................. **250,000,000,000**  
+**Credit:** 3000-TREASURY-CONVERSION-RESERVE (M0) ............... **250,000,000,000**
+
+**Check:** Debit = Credit = 250,000,000,000 ✓
+
+**Memo:** Segregation of 250B M0 under GRU Monetary Policy for denomination conversion.
+
+---
+
+### Entry T-101 — Recognition of M1 liability capacity (1:5 ratio)
+
+| Field | Value |
+|-------|--------|
+| **Reference** | OMNL-T-101 |
+
+**Compound journal entry (two debit legs, one credit leg):**
+
+| Leg | Account | Debit | Credit |
+|-----|---------|-------|--------|
+| 1 | 3000-TREASURY-CONVERSION-RESERVE (M0) | 250,000,000,000 | — |
+| 2 | 3100-OPENING-BALANCE-CONTROL (M1 expansion) | 1,000,000,000,000 | — |
+| 3 | 2100-M1-CENTRAL-LIABILITIES (Client 1 – Treasury) | — | 1,250,000,000,000 |
+
+**Check:** Total Debit = 250B + 1,000B = 1,250B. Total Credit = 1,250B. ✓
+
+**Memo:** Conversion executed under formal GRU ratio (1 M0 = 5 M1). Creation of M1 liabilities backed by segregated M0 reserve (250B) and GRU monetary policy expansion (1,000B); 3100 used as internal balancing account for M1 capacity so that the entry is fully double-entry compliant.
+
+---
+
+## 4. Section C — M1 distributions (internal reallocations)
+
+All entries below are balanced (Debit = Credit). Amounts in full units (e.g. 2,900,000,000 = 2.9B).
+
+### Entry T-201A — Shamrayan available allocation (58%)
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **2,900,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 2) .............. **2,900,000,000**
+
+**Memo:** Operational M1 allocation to Shamrayan Enterprises (available balance). Ref: OMNL-T-201A
+
+---
+
+### Entry T-201B — Shamrayan restricted allocation (42%)
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **2,100,000,000**  
+**Credit:** 2200-M1-RESTRICTED-LIABILITIES (Client 2) ........... **2,100,000,000**
+
+**Memo:** Restricted M1 allocation to Shamrayan (42% hold). Ref: OMNL-T-201B
+
+---
+
+### Entry T-202A — HYBX regulatory capitalization (restricted)
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **350,000,000,000**  
+**Credit:** 2200-M1-RESTRICTED-LIABILITIES (Client 3) ........... **350,000,000,000**
+
+**Memo:** Restricted capitalization allocation to HYBX. Release subject to supervisory approval. Ref: OMNL-T-202A
+
+---
+
+### Entry T-202B — HYBX liquidity allocation (operational)
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **98,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 3) .............. **98,000,000,000**
+
+**Memo:** Designated liquidity allocation to HYBX for NSB-authorized AUSDT mint liquidity pools on Alltra Mainnet. Subject to Treasury and NSB governance controls. Ref: OMNL-T-202B
+
+---
+
+### Entry T-203 — TAJ allocation
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **5,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 4) .............. **5,000,000,000**
+
+**Memo:** Operational M1 allocation to TAJ Private Single Family Office. Ref: OMNL-T-203
+
+---
+
+### Entry T-204 — Aseret Mortgage Bank allocation
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **5,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 5) .............. **5,000,000,000**
+
+**Memo:** Operational M1 allocation to Aseret Mortgage Bank. Ref: OMNL-T-204
+
+---
+
+### Entry T-205 — Mann Li Family Offices allocation
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **5,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 6) .............. **5,000,000,000**
+
+**Memo:** Operational M1 allocation to Mann Li Family Offices. Ref: OMNL-T-205
+
+---
+
+### Entry T-206 — Sovereign Order of Malta OSJ allocation
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **50,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 7) .............. **50,000,000,000**
+
+**Memo:** Operational M1 allocation to Sovereign Order of Malta OSJ. Ref: OMNL-T-206
+
+---
+
+### Entry T-207 — Alltra Mainnet allocation
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 1) .............. **50,000,000,000**  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Client 8) .............. **50,000,000,000**
+
+**Memo:** Operational M1 allocation to Alltra Mainnet. Ref: OMNL-T-207
+
+---
+
+## 5. Section D — Post-transaction balance summary (reconciled)
+
+### 5.1 Head Office (Client 1)
+
+| Balance type | Amount | Derivation |
+|--------------|--------|------------|
+| **Remaining M0** | 650,000,000,000 | 900B (opening) − 250B (T-100) |
+| **Remaining M1 Treasury** | 682,000,000,000 | 1,250B (T-101 credit) − 568B (total Section C debits) |
+
+### 5.2 Total M1 allocated (by beneficiary)
+
+| Beneficiary | Allocated M1 | Entries |
+|-------------|--------------|---------|
+| Shamrayan (Client 2) | 5,000,000,000 | T-201A (2.9B) + T-201B (2.1B) |
+| HYBX Restricted (Client 3) | 350,000,000,000 | T-202A |
+| HYBX Liquidity (Client 3) | 98,000,000,000 | T-202B |
+| TAJ (Client 4) | 5,000,000,000 | T-203 |
+| Aseret (Client 5) | 5,000,000,000 | T-204 |
+| Mann Li (Client 6) | 5,000,000,000 | T-205 |
+| OSJ Treasury / Client 7 | 50,000,000,000 | T-206 |
+| Alltra (Client 8) | 50,000,000,000 | T-207 |
+| **Total allocated M1** | **568,000,000,000** | Sum of Section C debits from Client 1 |
+
+All balances reconcile under the formal GRU ratio (1 M0 = 5 M1).
+
+---
+
+## 6. FQBM identity and journal balance check
+
+### 6.1 Double-entry check (all entries)
+
+| Entry | Debit | Credit | Balanced |
+|-------|--------|--------|----------|
+| T-001 | 900,000,000,000 | 900,000,000,000 | ✓ |
+| T-100 | 250,000,000,000 | 250,000,000,000 | ✓ |
+| T-101 (compound) | 1,250,000,000,000 | 1,250,000,000,000 | ✓ (250B + 1,000B Dr; 1,250B Cr) |
+| T-201A | 2,900,000,000 | 2,900,000,000 | ✓ |
+| T-201B | 2,100,000,000 | 2,100,000,000 | ✓ |
+| T-202A | 350,000,000,000 | 350,000,000,000 | ✓ |
+| T-202B | 98,000,000,000 | 98,000,000,000 | ✓ |
+| T-203 | 5,000,000,000 | 5,000,000,000 | ✓ |
+| T-204 | 5,000,000,000 | 5,000,000,000 | ✓ |
+| T-205 | 5,000,000,000 | 5,000,000,000 | ✓ |
+| T-206 | 50,000,000,000 | 50,000,000,000 | ✓ |
+| T-207 | 50,000,000,000 | 50,000,000,000 | ✓ |
+
+### 6.2 FQBM consolidated view (after all entries)
+
+- **Assets (Dr):** 1000-USD-RESERVE-ASSETS = 900B (unchanged after T-001).  
+- **Liabilities (Dr):** M0 2000 = 650B; M1 2100 + 2200 = consolidated M1 balances across all clients (Client 1 Treasury 682B + allocations 568B + restricted 350B + 2.1B = total M1 liability).  
+- **Control:** 3000 net to zero after T-100 and T-101. 3100 holds 1,000B (M1 expansion balancing) as internal control.
+
+Central bank identity (FQBM): **Assets = Liabilities + Equity**. This ledger’s GL structure preserves that identity when control account 3000 is treated as internal (release of 250B M0 from 2000 into 3000, then 3000 into 2100 at 1:5).
+
+### 6.3 Idempotency references (for API posting)
+
+Use the following as unique references when posting to MIFOS/Fineract (or any downstream system) to avoid duplicate posting:
+
+- OMNL-T-001, OMNL-T-100, OMNL-T-101, OMNL-T-201A, OMNL-T-201B, OMNL-T-202A, OMNL-T-202B, OMNL-T-203, OMNL-T-204, OMNL-T-205, OMNL-T-206, OMNL-T-207.
+
+---
+
+## 7. Section E — Client 7 sub-entity structure (Sovereign Order of Malta OSJ Treasury)
+
+Client 7 operates as a Treasury Parent and maintains standalone sub-clients under its governance framework. These entities are separately identifiable clients within Fineract and may hold independent balances subject to OSJ Treasury authorization.
+
+### 7.1 Sub-entities
+
+- **Client 7A** — DBIS  
+- **Client 7B** — ICCC  
+- **Client 7C** — Elemental Imperium  
+- **Client 7D** — Additional OSJ affiliated entity (as designated)
+
+These entities are established as independent client records with their own M1 liability accounts.
+
+### 7.2 Recommended GL mapping for sub-entities
+
+- 2100-M1-CENTRAL-LIABILITIES (Client 7A – DBIS)  
+- 2100-M1-CENTRAL-LIABILITIES (Client 7B – ICCC)  
+- 2100-M1-CENTRAL-LIABILITIES (Client 7C – Elemental Imperium)  
+- 2100-M1-CENTRAL-LIABILITIES (Client 7D – Affiliated Entity)
+
+### 7.3 Internal transfer protocol (if OSJ Treasury allocates)
+
+Any transfer from OSJ Treasury (Client 7 Parent) to its sub-entities shall be recorded as:
+
+**Debit:** 2100-M1-CENTRAL-LIABILITIES (Client 7 Parent)  
+**Credit:** 2100-M1-CENTRAL-LIABILITIES (Sub-Entity)
+
+**Memo:** Internal OSJ Treasury allocation under parent authorization.
+
+No automatic allocation is recorded herein. The initial 50B M1 allocation remains at Client 7 Parent Treasury level unless subsequently reallocated via formal instruction.
+
+---
+
+**END OF LEDGER**
+
+*This ledger is aligned with the FQBM and the stored example [TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md](TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md). For proper posting to MIFOS/Fineract via API, use the idempotency references above and the GL → FQBM mapping in §1.1.*
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -0,0 +1,39 @@
+# FQBM Examples
+
+Canonical, referenceable examples for the Four-Quadrant Balance Sheet Matrix (FQBM) and its integrations.
+
+## Stored example: Transfer due diligence, M1 creation, and FQBM → MIFOS/Fineract API
+
+**Primary reference:** [TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md](TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md)
+
+This document stores the full end-to-end example and is the **single reference** for:
+
+1. **Narrative** — Due diligence PDF with MT-103 (900B USD M0); GRU exchange (309B M00 USD); OMNL ledger (900B USD M0 + 350B M00 EUR); M1 EUR/USD creation under GRU Monetary Policies.
+2. **Distribution** — 15 entities each receive a portion of the M1 (funds downloaded).
+3. **Transmission** — Each entity can transmit the fully compliant SWIFT DOT-FIN file and appropriate ISO 20022 messages **in whole or in parts**.
+4. **FQBM mapping** — State variables (B, R, C, Loans, Deposits, E_cb, E_b, L_cb, etc.), identities, and DOT-FIN integration.
+5. **Proper entries: FQBM → MIFOS/Fineract via API** — How to post matrix state (and DOT-FIN-derived entries) to Apache Fineract as GL journal entries; mapping table (FQBM variable → Fineract GL); double-entry and idempotency rules; flow for 15-entity distribution.
+
+Use this example when implementing:
+
+- SWIFT DOT-FIN parsing and application to FQBM state.
+- Multi-entity serialization (DOT-FIN and ISO 20022, whole or in parts).
+- **API integration from the Quadrant Balance Sheet Matrix to MIFOS/Fineract** (proper GL entries from FQBM deltas).
+
+---
+
+## OMNL Central Bank ledger (GRU M1 conversion & allocations)
+
+**Operational ledger:** [OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md](OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md)
+
+Cleaned, compliance-ready detailed transactional ledger for OMNL Central Bank:
+
+- **Chart of accounts** with **FQBM quadrant and state-variable mapping** (GL → FQBM).
+- **Section A:** Opening balance (T-001) — 900B USD M0.
+- **Section B:** Treasury conversion (T-100, T-101) — 250B M0 segregated, 1,250B M1 created (1:5 GRU ratio); T-101 is a compound double-entry balanced entry.
+- **Section C:** M1 distributions (T-201A/B, T-202A/B, T-203–T-207) — allocations to Shamrayan, HYBX, TAJ, Aseret, Mann Li, OSJ (Client 7), Alltra; total allocated 568B.
+- **Section D:** Post-transaction summary (reconciled); Client 1 remaining M0 650B, M1 Treasury 682B.
+- **Section E:** Client 7 sub-entity structure (7A–7D) and internal transfer protocol.
+- **§6:** Double-entry check for all entries, FQBM identity note, **idempotency references** for FQBM → MIFOS/Fineract API posting.
+
+Use this ledger as the source of truth for posting the same entries to Fineract via API (see idempotency refs and GL mapping in the doc).
--- a/docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md
+++ b/docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md
@@ -0,0 +1,180 @@
+# Example: Transfer Due Diligence, M1 Creation, and FQBM → MIFOS/Fineract API
+
+**Stored example (canonical reference).** This document stores the full end-to-end example from the design conversation: due diligence PDF and MT-103, GRU exchange, OMNL M1 creation, distribution to 15 entities with transmittable DOT-FIN and ISO 20022 (whole or in parts), and **proper entries from the Four-Quadrant Balance Sheet Matrix (FQBM) to MIFOS/Fineract via API**. Use it as the single reference for implementing this flow and for FQBM → Fineract integration.
+
+This document describes a **concrete use case** that ties together: due diligence documentation; an MT-103 transfer; ledger deposit; creation of M1 money supply under a reserve-unit (GRU) monetary policy; distribution to 15 entities with transmittable SWIFT DOT-FIN and ISO 20022; and posting of FQBM-derived entries to **MIFOS/Apache Fineract** via its REST API.
+
+---
+
+## 1. Narrative (end-to-end)
+
+### Step 1: Due diligence package and MT-103
+
+- **Input**: A PDF file containing all due diligence components for a transfer, including an **MT-103 Hardcopy** for **900B USD M0**.
+- The MT-103 (single customer credit transfer) evidences the movement of high-value base money (M0) and is supported by the full due diligence package.
+
+### Step 2: Origin of the transfer
+
+- The transaction that **led to** the MT-103 Hardcopy was an **Exchange of 309B M00 USD of Global Reserve Unit (GRU)**.
+- So: GRU (M00) → exchange → MT-103 (900B USD M0). The 900B USD M0 is the resulting base-money leg of that exchange.
+
+### Step 3: Ledger deposit and M1 creation
+
+- The **900B USD M0**, together with an **additional 350B M00 EUR** deposited into the **OMNL ledger** (hosted with **HYBX/Alltra**), will be the **basis for the creation of M1 EUR and M1 USD** money supply, utilizing the **GRU Monetary Policies**.
+
+So the flow is:
+
+1. **PDF** (due diligence + MT-103) → evidences **900B USD M0**.
+2. **Origin**: 309B M00 USD GRU exchange → MT-103 (900B USD M0).
+3. **Use**: 900B USD M0 + 350B M00 EUR on OMNL (HYBX/Alltra) → **M1 EUR and M1 USD** under GRU Monetary Policies.
+
+### Step 4: Distribution to 15 entities and transmission
+
+- Once the OMNL transactions are complete and part of the M0/M00 has been converted to **M1**, **15 entities** will each receive a **portion of the M1** (the funds will be “downloaded” to them).
+- Each of the 15 entities must be able to **transmit**, in **whole or in parts**:
+  - The **fully compliant and complete SWIFT DOT-FIN file** (audit trail, ledger entries, and any subset relevant to that entity).
+  - **Appropriate ISO 20022 messages** (e.g. pacs.008, pacs.002, camt.052/053/054 for statements, or other MX as needed for payments and reconciliation).
+
+So the post-M1 flow is:
+
+4. **Distribution**: M1 allocated to 15 entities (each gets a portion).
+5. **Transmission**: Each entity can send the full DOT-FIN file and ISO 20022 messages **in whole or in parts** (e.g. only their leg, or the full file for audit).
+
+---
+
+## 2. Mapping to FQBM and DOT-FIN
+
+### 2.1 Where this fits in the framework
+
+| Stage | Description | FQBM / DOT-FIN concept |
+|--------|-------------|-------------------------|
+| **Due diligence PDF** | Source document set; includes MT-103 hardcopy | Input to parser/validator; MT-103 is a SWIFT message type that can feed DOT-FIN **transfer** entries. |
+| **MT-103 (900B USD M0)** | Single customer credit transfer; base money | **Transfer** (debit/credit pair); affects base money → maps to **R** (reserves) and/or **C** (currency) and/or **L_cb** depending on sector. |
+| **GRU exchange (309B M00)** | Pre-MT-103 exchange of Global Reserve Unit | **Creation** or **transfer** in DOT-FIN; may map to reserve/liability side (e.g. **R**, **E_cb**) or external ledger before conversion to M0. |
+| **OMNL ledger (HYBX/Alltra)** | Destination ledger for 900B USD M0 + 350B M00 EUR | Ledger that receives deposits; in FQBM terms, deposits here can drive **Deposits** (commercial-bank or consolidated) and thus **M1**. |
+| **M1 EUR / M1 USD creation** | Money supply creation under GRU Monetary Policies | In FQBM: **M1** ≈ **Deposits + C** (narrow money); creation via **commercial_bank_step** (e.g. d_Deposits → d_Loans) and/or **central_bank_step** (reserve/currency operations). GRU policies define the rules (e.g. reserve ratios, eligibility). |
+| **15 entities receive M1** | Each entity gets a portion of M1 after OMNL completion | In FQBM: split **Deposits** (and/or **C**) across 15 sectoral/entity positions; each entity’s portion is a subset of the consolidated state. DOT-FIN must support **per-entity views** and **partial serialization**. |
+| **Transmission (whole or in parts)** | Each entity transmits DOT-FIN file + ISO 20022 messages | **DOT-FIN**: one canonical file; **serialize** so each entity gets the **full file** or a **compliant subset** (e.g. only entries where they are party). **ISO 20022**: generate appropriate MX (pacs.*, camt.*, etc.) for each entity, in whole or in parts as required. |
+
+### 2.2 FQBM state variables involved
+
+- **R** — Reserve balances (base money held by banks; part of M0).
+- **C** — Currency in circulation (part of M0).
+- **Deposits** — Commercial bank deposits (core of M1).
+- **Loans** — Commercial bank loans (balance-sheet identity: Loans = Deposits + E_b).
+- **L_cb** — Central bank loans (if CB lending is used).
+- **B** — Government securities (CB assets); relevant if GRU/OMNL operations interact with CB balance sheet.
+- **E_cb**, **E_b** — Equity; may be touched by revaluations or policy allocations.
+
+Identities to preserve when applying any DOT-FIN-derived deltas:
+
+- Central bank: **B + L_cb = R + C + E_cb**
+- Commercial bank: **Loans = Deposits + E_b**
+
+### 2.3 DOT-FIN integration (when implemented)
+
+- **Parse**: PDF → extract or reference MT-103 data → map to DOT-FIN **transfer** (and optionally **creation**) entries.
+- **Validate**: Double-entry per transfer; required fields; idempotency key (e.g. MT-103 reference).
+- **Map to deltas**: One (or batch) DOT-FIN entries → (d_R, d_C, d_Deposits, d_Loans, …) preserving identities.
+- **Apply**: Update `FQBMState`; run `cross_sector_consistency_check(state)`.
+- **M1 creation**: Model the OMNL deposit and GRU policy rules as parameterised steps (e.g. reserve requirement, eligible collateral) that determine how much of the 900B USD M0 + 350B M00 EUR becomes new M1 EUR and M1 USD in the matrix.
+- **15-entity distribution**: After M1 creation, allocate portions to 15 entities; support per-entity balance views and per-entity DOT-FIN/ISO 20022 output.
+- **Transmittable DOT-FIN and ISO 20022**: Produce a **fully compliant and complete** DOT-FIN file that any of the 15 entities can **transmit in whole or in parts**. Produce **appropriate ISO 20022 messages** (e.g. payment status, statements) that each entity can likewise transmit in whole or in parts (e.g. only their transactions or the full set).
+
+---
+
+## 3. Summary
+
+| Item | Value / system |
+|------|----------------|
+| Due diligence | PDF with all components for the transfer |
+| MT-103 | 900B USD M0 (hardcopy in PDF) |
+| Origin | 309B M00 USD GRU exchange → MT-103 |
+| Ledger | OMNL (HYBX/Alltra): 900B USD M0 + 350B M00 EUR |
+| Outcome | Basis for M1 EUR and M1 USD under GRU Monetary Policies |
+| M1 distribution | 15 entities each receive a portion of the M1 (funds downloaded) |
+| Transmission | Each of the 15 entities must be able to transmit the **full SWIFT DOT-FIN file** and **appropriate ISO 20022 messages**, **in whole or in parts** |
+| FQBM focus | R, C, Deposits, Loans; identities; DOT-FIN → state deltas → M1 creation → per-entity allocation; serialization (whole/parts); ISO 20022 output |
+
+This example can be used to derive test cases, mapping tables (MT-103 field → FQBM variable), scenario parameters for the workbook or Monte Carlo runs (e.g. initial state with large R and Deposits, then stress tests), requirements for multi-entity DOT-FIN serialization and ISO 20022 message generation (whole or in parts), and **proper FQBM → MIFOS/Fineract API entry posting** (see §5).
+
+---
+
+## 4. References (internal)
+
+- [SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md](../../SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md) — DOT-FIN components and FQBM integration.
+- [docs/framework_summary.md](../framework_summary.md) — Four-quadrant matrix and Parts I–XVI.
+- [docs/DATA_DICTIONARY.md](../DATA_DICTIONARY.md) — State variables (B, R, C, Loans, Deposits, …).
+
+---
+
+## 5. Proper entries: FQBM → MIFOS/Fineract via API
+
+This section defines how to post **proper entries** from the Four-Quadrant Balance Sheet Matrix (FQBM) state and ledger to **MIFOS/Apache Fineract** via its REST API. It is the reference for implementing the integration so that matrix state (and any DOT-FIN-derived entries) are correctly reflected in Fineract’s General Ledger and accounting.
+
+### 5.1 Why FQBM → Fineract
+
+- **FQBM** holds the canonical monetary state (B, R, C, Loans, Deposits, E_cb, E_b, L_cb, etc.) and four-quadrant identities.
+- **Fineract** is used for operational accounting, loan/deposit products, and reporting. To keep systems aligned, **entries derived from FQBM state (or from DOT-FIN applied to FQBM) must be postable to Fineract** as GL journal entries (and, where applicable, as loan/savings transactions).
+- In the context of this example: after OMNL M1 creation and distribution to 15 entities, each entity may use Fineract; posting from FQBM ensures the same economic events are reflected in Fineract’s books.
+
+### 5.2 Fineract concepts relevant to FQBM
+
+| Fineract concept | Role | FQBM mapping |
+|------------------|------|--------------|
+| **Chart of Accounts (GL)** | Ledger accounts for debits/credits | Map FQBM state variables to GL account IDs (or types). |
+| **Journal entries** | Single or compound debit/credit entries | Each FQBM state delta (or DOT-FIN entry applied to state) becomes one or more journal entries. |
+| **Offices** | Organizational unit (e.g. per entity) | Optional: map 15 entities to offices (or use one office with account segmentation). |
+| **Financial activity → account mapping** | Links product/activity to GL | Use to drive automated entries from loans/savings; align product behaviour with FQBM identities. |
+
+### 5.3 Mapping FQBM state variables to Fineract GL
+
+Define a **mapping table** from FQBM state variables to Fineract GL account identifiers (or account type codes). Example (conceptual; actual account IDs come from your Fineract instance):
+
+| FQBM variable | Quadrant / role | Fineract GL usage |
+|---------------|-----------------|-------------------|
+| **B** | Assets (Dr) — government securities | GL asset account (e.g. “CB – Govt securities”) |
+| **L_cb** | Assets (Dr) — CB loans to banks | GL asset account (e.g. “CB – Loans to banks”) |
+| **Loans** | Assets (Dr) — bank loans | GL asset account (e.g. “Bank – Loans”) or loan portfolio account |
+| **R** | Liabilities (Dr) — reserves | GL liability account (e.g. “Reserve balances”) |
+| **C** | Liabilities (Dr) — currency | GL liability account (e.g. “Currency in circulation”) |
+| **Deposits** | Liabilities (Dr) — deposits | GL liability account (e.g. “Customer deposits”) or savings product mapping |
+| **E_cb** | Liabilities (Cr) — CB equity | GL equity account (e.g. “CB – Equity”) |
+| **E_b** | Liabilities (Cr) — bank equity | GL equity account (e.g. “Bank – Equity”) |
+| **cbdc_liability** | Liabilities (Dr) — CBDC | GL liability account (e.g. “CBDC liability”) |
+
+- **Identities to preserve in Fineract:**  
+  - Central bank: `B + L_cb = R + C + E_cb` (sum of debits = sum of credits for CB accounts).  
+  - Commercial bank: `Loans = Deposits + E_b` (same for bank accounts).  
+  Every journal entry batch posted from FQBM must be balanced and consistent with these identities.
+
+### 5.4 Posting FQBM entries via Fineract API
+
+- **Endpoint (conceptual):** Use Fineract’s **journal entry** (or equivalent) API to create entries. Exact endpoint names depend on your Fineract version (e.g. `journalentries` or accounting-related resource).
+- **Inputs per entry (typical):**  
+  - Office ID (optional, for multi-entity).  
+  - Currency code (e.g. USD, EUR).  
+  - Transaction date.  
+  - Debit/credit lines: each line = GL account ID + amount + debit or credit.  
+  - Reference number (e.g. FQBM state snapshot id, DOT-FIN reference, or MT-103 reference).  
+- **Proper entry rules:**  
+  1. **One FQBM state delta → one or more journal entries** such that the net effect on the mapped GL accounts matches the delta (e.g. d_R, d_Deposits).  
+  2. **Double-entry:** every journal entry must be balanced (total debits = total credits).  
+  3. **Idempotency:** use a unique reference (e.g. from DOT-FIN or FQBM run id) so the same event is not posted twice.  
+  4. **Ordering:** post in the same order as FQBM/DOT-FIN application (e.g. by reporting_date or sequence) so Fineract’s books replicate the matrix timeline.
+
+### 5.5 Flow in this example (FQBM → Fineract)
+
+1. **OMNL M1 creation** is reflected in FQBM as changes to R, C, Deposits (and possibly Loans).  
+2. **Distribution to 15 entities** splits Deposits (and/or other variables) across entities; each entity’s portion is a subset of the consolidated state.  
+3. **Per entity (or consolidated):**  
+   - Compute the **deltas** that correspond to that entity’s portion (or to the full M1 creation + distribution).  
+   - Map deltas to **debit/credit lines** using the FQBM → GL mapping table.  
+   - Call the **Fineract API** to create the journal entry (or batch) with a unique reference and transaction date.  
+4. **Transmission:** Each of the 15 entities can transmit the DOT-FIN file and ISO 20022 messages (whole or in parts). The **same economic events** that are in DOT-FIN and FQBM should be the source for Fineract journal entries so that Fineract stays aligned with the matrix and with SWIFT/ISO 20022.
+
+### 5.6 References (external)
+
+- [Apache Fineract API (demo)](https://demo.mifos.io/api-docs/apiLive.htm) — REST API documentation.  
+- [Apache Fineract (legacy docs)](https://fineract.apache.org/docs/legacy/) — Legacy documentation.  
+- [MIFOS – Add Journal Entries](https://docs.mifos.org/mifosx/user-manual/for-operational-users-mifos-x-web-app/accounting-operations/add-journal-entries) — Manual journal entry process (UI); same concepts apply for API-driven entries.