# Cross-Chain Settlement Flow

## Overview

Cross-chain settlement enables atomic swaps across multiple ledger types (sovereign, CBDC, commodity, security token chains). This flow documents the complete process from commitment creation through atomic swap execution.

## Prerequisites

- Source and destination chains are registered
- Valid cross-chain settlement request
- Sufficient balance/position in source chain
- Cross-chain contract service operational

## Visual Flow Diagram

```
┌─────────────┐
│ Settlement  │
│  Request    │
└──────┬──────┘
       │
       │ 1. Create Settlement Record
       ▼
┌─────────────────────────┐
│ Create Settlement Record│
│  - Settlement ID         │
│  - Chain types & IDs     │
│  - Amount & asset type   │
└──────┬──────────────────┘
       │
       │ 2. Create Commitments
       ▼
┌─────────────────────────┐
│ Create Cross-Chain      │
│  Commitments             │
│  - Source commitment     │
│  - Target commitment     │
└──────┬──────────────────┘
       │
       │ 3. Execute Atomic Swap
       ▼
┌─────────────────────────┐
│ Execute Atomic Swap     │
│  - Verify commitments    │
│  - Execute on both chains│
│  - Verify success        │
└──────┬──────────────────┘
       │
       │ 4. Update Status
       ▼
┌─────────────┐
│ Settlement  │
│  Complete   │
└─────────────┘
```

## Step-by-Step Process

### Step 1: Create Settlement Record
1. Receive cross-chain settlement request
2. Generate settlement ID: `CCS-{uuid}`
3. Create settlement record with source/target chain details
4. Set status: `pending`

**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:29-48`

### Step 2: Create Commitments
1. Create commitments for both chains
2. Store commitment hashes
3. Link to settlement record

**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:85-124`

### Step 3: Execute Atomic Swap
1. Call cross-chain contract service
2. Verify both commitments
3. Execute swap on both chains atomically
4. Verify execution success

**Code Reference**: `src/core/settlement/cross-chain/cross-chain-contract.service.ts`

### Step 4: Update Status
1. If successful: Set status `settled`
2. If failed: Set status `failed`
3. Record completion timestamp

**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:60-79`

## Error Handling

- Commitment creation failure: Rollback, return error
- Atomic swap failure: Rollback both chains, mark failed
- Verification failure: Mark failed, create reconciliation record

## Integration Points

- Cross-Chain Settlement Service: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts`
- Cross-Chain Contract Service: `src/core/settlement/cross-chain/cross-chain-contract.service.ts`
- Atomic Settlement Service: `src/core/settlement/isn/atomic-settlement.service.ts`

## Performance Metrics

- Total End-to-End: < 200ms target
- Throughput: 5,000+ settlements/second

## Security Considerations

- Atomic execution ensures both chains update or neither
- Commitment verification prevents tampering
- Hash verification ensures integrity

---

**Related Flows**:
- [Atomic Settlement Flow](./atomic-settlement-flow.md)
- [GSS Settlement Flow](./gss-settlement-flow.md)