proxmox/docs/dbis-rail/DBIS_RAIL_TECHNICAL_SPEC_V1.md

DBIS Rail Technical Spec v1

Network: DBIS Mainnet (ChainID 138) Purpose: Bank-rail settlement + GRU mint orchestration using ISO-20022–anchored authorizations.

0. Scope and Non-Goals

In-scope

• A standardized message-to-settlement lifecycle rooted in ISO-20022 evidence, but executed as compact on-chain authorizations.

• On-chain contracts that:

  • enforce participant allowlisting
  • validate threshold signer authorization
  • provide replay protection
  • record immutable settlement + accounting references
  • gate GRU minting so it is only possible after compliant authorization

Out-of-scope (v1)

• On-chain parsing of ISO-20022 XML/JSON payloads.
• ZK proofs or light-client proofs of bank-rail events.
• Fully automated validator rotation on-chain (documented operationally for v1).

---

1. Definitions

Terms

• FI: Financial Institution participant on the DBIS rail (bank, MSB, custodian, trustee, operator).

• ISO Gateway: Off-chain service that ingests ISO-20022 messages, runs compliance + accounting, and produces signed on-chain authorizations.

• Mint Authorization (MintAuth): A compact signed instruction authorizing settlement recording and GRU minting.

• Funds Status:

  • ON_LEDGER_FINAL: funds final in DBIS-controlled ledger domain (core/omnibus/segregated reserve).
  • OFF_LEDGER_FINAL: funds final via external rail + reconciliation per DBIS policy.

• Accounting Reference (accountingRef): Immutable identifier for the journal/batch/posting in DBIS ledger domain.

Design principle

The chain never "decides" fiat finality. Fiat finality, compliance, and accounting occur in the regulated domain; the chain enforces authorization integrity and policy.

---

2. System Overview

2.1 Contract set (v1)

1. DBIS_RootRegistry
2. DBIS_ParticipantRegistry
3. DBIS_SignerRegistry
4. DBIS_SettlementRouter
5. DBIS_GRU_MintController

Note: Existing registries (e.g., UniversalAssetRegistry, ChainRegistry, GRU Diamond facets) remain valid. v1 adds DBIS Rail components in a way that can "wrap" or "gate" existing mint paths.

2.2 Roles

• ROOT_ADMIN: owns RootRegistry configuration.
• PARTICIPANT_ADMIN: can onboard/update participants.
• SIGNER_ADMIN: manages signer allowlist and quorum rules.
• ROUTER_ADMIN: can pause router, update policy caps.
• MINTER: only DBIS_SettlementRouter (for GRU mint execution).

---

3. Network and Governance Baseline (Chain 138)

3.1 Consensus

• Besu QBFT (permissioned) with ~2s block time, epoch ~30k blocks (document actual values used in current deployment).
• Node allowlists enforced by Besu permissioning config (permissions-nodes-config-file, permissions-accounts-config-file).

3.2 Governance in v1

• Validator management remains operational + infra-managed for v1.
• Contract governance uses a multisig or your GovernanceController/timelock pattern for admin roles.

---

4. Data Model

4.1 Participant

Participant represents an FI / operator entity allowed to initiate or receive settlement/mint instructions.

Participant fields

• participantId: bytes32 (stable ID, e.g., hash of legal name + jurisdiction)
• legalName: string
• jurisdiction: string
• entityType: enum (BANK, MSB, CUSTODIAN, TRUSTEE, OPERATOR, AUDITOR)
• status: enum (ACTIVE, SUSPENDED, REVOKED)
• policyTags: bytes32[] (corridors, product permissions)
• operationalWallets: address[] (approved wallets for receipts/payouts)
• signingKeys: address[] (if participant is also a signer entity)

4.2 Mint Authorization (MintAuth)

MintAuth is a compact, deterministic struct signed by an allowlisted signer set.

enum FundsStatus { ON_LEDGER_FINAL, OFF_LEDGER_FINAL }
enum AssetClass { GRU_M00, GRU_M0, GRU_M1 } // optional mapping; v1 can use GRU_M00 only

