proxmox/config/dbis-institutional

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

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
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.

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

# 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

# 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 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).