proxmox/docs/dbis-rail/E2E_WHITEPAPER_SIMPLE.md

# DBIS Rail — End-to-End White Paper (Simple Terms)

**What is it?**  
The DBIS Rail is a **settlement and minting system** that runs on a dedicated blockchain (Chain 138). It connects **traditional banking and ledger evidence** (ISO messages, double-entry bookkeeping) to **on-chain token creation (GRU)**. Only properly authorized, compliant instructions can record a settlement and mint tokens—and the chain never decides whether “real money” is final; that stays in the regulated world.

---

## 1. The Problem It Solves

**Banks and institutions** need to:

- Move value in a way that is **auditable** and tied to **real ledger entries** and **compliance checks**.
- **Mint digital tokens (GRU)** only when a defined process has been completed: messages received, funds confirmed, accounting done, and a **group of authorized signers** has agreed.
- Avoid **single points of failure**: no one person or system can approve a mint alone.
- Keep **proof** that each on-chain settlement links back to a specific message, accounting batch, and evidence bundle.

The DBIS Rail does this by:

1. Taking **off-chain** evidence (ISO-20022 messages, ledger postings, compliance) and turning it into a **signed authorization**.
2. Running that authorization **on-chain** through contracts that check signers, replay, limits, and participant allowlists.
3. **Recording** the settlement and **minting** GRU only when every check passes.

---

## 2. How It Works End-to-End (Settlement and Mint)

### Step 1: Message and compliance (off-chain)

- An **ISO Gateway** (off-chain system) receives banking messages (e.g. payment instructions, statements).
- It runs **compliance** (KYC, AML, sanctions, limits) per the Rulebook. No authorization is built for failed or unresolved cases.
- It posts the transaction in the **DBIS ledger** (double-entry, reserve accounts) and creates a **unique accounting reference** from that posting (journal, batch, timestamp, reserve account). That reference will be attached to the on-chain settlement forever.

### Step 2: “Good funds” and finality (off-chain)

- The Rulebook defines **when** funds are treated as final (e.g. wire posted, ACH return window passed, internal transfer completed).
- The Gateway sets a **funds status** (e.g. ON_LEDGER_FINAL or OFF_LEDGER_FINAL) only when the right conditions are met. **The chain does not decide finality**—the regulated process does.

### Step 3: Building the Mint Authorization (off-chain)

- The Gateway builds a **Mint Authorization**: a compact package that includes:
  - A **unique message ID** (from the payment/instruction).
  - **Evidence hash** (hash of the canonical evidence bundle).
  - **Accounting reference** (tied to the ledger posting).
  - **Recipients and amounts** (who gets GRU and how much).
  - **Time window** (valid from/until).
  - **Chain and contract** (Chain 138, Settlement Router address).
- This package is in a standard signing format (EIP-712) so signers sign **exactly this instruction**.

### Step 4: Signers approve (off-chain)

- A **quorum of authorized signers** (e.g. 3 of 5) must sign the Mint Authorization. One of them must be from a **Compliance** category. No single signer can approve alone.
- Signers are expected to sign only when the Rulebook and good-funds rules are satisfied. Their keys are kept secure (e.g. HSM).

### Step 5: Relayer submits on-chain

- A **relayer** (script or service) sends the **signed Mint Authorization + signatures** to the **Settlement Router** contract on Chain 138.

### Step 6: Router validates and records (on-chain)

- The **Settlement Router**:
  - Checks **signatures** (correct hash, valid signers).
  - Checks **quorum and categories** (enough signers, including Compliance).
  - Ensures **message ID** has never been used (no replay).
  - Checks **time window** and **chain/contract**.
  - Checks **policy** (per-message caps, corridor limits).
  - Confirms **recipients** are approved participant wallets.
- If anything fails, the transaction reverts. If all pass, the Router **records** the settlement and calls the **Mint Controller**.

### Step 7: Mint (on-chain)

- The **Mint Controller** is the **only** contract allowed to mint GRU. It accepts instructions **only** from the Settlement Router.
- It mints the agreed amounts to the recipient addresses. **SettlementRecorded** and **MintExecuted** events are emitted for audit and reporting.

### Step 8: Audit trail

- Every settlement is tied on-chain to:
  - **Message ID** (links to the original instruction).
  - **Accounting reference** (links to the ledger posting).
  - **Evidence hash** (links to the off-chain evidence bundle).
