From 439a5d9e512d672647d11086bdd65cb71d013d7c Mon Sep 17 00:00:00 2001 From: defiQUG Date: Mon, 23 Feb 2026 03:48:39 -0800 Subject: [PATCH] Docs and examples: CHANGELOG, README, API_REFERENCE, RECOMMENDATIONS, OMNL/transfer examples Co-authored-by: Cursor --- CHANGELOG.md | 2 +- README.md | 3 +- docs/API_REFERENCE.md | 4 + docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md | 9 +- docs/RECOMMENDATIONS.md | 2 +- .../OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md | 298 ++++++++++++++++++ docs/examples/README.md | 39 +++ .../TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md | 180 +++++++++++ 8 files changed, 529 insertions(+), 8 deletions(-) create mode 100644 docs/examples/OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md create mode 100644 docs/examples/README.md create mode 100644 docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a0175d..94a6e41 100644 --- 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. diff --git a/README.md b/README.md index 7b7dae2..4cfa140 100644 --- 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 `, 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 `, 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)) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 671fde4..7868527 100644 --- 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). diff --git a/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md b/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md index 9ab8b77..734ab9d 100644 --- 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. | --- diff --git a/docs/RECOMMENDATIONS.md b/docs/RECOMMENDATIONS.md index aa9f498..5ada18c 100644 --- 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. | --- diff --git a/docs/examples/OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md b/docs/examples/OMNL_CENTRAL_BANK_LEDGER_GRU_M1.md new file mode 100644 index 0000000..4709aee --- /dev/null +++ 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.* diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 0000000..9750acc --- /dev/null +++ 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). diff --git a/docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md b/docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md new file mode 100644 index 0000000..633274f --- /dev/null +++ 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.