defi-arbitrage/README.md

# Deal Orchestration Tool

**Freeze-Resistant, Capital-Preserving Arbitrage Loop**

A sophisticated TypeScript-based deal orchestration tool that executes freeze-resistant arbitrage loops designed to preserve capital even when individual legs fail. Built for ChainID 138 (SMOM-DBIS-138) with ETH/WETH, USDT/cUSDT, and discounted USDTz.

> **Deployment**: This module runs in **Proxmox VE** as part of the DBIS Core Banking System (API containers VMID 10150-10199). See [PROXMOX_DEPLOYMENT.md](./PROXMOX_DEPLOYMENT.md) for deployment details.

## 🎯 Quick Start

```bash
# Install dependencies (from parent workspace)
pnpm install

# Execute a deal via CLI
node cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001
```

## 📖 Documentation

For comprehensive documentation, see **[README_SUBMODULE.md](./README_SUBMODULE.md)** which includes:
- Complete architecture overview
- Detailed step-by-step loop explanation
- Risk control mechanisms
- Failure scenario handling
- API reference
- Configuration guide

## 🏗️ Architecture

```
arbitrage/
├── types.ts                      # Type definitions
├── config.ts                     # ChainID 138 configuration
├── risk-control.service.ts       # Risk validation & enforcement
├── step-execution.service.ts     # Step implementations (0-4)
├── redemption-test.service.ts    # Progressive redemption testing
├── deal-orchestrator.service.ts  # Main orchestrator
├── cli.ts                        # CLI interface
└── index.ts                      # Exports
```

## 🔒 Design Principles

1. **One-Way Risk Only**: Redemption is upside, not critical for principal recovery
2. **Anchor Asset Untouchable**: ETH/WETH (50%) never touched in risky operations
3. **No Leverage on Discounted Assets**: USDTz never borrowed against
4. **Independent Leg Settlement**: Each leg can settle independently

## 🔄 The Arbitrage Loop

### STEP 0: Capital Split
- 50% Core ETH (untouchable)
- 30% Working Liquidity
- 20% Opportunistic USDTz

### STEP 1: Generate Working Liquidity
- Wrap ETH → WETH
- Supply as collateral
- Borrow USDT at ≤30% LTV

### STEP 2: Execute Discount Arbitrage
- Buy USDTz at 40% discount
- Never pledge or bridge without testing

### STEP 3: Partial Monetization
- 35% attempt redemption
- 65% hold cold
- Progressive testing: $50k → $250k → $1M+

### STEP 4: Close the Loop
- Repay borrow
- Unlock ETH
- Capture profit

## ⚠️ Risk Controls

- **Max LTV**: 30% (hard cap)
- **Max USDTz Exposure**: <25% of total NAV
- **No Rehypothecation**: USDTz never used as collateral
- **Progressive Testing**: Redemption tested incrementally

## 💻 Usage

### CLI

```bash
node cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001 \
  --usdtzDiscount 0.40 \
  --maxLtv 0.30
```

### Programmatic

```typescript
import { dealOrchestratorService } from '@/core/defi/arbitrage';

const result = await dealOrchestratorService.executeDeal({
  totalEthValue: '10000000',
  participantBankId: 'BANK001',
  moduleId: 'MODULE001',
});

console.log('Status:', result.status);
console.log('Profit:', result.finalProfit?.toString());
```

## 🛡️ Failure Scenarios

The system gracefully handles:
- **USDTz Redemption Freezes**: ETH safe, loan healthy, USDTz held as upside
- **USDT Borrow Market Freezes**: Low LTV allows waiting, no forced unwind
- **ChainID 138 Congestion**: No cross-chain dependencies, can wait

## 📋 Requirements

- Node.js 16+
- TypeScript 5.0+
- Prisma ORM
- Winston Logger
- Decimal.js

## 🔗 Token Addresses (ChainID 138)

- **WETH**: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
- **WETH10**: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
- **cUSDT**: `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
- **cUSDC**: `0xf22258f57794CC8E06237084b353Ab30fFfa640b`

## 📝 Notes

- This loop **cannot blow up** unless ETH collapses or LTV discipline is violated
- USDTz is treated as **a deeply discounted call option, not money**
- Everything else becomes a **timing issue**, not a solvency issue

## 📚 See Also

- [Comprehensive Documentation](./README_SUBMODULE.md)
- [ChainID 138 Token Addresses](../../../../../docs/11-references/CHAIN138_TOKEN_ADDRESSES.md)
- [DeFi Swap Service](../sovereign/defi-swap.service.ts)

---

**Version**: 1.0.0  
**Created**: January 27, 2026  
**License**: UNLICENSED