Initial commit

docs/volume-iv/README.md

@@ -0,0 +1,130 @@
+# 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](./gdsl.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](./dsdm.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](./settlement-law.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](./stablecoin.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](./mace.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](./defi-sovereign.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.
+