zaragoza444
886a373356
Some checks failed
CI/CD Pipeline / Solidity Contracts (push) Failing after 1m16s
CI/CD Pipeline / Security Scanning (push) Successful in 2m39s
CI/CD Pipeline / Lint and Format (push) Failing after 50s
CI/CD Pipeline / Terraform Validation (push) Failing after 25s
CI/CD Pipeline / Kubernetes Validation (push) Successful in 30s
HYBX OMNL TypeScript & anchor / token-aggregation build + reconcile artifact (push) Failing after 29s
OMNL reconcile anchor / Run omnl:reconcile and upload artifacts (push) Failing after 29s
Validation / validate-genesis (push) Successful in 30s
Validation / validate-terraform (push) Failing after 30s
Validation / validate-kubernetes (push) Failing after 13s
Validation / validate-smart-contracts (push) Failing after 11s
Validation / validate-security (push) Failing after 1m24s
Validation / validate-documentation (push) Failing after 20s
Verify Deployment / Verify Deployment (push) Failing after 1m7s
Align interoffice HO allocations to 2100→2410 with branch 1410→2100 two-leg entries, registry v1.2.1, explicit same-GL rejection in validators, doc matrices, and validation tests. Co-authored-by: Cursor <cursoragent@cursor.com>
91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
# OMNL IPSAS / GL validation API (token-aggregation)
|
||
|
||
Endpoints are served under **`/api/v1`** when the token-aggregation service is running. They tie **on-chain OMNL compliance** to **IPSAS-aligned GL codes** documented for OMNL Hybx (Fineract).
|
||
|
||
**Discovery:** `GET /api/v1/omnl/catalog` — machine-readable list of all OMNL routes, auth notes, and query parameters.
|
||
|
||
**OpenAPI 3:** `GET /api/v1/omnl/openapi.json` — static OpenAPI 3.0 document for Swagger UI, Postman import, and codegen.
|
||
|
||
## Configuration files (smom-dbis-138)
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| [`config/omnl-ipsas-gl-registry.json`](../../config/omnl-ipsas-gl-registry.json) | Canonical GL codes (1000, 1050, 2000, 2100, 3000), IPSAS references, allowed pairs, monetary-layer hints |
|
||
| [`config/omnl-journal-matrix.json`](../../config/omnl-journal-matrix.json) | IPSAS double-entry matrix (Phase C interoffice, M0–M4, Office 24 opening) |
|
||
| [`docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-phase-c-interoffice.json`](../../docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-phase-c-interoffice.json) | Phase C HO/branch template |
|
||
| [`docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-hospitallers24-opening-1b.json`](../../docs/04-configuration/mifos-omnl-central-bank/omnl-journal-matrix-hospitallers24-opening-1b.json) | HOSPITALLERS-24 $1B opening two-leg reference |
|
||
|
||
Override paths with `OMNL_IPSAS_GL_REGISTRY` and `OMNL_JOURNAL_MATRIX_PATH` if needed.
|
||
|
||
## Fineract (live compare & health)
|
||
|
||
Set:
|
||
|
||
- `OMNL_FINERACT_BASE_URL`
|
||
- `OMNL_FINERACT_TENANT` (default `omnl`)
|
||
- `OMNL_FINERACT_USER` (default `app.omnl`) — or legacy **`OMNL_FINERACT_USERNAME`**
|
||
- `OMNL_FINERACT_PASSWORD`
|
||
- `OMNL_FINERACT_GL_PAGE_LIMIT` (pagination for large tenants)
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/omnl/ipsas/fineract-health` | Probe `/glaccounts?limit=1` — returns `ok`, `statusCode`, `configured` |
|
||
| GET | `/omnl/ipsas/fineract-compare` | Full GL list vs registry (requires **`OMNL_API_KEY`** when that env is set) |
|
||
|
||
## IPSAS validation
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/omnl/ipsas/registry` | Full IPSAS GL registry JSON |
|
||
| GET | `/omnl/ipsas/matrix` | Journal matrix entries |
|
||
| GET | `/omnl/ipsas/validate-pair?debitGlCode=&creditGlCode=` | Validate one pair (registry + matrix) |
|
||
| POST | `/omnl/ipsas/validate-pairs` | Body: `{ "pairs": [{ "debitGlCode", "creditGlCode" }, ...] }` — batch validation |
|
||
| GET | `/omnl/ipsas/layer/:layer` | `m0_reserve` \| `m1_liability` \| `settlement` \| `equity` |
|
||
| GET | `/omnl/ipsas/compliance-context/:lineId?aggregated=1` | Compliance snapshot + IPSAS guidance (**`OMNL_API_KEY`** when set) |
|
||
|
||
## Cross-cutting OMNL APIs (same `/api/v1` prefix)
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/omnl/reconcile-anchor` | SHA-256 of canonical IPSAS registry + journal matrix (same as `omnl-reconcile-report.mjs`) |
|
||
| GET | `/omnl/integration-status` | Booleans for configured env groups (no secrets) |
|
||
| GET | `/omnl/cross-chain-lines` | `hybx-omnl-cross-chain-lines.json` content + path |
|
||
| GET | `/omnl/zk-verifier` | Address from `OMNL_ZK_VERIFIER` |
|
||
| GET | `/omnl/mirror-coordinator?chainId=138` | On-chain `mirrorChainSelector`, `mirrorReceiver`, `feeToken` |
|
||
|
||
## Example
|
||
|
||
```http
|
||
GET /api/v1/omnl/ipsas/validate-pair?debitGlCode=1050&creditGlCode=2000
|
||
```
|
||
|
||
```http
|
||
POST /api/v1/omnl/ipsas/validate-pairs
|
||
Content-Type: application/json
|
||
|
||
{"pairs":[{"debitGlCode":"1050","creditGlCode":"2000"}]}
|
||
```
|
||
|
||
Expect `ipsasCompliantPair: true` when the pair is allowed in the registry or matrix. Same-GL pairs (e.g. `2000/2000`) return `doubleEntryValid: false`, `rejectReason: "same_gl_account"`.
|
||
|
||
### Post-deploy validation (token-aggregation default port 3000)
|
||
|
||
```bash
|
||
# FAIL — same GL (invalid double entry)
|
||
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2000&creditGlCode=2000"
|
||
|
||
# PASS — Office 24 branch leg (live $1B pattern)
|
||
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=1410&creditGlCode=2100"
|
||
|
||
# PASS — Phase C HO interoffice leg
|
||
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2100&creditGlCode=2410"
|
||
|
||
# PASS — M2→M3 token load
|
||
curl -s "http://127.0.0.1:3000/api/v1/omnl/ipsas/validate-pair?debitGlCode=2200&creditGlCode=2300"
|
||
|
||
# Reconcile anchor changes when registry/matrix updates
|
||
curl -s "http://127.0.0.1:3000/api/v1/omnl/reconcile-anchor"
|
||
```
|
||
|
||
**Phase C rule:** HO allocation uses **`2100 → 2410`** (not `2000 → 2410`). Branch leg **`1410 → 2100`**. GL `2100` is branch spendable M1 (matches Office 24 settlement profile `glM1`).
|