diff --git a/.env.example b/.env.example index 9d0cf17..7d1cf6e 100644 --- a/.env.example +++ b/.env.example @@ -22,11 +22,55 @@ EMAIL_ALERT_RECIPIENTS= CRYPTO_COM_API_KEY= CRYPTO_COM_API_SECRET= +# ---------------------------------------------------------------------------- +# API behind reverse proxy (rate limits, logging) +# TRUST_PROXY=1 + +# ---------------------------------------------------------------------------- +# IRU marketplace — rate limits (optional; sensible defaults in code) +# With TRUST_PROXY=1, limits key on real client IP from X-Forwarded-For. +# IRU_MARKETPLACE_INQUIRY_WINDOW_MS=900000 +# IRU_MARKETPLACE_INQUIRY_MAX=10 +# IRU_MARKETPLACE_PUBLIC_WINDOW_MS=60000 +# IRU_MARKETPLACE_PUBLIC_MAX=200 +# Jest disables limits when IRU_MARKETPLACE_RATE_LIMIT_IN_TEST=1 (set in tests only) + +# ---------------------------------------------------------------------------- +# IRU / marketplace email (notification.service) +# Default provider is SMTP (EMAIL_PROVIDER=smtp). On Proxmox LAN use the Mail Proxy VM: +# VMID 100 — 192.168.11.32 (hostname proxmox-mail-gateway) — ports 25, 587, 465 +# See: proxmox repo docs/04-configuration/ALL_VMIDS_ENDPOINTS.md (Mail Proxy note) +# EMAIL_PROVIDER=smtp +# SMTP_HOST=192.168.11.32 +# SMTP_PORT=587 +# SMTP_SECURE=false +# Lab relay with private CA: SMTP_TLS_REJECT_UNAUTHORIZED=false +# SMTP_USER= +# SMTP_PASSWORD= +# EMAIL_FROM=noreply@yourdomain.tld +# EMAIL_FROM_NAME=SolaceNet +# DBIS_SALES_EMAIL=sales@yourdomain.tld +# Or: EMAIL_PROVIDER=sendgrid | ses (set EMAIL_API_KEY / AWS creds per integration) + +# ---------------------------------------------------------------------------- +# SolaceNet — gateway rails (optional enforcement) +# ---------------------------------------------------------------------------- +# When 1|true, POST/GET rail adapter endpoints require capability gateway-microservices. +# SOLACENET_GATEWAY_RAILS_ENFORCE=0 +# Tenant for policy checks if not in x-tenant-id / body.tenantId: +# SOLACENET_DEFAULT_TENANT_ID=system +# Optional NDJSON audit file for allow/deny (create directory; rotate externally): +# SOLACENET_GATEWAY_AUDIT_LOG_PATH=/var/log/dbis/gateway-rails-audit.ndjson +# POST .../rails/:id/validate|receive — extra per-IP limit (default 120/min): +# GATEWAY_RAIL_MUTATE_WINDOW_MS=60000 +# GATEWAY_RAIL_MUTATE_MAX=120 +# Jest / integration: disable rail mutate limiter +# GATEWAY_RAIL_RATE_LIMIT_IN_TEST=1 + # ---------------------------------------------------------------------------- # Other (add as needed from dbis_core code) # ---------------------------------------------------------------------------- CHAIN138_RPC_URL=https://rpc-core.d-bis.org # ADMIN_CENTRAL_API_KEY= # VAULT_ROOT_TOKEN= -# DBIS_SALES_EMAIL= # etc. diff --git a/SOLACENET_IMPLEMENTATION_STATUS.md b/SOLACENET_IMPLEMENTATION_STATUS.md index 286db2f..7681922 100644 --- a/SOLACENET_IMPLEMENTATION_STATUS.md +++ b/SOLACENET_IMPLEMENTATION_STATUS.md @@ -66,6 +66,8 @@ This document tracks the implementation status of the SolaceNet Capability Platf - Request routing - Authentication/authorization - **Note**: Requires Go 1.21+ and Redis +- **Rail / protocol governance**: External messaging rails and adapter contracts (SWIFT, DTC/DTCC, TT, KTT legacy evidence, and northbound contracts from telecom boundaries) are **maintained under SolaceNet**. See `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md` and TypeScript adapters under `src/core/gateway/adapters/`. +- **Gateway REST (rails registry)**: `GET /api/v1/gateway/rails`, `GET/POST .../rails/:adapterId/health|validate|receive`, plus optional `SOLACENET_GATEWAY_RAILS_ENFORCE` on gateway routes — `src/core/gateway/routes/gateway.routes.ts`, `src/core/gateway/rails/gateway-rails-enforcement.ts`. ### ✅ Service SDK - **Status**: Complete @@ -273,6 +275,10 @@ To test the implementation: 3. Start the server: `npm run dev` 4. Test API endpoints using the Swagger UI: `http://localhost:3000/api-docs` +## Protocol gaps (rails and external messaging) + +Tracked checklist with gap IDs, RTGS matrix cross-reference, and suggested close order: `docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md`. Governance: `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md`. + ## Notes - The Go gateway requires Go 1.21+ and Redis diff --git a/SOLACENET_QUICK_REFERENCE.md b/SOLACENET_QUICK_REFERENCE.md index f1e9187..f704cc4 100644 --- a/SOLACENET_QUICK_REFERENCE.md +++ b/SOLACENET_QUICK_REFERENCE.md @@ -18,6 +18,12 @@ Quick reference guide for the SolaceNet Capability Platform. - Channel (API/UI/mobile) - Customer segment (optional) +### Rail and external protocol governance +Financial rails (SWIFT, DTC/DTCC, TT, KTT legacy evidence, etc.) and **integration contracts** for telecom-adjacent stacks (for example SS7 terminated at a carrier boundary) are **maintained under SolaceNet**: capabilities, policy, audit, Go gateway, and TypeScript adapters in `src/core/gateway/adapters/`. Full policy, code map, and change process: [docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md](docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md). **Tracked protocol gaps (complete list):** [docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md](docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md). + +### Gateway REST (dbis_core API) +Authenticated routes under **`/api/v1/gateway`**: **`GET /rails`** (list adapter IDs), **`GET /rails/:adapterId/health`**, **`POST .../validate`**, **`POST .../receive`**, plus existing instructions and event replay. Optional SolaceNet enforcement: **`SOLACENET_GATEWAY_RAILS_ENFORCE=1`** and **`SOLACENET_DEFAULT_TENANT_ID`** — see `src/core/gateway/rails/README.md` and `.env.example`. OpenAPI: **`/api-docs`** (tag **SolaceNet Gateway Rails**). + ## API Quick Reference ### Capability Registry @@ -206,5 +212,7 @@ JWT_SECRET=your-secret - **Services**: `src/core/solacenet/` - **Shared SDK**: `src/shared/solacenet/` - **Gateway**: `gateway/go/` +- **Rail adapters**: `src/core/gateway/adapters/` (governed per [docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md](docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md)) +- **Rail enforcement env**: `src/core/gateway/rails/README.md` - **Console**: `frontend/solacenet-console/` - **Schema**: `prisma/schema.prisma` diff --git a/docs/IRU_IMPLEMENTATION_STATUS.md b/docs/IRU_IMPLEMENTATION_STATUS.md index 3d89052..241e800 100644 --- a/docs/IRU_IMPLEMENTATION_STATUS.md +++ b/docs/IRU_IMPLEMENTATION_STATUS.md @@ -15,6 +15,7 @@ This document tracks the complete implementation of the IRU Production Readiness ### Phase 1: Marketplace & Portal Foundation ✅ COMPLETE #### 1.1 Sankofa Phoenix Marketplace ✅ +- **Catalog model:** Phoenix IRU marketplace rows are **partner-style** offerings (e.g. SolaceNet). **Native** platform services (VMs, IPs, app hosting, etc.) are documented and operated separately; see `docs/03-deployment/SANKOFA_MARKETPLACE_SURFACES.md` (native vs partner methodology). - ✅ Database schema (IruOffering, IruInquiry, IruSubscription, IruAgreement) - ✅ Backend services: - `marketplace.service.ts` - Marketplace business logic diff --git a/docs/solacenet/AUDIT_GAPS_INCONSISTENCIES_MISSING.md b/docs/solacenet/AUDIT_GAPS_INCONSISTENCIES_MISSING.md new file mode 100644 index 0000000..23e5636 --- /dev/null +++ b/docs/solacenet/AUDIT_GAPS_INCONSISTENCIES_MISSING.md @@ -0,0 +1,68 @@ +# Audit — gaps, inconsistencies, and missing elements (SolaceNet + gateway + edges) + +**Purpose:** Delta review beyond [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md): naming drift, missing wiring, doc collisions, and security/ops gaps. +**Last updated:** 2026-04-07 + +--- + +## 1. Gaps (not yet covered elsewhere or under-specified) + +| Topic | Detail | +|--------|--------| +| **HTTP integration tests** | ~~Added~~ `gateway-rails-http.integration.test.ts` + `createGatewayHttpTestApp`; run via `npm run test:gateway`. | +| **CI for gateway unit tests** | ~~Added~~ workflow `dbis-core-gateway-ci.yml` (Proxmox repo) on gateway path changes. | +| **Go edge vs Node rails** | Documented as **intentional layering** in [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md) §6; optional future shared config if one edge must enumerate `dbis.adapter.*`. | +| **Outbox / send pipeline** | No shared **idempotency store**, **DLQ**, or **transactional outbox** for rail `send` / instruction fan-out. | +| **Audit export** | **Partial:** Winston + optional `SOLACENET_GATEWAY_AUDIT_LOG_PATH` NDJSON (`gateway-rails-audit.ts`). SIEM signing/long-term store still operator-owned. | +| **Provider connector data** | **Partial:** `npm run seed:gateway-provider` upserts `dbis-gateway-rail-plane`. | +| **Telecom northbound** | **Example schema** in `docs/solacenet/schemas/telecom-northbound-event.example.json`; AsyncAPI when boundary exists. | +| **Rate limits** | **Partial:** extra per-IP limiter on `POST .../validate` and `.../receive` (`GATEWAY_RAIL_MUTATE_*`). Per-tenant budgets still open. | +| **Adapter state & secrets** | `initialize(config, secretsRef)` not exercised by REST routes (always `{}`); **no** pattern for loading HSM/KMS refs per rail. | + +--- + +## 2. Inconsistencies + +| Topic | Detail | +|--------|--------| +| **Naming: marketplace vs quantum vs adapter ID** | Marketplace says **“KTT Legacy”**; quantum uses **`KTT_EVIDENCE`**; adapter id is **`dbis.adapter.ktt-evidence`**. Same concept, three namespaces — integrators need a mapping table. | +| **`EntitlementCheckContext.capabilityId`** | ~~Fixed~~ for payment-gateway, mobile-money, wallet-accounts, card-issuing, and tokenization routes; re-audit other `requireCapability` call sites if new services are added. | +| **`GET /api/v1/gateway/rails` vs enforcement** | **Listing** adapters does **not** call `maybeRequireGatewayMicroservices` (by design: metadata). Still requires **same `/api` auth** as other routes. Document so it is not mistaken for “public” data. | +| **Synthetic vs failed send** | SWIFT FIN / TT scaffolds return **`SENT`** without wire; KTT returns **`FAILED`** on send — **test harness semantics** differ; UIs/dashboards could mislead if not labeled scaffold. | +| **“Remaining tasks” doc collision** | Proxmox **`docs/00-meta/REMAINING_TASKS.md`** is **unrelated** to **`dbis_core/docs/solacenet/REMAINING_TASKS_FULL_LIST.md`** — similar names, different scope (confusing in search). | +| **MASTER_INDEX row** | SolaceNet row links into **`dbis_core/`** submodule path; if submodule not checked out, links 404 from browser — **operator** must open from full monorepo. | +| **Section C checklist** (fixed) | Was stale vs `LegacyProtocol`; checklist now references **`legacy-protocol-types.ts`**. | + +--- + +## 3. Missing elements + +| Element | Where it should live / action | +|---------|-------------------------------| +| **Rail name mapping table** | ~~Done~~ — [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md) §5. | +| **Runbook: enable enforcement in prod** | ~~Done~~ — [SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md](SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md). | +| **OpenAPI request body** for `POST /instructions` | ~~Expanded~~ in `gateway.routes.ts` Swagger block. | +| **Go gateway** middleware hook (optional) | Still optional; see PLUGIN bridge §6. | +| **E2E list** | **Internal verifier:** `scripts/verify/check-dbis-core-gateway-rails.sh` (needs `DBIS_CORE_API_BASE` + bearer token). | +| **SEO / share** | **`/solacenet` document title** set in `SolaceNetPage` via `useEffect` (og tags still apex defaults unless SSR). | +| **`AGENTS.md` pointer** | ~~Done~~ — SolaceNet row links hub, full list, audit, API path. | +| **Cloudflare purge** | `purge-info-defi-oracle-cache.sh` purges static files only; **HTML** for new routes may still be served from stale **`index.html`** at edge in some setups — document **purge everything** or origin cache bust when needed. | +| **Thirdweb adapter** | **`ethers`** added as dependency; `Provider` / `Signer` via `import type` from `ethers` — full-repo `tsc` may still have unrelated errors. | + +--- + +## 4. Recommended follow-ups (short) + +1. ~~Add **rail mapping table** to [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md)~~ — done (section 5 + Go vs Node §6). +2. ~~Add **integration test** for `/api/v1/gateway/rails`~~ — done: `src/__tests__/integration/api/gateway-rails-http.integration.test.ts` + `npm run test:gateway` (HTTP suite uses `jest.gateway-http.config.js` with `ts-jest` `diagnostics: false` so it does not require full-repo Prisma strict compile); CI: `.github/workflows/dbis-core-gateway-ci.yml`. +3. ~~Align **`EntitlementCheckContext`**~~ — done for payment-gateway, mobile-money, wallet-accounts, card-issuing, tokenization routes. +4. ~~Link **AGENTS.md**~~ — done (SolaceNet row includes full list + audit). +5. **Remaining:** production **outbox/DLQ**, per-tenant rate budgets, full **`tsc`** green for entire `dbis_core`, wire **`requireGatewayMicroservicesForWorker`** into real MQ/file workers. + +--- + +## Related + +- [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md) +- [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md) +- [REMAINING_TASKS_FULL_LIST.md](REMAINING_TASKS_FULL_LIST.md) diff --git a/docs/solacenet/PLUGIN_AND_GATEWAY_BRIDGE.md b/docs/solacenet/PLUGIN_AND_GATEWAY_BRIDGE.md new file mode 100644 index 0000000..8052218 --- /dev/null +++ b/docs/solacenet/PLUGIN_AND_GATEWAY_BRIDGE.md @@ -0,0 +1,52 @@ +# SolaceNet — Plugin registry vs gateway rail adapters + +**Purpose:** Remove ambiguity between two integration surfaces in `dbis_core`. + +## 1. Plugin registry (`src/integration/plugins/plugin-registry.ts`) + +- **Intent:** Core-banking and ERP connectors (Temenos, Flexcube, SAP, Oracle Banking Platform). +- **Pattern:** `IPluginAdapter` instances registered by short name (`temenos`, `swift`, `iso20022`, …). +- **Use when:** Batch or API integration to a **core system** product, not necessarily a **marketplace rail** contract. + +## 2. Gateway rail adapters (`src/core/gateway/adapters/`) + +- **Intent:** Regulated **messaging rails** and evidence paths (SWIFT families, DTC/DTCC, TT, KTT evidence, Thirdweb contract invocation). +- **Pattern:** `GatewayAdapter` + **`gateway-adapter-registry.ts`** canonical IDs (`dbis.adapter.*`). +- **HTTP surface:** `/api/v1/gateway/rails`, `/api/v1/gateway/rails/:adapterId/health|validate|receive` (authenticated like other `/api/*` routes). +- **SolaceNet:** Optional enforcement via `SOLACENET_GATEWAY_RAILS_ENFORCE=1` and tenant resolution (`x-tenant-id` or body `tenantId`). + +## 3. Bridge strategy (recommended) + +1. **Do not** duplicate the same bank connection as both an unnamed `swift` plugin and a `dbis.adapter.swift-fin` rail without documentation. +2. Prefer **gateway adapters** for anything listed in `marketplace/gateway-microservices-offering.json` rails. +3. Implement a **facade service** if one physical SWIFT connection must feed both: the facade calls the single connector and exposes plugin vs gateway shapes. +4. Document the chosen path in the institutional onboarding pack. + +## 4. Quantum / QPS alignment + +`LegacyProtocol` in `src/infrastructure/quantum/proxy/legacy-protocol-types.ts` includes SolaceNet-extended rails so translation/compatibility APIs can reference the same protocol names where useful. + +## 5. Rail name mapping (marketplace ↔ quantum ↔ adapter ID) + +| Marketplace offering rail (`gateway-microservices-offering.json`) | `LegacyProtocol` (quantum) | Gateway adapter ID | +|----------------------------------|-----------------------------|-------------------| +| SWIFT FIN/MT | `SWIFT` | `dbis.adapter.swift-fin` | +| SWIFT ISO 20022 | `ISO20022` | `dbis.adapter.swift-iso` | +| SWIFT gpi | `SWIFT_GPI` | `dbis.adapter.swift-gpi` | +| DTC Settlement | `DTC_SETTLEMENT` | `dbis.adapter.dtc-settlement` | +| DTCC Family (NSCC) | `DTCC_NSCC` | `dbis.adapter.dtcc-nscc` | +| DTCC Family (FICC) | `DTCC_FICC` | `dbis.adapter.dtcc-ficc` | +| TT Route | `TT_ROUTE` | `dbis.adapter.tt-route` | +| KTT Legacy | `KTT_EVIDENCE` | `dbis.adapter.ktt-evidence` | +| Extensible Adapter SDK | N/A (integration pattern) | Add factory + ID in `gateway-adapter-registry.ts` | + +**HYBX sidecars:** map per deployment in `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` — not duplicated here. + +## 6. Go edge gateway vs Node rails + +The **Go** service under `gateway/go/` performs **generic** capability pre-checks from path/headers (`X-Capability-ID`, `X-Tenant-ID`, …). It does **not** embed the TypeScript **`dbis.adapter.*`** catalog. **Node** (`/api/v1/gateway/rails`) owns rail adapter IDs and enforcement via `gateway-rails-enforcement.ts`. Treat this as **intentional layering**: Go = edge policy cache + proxy; Node = rail semantics — or add a shared config artifact if a single edge must enumerate rails. + +--- + +**Version:** 1.1 +**Last updated:** 2026-04-07 diff --git a/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md b/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md new file mode 100644 index 0000000..38ae173 --- /dev/null +++ b/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md @@ -0,0 +1,164 @@ +# SolaceNet — protocol gaps checklist (tracked) + +**Purpose:** Single **complete** inventory of **protocol, messaging, and integration** gaps across `dbis_core`, SolaceNet, and cross-repo RTGS / DBIS Rail dependencies. Use for backlog triage, ownership, and closing the loop with [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md). + +**How to use status** + +| Status | Meaning | +|--------|---------| +| `open` | Not implemented or only stub/placeholder | +| `partial` | Some path exists; production contract or wiring incomplete | +| `n/a` | Explicitly out of scope for this repo (document boundary only) | +| `done` | Production-capable per defined gate (update row when true) | + +**Last updated:** 2026-04-07 + +--- + +## A. Carrier and telecom signaling + +| ID | Protocol / stack | Location / note | Status | Close when | +|----|------------------|-----------------|--------|------------| +| PG-CAR-001 | **SS7** (MTP2/3, SCCP, ISUP, TCAP…) | Not in repo | `open` | N/A in app repo unless a **telecom boundary service** is chartered; SolaceNet owns northbound API only per governance doc | +| PG-CAR-002 | **SIGTRAN** (M2PA, M3UA, SUA over SCTP) | Not in repo | `open` | Same as PG-CAR-001 | +| PG-CAR-003 | **MAP / CAP / INAP** (circuit intelligence) | Not in repo | `open` | Same | +| PG-CAR-004 | **Diameter** (LTE/5G adjacent) | Not in repo | `open` | Same | + +--- + +## B. `dbis_core` gateway rail adapters (TypeScript) + +Path: `src/core/gateway/adapters/`. All are **scaffolds** unless status changed. + +| ID | Rail | Adapter path | Status | Gap summary | +|----|------|--------------|--------|-------------| +| PG-GW-001 | SWIFT FIN/MT | `swift-fin/swift-fin-adapter.ts` | `open` | No SWIFTNet, no real MT build/parse/sign, synthetic SENT/ACK | +| PG-GW-002 | SWIFT ISO 20022 | `swift-iso/swift-iso-adapter.ts` | `open` | No transport, no XSD/JSON schema pipeline, no ACK semantics | +| PG-GW-003 | SWIFT gpi | `swift-gpi/swift-gpi-adapter.ts` | `open` | No UETR tracker integration | +| PG-GW-004 | DTC settlement | `dtc-settlement/dtc-settlement-adapter.ts` | `open` | No DTC message/API integration | +| PG-GW-005 | DTCC NSCC | `dtcc/dtcc-nscc-adapter.ts` | `open` | No NSCC API/protocol integration | +| PG-GW-006 | DTCC FICC | `dtcc/dtcc-ficc-adapter.ts` | `open` | No FICC API/protocol integration | +| PG-GW-007 | TT route | `tt-route/tt-route-adapter.ts` | `open` | Synthetic routing only | +| PG-GW-008 | KTT legacy evidence | `ktt-evidence/ktt-evidence-adapter.ts` | `open` | Trivial validate; **send unsupported**; no SoR match, no persistence contract | +| PG-GW-009 | Thirdweb (chain RPC) | `thirdweb/thirdweb-adapter.ts` | `partial` | Encode/path comments still **placeholder** in places; not a banking rail but shares adapter plane | + +**B1. Wiring and registry** + +| ID | Gap | Status | Close when | +|----|-----|--------|------------| +| PG-GW-W01 | No **single** gateway adapter registry importing all rail adapters | `partial` | **Registry + REST + OpenAPI + unit tests:** `gateway-adapter-registry.ts`, `/api/v1/gateway/rails*`, Swagger tag **SolaceNet Gateway Rails**, `src/__tests__/unit/core/gateway/*.test.ts`. **Remaining:** DI singleton policy, production connectors, optional `send` orchestration | +| PG-GW-W02 | **PluginRegistry** (`integration/plugins/`) vs **gateway adapters** — duplicate Swift/ISO concepts, no bridge doc in code | `partial` | **Doc:** [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md). **Remaining:** optional facade service in code | +| PG-GW-W03 | SolaceNet **requireCapability** not consistently enforced on adapter ingress paths | `partial` | **On:** `SOLACENET_GATEWAY_RAILS_ENFORCE=1` for `/api/v1/gateway/rails/*`, `POST /instructions`, `GET /events/replay`. **Runbook:** [SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md](SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md). **Audit:** structured logs + optional `SOLACENET_GATEWAY_AUDIT_LOG_PATH` NDJSON; **`requireGatewayMicroservicesForWorker`** for MQ/file. **Remaining:** wire worker call sites + SIEM pipelines | + +--- + +## C. Quantum / QPS legacy protocol coverage + +Services: `src/infrastructure/quantum/proxy/quantum-translation.service.ts`, `quantum-compatibility.service.ts`. + +**Type source:** `legacy-protocol-types.ts` — `LegacyProtocol` = core five plus **SolaceNet-extended** rails (`KTT_EVIDENCE`, `TT_ROUTE`, `DTC_SETTLEMENT`, `DTCC_NSCC`, `DTCC_FICC`, `SWIFT_GPI`, `MOJALOOP`, `RTGS`, `CARD_NETWORK`). **`GET /api/quantum-proxy/compatibility/protocols`** returns the full list. + +| ID | Missing vs marketplace / gateway rails | Status | +|----|----------------------------------------|--------| +| PG-QP-001 | **KTT**, **TT route**, **DTC**, **DTCC** (NSCC/FICC), **SWIFT gpi** as distinct handling | `partial` | **Types + defaults** in `legacy-protocol-types.ts` / quantum translation & compatibility | +| PG-QP-002 | **RTGS** (generic), **Mojaloop**, **card networks**, **instant payment** schemes | `partial` | **RTGS**, **MOJALOOP**, **CARD_NETWORK** in `LegacyProtocol`; still scaffold scoring | +| PG-QP-003 | **Telecom northbound** (carrier boundary event schema) | `partial` | **Example JSON Schema:** [schemas/telecom-northbound-event.example.json](schemas/telecom-northbound-event.example.json). **Remaining:** boundary service + AsyncAPI | + +--- + +## D. Admin dashboards and metrics (protocol surfaces) + +| ID | Component | Path | Status | Gap | +|----|-----------|------|--------|-----| +| PG-AD-001 | GAS/QPS legacy rails | `gas-qps.service.ts` | `partial` | **SolaceNet adapter IDs** merged into `legacyRails`; volumes still 0 / heuristic until QPS integration | +| PG-AD-002 | GAS/QPS mapping profiles | same | `open` | Placeholder profiles only | +| PG-AD-003 | Global overview QPS / Ω / GPN / etc. | `global-overview.service.ts` | `open` | Marked placeholder | +| PG-AD-004 | SCB payment rails | `scb-overview.service.ts` | `open` | Payment rails placeholder | + +--- + +## E. DBIS Rail — on-chain and authorization protocol (parent repo docs) + +Source of truth for deployment truth: `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md` (Proxmox repo). + +| ID | Protocol / contract layer | Status | Gap summary | +|----|---------------------------|--------|-------------| +| PG-RAIL-001 | **DBIS_RootRegistry** | `open` | Contract set not implemented in repo | +| PG-RAIL-002 | **DBIS_ParticipantRegistry** | `open` | Same | +| PG-RAIL-003 | **DBIS_SignerRegistry** | `open` | Same | +| PG-RAIL-004 | **DBIS_SettlementRouter** | `open` | Same | +| PG-RAIL-005 | **DBIS_GRU_MintController** (router-only mint) | `open` | Mint path still owner-mint on c* per master doc | +| PG-RAIL-006 | **Production ISO Gateway** matching EIP-712 MintAuth pipeline | `partial` | Spec/rulebook complete; production service + on-chain registry not aligned | +| PG-RAIL-007 | **MintAuth relayer** operational hardening | `partial` | Documented; full ops gate open | + +--- + +## F. RTGS and external messaging protocols (Proxmox matrix) + +Canonical table: `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md`. +Below: rows that are **protocol, endpoint, or message-contract** heavy and **not Complete**. (Infrastructure rows like Besu/Explorer are omitted here; see matrix for full operational checklist.) + +| ID | Matrix component | Typical protocol / contract gap | Matrix state (as of doc) | +|----|------------------|--------------------------------|--------------------------| +| PG-RTGS-001 | FireFly primary `6200` | Event/orchestration API contract across workflows | Partial | +| PG-RTGS-002 | FireFly secondary `6201` | HA / secondary node payload | Retired / standby | +| PG-RTGS-003 | Fabric `6000-6002` | Fabric channel/chaincode deployment contract if in scope | Partial | +| PG-RTGS-004 | Indy `6400-6402` | DID/ledger protocol production role | Partial | +| PG-RTGS-005 | Aries / AnonCreds / Ursa | DIDComm / credential protocol lifecycle | Partial | +| PG-RTGS-006 | Cacti | Cross-ledger connector protocol | Partial | +| PG-RTGS-007 | OMNL / Fineract API rail | REST/auth/tenant settlement contract | Partial | +| PG-RTGS-008 | Mifos X / Fineract UI | Operator/API procedures | Partial | +| PG-RTGS-009 | HYBX participant / treasury | Business protocol for nostro/vostro + IDs | Planned | +| PG-RTGS-010 | Depository / CSD | Securities settlement messaging model | Planned | +| PG-RTGS-011 | Global custodian | Custody reporting / instruction protocols | Planned | +| PG-RTGS-012 | FX pricing / dealing | Quote/booking protocol to OMNL | Planned | +| PG-RTGS-013 | Liquidity pooling + **source adapters** | Per-source bank/pool protocol contracts | Planned | +| PG-RTGS-014 | Custody / safekeeping lifecycle | End-to-end instruction + statement protocol | Planned | +| PG-RTGS-015 | **Mojaloop** | Quote/transfer/callback/settlement API contract | Planned | +| PG-RTGS-016 | HYBX sidecar layer + listed sidecars | Ingress/auth/retry/event protocols | Partial / Planned | +| PG-RTGS-017 | **mt103-hardcopy-sidecar** | MT103 ingest ↔ settlement correlation | Partial | +| PG-RTGS-018 | **card-networks-sidecar** | Card scheme settlement file/API protocol if in scope | Partial | +| PG-RTGS-019 | **securities-sidecar** | Securities instruction protocol vs CSD | Partial | +| PG-RTGS-020 | Chain 138 settlement path | Contract call graph as frozen protocol | Partial | +| PG-RTGS-021 | MerchantSettlementRegistry / WithdrawalEscrow | Invocation protocol in RTGS flow | Partial | +| PG-RTGS-022 | DBIS settlement tokens + reserve/oracle | Mint/burn and attestation protocols | Partial | +| PG-RTGS-023 | FireFly / sidecar / chain **event model** | Correlation ID, retry, DLQ protocol | Planned | +| PG-RTGS-024 | **ISO 20022 evidence and vault** | Archive/manifest/hash protocol | Partial | +| PG-RTGS-025 | **Institutional 4.995 package** | Submission package protocol | Partial | +| PG-RTGS-026 | **Indonesia / BNI** domestic | Live endpoint/auth/message contract | Planned | +| PG-RTGS-027 | **Global correspondent / liquidity bank** | SWIFT/ISO/correspondent API contract | Planned | +| PG-RTGS-028 | **ISO20022Router** on-chain + off-chain | G4 acceptance steps in matrix subsection | Partial until manual gate passes | +| PG-RTGS-029 | RTGS production gate | All mandatory protocol lanes green | Planned | + +--- + +## G. SolaceNet capability vs rail implementation + +| ID | Gap | Status | Close when | +|----|-----|--------|------------| +| PG-SN-001 | `gateway-microservices` capability describes rails; **adapters remain scaffolds** | `open` | Critical rails reach `done` in section B or scope reduced in offering JSON | +| PG-SN-002 | `solacenet_provider_connector` rows for each live rail provider | `partial` | **Seed:** `npm run seed:gateway-provider` (`dbis-gateway-rail-plane`). **Remaining:** per-institution connectors + bindings | +| PG-SN-003 | smom-dbis-138-publish / tokenization docs: **SolaceNet policy** integration called out as future in places | `partial` | Code paths call `requireCapability` or documented exception | + +--- + +## H. Suggested close order (dependencies) + +1. **PG-GW-W01 / W02 / W03** — Single registry + SolaceNet enforcement (enables safe iteration). +2. **PG-RAIL-001–005 / 006** — On-chain authorization protocol (or explicit deferral). +3. **PG-RTGS-007, PG-RTGS-023** — OMNL + canonical event/correlation protocol. +4. **PG-GW-001–008** — Replace scaffolds rail-by-rail with sandbox → prod endpoints. +5. **PG-RTGS-015, 026, 027** — External switch/domestic/correspondent protocols. +6. **PG-CAR-*** — Only if product scope includes carrier signaling; boundary service first. + +--- + +## Related documents + +- [REMAINING_TASKS_FULL_LIST.md](REMAINING_TASKS_FULL_LIST.md) — **prioritized full task list** (all remaining work in one place) +- [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](AUDIT_GAPS_INCONSISTENCIES_MISSING.md) — **delta audit** (naming drift, missing CI/integration tests, edge gaps) +- [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md) +- Proxmox: [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](../../../docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md) +- Proxmox: [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](../../../docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) +- `dbis_core/src/core/gateway/adapters/README.md` +- `dbis_core/marketplace/gateway-microservices-offering.json` diff --git a/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md b/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md new file mode 100644 index 0000000..2cc0748 --- /dev/null +++ b/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md @@ -0,0 +1,69 @@ +# SolaceNet — rail and external protocol governance + +**Purpose:** Define where **external messaging and carrier-style protocols** (payment rails, legacy evidence feeds, telecom-adjacent integrations) are **owned, versioned, and operated** inside the DBIS Core / SolaceNet stack. + +**Authority:** SolaceNet is the **control plane** for capabilities, entitlements, policy, audit, and the **Go edge gateway** (`gateway/go/`). Rails and protocol adapters are **maintained under SolaceNet** as defined below—not as ad-hoc modules without registry or policy hooks. + +--- + +## 1. What this covers + +| Class | Examples | SolaceNet role | +|--------|-----------|----------------| +| **Financial messaging rails** | SWIFT FIN/MT, SWIFT ISO 20022, SWIFT gpi, DTC, DTCC family, TT route, KTT legacy evidence | Capability `gateway-microservices` / `gateway-adapters`; adapter implementations; schema and version registry; policy before execute | +| **Institutional evidence** | KTT-style legacy files, batch ingest, untrusted evidence until SoR match | Same; explicit “evidence-only” adapters; no mint/settlement without downstream checks | +| **Telecom signaling (SS7 family)** | MTP/SCCP/SIGTRAN, MAP/CAP at carrier edge | **Not implemented in application code here.** SolaceNet owns only the **northbound contract** (HTTPS/MQ/events) from a dedicated telecom boundary service; carrier stack stays outside this repo | + +--- + +## 2. Maintenance responsibilities + +1. **Capability registry** — Each rail or protocol surface is registered (or sub-capability under `gateway-adapters`) with `defaultState`, dependencies, and version. +2. **Policy** — Ingress and execution require `requireCapability` / gateway middleware alignment per tenant, region, and channel. +3. **Audit** — Toggle changes, kill-switch use, and (where implemented) adapter decisions feed SolaceNet audit patterns. +4. **Adapter code** — Canonical TypeScript adapters live under `src/core/gateway/adapters/`; the **edge** is `gateway/go/` (proxy, auth, capability pre-check). +5. **Offerings and marketplace** — JSON offerings (e.g. `marketplace/gateway-microservices-offering.json`) declare rails; **governance** field identifies SolaceNet as maintainer. + +--- + +## 3. Code and doc map + +| Artifact | Path | +|----------|------| +| Capability platform | `src/core/solacenet/` | +| SolaceNet SDK | `src/shared/solacenet/sdk.ts` | +| Go API gateway | `gateway/go/` | +| Rail adapters (TS) | `src/core/gateway/adapters/` | +| Docker stack | `docker-compose.solacenet.yml` | +| Operator quick reference | `SOLACENET_QUICK_REFERENCE.md` (repo root of `dbis_core`) | +| This governance doc | `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md` | + +--- + +## 4. Adding or changing a protocol + +1. Register or update **capability** (and entitlements) in the SolaceNet registry. +2. Add adapter under `src/core/gateway/adapters//` implementing `GatewayAdapter` (`sdk/adapter-interface.ts`). +3. Wire adapter into the **single** gateway adapter registry when introduced (avoid parallel unregistered copies). +4. Document trust model (trusted rail vs evidence-only vs telecom boundary). +5. Update marketplace offering JSON and, if needed, seed scripts (`scripts/seed-gateway-capability.ts`). + +--- + +## 5. Related platform notes + +- **Plugin registry** (`src/integration/plugins/plugin-registry.ts`) covers core-banking connectors; **rail protocol contracts** for regulated messaging should align with this governance doc or be explicitly bridged—do not treat plugins and gateway adapters as competing sources of truth without documentation. **Bridge guide:** [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md). +- **DBIS Rail / Chain 138** settlement docs in the parent Proxmox repo describe on-chain authorization; SolaceNet rails feed **off-chain** evidence and controls that must satisfy those specs before submission. + +## 6. Tracked protocol gaps + +Maintained checklist (IDs, status, close criteria, RTGS cross-reference): [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md). + +## 7. Public documentation + +Markdown for **public** audiences (mirrored in spirit on **info.defi-oracle.io/solacenet**): [public/OVERVIEW.md](public/OVERVIEW.md), [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md). Hub index: `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` (parent Proxmox repo). + +--- + +**Version:** 1.2 +**Last updated:** 2026-04-07 diff --git a/docs/solacenet/REMAINING_TASKS_FULL_LIST.md b/docs/solacenet/REMAINING_TASKS_FULL_LIST.md new file mode 100644 index 0000000..6f42e7a --- /dev/null +++ b/docs/solacenet/REMAINING_TASKS_FULL_LIST.md @@ -0,0 +1,171 @@ +# SolaceNet, gateway rails, and RTGS — full remaining task list + +**Purpose:** One actionable backlog derived from [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md), [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md), and the Proxmox RTGS / DBIS Rail docs. Update row statuses in the checklist as tasks close. + +**Last reviewed:** 2026-04-07 + +**Priority legend** + +| Tier | Meaning | +|------|---------| +| **P0** | Blocks honest production claims or regulatory narrative alignment | +| **P1** | Core path to first production slice (settlement + evidence + one live rail) | +| **P2** | Breadth, observability, UX, secondary rails | +| **P3** | Optional, carrier, or explicit deferrals | + +--- + +## P0 — Truth in advertising and critical alignment + +| # | Task | Gap ID(s) | Notes | +|---|------|-----------|--------| +| 1 | **Reconcile marketplace/offering copy** with live connector maturity — or scope down `gateway-microservices-offering.json` until rails are real | PG-SN-001, offering JSON | **Updated 2026-04-08:** description names scaffolds + KTT evidence semantics; keep row until production connectors ship. | +| 2 | **Document KTT explicitly** as evidence-only in marketplace/UI copy; separate from symmetric send/receive rails | PG-GW-008, inconsistencies doc | Code already fails `send` by design | +| 3 | **Decide DBIS Rail scope:** implement contracts + router-only mint **or** formally defer and update all docs that imply live Rail | PG-RAIL-001–005, master doc | See `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md` | +| 4 | **Fix or quarantine Thirdweb adapter** type issues (`ethers` namespace) for clean `tsc` / CI | PG-GW-009 | **Partial:** `ethers` dependency + `import type { Provider, Signer }`; full `dbis_core` `tsc` may still fail elsewhere. | + +--- + +## P1 — Gateway core (SolaceNet + REST + enforcement) + +| # | Task | Gap ID(s) | Notes | +|---|------|-----------|--------| +| 5 | **DI / lifecycle policy** for rail adapters (singleton vs per-request) and document | PG-GW-W01 | Registry exists; avoid accidental state bleed | +| 6 | **Orchestrated `send` path** (outbox, idempotency, DLQ) for rails that support outbound messages | PG-GW-W01, PG-GW-001–007 | KTT may stay receive-only | +| 7 | **Extend `SOLACENET_GATEWAY_RAILS_ENFORCE`** to every rail ingress (file drop, MQ, future workers) + **audit log** export for denied/allowed | PG-GW-W03 | HTTP path partially done | +| 8 | **Optional code facade** for PluginRegistry ↔ gateway adapters when one physical connector serves both | PG-GW-W02 | Doc exists; implement if needed | +| 9 | **Register `solacenet_provider_connector`** rows per environment for each live provider | PG-SN-002 | Tie to capability bindings | +|10 | **smom-dbis-138-publish / tokenization:** wire `requireCapability` or document explicit exception | PG-SN-003 | | + +--- + +## P1 — Replace rail scaffolds (production connectors) + +| # | Task | Gap ID | Notes | +|---|------|--------|--------| +|11| SWIFT FIN/MT — SWIFTNet, crypto, parse, ACK/NAK, sandbox → prod | PG-GW-001 | | +|12| SWIFT ISO 20022 — transport + schema validation + status | PG-GW-002 | | +|13| SWIFT gpi — UETR tracker integration | PG-GW-003 | | +|14| DTC settlement — real message/API | PG-GW-004 | | +|15| DTCC NSCC — API/protocol | PG-GW-005 | | +|16| DTCC FICC — API/protocol | PG-GW-006 | | +|17| TT route — real routing contract | PG-GW-007 | | +|18| KTT evidence — real validate, persistence, **SoR match**, correlation IDs; keep or drop `send` | PG-GW-008 | | +|19| Thirdweb — remove encode placeholders or document as non-prod | PG-GW-009 | | + +--- + +## P1 — DBIS Rail off-chain + relayer + +| # | Task | Gap ID | Notes | +|---|------|--------|--------| +|20| **Production ISO Gateway** aligned with EIP-712 MintAuth + `accountingRef` / `isoHash` | PG-RAIL-006 | Spec/rulebook exist | +|21| **MintAuth relayer** — ops runbook, monitoring, key rotation, incident drill | PG-RAIL-007 | | + +--- + +## P1 — RTGS spine (canonical docs matrix) + +*Full row-by-row status lives in* `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md`. *Tasks below are the protocol-heavy items still not Complete.* + +| # | Task | Gap ID | Matrix state | +|---|------|--------|--------------| +|22| Freeze **OMNL / Fineract** tenant, auth, settlement API contract | PG-RTGS-007 | Partial | +|23| **Canonical event model** — correlation ID, retry, DLQ, FireFly/sidecar/chain | PG-RTGS-023 | Planned | +|24| **Mojaloop** — live endpoint, auth, quote/transfer/callback | PG-RTGS-015 | Planned | +|25| **Indonesia / BNI** — live domestic contract | PG-RTGS-026 | Planned | +|26| **Global correspondent** — SWIFT/ISO, nostro/vostro, confirmations | PG-RTGS-027 | Planned | +|27| **ISO 20022 evidence + vault** — manifests, hashes, legal path | PG-RTGS-024 | Partial | +|28| **Institutional 4.995 package** — `--strict` readiness, real materials | PG-RTGS-025 | Partial | +|29| **ISO20022Router** — complete G4 manual acceptance (deploy, payload, tx, correlation, evidence) | PG-RTGS-028 | Partial | +|30| Freeze **Chain 138 settlement** contract graph for RTGS | PG-RTGS-020 | Partial | +|31| Place **MerchantSettlementRegistry** / **WithdrawalEscrow** in canonical flows | PG-RTGS-021 | Partial | +|32| **MT103 hardcopy sidecar** — ingest ↔ settlement correlation | PG-RTGS-017 | Partial | +|33| **HYBX sidecars** — boundaries, auth, retries (all listed in matrix) | PG-RTGS-016 | Partial / Planned | +|34| **RTGS production gate** — all mandatory rows green for chosen architecture | PG-RTGS-029 | Planned | + +--- + +## P2 — Hyperledger / identity / interoperability (RTGS matrix) + +| # | Task | Gap ID | Notes | +|---|------|--------|--------| +|35| FireFly primary — orchestration role + real workflow | PG-RTGS-001 | Partial | +|36| FireFly secondary — rebuild or formally exclude | PG-RTGS-002 | Retired / standby | +|37| Fabric — production topology decision | PG-RTGS-003 | Partial | +|38| Indy — production role decision | PG-RTGS-004 | Partial | +|39| Aries / AnonCreds / Ursa — lifecycle validation | PG-RTGS-005 | Partial | +|40| Cacti — cross-ledger contract | PG-RTGS-006 | Partial | +|41| Mifos X / operator procedures | PG-RTGS-008 | Partial | +|42| HYBX participant / treasury / nostro-vostro model | PG-RTGS-009 | Planned | +|43| Depository / CSD layer | PG-RTGS-010 | Planned | +|44| Global custodian | PG-RTGS-011 | Planned | +|45| FX pricing / dealing engine | PG-RTGS-012 | Planned | +|46| Liquidity pooling + source adapters | PG-RTGS-013 | Planned | +|47| Custody / safekeeping lifecycle | PG-RTGS-014 | Planned | +|48| Card-networks sidecar — scope + protocol | PG-RTGS-018 | Partial | +|49| Securities sidecar — CSD alignment | PG-RTGS-019 | Partial | +|50| Settlement tokens + reserve/oracle mapping | PG-RTGS-022 | Partial | + +--- + +## P2 — Quantum / QPS and admin dashboards + +| # | Task | Gap ID | Notes | +|---|------|--------|--------| +|51| Replace **scaffold** FX/risk/scoring for `LegacyProtocol` extended rails with real rules | PG-QP-001, PG-QP-002 | Types exist | +|52| **Telecom northbound event schema** (when boundary service exists) | PG-QP-003 | | +|53| **GAS/QPS mapping profiles** — real profiles, not placeholders | PG-AD-002 | | +|54| **Global overview** — QPS / Ω / GPN placeholders → real metrics or remove | PG-AD-003 | | +|55| **SCB payment rails** — real data source | PG-AD-004 | | +|56| **GAS/QPS** — wire true volumes per rail (not only adapter ID list + heuristics) | PG-AD-001 | | + +--- + +## P3 — Carrier / telecom (out of app repo unless product requires) + +| # | Task | Gap ID | Notes | +|---|------|--------|--------| +|57| Charter **telecom boundary service** + northbound API into SolaceNet | PG-CAR-001–004 | SS7/SIGTRAN/MAP/CAP/Diameter | + +--- + +## P3 — Consistency and hygiene (ongoing) + +| # | Task | Source | Notes | +|---|------|--------|--------| +|58| Align **outbox semantics** — synthetic `SENT` vs KTT `FAILED` on send; document test vs prod behavior | GAPS_AND_INCONSISTENCIES | | +|59| **QPS “SWIFT” volume** — replace `iso_messages` string heuristic with real classification | GAPS_AND_INCONSISTENCIES | | +|60| Keep **agent-hints / sitemap / verify script** in sync when adding public routes | Public gaps §3 | | +|61| Run **`pnpm run verify:info-defi-oracle-public`** after each hub deploy | Ops | | +|62| Optional **`pnpm run audit:info-defi-oracle-site`** (Playwright) in release cadence | Ops | | +|63| Maintain **`PROTOCOL_GAPS_CHECKLIST.md`** statuses as backlog moves | Process | | + +--- + +## Infrastructure rows (not duplicated here) + +Besu, Explorer, Caliper benchmarks, and other **non-protocol** RTGS matrix rows remain in `DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` — track there for VM/LXC/ops completeness. + +--- + +## Suggested execution waves (summary) + +1. **Wave A:** P0 items + PG-RAIL decision + first real rail sandbox (pick one: SWIFT ISO or domestic). +2. **Wave B:** OMNL freeze + event model + ISO evidence path + ISO20022Router G4. +3. **Wave C:** Remaining gateway adapters + provider connectors + QPS real metrics. +4. **Wave D:** Mojaloop / BNI / correspondent as jurisdiction requires. +5. **Wave E:** P2 institutional layers (CSD, custody, FX engine) per product scope. +6. **Wave F:** Carrier only if explicitly in scope. + +--- + +## Related documents + +- [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md) — ID-level tracking +- [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md) — narrative gaps +- [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md) +- [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md) +- Proxmox: `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` +- Proxmox: `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md` +- Proxmox: `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` diff --git a/docs/solacenet/SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md b/docs/solacenet/SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md new file mode 100644 index 0000000..e8881bf --- /dev/null +++ b/docs/solacenet/SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md @@ -0,0 +1,36 @@ +# Runbook — enable `SOLACENET_GATEWAY_RAILS_ENFORCE` (gateway rails) + +**Purpose:** Turn on SolaceNet capability checks for mutating gateway rail endpoints and related ingress (`/api/v1/gateway/rails/*` except `GET /rails` list, `POST /instructions`, `GET /events/replay`). + +**Prerequisites** + +- Policy engine / entitlements can resolve `gateway-microservices` for target tenants. +- Tenants that must use rails have **active entitlements** (or policy allow) for capability id **`gateway-microservices`**. +- Clients send **`x-tenant-id`** (or `tenantId` in JSON body where applicable). Optional default: set **`SOLACENET_DEFAULT_TENANT_ID`** in environment for lab only. + +**Audit** + +- Every allow/deny is logged as structured **`Gateway rails enforcement audit`** (Winston). +- Optional **NDJSON file:** set `SOLACENET_GATEWAY_AUDIT_LOG_PATH` to an operator-writable path; append-only, rotate externally. + +**Steps** + +1. **Seed or verify entitlements** for each production tenant that should call rail adapters. +2. Set environment on the API process: + - `SOLACENET_GATEWAY_RAILS_ENFORCE=1` (or `true`) + - Optionally `SOLACENET_DEFAULT_TENANT_ID=…` for single-tenant lab (not recommended for multi-tenant prod). +3. **Smoke test without entitlement:** call `GET /api/v1/gateway/rails/dbis.adapter.ktt-evidence/health` with a tenant that lacks the capability — expect **403** with a forbidden message. +4. **Smoke test with entitlement:** same call with an entitled tenant — expect **200** and health JSON. +5. **Confirm list endpoint:** `GET /api/v1/gateway/rails` remains **200** (metadata only; still requires normal API auth). + +**Rollback** + +- Unset `SOLACENET_GATEWAY_RAILS_ENFORCE` or set to `0` / `false` and restart the API. + +**Related** + +- `src/core/gateway/rails/gateway-rails-enforcement.ts` +- `dbis_core/.env.example` — SolaceNet gateway variables +- `AUDIT_GAPS_INCONSISTENCIES_MISSING.md` — SIEM/export pipelines beyond file + logs remain optional + +**Version:** 1.0 · **Last updated:** 2026-04-07 diff --git a/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md b/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md new file mode 100644 index 0000000..2b50d4d --- /dev/null +++ b/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md @@ -0,0 +1,59 @@ +# SolaceNet — gaps and inconsistencies (consolidated) + +**Purpose:** Single list of **protocol gaps**, **product/documentation mismatches**, and **structural inconsistencies** relevant to SolaceNet, gateway rails, and public messaging. For **actionable gap IDs** and close criteria, use [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md). For a **delta audit** (missing CI, naming drift, dual edge), see [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](../AUDIT_GAPS_INCONSISTENCIES_MISSING.md). + +**Last updated:** 2026-04-07 + +--- + +## 1. Protocol and implementation gaps (summary) + +- **Carrier signaling (SS7/SIGTRAN/MAP/CAP/Diameter):** Not implemented in application repos; only a **northbound integration contract** is in scope for SolaceNet if a telecom boundary service is added. +- **All TypeScript gateway rail adapters** under `src/core/gateway/adapters/` remain **scaffolds** (synthetic success or evidence-only stubs) until replaced with live connectors. +- **KTT evidence adapter:** `send` is explicitly unsupported; **validate** is trivial; no system-of-record match. +- **DBIS Rail on-chain contracts** (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController): **not deployed** per Proxmox DBIS Rail master status; **owner mint** vs **router-only mint** remains a gap. +- **Quantum / QPS** — **Partial:** `LegacyProtocol` now includes SolaceNet-aligned rails (KTT evidence, TT, DTC/DTCC, gpi, Mojaloop, RTGS, card); scoring remains **scaffold** until field contracts are frozen. +- **Admin dashboards** (`gas-qps`, `global-overview`, `scb-overview`): **placeholder** rail metrics and profiles. +- **RTGS / external bank protocols:** Many matrix rows **Planned** or **Partial** (Mojaloop, BNI, correspondent/SWIFT live contracts, ISO evidence packages, etc.)—see `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` in the Proxmox repo. + +--- + +## 2. Inconsistencies (architecture and naming) + +| Topic | Issue | +|--------|--------| +| **Dual adapter systems** | **Mitigated (doc):** [PLUGIN_AND_GATEWAY_BRIDGE.md](../PLUGIN_AND_GATEWAY_BRIDGE.md). **Remaining:** optional facade in code if one physical connector serves both shapes. | +| **KTT vs other rails** | Marketplace lists **KTT Legacy** next to full **send/receive** rails; code is **evidence-only** and **send** fails by design. | +| **Synthetic success** | SWIFT FIN / TT scaffolds return **SENT** without network I/O; **KTT** returns **FAILED** on send—mixed semantics for “outbox” testing. | +| **Thirdweb in gateway folder** | Shares adapter plane with **bank rails**; not a messaging rail—boundary should stay documented for integrators. | +| **Offering copy vs reality** | `gateway-microservices-offering.json` describes a regulated fabric; **implementations are not production-grade** connectors yet. | +| **QPS dashboard “SWIFT” volume** | Derived from `iso_messages` heuristics (`messageType.includes('SWIFT')`)—**not** true SWIFT FIN volume. | + +--- + +## 3. Public web and documentation gaps + +| Topic | Issue | +|--------|--------| +| **info.defi-oracle.io** | **Mitigated:** `/solacenet` SPA page and nav link; `agent-hints.json`, `sitemap.xml`, `llms.txt`, and `verify:info-defi-oracle-public` updated. Deep technical docs remain in repo markdown only. | +| **Cross-repo discovery** | **Mitigated:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` indexes public web + `dbis_core/docs/solacenet/`. | +| **Agent hints / sitemap** | Ongoing hygiene: any **new** public routes must update the same artifacts. | + +--- + +## 4. Recommended next steps (ordered) + +1. Keep **PROTOCOL_GAPS_CHECKLIST.md** statuses current as code changes. +2. Enforce **SolaceNet capability checks** on any new rail ingress path. +3. Replace scaffolds **rail-by-rail** with sandbox then production connectors; update **public** pages to reflect “generally available” only when true. +4. Unify or document **PluginRegistry ↔ gateway adapters** with one facade. +5. Align **quantum** protocol enums with **marketplace** rails or explicitly exclude them. + +--- + +## Related documents + +- [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md) +- [RAIL_AND_PROTOCOL_GOVERNANCE.md](../RAIL_AND_PROTOCOL_GOVERNANCE.md) +- Proxmox: [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](../../../../docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md) +- Proxmox: [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](../../../../docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) diff --git a/docs/solacenet/public/OVERVIEW.md b/docs/solacenet/public/OVERVIEW.md new file mode 100644 index 0000000..c0614f8 --- /dev/null +++ b/docs/solacenet/public/OVERVIEW.md @@ -0,0 +1,39 @@ +# SolaceNet — public overview + +**Audience:** Institutions, integrators, and supervisors evaluating how **capabilities, policy, and rails** are governed in the DBIS Core stack. This page is **non-operational**: it does not expose credentials, internal endpoints, or live tenant data. + +--- + +## What SolaceNet is + +**SolaceNet** is the **capability and control plane** in DBIS Core: it registers **what** product functions may run (payment gateway, tokenization, limits, fees, **gateway microservices / rail adapters**), for **whom** (tenant, program, region, channel), and under **which policy** (allow/deny, kill switch, audit). The **Go API gateway** (`dbis_core/gateway/go/`) can enforce capability checks at the edge before traffic reaches Node services. + +**Rail and messaging protocols** (for example SWIFT families, DTC/DTCC, telegraphic transfer routes, legacy evidence ingest such as KTT) are **maintained under SolaceNet**—see internal governance: `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md`. + +--- + +## What the public should expect + +| Topic | Public | Authenticated / contract | +|--------|--------|---------------------------| +| **Existence and scope** of SolaceNet | Yes — this document and the info hub page | — | +| **Capability names and high-level behavior** | Summarized | Full API schemas and runbooks | +| **Rail adapter wire protocols** | Described at category level only | Message formats, endpoints, keys, IPs | +| **Production status** | “Integration in progress” where adapters are scaffolds | Environment-specific readiness | +| **Chain 138 settlement** | Via [info.defi-oracle.io](https://info.defi-oracle.io) hub and explorer | DBIS Rail / RTGS runbooks (restricted) | + +--- + +## Related reading (repository) + +- **Governance:** `dbis_core/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md` +- **Protocol gap tracking:** `dbis_core/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md` +- **Gaps and inconsistencies (product/doc):** `dbis_core/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md` +- **Operator quick reference:** `dbis_core/SOLACENET_QUICK_REFERENCE.md` +- **Proxmox public hub pointer:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` +- **Authenticated API (integrators):** `GET /api/v1/gateway/rails` and related routes on DBIS Core (see `gateway.routes.ts`); optional `SOLACENET_GATEWAY_RAILS_ENFORCE` — `dbis_core/.env.example` + +--- + +**Version:** 1.0 +**Last updated:** 2026-04-07 diff --git a/docs/solacenet/public/README.md b/docs/solacenet/public/README.md new file mode 100644 index 0000000..e79170b --- /dev/null +++ b/docs/solacenet/public/README.md @@ -0,0 +1,12 @@ +# SolaceNet — public documentation (markdown) + +Markdown in this folder is the **canonical source** for public-facing SolaceNet narrative. The live **web** summary is published on **https://info.defi-oracle.io/solacenet** (see `info-defi-oracle-138` in the Proxmox repo). + +| File | Purpose | +|------|---------| +| [OVERVIEW.md](OVERVIEW.md) | What SolaceNet is; public vs authenticated expectations; repo pointers | +| [GAPS_AND_INCONSISTENCIES.md](GAPS_AND_INCONSISTENCIES.md) | Consolidated gaps and doc/product inconsistencies | + +**Internal** (not necessarily reproduced on the public site): [RAIL_AND_PROTOCOL_GOVERNANCE.md](../RAIL_AND_PROTOCOL_GOVERNANCE.md), [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md), [REMAINING_TASKS_FULL_LIST.md](../REMAINING_TASKS_FULL_LIST.md) (prioritized backlog), [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](../AUDIT_GAPS_INCONSISTENCIES_MISSING.md) (delta audit), [PLUGIN_AND_GATEWAY_BRIDGE.md](../PLUGIN_AND_GATEWAY_BRIDGE.md). + +**Operator index:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` (Proxmox repo root). diff --git a/docs/solacenet/schemas/telecom-northbound-event.example.json b/docs/solacenet/schemas/telecom-northbound-event.example.json new file mode 100644 index 0000000..73a0039 --- /dev/null +++ b/docs/solacenet/schemas/telecom-northbound-event.example.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://dbis.example/schemas/solacenet/telecom-northbound-event.example.json", + "title": "Telecom boundary → Core northbound event (example)", + "description": "Placeholder contract for PG-QP-003 when a carrier boundary service exists. Not wire format for SS7; JSON over HTTPS/Kafka from the boundary only.", + "type": "object", + "required": ["eventId", "eventType", "occurredAt", "correlationId", "tenantId"], + "properties": { + "eventId": { "type": "string", "format": "uuid" }, + "eventType": { + "type": "string", + "examples": ["carrier.signaling.observed", "carrier.route.health", "carrier.fraud.signal"] + }, + "occurredAt": { "type": "string", "format": "date-time" }, + "correlationId": { "type": "string" }, + "tenantId": { "type": "string" }, + "programId": { "type": "string" }, + "region": { "type": "string" }, + "channel": { "type": "string", "const": "TELECOM_NORTHBOUND" }, + "payload": { + "type": "object", + "additionalProperties": true, + "description": "Opaque carrier-normalized facts; no raw MAP/CAP on this bus." + } + }, + "additionalProperties": false +} diff --git a/frontend/src/constants/marketplace.ts b/frontend/src/constants/marketplace.ts new file mode 100644 index 0000000..3be3a46 --- /dev/null +++ b/frontend/src/constants/marketplace.ts @@ -0,0 +1,30 @@ +/** + * Sankofa Marketplace — product and vendor labels. + * SolaceNet is the commercial name for the IRU offering line; other products may be added over time. + */ +import { OfferMetadata } from '@/constants/offerTaxonomy'; + +export { + BILLING_MODE_LABELS, + COMMERCIAL_MODEL_LABELS, + FULFILLMENT_MODE_LABELS, + OFFER_STATUS_LABELS, + OFFER_TYPE_LABELS, + SUPPORT_OWNER_LABELS, +} from '@/constants/offerTaxonomy'; + +export const MARKETPLACE_NAME = 'Sankofa Phoenix Marketplace'; + +export const SOLACENET_PRODUCT_NAME = 'SolaceNet'; +export const SOLACENET_VENDOR_NAME = 'Solace Bank Group PLC'; +/** Legal / technical term shown alongside the product name */ +export const SOLACENET_IRU_LABEL = 'Irrevocable Right of Use (IRU)'; + +export const SOLACENET_OFFER_METADATA: OfferMetadata = { + offerType: 'partner', + commercialModel: 'IRU', + supportOwner: 'partner', + fulfillmentMode: 'request_only', + billingMode: 'contract', + status: 'request_only', +}; diff --git a/frontend/src/constants/offerTaxonomy.ts b/frontend/src/constants/offerTaxonomy.ts new file mode 100644 index 0000000..430e5be --- /dev/null +++ b/frontend/src/constants/offerTaxonomy.ts @@ -0,0 +1,57 @@ +export type OfferType = 'native' | 'partner'; +export type CommercialModel = + | 'IRU' + | 'SaaS' + | 'managed_service' + | 'reserved_capacity' + | 'custom'; +export type SupportOwner = 'sankofa' | 'partner' | 'shared'; +export type FulfillmentMode = 'self_service' | 'request_only' | 'operator_provisioned'; +export type BillingMode = 'subscription' | 'contract' | 'quote'; +export type OfferStatus = 'active' | 'preview' | 'request_only'; + +export interface OfferMetadata { + offerType: OfferType; + commercialModel: CommercialModel; + supportOwner: SupportOwner; + fulfillmentMode: FulfillmentMode; + billingMode: BillingMode; + status: OfferStatus; +} + +export const OFFER_TYPE_LABELS: Record = { + native: 'Native offer', + partner: 'Partner offer', +}; + +export const COMMERCIAL_MODEL_LABELS: Record = { + IRU: 'IRU', + SaaS: 'SaaS', + managed_service: 'Managed service', + reserved_capacity: 'Reserved capacity', + custom: 'Custom commercial model', +}; + +export const SUPPORT_OWNER_LABELS: Record = { + sankofa: 'Sankofa support', + partner: 'Partner support', + shared: 'Shared support', +}; + +export const FULFILLMENT_MODE_LABELS: Record = { + self_service: 'Self-service', + request_only: 'Request only', + operator_provisioned: 'Operator provisioned', +}; + +export const BILLING_MODE_LABELS: Record = { + subscription: 'Subscription billing', + contract: 'Contract billing', + quote: 'Quote-based billing', +}; + +export const OFFER_STATUS_LABELS: Record = { + active: 'Active', + preview: 'Preview', + request_only: 'Request only', +}; diff --git a/frontend/src/pages/marketplace/AgreementViewer.tsx b/frontend/src/pages/marketplace/AgreementViewer.tsx index de8e719..c55a7c3 100644 --- a/frontend/src/pages/marketplace/AgreementViewer.tsx +++ b/frontend/src/pages/marketplace/AgreementViewer.tsx @@ -1,8 +1,8 @@ -// Agreement Viewer Component -// Preview and e-signature for IRU Agreement +// SolaceNet (IRU) agreement preview / e-signature import React, { useState, useEffect } from 'react'; import { apiClient } from '@/services/api/client'; +import { SOLACENET_PRODUCT_NAME, SOLACENET_VENDOR_NAME } from '@/constants/marketplace'; interface AgreementViewerProps { agreementId?: string; @@ -27,7 +27,7 @@ export const AgreementViewer: React.FC = ({ // For now, use placeholder setLoading(false); setAgreement({ - content: 'IRU Participation Agreement content will be loaded here...', + content: `${SOLACENET_PRODUCT_NAME} participation agreement content will be loaded here...`, status: 'draft', }); }, [agreementId, subscriptionId]); @@ -74,8 +74,9 @@ export const AgreementViewer: React.FC = ({
+

