defi-arbitrage/README_SUBMODULE.md

# Deal Orchestration Tool - Arbitrage Module

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

This module implements a sophisticated deal orchestration tool designed to execute freeze-resistant arbitrage loops that preserve capital even when individual legs fail. The system is built on four non-negotiable design principles that ensure no single leg failure can trap principal.

## 📋 Table of Contents

- [Overview](#overview)
- [Design Principles](#design-principles)
- [Architecture](#architecture)
- [The Arbitrage Loop](#the-arbitrage-loop)
- [Risk Controls](#risk-controls)
- [Implementation Details](#implementation-details)
- [Usage](#usage)
- [Configuration](#configuration)
- [Failure Scenarios](#failure-scenarios)
- [Development](#development)

---

## Overview

This tool executes a multi-step arbitrage loop using:
- **ETH/WETH** as the anchor asset (never touched in risky operations)
- **USDT/cUSDT** as working capital (borrowed against ETH collateral)
- **USDTz** as discounted upside (bought at 40% discount, never leveraged)

The loop is designed so that if any single leg fails (redemption freezes, borrow market freezes, network congestion), the system degrades gracefully into a holding state rather than causing losses.

### Key Features

✅ **One-Way Risk**: Principal recovery never depends on redemption  
✅ **Anchor Protection**: Core ETH remains untouched  
✅ **No Leverage on Discounted Assets**: USDTz never used as collateral  
✅ **Independent Settlement**: Each leg can settle independently  
✅ **Progressive Testing**: Redemption tested incrementally ($50k → $250k → $1M+)  
✅ **Hard Risk Caps**: 30% max LTV, 25% max USDTz exposure  

---

## Design Principles

### Rule 1 — One-Way Risk Only

- You never **need** redemption to recover principal
- Redemption = upside, not survival
- Principal is protected by ETH collateral

### Rule 2 — Anchor Asset is Untouchable

- ETH / WETH is the anchor
- Stables are temporary instruments
- Core ETH bucket (50%) is never touched

### Rule 3 — Discounted Assets Never Carry Leverage

- USDTz bought at 40% discount is **never borrowed against**
- It never collateralizes anything critical
- No rehypothecation allowed

### Rule 4 — Every Leg Can Settle Independently

- No atomic dependency across chains or issuers
- If one leg freezes, loop degrades into a **holding**, not a loss
- Each step can complete independently

---

## Architecture

### File Structure

```
arbitrage/
├── types.ts                      # Type definitions and interfaces
├── config.ts                     # ChainID 138 addresses and risk params
├── risk-control.service.ts       # Risk validation and enforcement
├── step-execution.service.ts     # Individual step implementations
├── redemption-test.service.ts    # Progressive redemption testing
├── deal-orchestrator.service.ts # Main orchestrator
├── cli.ts                        # Command-line interface
├── index.ts                      # Main exports
└── README.md                     # This file
```

### Core Services

#### `RiskControlService`
- Validates deal requests against risk parameters
- Enforces LTV compliance (max 30%)
- Checks USDTz exposure limits (max 25% NAV)
- Validates no rehypothecation

#### `StepExecutionService`
- **Step 0**: Capital split into three buckets
- **Step 1**: Generate working liquidity (wrap, supply, borrow)
- **Step 2**: Execute discount arbitrage (buy USDTz)
- **Step 3**: Partial monetization (split and attempt redemption)
- **Step 4**: Close the loop (repay, unlock, capture profit)

#### `RedemptionTestService`
- Progressive testing: $50k → $250k → $1M+
- Success probability decreases with amount
- Stops testing if any test fails

#### `DealOrchestratorService`
- Orchestrates the entire loop
- Manages state transitions
- Handles errors and graceful degradation
- Tracks all risk checks and redemption tests

---

## The Arbitrage Loop

### STEP 0 — Capital Split

**Purpose**: Divide initial ETH into three strategic buckets

**Example with $10M equivalent ETH**:

| Bucket | Purpose | Amount | Percentage |
|--------|---------|--------|------------|
| A | Core ETH (never touched) | $5.0M | 50% |
| B | Working Liquidity | $3.0M | 30% |
| C | Opportunistic USDTz | $2.0M | 20% |

**Critical Constraint**: ETH **never** enters the USDTz leg directly.

**Implementation**: `StepExecutionService.executeStep0()`

---

### STEP 1 — Generate Working Liquidity (Safe)

**Purpose**: Create working capital by borrowing against ETH collateral

**Process**:
1. Wrap ETH → WETH (1:1 ratio)
2. Supply WETH to lending protocol on ChainID 138
3. Borrow USDT/cUSDT at ≤30% LTV

**Example**:
- $3M WETH collateral supplied
- $900k USDT borrowed (30% LTV)

**Safety**: If anything freezes later, ETH is recoverable due to low LTV.

**Implementation**: `StepExecutionService.executeStep1()`

**Risk Checks**:
- LTV compliance (must be ≤30%)
- Collateral value validation

---

### STEP 2 — Execute Discount Arbitrage (Isolated)

**Purpose**: Use borrowed USDT to buy discounted USDTz

**Process**:
1. Use borrowed USDT ($900k in example)
2. Buy USDTz at 40% discount
3. Receive ≈ $1.5M USDTz (at 40% discount: $900k / 0.6 = $1.5M)

**Critical Rules**:
- This USDTz is **never pledged** as collateral
- Never bridged unless tested small first
- Treated as optional upside, not money

**Implementation**: `StepExecutionService.executeStep2()`

**Risk Checks**:
- USDTz exposure limit (must be <25% of total NAV)
- No rehypothecation validation

---

### STEP 3 — Partial Monetization (Optional, Safe)

**Purpose**: Attempt to monetize a portion of USDTz while holding the rest

**Process**:
1. Split USDTz into two portions:
   - **30-40%**: Attempt redemption/swap to USDT
   - **60-70%**: Hold cold as optional upside

2. Progressive redemption testing:
   - Test $50k first (95% success probability)
   - Then $250k (85% success probability)
   - Then $1M+ (75% success probability)

3. If redemption works:
   - Convert to USDT
   - Ready to repay borrow
   - Capture spread

4. If redemption freezes:
   - Nothing upstream is affected
   - ETH collateral remains safe
   - Loan remains healthy
   - USDTz held as optional upside

**Implementation**: `StepExecutionService.executeStep3()` + `RedemptionTestService`

---

### STEP 4 — Close the Loop (If Redemption Works)

**Purpose**: Complete the arbitrage by repaying borrow and unlocking collateral

**Process** (if 40% redeems successfully):
1. $600k USDTz → $600k USDT (from redemption)
2. Repay $900k borrow (may need additional liquidity or wait for more redemption)
3. Residual ETH unlocked
4. Remaining USDTz ($900k) is pure upside

**Profit Sources**:
- Discount capture (40% on USDTz)
- ETH appreciation (if ETH price increases)
- Interest spread (if borrowing rate < redemption yield)

**Implementation**: `StepExecutionService.executeStep4()`

**Note**: If redemption fails, this step is skipped and the deal remains in "frozen" state.

---

## Risk Controls

### Hard Caps

| Control | Limit | Enforcement |
|---------|-------|-------------|
| **Max LTV** | 30% | Validated before and after borrowing |
| **Max USDTz Exposure** | <25% of total NAV | Checked after USDTz acquisition |
| **No Rehypothecation** | USDTz cannot be collateral | Validated throughout execution |

### Redemption Testing

Progressive testing ensures redemption throughput is verified before committing large amounts:

1. **$50k test** (95% success probability)
   - Small test to verify basic functionality
   - If fails, stop immediately

2. **$250k test** (85% success probability)
   - Medium test to verify scaling
   - Cumulative: $300k tested

3. **$1M+ test** (75% success probability)
   - Large test to verify production capacity
   - Cumulative: $1.3M+ tested

**Implementation**: `RedemptionTestService.executeProgressiveTests()`

---

## Implementation Details

### Type System

All types are defined in `types.ts`:

- `DealExecutionRequest`: Input parameters for deal execution
- `DealState`: Current state of a deal (step, buckets, amounts, tx hashes)
- `DealStep`: Enum of possible deal steps
- `Step0Result` through `Step4Result`: Results from each step
- `RiskCheckResult`: Risk validation results
- `RedemptionTestResult`: Individual redemption test results
- `DealExecutionResult`: Complete execution result

### State Management

Deals progress through states:
1. `INITIALIZED` → Deal created
2. `CAPITAL_SPLIT` → Step 0 complete
3. `WORKING_LIQUIDITY_GENERATED` → Step 1 complete
4. `ARBITRAGE_EXECUTED` → Step 2 complete
5. `MONETIZATION_ATTEMPTED` → Step 3 complete
6. `LOOP_CLOSED` → Step 4 complete (success)
7. `FROZEN` → Redemption failed, holding state
8. `FAILED` → Error occurred

### Error Handling

- **Graceful Degradation**: Failures in optional steps (redemption) don't affect core positions
- **Risk Validation**: All steps validated before execution
- **Transaction Tracking**: All on-chain transactions tracked with hashes
- **Error Logging**: Comprehensive logging via Winston

### Integration Points

The tool integrates with:
- **Prisma ORM**: For database persistence (when implemented)
- **Winston Logger**: For structured logging
- **Existing DeFi Services**: Follows patterns from `DeFiSwapService`
- **ChainID 138**: All operations on ChainID 138 network

---

## Usage

### Command-Line Interface

```bash
# Basic execution
node cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001

# With custom parameters
node cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001 \
  --usdtzDiscount 0.40 \
  --maxLtv 0.30 \
  --redemptionPortion 0.35 \
  --coldStoragePortion 0.65
```

### Programmatic API

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

const request: DealExecutionRequest = {
  totalEthValue: '10000000', // $10M
  participantBankId: 'BANK001',
  moduleId: 'MODULE001',
  usdtzDiscountRate: 0.40, // 40% discount
  maxLtv: 0.30, // 30% LTV
  monetizationSplit: {
    redemptionPortion: 0.35, // 35% for redemption
    coldStoragePortion: 0.65, // 65% for cold storage
  },
};

const result = await dealOrchestratorService.executeDeal(request);

console.log('Deal ID:', result.dealId);
console.log('Status:', result.status);
console.log('Step:', result.state.step);
console.log('Final Profit:', result.finalProfit?.toString());

// Check risk compliance
const allRiskChecksPassed = result.riskChecks.every(r => r.passed);
console.log('All Risk Checks Passed:', allRiskChecksPassed);

// Check redemption tests
const redemptionReliable = result.redemptionTests.every(r => r.successful);
console.log('Redemption Reliable:', redemptionReliable);
```

### Service-Level Usage

```typescript
// Use individual services
import {
  riskControlService,
  stepExecutionService,
  redemptionTestService,
} from '@/core/defi/arbitrage';

// Validate a deal request
const riskCheck = await riskControlService.validateDealRequest(
  request,
  new Decimal('10000000')
);

// Execute a specific step
const step0Result = await stepExecutionService.executeStep0(request);

// Test redemption
const testResults = await redemptionTestService.executeProgressiveTests(
  new Decimal('1500000')
);
```

---

## Configuration

### Environment Variables

Set these environment variables for protocol addresses:

```bash
# RPC Configuration
export CHAIN138_RPC_URL="http://192.168.11.250:8545"
# or
export CHAIN138_RPC_URL="https://rpc-core.d-bis.org"

# Protocol Addresses (to be configured based on actual deployment)
export CHAIN138_LENDING_PROTOCOL="<lending-protocol-address>"
export CHAIN138_VAULT_ADDRESS="<vault-contract-address>"
export CHAIN138_LEDGER_ADDRESS="<ledger-contract-address>"
export CHAIN138_USDTZ_SWAP_ADDRESS="<usdtz-swap-contract-address>"
export CHAIN138_USDTZ_REDEEM_ADDRESS="<usdtz-redeem-contract-address>"
```

### Token Addresses (ChainID 138)

Pre-configured in `config.ts`:

| Token | Address | Decimals |
|-------|---------|----------|
| **WETH** | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 |
| **WETH10** | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 |
| **LINK** | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 |
| **cUSDT** | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 |
| **cUSDC** | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 |

### Risk Parameters

Default values in `config.ts`:

```typescript
DEFAULT_RISK_PARAMS = {
  MAX_LTV: 0.30,                    // 30% maximum
  MAX_USDTZ_EXPOSURE_PCT: 0.25,      // 25% of NAV
  DEFAULT_USDTZ_DISCOUNT: 0.40,      // 40% discount
  DEFAULT_MONETIZATION_SPLIT: {
    redemptionPortion: 0.35,         // 35% for redemption
    coldStoragePortion: 0.65,         // 65% for cold storage
  },
}
```

### Capital Split Defaults

```typescript
DEFAULT_CAPITAL_SPLIT = {
  coreEthPct: 0.50,                  // 50% core ETH
  workingLiquidityPct: 0.30,         // 30% working liquidity
  opportunisticUsdtzPct: 0.20,       // 20% opportunistic
}
```

---

## Failure Scenarios

### Failure Case A — USDTz Redemption Freezes

**What Happens**:
- ✅ ETH collateral untouched
- ✅ Loan still healthy (low LTV)
- ✅ USDTz just sits as optional upside
- ❌ No liquidation
- ❌ No margin calls

**System Response**:
- Deal state transitions to `FROZEN`
- No upstream impact
- Can wait indefinitely or attempt redemption later

**Implementation**: Handled in `StepExecutionService.executeStep3()`

---

### Failure Case B — USDT Borrow Market Freezes

**What Happens**:
- ✅ ETH collateral still priced
- ✅ LTV low enough to wait (30% max)
- ✅ No forced unwind

**System Response**:
- Can wait for market to recover
- Can repay from other liquidity sources
- Can refinance later

**Implementation**: Low LTV ensures safety margin

---

### Failure Case C — ChainID 138 Congestion

**What Happens**:
- ✅ ETH is base layer or wrapped (no cross-chain dependency)
- ✅ No issuer dependency
- ✅ No atomic cross-chain operations

**System Response**:
- Operations can wait for network to clear
- No time-sensitive atomic dependencies
- Each leg can complete independently

---

## Development

### Prerequisites

- TypeScript 4.5+
- Node.js 16+
- Prisma ORM (for database integration)
- Winston (for logging)
- Decimal.js (for precise decimal arithmetic)

### Dependencies

```json
{
  "@prisma/client": "^5.0.0",
  "decimal.js": "^10.4.0",
  "uuid": "^9.0.0",
  "winston": "^3.11.0"
}
```

### Building

```bash
cd dbis_core/src/core/defi/arbitrage
tsc --build
```

### Testing

```bash
# Run tests (when test suite is implemented)
npm test

# Run with coverage
npm run test:coverage
```

### Integration with Existing Services

The tool follows patterns from existing `DeFiSwapService`:
- Uses Prisma for database operations
- Uses Winston for logging
- Uses Decimal.js for financial calculations
- Follows TypeScript path aliases (`@/core/*`)

### Future Enhancements

1. **On-Chain Integration**: Replace mock transactions with actual smart contract calls
2. **Database Persistence**: Store deal states in Prisma database
3. **Monitoring**: Add metrics and alerting
4. **API Endpoints**: REST/GraphQL API for deal management
5. **WebSocket Updates**: Real-time deal status updates
6. **Multi-Chain Support**: Extend to other chains beyond ChainID 138

---

## Notes

### Why This Loop Cannot Blow Up

The loop **cannot blow up** unless:
1. ETH itself collapses (systemic risk, not loop-specific)
2. LTV discipline is violated (prevented by hard caps)

Everything else becomes a **timing issue**, not a solvency issue.

### USDTz Treatment

USDTz is treated as:
> **A deeply discounted call option, not money**

This means:
- Never used as critical collateral
- Never required for principal recovery
- Always optional upside
- Can be held indefinitely if redemption freezes

### Capital Preservation

The system is designed for capital preservation:
- Core ETH (50%) never touched
- Low LTV (30%) provides safety margin
- Independent leg settlement prevents cascade failures
- Graceful degradation to holding state

---

## License

[To be determined based on parent project license]

---

## Author

Created as part of the DBIS Core Banking System - DeFi Arbitrage Module

**Date**: January 27, 2026  
**Version**: 1.0.0

---

## References

- ChainID 138 Token Addresses: `docs/11-references/CHAIN138_TOKEN_ADDRESSES.md`
- DeFi Swap Service: `dbis_core/src/core/defi/sovereign/defi-swap.service.ts`
- Vault Contract: `smom-dbis-138/contracts/vault/Vault.sol`
- Ledger Contract: `smom-dbis-138/contracts/vault/Ledger.sol`