struct MintAuth {
  // Identity / Evidence
  bytes32 messageId;        // unique; derived from UETR/EndToEndId/instructionId
  bytes32 isoType;          // e.g., keccak256("pacs.008"), keccak256("camt.054")
  bytes32 isoHash;          // hash of canonical ISO payload bundle (off-chain)
  bytes32 accountingRef;    // journal/batch/posting reference in DBIS ledger domain
  FundsStatus fundsStatus;  // ON_LEDGER_FINAL or OFF_LEDGER_FINAL

  // Settlement intent
  bytes32 corridor;         // optional (e.g., USD->XAU->GRU, internal corridor tag)
  AssetClass assetClass;    // GRU tier/class
  address[] recipients;     // 1..N
  uint256[] amounts;        // matched length, base units

  // Policy & replay window
  uint64 notBefore;         // unix seconds
  uint64 expiresAt;         // unix seconds

  // Domain separation
  uint256 chainId;          // MUST be 138
  address verifyingContract;// SettlementRouter address
}

Rules

• recipients.length == amounts.length
• expiresAt > notBefore
• chainId == 138
• verifyingContract == address(DBIS_SettlementRouter)
• messageId must be unique (replay protection)

---

5. Message Lifecycle

5.1 Off-chain (ISO Gateway) steps

1. Ingest ISO-20022 message(s) and evidence:

   • pacs / camt / pain family as applicable
   • cash receipt evidence for M0 if used

2. Canonicalize and compute:

   • isoHash = hash(canonical_bundle)
   • messageId = deterministicUniqueId(...)
   • isoType = keccak256(typeString)

3. Determine funds status:

   • ON_LEDGER_FINAL: final posting in DBIS ledger domain
   • OFF_LEDGER_FINAL: external finality + reconciliation

4. Perform required double-entry accounting:

   • must produce accountingRef

5. Run compliance gates:

   • KYC, sanctions, AML rules, limits, exception flags

6. Emit MintAuth and obtain threshold signatures from allowlisted signers.

7. Relayer submits to chain calling submitMintAuth(MintAuth, signatures).

5.2 On-chain steps (SettlementRouter)

1. Verify signatures meet quorum for the corridor/product/participant class.
2. Check time window + chainId + verifyingContract.
3. Enforce replay protection.
4. Enforce router policy caps.
5. Record settlement.
6. Call GRU mint controller to mint to recipients.
7. Emit events for audit.

---

6. Contract Specifications

6.1 DBIS_RootRegistry

Purpose: Single source of truth for DBIS rail component addresses + versioning.

State

• address participantRegistry
• address signerRegistry
• address settlementRouter
• address gruMintController
• string railVersion (e.g., "v1")

Functions

• setComponent(bytes32 key, address addr) (admin)
• getComponent(bytes32 key) returns (address)

Events

• ComponentUpdated(bytes32 indexed key, address indexed addr, string railVersion)

---

6.2 DBIS_ParticipantRegistry

Purpose: Institution onboarding + wallet bindings + policy tags.

Functions

• registerParticipant(Participant calldata p) (admin)
• setParticipantStatus(bytes32 participantId, Status s) (admin)
• addOperationalWallet(bytes32 participantId, address wallet) (admin)
• removeOperationalWallet(bytes32 participantId, address wallet) (admin)
• isOperationalWallet(address wallet) returns (bool)
• getParticipantByWallet(address wallet) returns (bytes32 participantId)

Events

• ParticipantRegistered(bytes32 indexed participantId, string legalName, string jurisdiction, uint8 entityType)
• ParticipantStatusChanged(bytes32 indexed participantId, uint8 status)
• OperationalWalletAdded(bytes32 indexed participantId, address wallet)
• OperationalWalletRemoved(bytes32 indexed participantId, address wallet)

---

6.3 DBIS_SignerRegistry

Purpose: Maintain signer allowlist + roles + quorum policy.

Signer model (v1)

• Allowlisted signer addresses with categories:

  • OPS
  • COMPLIANCE
  • CUSTODY
  • RISK
  • AUDITOR (optional but recommended)

Quorum (default v1)

• requiredSignatures = 3

• requiredCategories: must include at least:

  • COMPLIANCE (mandatory)
  • and any 2 of OPS/CUSTODY/RISK/AUDITOR

Functions