- These anchors support regulatory and internal audit.

---

## 3. The Main Pieces (Simple Map)

| Piece | Where | Role in simple terms |
|-------|--------|------------------------|
| **ISO Gateway** | Off-chain | Receives messages, runs compliance, does ledger posting, builds the Mint Authorization, asks signers to sign. |
| **Signers** | Off-chain | Authorized people/systems that sign the Mint Authorization when the Rulebook and good-funds rules are met. |
| **Relayer** | Off-chain | Submits the signed authorization to the Settlement Router (pays gas; no custody of funds). |
| **Chain 138** | Blockchain | Runs the contracts and stores immutable settlement and mint events. |
| **Participant Registry** | On-chain | List of allowed institutions and their approved wallets (only those can receive GRU). |
| **Signer Registry** | On-chain | List of allowed signers and quorum rules (who can sign, how many, which category required). |
| **Settlement Router** | On-chain | Validates the signed Mint Authorization and policy; records settlement; calls Mint Controller. |
| **Mint Controller** | On-chain | Mints GRU only when called by the Settlement Router. |
| **Root Registry** | On-chain | Holds addresses of the other DBIS contracts (single place to find them). |

---

## 4. Conversions (Swaps) in Short

- The rail also supports **governed token conversions** (e.g. swap one token for another) via a **Conversion Router**.
- A **Swap Authorization** is built (with venue, quote, amounts, deadline), signed by the allowlisted signers (with rules for small vs large swaps), and submitted on-chain.
- The Conversion Router checks: chain, contract, deadline, **venue allowlist**, **quote-issuer allowlist**, **stablecoin status**, and **blocklist**. Only then is the conversion treated as authorized; execution (e.g. DEX swap) is done so that the outcome meets the signed minimum output.
- **Stablecoin policy** defines which tokens count as canonical stablecoins and how they are monitored; the Conversion Router can enforce that only active, compliant ones are used.

---

## 5. Safety and Controls (Plain Language)

- **No single point of approval**  
  Mint and swap authorizations need a **quorum** of signers, with **Compliance** required for mints (and for large swaps where configured).

- **Replay protection**  
  Each message ID can be used **once**. Reusing it is rejected.

- **Time-bound**  
  Every authorization has a validity window; expired or not-yet-valid submissions are rejected.

- **Chain and contract binding**  
  Signatures are tied to Chain 138 and to the correct contract address. Wrong chain or wrong contract → invalid.

- **Only the Router can trigger mint**  
  GRU is minted **only** via the Mint Controller when the Settlement Router calls it. Other mint paths (e.g. owner mint) are removed or revoked.

- **Pause**  
  Authorized roles can **pause** the Settlement Router (and related components) to stop new settlements in an emergency.

- **Participant and signer allowlists**  
  Only registered participants’ wallets can receive GRU; only registered signers’ signatures count. Signers can be revoked; procedures cover key compromise and in-flight authorizations.

- **Caps and corridors**  
  The Router can enforce **per-message** and **per-corridor** limits so that no single instruction or corridor exceeds policy.

- **Audit trail**  
  Settlement and mint (and conversion) produce **on-chain events** with message ID, accounting reference, evidence hash, and amounts—so every move can be traced and reported.

---

## 6. Who It’s For and What You Get

- **Banks and financial institutions** that need settlement and token minting tied to **real messages, ledger, and compliance**, with **multi-party sign-off** and a clear audit trail.
- **Operators** who run the ISO Gateway, signer set, and relayer—with a **Rulebook** and **runbooks** for good funds, finality, reversals, and incidents.
- **Regulators and auditors** who need to see **who can sign**, **how** finality is decided (off-chain), **how** the chain enforces authorization and policy, and **how** each settlement links to message, ledger, and evidence.

**In one sentence:**  
The DBIS Rail turns **compliant, ledger-anchored banking instructions** into **on-chain settlements and GRU mints** that are **multi-signer authorized, replay-proof, and fully auditable**, while leaving **finality of “real money”** in the regulated domain.

---

## Document info

| Field | Value |
|-------|--------|
| Title | DBIS Rail — End-to-End White Paper (Simple Terms) |
| Network | DBIS Mainnet (Chain 138) |
| Audience | General technical and business readers |
| Companion docs | Technical Spec v1, Rulebook v1, Regulator Brief v1, ISO Gateway & Relayer Spec |