proxmox/config/dbis-institutional/README.md

# DBIS institutional config (schemas + examples)

Machine-readable artifacts for **OMNL + DBIS Core + Chain 138 + RTGS** integration and **identifier** alignment (LEI, IBAN, ISIN, ENS, WEB3-ETH-IBAN, explorer labels).

## Canonical narrative doc

[OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md](../../docs/03-deployment/OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md)

## Event producers (`event-producers.manifest.json`)

Registered logical emitters for `settlement-event.event_producer` (kept in sync with the `enum` in `schemas/settlement-event.schema.json`). Add a producer: extend both the manifest and the schema enum in one change.

## Schemas (`schemas/`)

| File | Purpose |
|------|---------|
| `settlement-event.schema.json` | Cross-system settlement / evidence event (section 6 of runbook). |
| `address-registry-entry.schema.json` | Vault or wallet row: `0x` address, fiat rails, Web3 aliases, optional ISIN/CUSIP, Blockscout label hints (sections 3, 7, 13). |

## Examples (`examples/`)

| File | Pairs with |
|------|------------|
| `settlement-event.example.json` | `settlement-event.schema.json` (hybrid: includes `uetr` + internal refs) |
| `settlement-event.chain138-primary.example.json` | Same schema; **Chain 138 as authoritative rail** — no `uetr`; `rtgs_message_ids.rail` + internal refs; see [OJK_BI_AUDIT_JVMTM_REMEDIATION_AND_UETR_POLICY.md](../../docs/03-deployment/OJK_BI_AUDIT_JVMTM_REMEDIATION_AND_UETR_POLICY.md) |
| `settlement-event.min.json` | **Minimal** valid `CHAIN_SETTLEMENT` fixture (required fields + `chain_tx_hash` / `chain_id`); CI baseline in `validate-dbis-institutional-schemas.sh`. |
| `settlement-events-batch.example.json` | Each array element validated against `settlement-event.schema.json` (see `validate-dbis-institutional-schemas.sh`) |
| `address-registry-entry.example.json` | `address-registry-entry.schema.json` |
| `address-registry-entries-batch.example.json` | Each array element validated against `address-registry-entry.schema.json` |

Examples use placeholder addresses and ids; replace with live data in a secure store (not committed).

### Settlement `amount` convention (operators + integrators)

Use **major currency units** as a decimal string, with explicit scale for fiat:

- **`amount`:** string matching `^-?[0-9]+(\.[0-9]+)?$` (e.g. USD 25,000,000.00 → `"25000000.00"`).
- **`amount_scale`:** use **`2`** for USD and other ISO 4217 currencies with two decimal places.

Fineract journal APIs may still use **minor units (cents)**; convert at the boundary and record settlement events in **major units** so logs and regulatory exports stay human-aligned. Do not mix major and minor in the same field without documenting which convention applies.

### Chain 138 as SWIFT replacement vs UETR

When settlement is **authoritative on Chain 138** (chain id **138**), treat **`correlation_id` + `chain_tx_hash` + `occurred_at`** as the primary rail-native E2E evidence for that leg. **`rtgs_message_ids.uetr`** is **optional** unless you also run a **parallel SWIFT gpi** leg (hybrid); then record both UETR and chain fields on the same **`correlation_id`**.

### SWIFT UETR vs internal “message sent” reference

**UETR** belongs in `rtgs_message_ids.uetr` when the payment is on **SWIFT gpi** (or your counterparty/scheme requires it). You **cannot** treat an arbitrary internal message id as a regulatory substitute for UETR on **those** legs.

When no UETR exists yet (internal-only, pre-SWIFT, DLT-only, domestic rail), add extra keys under **`rtgs_message_ids`** (the schema allows any string keys), e.g. `internal_instruction_ref`, `operator_message_ref`, or a digest of the submitted instruction — and keep **`correlation_id`** as the cross-system spine. When UETR is later assigned, **record it** and retain internal refs for audit lineage.

Policy and audit-scope notes: [OJK_BI_AUDIT_JVMTM_REMEDIATION_AND_UETR_POLICY.md](../../docs/03-deployment/OJK_BI_AUDIT_JVMTM_REMEDIATION_AND_UETR_POLICY.md).

## Related repo config

- OMNL entity master: `docs/04-configuration/mifos-omnl-central-bank/OMNL_ENTITY_MASTER_DATA.json`
- Institutional subdomains: `docs/04-configuration/DBIS_INSTITUTIONAL_SUBDOMAINS.md`
- Blockscout address labeling (K8s): `smom-dbis-138/k8s/blockscout/address-labeling-config.yaml`

## Validation

```bash
# JSON parse (all examples/*.json)
bash scripts/validation/validate-dbis-institutional-json.sh

# JSON Schema — requires check-jsonschema on PATH (PEP 668 / “externally managed” Python):
#   python3 -m venv .venv-checkjson && .venv-checkjson/bin/pip install check-jsonschema
#   PATH="$PWD/.venv-checkjson/bin:$PATH" bash scripts/validation/validate-dbis-institutional-schemas.sh
# Or: pipx install check-jsonschema
SCHEMA_STRICT=1 bash scripts/validation/validate-dbis-institutional-schemas.sh
```

`scripts/validation/validate-dbis-institutional-schemas.sh` validates **checked-in examples** only. For a **live or one-off** settlement event file, validate it directly:

### Validation — ad-hoc settlement event

```bash
# From repository root; use the same venv as above or any check-jsonschema on PATH.
PATH="$PWD/.venv-checkjson/bin:$PATH" check-jsonschema \
  --schemafile config/dbis-institutional/schemas/settlement-event.schema.json \
  your-event.json
```

- **Success:** exit code **0**; typical stdout is `ok -- validation done` (wording may vary by version).
- **Failure:** non-zero exit; `ValidationError` / `SchemaError` in stderr — treat as **not schema-closed**.

Do not use `validate-dbis-institutional-schemas.sh` as a substitute for validating arbitrary payload files.

`validate-config-files.sh` runs schema validation automatically when `check-jsonschema` is on `PATH`. The gitignored venv `.venv-checkjson/` is listed in `.gitignore` for this purpose.

Validated pairs (examples versus schemas): `settlement-event`, `address-registry-entry`, `trust`, `governance`, `policy` (against `policy-manifest.schema.json`).

`settlement-event` optionally carries **ISO-20022** (`iso_msg_type`, `iso_instruction_id`, `iso_payload_hash`, `rail_iso_hash`) and **identity** (`holder_did`, `identity_verification_ref`) for full fiat / FX / chain correlation — see runbook section 14.

`address-registry-entry` supports **`iso_intake`** and **`dbis_settlement_router`** roles plus optional **`primary_holder_did`** and **`identity_anchor_ref`** (section 14.6 checklist).

## Blockscout address labels

Plan or sync labels from registry JSON (`blockscout.label` + `status: active`):

```bash
bash scripts/verify/sync-blockscout-address-labels-from-registry.sh config/dbis-institutional/examples/address-registry-entry.example.json
bash scripts/verify/sync-blockscout-address-labels-from-registry.sh --from-dir config/dbis-institutional/registry
# Preferred for the self-hosted Chain 138 explorer (writes Blockscout Postgres address_names):
bash scripts/verify/sync-blockscout-address-labels-from-registry.sh --apply --mode=db --from-dir config/dbis-institutional/registry
```

On `explorer.d-bis.org`, public `/api/v1/*` is served by token-aggregation, not by a Blockscout label-write API, so `--mode=db` is the correct operator path for live labels unless you have separately enabled a dedicated label endpoint. See `registry/README.md` for drop-in files (gitignored by default).