• addSigner(address signer, uint8 category) (admin)
• removeSigner(address signer) (admin)
• setQuorum(uint8 requiredSigs, uint256 categoryMaskRequired, uint256 categoryMaskAllowed) (admin)
• isSigner(address signer) returns (bool)
• validateSigners(address[] signers) returns (bool ok, string reason) (view)

Events

• SignerAdded(address indexed signer, uint8 category)
• SignerRemoved(address indexed signer)
• QuorumUpdated(uint8 requiredSigs, uint256 requiredMask, uint256 allowedMask)

---

6.4 DBIS_SettlementRouter

Purpose: Verify MintAuth signatures, enforce rail policy, record settlement, and trigger GRU mint.

State

• RootRegistry root

• mapping(bytes32 => bool) usedMessageIds

• policy:

  • uint256 maxAmountPerMessage
  • mapping(bytes32 corridor => uint256 corridorDailyCap)
  • mapping(bytes32 corridor => mapping(uint256 day => uint256 usedToday))

• bool paused

Core function

submitMintAuth(MintAuth calldata auth, bytes[] calldata signatures)

Validation

• paused == false

• auth.chainId == 138

• auth.verifyingContract == address(this)

• block.timestamp in [auth.notBefore, auth.expiresAt]

• !usedMessageIds[auth.messageId]

• recipients/amounts lengths match

• total amount <= maxAmountPerMessage

• ParticipantRegistry check:

  • every recipient must be an operational wallet of an ACTIVE participant OR
  • allow "unhosted wallets" only if corridor policy permits (default: hosted-only)

• Signature validation:

  • EIP-712 typed hash of MintAuth
  • recover signers from signatures
  • require unique signers
  • require signer allowlist + quorum per SignerRegistry

Effects

• mark usedMessageIds[messageId] = true
• update daily corridor usage
• record settlement data in storage (optional; events are mandatory)
• call DBIS_GRU_MintController.mintFromAuthorization(auth)

Events (audit-grade)

• SettlementRecorded(bytes32 indexed messageId, bytes32 indexed isoType, bytes32 isoHash, bytes32 accountingRef, uint8 fundsStatus, bytes32 corridor, uint8 assetClass, uint256 totalAmount)
• MintExecuted(bytes32 indexed messageId, address indexed recipient, uint256 amount, uint8 assetClass)
• MessageIdConsumed(bytes32 indexed messageId)
• RouterPaused(bool paused)

---

6.5 DBIS_GRU_MintController

Purpose: Only mint GRU when invoked by SettlementRouter with a validated MintAuth.

State

• address settlementRouter
• address gruTokenOrDiamond (depending on your GRU deployment)
• bool paused

Function

mintFromAuthorization(MintAuth calldata auth)

Rules

