e4c9dda0fd
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
159 lines
9.2 KiB
Markdown
159 lines
9.2 KiB
Markdown
# 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 |
|