dbis_core/docs/flows/gss-settlement-flow.md

GSS Settlement Flow

Overview

The Global Settlement System (GSS) implements a four-layer architecture for sovereign-grade settlement: Layer 1 (Sovereign), Layer 2 (DBIS Master), Layer 3 (Smart Clearing Fabric), and Layer 4 (Finality & Irreversibility). This flow documents the dual-ledger synchronization process.

Prerequisites

• Source and destination banks are registered SCBs
• Valid sovereign settlement node (SSN) configuration
• Source and destination accounts exist
• Sufficient balance in source account
• Sovereign signature available (if required)

Visual Flow Diagram

┌─────────────┐
│ Settlement  │
│  Request    │
└──────┬──────┘
       │
       │ 1. Settlement Entry
       ▼
┌─────────────────────────┐
│ Layer 1: Sovereign      │
│ Ledger Posting          │
│  - Account lookup        │
│  - Debit/Credit entries  │
│  - Generate hash         │
└──────┬──────────────────┘
       │
       │ 2. Sovereign Hash
       ▼
┌─────────────────────────┐
│ Layer 2: DBIS Master    │
│ Ledger Posting          │
│  - Master ledger entry  │
│  - Generate hash         │
└──────┬──────────────────┘
       │
       │ 3. DBIS Hash
       ▼
┌─────────────────────────┐
│ Layer 3: Signature      │
│ Validation (if provided) │
│  - HSM verification      │
│  - Identity check        │
└──────┬──────────────────┘
       │
       │ 4. Validated
       ▼
┌─────────────────────────┐
│ Layer 4: Master Entry   │
│ Creation                 │
│  - Dual-ledger commit   │
│  - Status: settled       │
└──────┬──────────────────┘
       │
       │ 5. Finality
       ▼
┌─────────────┐
│ Settlement  │
│  Complete   │
└─────────────┘

Step-by-Step Process

Step 1: Settlement Entry Creation

1. Receive settlement request with:
   • Source bank ID
   • Destination bank ID
   • Amount and currency
   • Asset type
   • Optional sovereign signature
2. Generate unique entry ID: GSS-ENTRY-{uuid}
3. Validate node configuration for source bank
4. Verify both banks are active SCBs

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:35-38

Step 2: Layer 1 - Sovereign Ledger Posting

1. Lookup source accounts:
   • Filter by sovereign bank ID
   • Match currency code and asset type
   • Select active account
2. Lookup destination accounts:
   • Filter by sovereign bank ID
   • Match currency code and asset type
   • Select active account
3. Post double-entry to sovereign ledger:
   • Debit source account
   • Credit destination account
   • Use ledger ID: Sovereign_{sourceBankId}
   • Transaction type: Type_A
4. Retrieve ledger entry and extract block hash
5. Store sovereign ledger hash

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:101-150

Step 3: Layer 2 - DBIS Master Ledger Posting

1. Lookup source accounts (same as Step 2)
2. Lookup destination accounts (same as Step 2)
3. Post double-entry to DBIS master ledger:
   • Debit source account
   • Credit destination account
   • Use ledger ID: Master
   • Transaction type: Type_A
   • Metadata: { gssEntry: true, masterLedger: true }
4. Retrieve ledger entry and extract block hash
5. Store DBIS ledger hash

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:155-203

Step 4: Layer 3 - Sovereign Signature Validation (if provided)

1. Check if sovereign signature is provided
2. If provided:
   • Lookup sovereign identity by bank ID
   • Verify identity type is 'Settlement'
   • Validate signature using HSM (in production)
   • Verify signature matches entry data
3. If validation fails, throw error and rollback

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:208-232

Step 5: Layer 4 - Master Entry Creation & Finality

1. Create GSS master ledger entry with:
   • Entry ID
   • Node ID
   • Source and destination bank IDs
   • Amount, currency, asset type
   • Sovereign signature (if provided)
   • Dual-ledger commit flag: true
   • Sovereign ledger hash
   • DBIS ledger hash
   • Status: settled
   • Committed and settled timestamps
2. Verify dual-ledger synchronization:
   • Both hashes exist
   • Both ledger entries exist
   • Dual-commit flag is true
3. Return dual-ledger result

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:52-77

Step 6: Error Handling (if any step fails)

1. If error occurs after Step 1:
   • Create failed entry record
   • Set dual-ledger commit: false
   • Set status: failed
   • Log error details
2. Rollback any partial ledger entries
3. Throw error to caller

Code Reference: src/core/settlement/gss/gss-master-ledger.service.ts:78-95

Error Handling

Error: Accounts Not Found

• Detection: Account lookup returns empty array
• Action: Throw error "Accounts not found for sovereign ledger posting"
• Recovery: Verify account configuration, retry with correct parameters

Error: Sovereign Signature Invalid

• Detection: Signature validation fails
• Action: Throw error "Sovereign identity not found" or "Signature invalid"
• Recovery: Request new signature, verify HSM configuration

Error: Dual-Ledger Mismatch

• Detection: Hashes don't match or entries missing
• Action: Mark entry as failed, create reconciliation record
• Recovery: Manual reconciliation process, verify ledger integrity

Error: Node Configuration Missing

• Detection: SSN not configured for source bank
• Action: Return error, prevent settlement
• Recovery: Configure SSN, retry settlement

Integration Points

Related Services

• GSS Master Ledger Service: src/core/settlement/gss/gss-master-ledger.service.ts
• Ledger Service: src/core/ledger/ledger.service.ts
• Account Service: src/core/accounts/account.service.ts
• GSS Architecture Service: src/core/settlement/gss/gss-architecture.service.ts

API Endpoints

• POST /api/v1/gss/settlement/execute - Execute GSS settlement
• GET /api/v1/gss/master-ledger/entries - Query master ledger entries
• GET /api/v1/gss/master-ledger/entries/:entryId - Get specific entry
• POST /api/v1/gss/master-ledger/verify - Verify dual-ledger sync

Database Models

• GssMasterLedger - Master ledger entries
• SovereignSettlementNode - SSN configuration
• LedgerEntry - Individual ledger entries

Performance Metrics

• Layer 1 (Sovereign Posting): < 100ms target
• Layer 2 (DBIS Posting): < 100ms target
• Layer 3 (Signature Validation): < 50ms target (if required)
• Layer 4 (Master Entry): < 50ms target
• Total End-to-End: < 300ms target
• Throughput: 5,000+ settlements/second
• Availability: 99.99% uptime target

Security Considerations

Authentication

• Sovereign bank must be registered and active
• Node ID must match configured SSN

Authorization

• Source bank must have settlement permissions
• Accounts must be active and accessible

Data Integrity

• Dual-ledger commit ensures consistency
• Hash verification prevents tampering
• Sovereign signatures provide non-repudiation

Audit Trail

• All entries logged with timestamps
• Dual-ledger hashes provide proof
• Failed entries tracked for reconciliation

Testing Scenarios

Happy Path

1. Valid settlement request
2. Successful sovereign ledger posting
3. Successful DBIS master ledger posting
4. Valid sovereign signature (if provided)
5. Successful master entry creation
6. Dual-ledger verification passes

Error Scenarios

1. Accounts not found
2. Sovereign signature invalid
3. Dual-ledger mismatch
4. Node configuration missing
5. Network timeout during posting

Edge Cases

1. Concurrent settlements to same account
2. Maximum settlement amount
3. Settlement with missing signature
4. Settlement during ledger maintenance
5. Cross-currency settlements

---

Related Flows:

• GPN Payment Flow
• Atomic Settlement Flow
• M-RTGS Settlement Flow