{SOLACENET_VENDOR_NAME}

- IRU Participation Agreement + {SOLACENET_PRODUCT_NAME} participation agreement

{agreement?.status && ( diff --git a/frontend/src/pages/marketplace/CheckoutFlow.tsx b/frontend/src/pages/marketplace/CheckoutFlow.tsx index 5789968..df94e0b 100644 --- a/frontend/src/pages/marketplace/CheckoutFlow.tsx +++ b/frontend/src/pages/marketplace/CheckoutFlow.tsx @@ -1,8 +1,8 @@ -// Checkout Flow Component -// Subscription and payment flow for IRU +// Checkout — SolaceNet (IRU) subscription flow import React, { useState } from 'react'; import { apiClient } from '@/services/api/client'; +import { SOLACENET_PRODUCT_NAME, SOLACENET_VENDOR_NAME } from '@/constants/marketplace'; interface CheckoutFlowProps { subscriptionId?: string; @@ -86,7 +86,8 @@ export const CheckoutFlow: React.FC = ({

Offering ID: {offeringId}

- Please review the IRU Participation Agreement before proceeding. + Please review the {SOLACENET_PRODUCT_NAME} participation agreement ( + {SOLACENET_VENDOR_NAME}) before proceeding.

+

+ {SOLACENET_VENDOR_NAME} · {SOLACENET_PRODUCT_NAME} ({SOLACENET_IRU_LABEL}) +

{offering.name}

-
+
+ + {OFFER_TYPE_LABELS[SOLACENET_OFFER_METADATA.offerType]} + + + {COMMERCIAL_MODEL_LABELS[SOLACENET_OFFER_METADATA.commercialModel]} + + + {FULFILLMENT_MODE_LABELS[SOLACENET_OFFER_METADATA.fulfillmentMode]} + + + {SUPPORT_OWNER_LABELS[SOLACENET_OFFER_METADATA.supportOwner]} + +
+
Tier {offering.capacityTier}: {TIER_NAMES[offering.capacityTier]} @@ -214,11 +241,25 @@ export const OfferingDetail: React.FC = () => { {/* Pricing Card */}

Pricing

+

+ This is a request-based partner program. Commercial terms are handled through qualification and agreement, + not as a separate marketplace type. +

+
+ + {BILLING_MODE_LABELS[SOLACENET_OFFER_METADATA.billingMode]} + + + {FULFILLMENT_MODE_LABELS[SOLACENET_OFFER_METADATA.fulfillmentMode]} + +
{pricing ? (
{pricing.basePrice && (
-
IRU Grant Fee
+
+ {SOLACENET_PRODUCT_NAME} grant fee ({SOLACENET_IRU_LABEL}) +
{pricing.currency} {pricing.basePrice.toLocaleString()}
@@ -296,7 +337,9 @@ export const OfferingDetail: React.FC = () => {
-

Request Information

+

+ Request information — {SOLACENET_PRODUCT_NAME} +