# 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/<rail>/` 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
