dbis_core/docs/flows/cbdc-mint-burn-flow.md

# CBDC Mint Burn Flow

## Overview

CBDC minting and burning operations ensure 1:1 reserve backing for all CBDC issuance. This flow documents the complete process from reserve verification through ledger posting for both minting (issuance) and burning (redemption) operations.

## Prerequisites

- Sovereign bank is registered and active
- Treasury account exists for the sovereign bank
- Reserve account has sufficient balance (for minting)
- Valid operator identity
- CBDC service operational

## Visual Flow Diagram

### Minting Flow

```
┌─────────────┐
│ Mint Request│
└──────┬──────┘
       │
       │ 1. Verify Reserve
       ▼
┌─────────────────────────┐
│ Verify 1:1 Reserve       │
│  Backing                 │
│  - Check reserve balance │
│  - Verify >= mint amount │
└──────┬──────────────────┘
       │
       │ 2. Reserve OK
       ▼
┌─────────────────────────┐
│ Create Issuance Record  │
│  - Record ID            │
│  - Amount minted         │
│  - Operator identity     │
│  - Reserve backing       │
└──────┬──────────────────┘
       │
       │ 3. Post to Ledger
       ▼
┌─────────────────────────┐
│ Ledger Posting          │
│  - Debit: Treasury       │
│  - Credit: CBDC wallet   │
│  - Type: TYPE_B          │
└──────┬──────────────────┘
       │
       │ 4. Complete
       ▼
┌─────────────┐
│ CBDC Minted │
└─────────────┘
```

### Burning Flow

```
┌─────────────┐
│ Burn Request│
└──────┬──────┘
       │
       │ 1. Create Record
       ▼
┌─────────────────────────┐
│ Create Issuance Record  │
│  - Record ID            │
│  - Amount burned        │
│  - Operator identity     │
└──────┬──────────────────┘
       │
       │ 2. Post to Ledger
       ▼
┌─────────────────────────┐
│ Ledger Posting          │
│  - Debit: CBDC wallet    │
│  - Credit: Treasury      │
│  - Type: TYPE_B          │
└──────┬──────────────────┘
       │
       │ 3. Release Reserve
       ▼
┌─────────────┐
│ CBDC Burned │
└─────────────┘
```

## Step-by-Step Process

### Minting Process

#### Step 1: Reserve Verification
1. Receive mint request with:
   - Sovereign bank ID
   - Wallet ID (optional)
   - Amount to mint
   - Operator identity
   - Reason (optional)
2. Get treasury account for sovereign bank:
   - Lookup accounts by sovereign bank ID
   - Filter by account type: `treasury`
   - Filter by currency: `OMF` (reserve currency)
3. Check reserve balance:
   - Get current balance
   - Compare with mint amount
   - Verify: `reserveBalance >= mintAmount`
4. If insufficient reserve, throw error: "Insufficient reserve backing for CBDC minting"

**Code Reference**: `src/core/cbdc/cbdc.service.ts:22-136`

#### Step 2: Create Issuance Record
1. Generate unique record ID: `CBDC-MINT-{uuid}`
2. Create CBDC issuance record:
   - Record ID
   - Sovereign bank ID
   - Wallet ID (if provided)
   - Amount minted: `amount`
   - Amount burned: `0`
   - Net change: `amount`
   - Operation type: `MINT`
   - Operator identity
   - Reserve backing: `amount` (1:1 backing)
   - Timestamp: current UTC time
   - Metadata: reason if provided
3. Store record in database

**Code Reference**: `src/core/cbdc/cbdc.service.ts:38-52`

#### Step 3: Ledger Posting
1. Get treasury account (same as Step 1)
2. Determine ledger ID: `{sovereignBankId}-CBDC`
3. Post double-entry to ledger:
   - Debit account: Treasury account ID
   - Credit account: Treasury account ID (simplified - in production would be CBDC wallet)
   - Amount: `amount`
   - Currency: `OMDC` (CBDC currency code)
   - Asset type: `CBDC`
   - Entry type: `TYPE_B` (CBDC issuance)
   - Reference ID: record ID
   - Metadata: `{ operationType: 'mint', walletId, reason }`
4. Verify ledger entry created successfully

**Code Reference**: `src/core/cbdc/cbdc.service.ts:54-67`

#### Step 4: Return Result
1. Map issuance record to CbdcIssuance type
2. Return issuance details:
   - Record ID
   - Amount minted
   - Reserve backing
   - Timestamp

**Code Reference**: `src/core/cbdc/cbdc.service.ts:69`

### Burning Process

