# DBIS Volume IV Documentation

This directory contains documentation for DBIS Expansion Volume IV: Global Derivatives, Sovereign Capital Markets, Quantum Wallet Standards, and Settlement Law Codebook.

## Modules

### 1. Global Derivatives Settlement Layer (GDSL)
- **Location**: `src/core/derivatives/gdsl/`
- **Services**: `gdsl-clearing.service.ts`, `gdsl-margin.service.ts`, `gdsl-settlement.service.ts`, `gdsl-contract.service.ts`
- **API Routes**: `/api/derivatives/gdsl`
- **Documentation**: [gdsl.md](./README.md)

### 2. Inter-SCB Bond Issuance Network (IBIN)
- **Location**: `src/core/securities/ibin/`
- **Services**: `ibin-issuance.service.ts`, `ibin-matching.service.ts`, `ibin-settlement.service.ts`, `ibin-coupon.service.ts`
- **API Routes**: `/api/securities/ibin`
- **Documentation**: [ibin.md](./ibin.md)

### 3. Digital Sovereign Debt Market (DSDM)
- **Location**: `src/core/securities/dsdm/`
- **Services**: `dsdm-market.service.ts`, `dsdm-ladder.service.ts`, `dsdm-pmo.service.ts`, `dsdm-compliance.service.ts`
- **API Routes**: `/api/securities/dsdm`
- **Documentation**: [dsdm.md](./README.md)

### 4. Quantum-Safe CBDC Wallet Standards
- **Location**: `src/core/cbdc/wallet-quantum/`
- **Services**: `quantum-wallet.service.ts`, `wallet-attestation.service.ts`, `quantum-capsule.service.ts`, `wallet-risk.service.ts`
- **API Routes**: `/api/cbdc/quantum-wallet`
- **Documentation**: [quantum-wallet.md](./quantum-wallet.md)

### 5. DBIS Settlement Law Codebook
- **Location**: `src/core/governance/settlement-law/`
- **Services**: `settlement-law.service.ts`, `settlement-finality.service.ts`, `settlement-dispute.service.ts`, `settlement-arbitration.service.ts`
- **API Routes**: `/api/governance/settlement-law`
- **Documentation**: [settlement-law.md](./README.md)

### 6. Sovereign Stablecoin Compliance Framework
- **Location**: `src/core/compliance/stablecoin/`
- **Services**: `stablecoin-compliance.service.ts`, `stablecoin-reserves.service.ts`, `stablecoin-audit.service.ts`, `stablecoin-proof.service.ts`
- **API Routes**: `/api/compliance/stablecoin`
- **Documentation**: [stablecoin.md](./README.md)

### 7. Multi-Asset Collateralization Engine (MACE)
- **Location**: `src/core/collateral/mace/`
- **Services**: `mace-allocation.service.ts`, `mace-optimization.service.ts`, `mace-valuation.service.ts`, `mace-monitoring.service.ts`
- **API Routes**: `/api/collateral/mace`
- **Documentation**: [mace.md](./README.md)

### 8. Global DeFi-Integrated Sovereign Layer
- **Location**: `src/core/defi/sovereign/`
- **Services**: `defi-module.service.ts`, `defi-node.service.ts`, `defi-pool.service.ts`, `defi-swap.service.ts`
- **API Routes**: `/api/defi/sovereign`
- **Documentation**: [defi-sovereign.md](./README.md)

## Database Schema

All Volume IV models are defined in `prisma/schema.prisma`. Key models include:

- **GDSL**: `DerivativeContract`, `DerivativeMargin`, `DerivativeSettlement`, `DerivativeCollateral`
- **IBIN**: `DigitalBond`, `BondOrderBook`, `BondTrade`, `BondCouponPayment`
- **DSDM**: `SovereignDebtInstrument`, `DebtLadder`, `DebtRollover`, `PublicMarketOperation`
- **Quantum Wallets**: `QuantumWallet`, `WalletAttestationObject`, `QuantumWalletCapsule`, `WalletRiskScore`
- **Settlement Law**: `SettlementLawArticle`, `SettlementFinality`, `SettlementDispute`, `SettlementArbitration`
- **Stablecoin**: `SovereignStablecoin`, `StablecoinCollateral`, `StablecoinReserve`, `StablecoinAudit`
- **MACE**: `MultiAssetCollateral`, `CollateralOptimization`, `CollateralHaircut`, `CollateralLiquidity`
- **DeFi**: `DeFiModule`, `DeFiNode`, `DeFiLiquidityPool`, `DeFiSwap`

## Integration

Volume IV modules integrate with existing DBIS core services:

- **GDSL ↔ SRI**: Margin calculations use SRI for risk factors (IM = exposure * volatility * SRI_factor)
- **IBIN ↔ GSS**: Bond settlement uses GSS dual-ledger architecture
- **Quantum Wallets ↔ CIM**: Wallet identity integrates with CIM identity mapping
- **MACE ↔ Collateral Sub-Ledger**: Extends existing collateral infrastructure
- **Settlement Law ↔ Constitution**: Articles reference constitutional mandates
- **DeFi ↔ Smart Contracts**: Uses existing contract fabric

## Key Features

### GDSL
- Central clearing of sovereign and multi-asset derivatives
- Real-time margining across 33 SCBs
- Quantum-secure smart contract execution
- Multi-asset collateralization (fiat, CBDC, commodity, security)

### IBIN
- Digital sovereign bonds with HSM-signed signatures
- Distributed sovereign matching engine
- Real-time settlement of bond trades
- Cross-border CBDC coupon payments

### DSDM
- Instant issuance with transparent settlement
- Maturity laddering and automated rollovers
- CBDC-funded debt refinancing
- DBIS risk controls enforcement

### Quantum Wallets
- PQC key management (Dilithium signatures, Kyber key exchange)
- Device attestation (12-hour cycle)
- Offline quantum CBDC capsules with double-spend prevention
- Real-time risk scoring

### Settlement Law
- Principle 1 (Finality), Principle 2 (Irrevocability), Principle 3 (Multilateral Recognition)
- Three-stage dispute resolution: bilateral → CAA review → Arbitration Tribunal
- Articles 12, 19, 27 enforcement

### Stablecoin Compliance
- Full collateralization verification
- Daily reserve snapshots
- HSM-signed audits
- Zero-knowledge collateral proofs

### MACE
- Optimal collateral allocation: argmin(haircuts + fx_cost + liquidity_weight + risk_penalty(SRI))
- Support for fiat, CBDC, commodities, securities, SSUs
- Real-time collateral monitoring

### DeFi Sovereign Layer
- Permissioned DeFi modules
- Sovereign-verified nodes
- DBIS-governed liquidity pools
- Multi-asset swaps with SCB oversight

## API Documentation

Full API documentation is available via Swagger UI at `/api-docs` when the server is running.