• msg.sender == settlementRouter
• paused == false
• mint exactly amounts[i] to recipients[i]
• emit per-recipient mint event (or rely on SettlementRouter's MintExecuted event)

Integration notes

• If GRU is minted via Diamond facets:

  • MintController should call the GRU mint facet method.

• If GRU is represented as a CompliantFiatToken (ERC-20):

  • MintController must be granted MINTER_ROLE, and all other direct mint paths must be disabled or moved behind router gating.

---

7. Signature Standard (EIP-712)

Domain

• name: "DBISSettlementRouter"
• version: "1"
• chainId: 138
• verifyingContract: DBIS_SettlementRouter

Typed data

MintAuth struct fields as defined in §4.2.

Signature set

• bytes[] signatures (each 65-byte ECDSA signature)
• address[] recoveredSigners computed on-chain
• signers must be unique and satisfy SignerRegistry quorum rules

v1 uses "multi-sig by aggregation" (array of signatures). True threshold crypto can be introduced in v2 without changing MintAuth.

---

8. Policy Controls

8.1 Default policy (recommended v1)

• Hosted wallets only (participants) unless corridor allows unhosted.
• Mandatory COMPLIANCE signer present for all authorizations.
• expiresAt maximum horizon (e.g., <= 15 minutes) to reduce replay/exfiltration risk.
• Daily corridor caps + per-message cap.

8.2 Emergency controls

• Router pause (ROUTER_ADMIN)
• Mint controller pause (ROUTER_ADMIN)
• Signer revocation (SIGNER_ADMIN)
• Participant suspension (PARTICIPANT_ADMIN)

---

9. Replay Protection and Idempotency

Replay

• messageId is consumed once. Submitting same messageId reverts.

Idempotency (optional extension)

If you want "retry safe" behavior:

• allow resubmission if exact same auth hash and messageId already consumed → return success without minting (but emit a "duplicate accepted" event). Default v1: revert on reuse.

---

10. Reporting and Audit

Required on-chain audit events

• SettlementRecorded (includes isoHash + accountingRef)
• MintExecuted per recipient (or token Transfer + SettlementRecorded)

Off-chain reporting (DBIS Rail Rulebook v1)

• Maintain mapping from messageId → ISO evidence bundle and accountingRef → ledger postings.

• Support camt-like extracts for:

  • completed settlements
  • exceptions / rejected authorizations
  • signer approvals and revocations
  • participant status changes

---

11. Backward Compatibility / Migration Plan

Immediate hardening steps (recommended)

• Identify and eliminate "owner mint" pathways for GRU/c* tokens on chain 138:

  • Either revoke direct mint permissions or route them exclusively through DBIS_GRU_MintController.

• For any existing MintController pattern:

  • adapt it so MINTER_ROLE = SettlementRouter only.
  • require MintAuth signature validation at router level.

Naming/identity alignment

• Update chain metadata artifacts so canonical identity is DBIS Mainnet (Chain 138).
• Keep a compatibility alias field if needed, but ensure DBIS is primary.

---

12. Open Items for v1 Freeze

These are the only "knobs" that change code/constants:

1. Quorum rule (3-of-5 default) and required categories.
2. Hosted-only vs allow unhosted corridors.
3. Per-message and daily caps.
4. Whether messageId reuse reverts or is idempotent.

---

Appendix A — Recommended Quorum Defaults

Signer categories: OPS, COMPLIANCE, CUSTODY, RISK, AUDITOR Default quorum: 3-of-5 Required: COMPLIANCE + any 2 of {OPS, CUSTODY, RISK, AUDITOR}

Rationale: ensures compliance sign-off and prevents single-domain control.

---

Appendix B — Minimal Event Field Set

SettlementRecorded

• messageId
• isoType
• isoHash
• accountingRef
• fundsStatus
• corridor
• assetClass
• totalAmount

MintExecuted

• messageId
• recipient
• amount
• assetClass

---

Appendix C — v1.5 Add-Ons (AAA+++)

The v1.5 add-ons extend this Spec for examiner-credible completeness. They are implemented via the following documents; only summary points are repeated here.

1. DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md — LPA state machine (POSTED_FINAL, POSTED_ADJUSTMENT, POSTED_REVERSAL, DISPUTED_HOLD), Reversal Policy Matrix (before mint: invalidate; after mint: primary offset/corridor restriction, secondary burn, tertiary debt/dispute), and mandatory signer effective/revoked block enforcement: SignerRegistry adds effectiveFromBlock and revokedAtBlock per signer; SettlementRouter validates each recovered signer is active at block.number.
2. DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md — SwapAuthorization (SwapAuth) EIP-712 struct, quorum (2-of-4 small / 3-of-5 + COMPLIANCE large), best execution and MEV posture, quote provenance (quoteHash, quoteIssuer), venue allowlist, sanctions/AML (blocklist, Compliance for elevated swaps and new venues), and ConversionExecuted event.
3. DBIS_RAIL_STABLECOIN_POLICY_V1_5.md — Canonical stablecoin definition: Stablecoin Reference Registry (tokenSymbol, tokenAddress, issuer/bridge, legalClaimType, redemptionPath, reserveDisclosureRef, riskTier, pauseAuthority, stablecoinStatus); Rulebook addendum that only ACTIVE registered stablecoins may be used for routing; monitoring (peg deviation, bridge health, emergency corridor halt).
4. DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md — LEB/LPA/ISO schemas, canonicalization rules (UTF-8 NFC, sorted keys, fixed decimal and timestamp, rounding policy), and test vectors for lebHash, lpaId, isoHash, and accountingRef so that any auditor can reproduce hashes.