#### Step 1: Create Issuance Record
1. Receive burn request with:
   - Sovereign bank ID
   - Wallet ID (optional)
   - Amount to burn
   - Operator identity
   - Reason (optional)
2. Generate unique record ID: `CBDC-BURN-{uuid}`
3. Create CBDC issuance record:
   - Record ID
   - Sovereign bank ID
   - Wallet ID (if provided)
   - Amount minted: `0`
   - Amount burned: `amount`
   - Net change: `-amount` (negative)
   - Operation type: `BURN`
   - Operator identity
   - Timestamp: current UTC time
   - Metadata: reason if provided
4. Store record in database

**Code Reference**: `src/core/cbdc/cbdc.service.ts:75-101`

#### Step 2: Ledger Posting
1. Get treasury account for sovereign bank
2. Determine ledger ID: `{sovereignBankId}-CBDC`
3. Post double-entry to ledger:
   - Debit account: Treasury account ID (CBDC wallet - simplified)
   - Credit account: Treasury account ID (Treasury - simplified)
   - Amount: `amount`
   - Currency: `OMDC`
   - Asset type: `CBDC`
   - Entry type: `TYPE_B` (CBDC redemption)
   - Reference ID: record ID
   - Metadata: `{ operationType: 'burn', walletId, reason }`
4. Verify ledger entry created successfully

**Code Reference**: `src/core/cbdc/cbdc.service.ts:103-116`

#### Step 3: Return Result
1. Map issuance record to CbdcIssuance type
2. Return issuance details:
   - Record ID
   - Amount burned
   - Net change
   - Timestamp

**Code Reference**: `src/core/cbdc/cbdc.service.ts:118`

## Error Handling

### Error: Insufficient Reserve Backing
- **Detection**: Reserve balance < mint amount
- **Action**: Throw error "Insufficient reserve backing for CBDC minting"
- **Recovery**: Add reserves, retry minting

### Error: Treasury Account Not Found
- **Detection**: No treasury account found
- **Action**: Throw error "Treasury account not found"
- **Recovery**: Create treasury account, retry

### Error: Ledger Posting Failure
- **Detection**: Ledger service returns error
- **Action**: Rollback issuance record, throw error
- **Recovery**: Verify ledger service, retry

### Error: Invalid Amount
- **Detection**: Amount <= 0
- **Action**: Throw validation error
- **Recovery**: Correct amount, retry

## Integration Points

### Related Services
- **CBDC Service**: `src/core/cbdc/cbdc.service.ts`
- **Account Service**: `src/core/accounts/account.service.ts`
- **Ledger Service**: `src/core/ledger/ledger.service.ts`
- **CBDC Wallet Service**: `src/core/cbdc/cbdc-wallet.service.ts`

### API Endpoints
- `POST /api/v1/cbdc/mint` - Mint CBDC
- `POST /api/v1/cbdc/burn` - Burn CBDC
- `GET /api/v1/cbdc/issuance/:recordId` - Get issuance record

### Database Models
- `CbdcIssuance` - CBDC issuance records
- `CbdcWallet` - CBDC wallet records
- `BankAccount` - Treasury accounts

## Performance Metrics

- **Reserve Verification**: < 20ms target
- **Record Creation**: < 10ms target
- **Ledger Posting**: < 50ms target
- **Total End-to-End**: < 80ms target
- **Throughput**: 5,000+ operations/second
- **Availability**: 99.99% uptime target

## Security Considerations

### Reserve Backing
- 1:1 reserve backing enforced
- Reserve balance checked before minting
- Reserve backing recorded in issuance record

### Operator Identity
- Operator identity required for all operations
- Identity logged in issuance record
- Audit trail for all mint/burn operations

### Authorization
- Only authorized operators can mint/burn
- Sovereign bank must be active
- Treasury account must exist

## Testing Scenarios

### Happy Path - Minting
1. Valid mint request
2. Sufficient reserve balance
3. Successful record creation
4. Successful ledger posting
5. CBDC minted

### Happy Path - Burning
1. Valid burn request
2. Successful record creation
3. Successful ledger posting
4. CBDC burned

### Error Scenarios
1. Insufficient reserve backing
2. Treasury account not found
3. Ledger posting failure
4. Invalid amount
5. Invalid operator identity

### Edge Cases
1. Maximum mint amount
2. Minimum mint amount
3. Mint with zero amount (should fail)
4. Burn more than available
5. Concurrent mint/burn operations

---

**Related Flows**:
- [CBDC Wallet Transfer Flow](./cbdc-wallet-transfer-flow.md)
- [CBDC Interoperability Flow](./cbdc-interoperability-flow.md)
- [GSS Settlement Flow](./gss-settlement-flow.md)