smom-dbis-138/docs/MONITORING_SETUP.md

# Monitoring Setup Guide

**Date**: Monitoring Setup  
**Status**: ✅ COMPLETE

---

## Overview

This guide covers monitoring setup for:
1. Vault System
2. ISO-4217 W Token System
3. Bridge System
4. Infrastructure

---

## 1. Monitoring Architecture

### 1.1 Components

```
┌─────────────────────────────────────────────────────────┐
│                   Monitoring Stack                       │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Prometheus  │  │   Grafana    │  │    Alerts    │  │
│  │  (Metrics)   │  │  (Dashboards)│  │  (PagerDuty) │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                  │                  │          │
│         └──────────────────┴──────────────────┘          │
│                          │                               │
│         ┌────────────────┴────────────────┐             │
│         │                                  │             │
│  ┌──────▼──────┐                  ┌───────▼──────┐     │
│  │   Contract   │                  │   Oracle      │     │
│  │   Events     │                  │   Monitors    │     │
│  └──────────────┘                  └──────────────┘     │
└──────────────────────────────────────────────────────────┘
```

---

## 2. Key Metrics

### 2.1 Vault System Metrics

#### Collateral Metrics
```promql
# Total collateral by asset
vault_collateral_total{asset="ETH"}

# Collateral per vault
vault_collateral{vault="0x..."}

# Collateral value in XAU
vault_collateral_value_xau{asset="ETH"}
```

#### Debt Metrics
```promql
# Total debt by currency
vault_debt_total{currency="USDC"}

# Debt per vault
vault_debt{vault="0x...", currency="USDC"}

# Debt with interest
vault_debt_with_interest{vault="0x...", currency="USDC"}
```

#### Health Metrics
```promql
# Vault health ratio
vault_health_ratio{vault="0x..."}

# Average health ratio
avg(vault_health_ratio)

# Vaults below threshold
count(vault_health_ratio < 1.2)
```

#### Liquidation Metrics
```promql
# Liquidation events
vault_liquidation_total

# Liquidation value
vault_liquidation_value_total
```

---

### 2.2 ISO-4217 W Token Metrics

#### Supply Metrics
```promql
# Total supply by token
wtoken_supply_total{token="USDW"}

# Supply growth rate
rate(wtoken_supply_total[1h])
```

#### Reserve Metrics
```promql
# Verified reserve by token
wtoken_reserve_verified{token="USDW"}

# Reserve ratio (reserve / supply)
wtoken_reserve_ratio{token="USDW"}

# Reserve sufficiency (1 = sufficient, 0 = insufficient)
wtoken_reserve_sufficient{token="USDW"}
```

#### Mint/Burn Metrics
```promql
# Mint events
wtoken_mint_total{token="USDW"}

# Burn events
wtoken_burn_total{token="USDW"}

# Net supply change
wtoken_mint_total - wtoken_burn_total
```

#### Oracle Metrics
```promql
# Oracle quorum status
wtoken_oracle_quorum{token="USDW"}

# Oracle report count
wtoken_oracle_reports{token="USDW"}

# Stale reports
wtoken_oracle_stale_reports{token="USDW"}
```

---

### 2.3 Bridge Metrics

#### Bridge Operations
```promql
# Bridge success rate
bridge_success_rate{destination="polygon"}

# Bridge failure rate
bridge_failure_rate{destination="polygon"}

# Average settlement time
bridge_settlement_time_avg{destination="polygon"}
```

#### Reserve Verification
```promql
# Reserve verification success rate
bridge_reserve_verification_success_rate

# Reserve verification failures
bridge_reserve_verification_failures_total
```

#### Compliance Metrics
```promql
# Compliance check success rate
bridge_compliance_success_rate

# Compliance violations
bridge_compliance_violations_total
```

---

## 3. Alert Configuration

### 3.1 Critical Alerts

#### Reserve Shortfall
```yaml
alert: ReserveShortfall
expr: wtoken_reserve_ratio{token="USDW"} < 1.0
for: 0m
labels:
  severity: critical
annotations:
  summary: "Reserve shortfall detected for {{ $labels.token }}"
  description: "Reserve ratio is {{ $value }}, must be >= 1.0"
```

#### Money Multiplier Violation
```yaml
alert: MoneyMultiplierViolation
expr: wtoken_reserve_sufficient{token="USDW"} == 0
for: 0m
labels:
  severity: critical
annotations:
  summary: "Money multiplier violation for {{ $labels.token }}"
  description: "Reserve < Supply, money multiplier < 1.0"
```

#### Oracle Quorum Failure
```yaml
alert: OracleQuorumFailure
expr: wtoken_oracle_quorum{token="USDW"} == 0
for: 5m
labels:
  severity: critical
annotations:
  summary: "Oracle quorum not met for {{ $labels.token }}"
  description: "Insufficient oracle reports for consensus"
```

---

### 3.2 Warning Alerts

#### Low Reserve Ratio
```yaml
alert: LowReserveRatio
expr: wtoken_reserve_ratio{token="USDW"} < 1.05
for: 15m
labels:
  severity: warning
annotations:
  summary: "Low reserve ratio for {{ $labels.token }}"
  description: "Reserve ratio is {{ $value }}, should be >= 1.05"
```

#### Vault Health Low
```yaml
alert: VaultHealthLow
expr: vault_health_ratio{vault=~".+"} < 1.2
for: 10m
labels:
  severity: warning
annotations:
  summary: "Vault health ratio low for {{ $labels.vault }}"
  description: "Health ratio is {{ $value }}, liquidation threshold is 1.1"
```

#### Bridge Failure Rate High
```yaml
alert: BridgeFailureRateHigh
expr: bridge_failure_rate{destination=~".+"} > 0.1
for: 15m
labels:
  severity: warning
annotations:
  summary: "High bridge failure rate for {{ $labels.destination }}"
  description: "Failure rate is {{ $value | humanizePercentage }}"
```

---

## 4. Dashboard Configuration

### 4.1 Vault System Dashboard

#### Panels
1. **Total Collateral** (Gauge)
   - Total ETH collateral
   - Total value in XAU

2. **Total Debt** (Gauge)
   - Total debt by currency
   - Debt with accrued interest

3. **Health Distribution** (Histogram)
   - Vault health ratios
   - Vaults below threshold

4. **Liquidation Events** (Time Series)
   - Liquidation count over time
   - Liquidation value

---

### 4.2 W Token Dashboard

#### Panels
1. **Supply by Token** (Time Series)
   - USDW, EURW, GBPW supply
   - Supply growth rate

2. **Reserve Ratios** (Gauge)
   - Reserve ratio per token
   - Reserve sufficiency status

3. **Mint/Burn Activity** (Time Series)
   - Mint events
   - Burn events
   - Net supply change

4. **Oracle Status** (Status Panel)
   - Quorum status
   - Report count
   - Stale reports

---

### 4.3 Bridge Dashboard

#### Panels
1. **Bridge Success Rate** (Gauge)
   - Success rate by destination
   - Overall success rate

2. **Settlement Times** (Time Series)
   - Average settlement time
   - P95 settlement time

3. **Reserve Verification** (Status Panel)
   - Verification success rate
   - Verification failures

4. **Compliance Status** (Status Panel)
   - Compliance check success rate
   - Compliance violations

---

## 5. Event Monitoring

### 5.1 Contract Events

#### Vault System Events
```solidity
// Monitor these events
event CollateralModified(address indexed vault, address indexed asset, int256 delta);
event DebtModified(address indexed vault, address indexed currency, int256 delta);
event VaultLiquidated(address indexed vault, address indexed currency, uint256 seizedCollateral, uint256 repaidDebt);
```

#### W Token Events
```solidity
// Monitor these events
event Minted(address indexed to, uint256 amount, string indexed currencyCode);
event Burned(address indexed from, uint256 amount, string indexed currencyCode);
event ReserveUpdated(uint256 reserveBalance, uint256 totalSupply);
```

#### Bridge Events
```solidity
// Monitor these events
event DepositTokenRegistered(address indexed depositToken, address indexed vault, uint256[] destinationChainIds);
event ReserveVerified(address indexed token, uint256 reserve, uint256 supply, uint256 bridgeAmount, bool sufficient);
event ComplianceChecked(address indexed token, bytes32 reasonCode, bool compliant);
```

---

## 6. Log Aggregation

### 6.1 Structured Logging

#### Log Format
```json
{
  "timestamp": "2024-01-09T00:00:00Z",
  "level": "info",
  "system": "vault",
  "component": "ledger",
  "event": "collateral_modified",
  "vault": "0x...",
  "asset": "ETH",
  "delta": "10000000000000000000",
  "new_balance": "20000000000000000000"
}
```

#### Log Levels
- **ERROR**: System errors, failures
- **WARN**: Warnings, degraded state
- **INFO**: Normal operations, events
- **DEBUG**: Detailed debugging info

---

## 7. Monitoring Tools Setup

### 7.1 Prometheus Configuration

```yaml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'chain-138'
    static_configs:
      - targets: ['localhost:8545']
    
  - job_name: 'contract-events'
    static_configs:
      - targets: ['event-monitor:9090']

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']
```

---

### 7.2 Grafana Dashboard Import

#### Dashboard JSON
- Export dashboard configurations
- Import into Grafana
- Configure data sources
- Set up alerts

---

## 8. Incident Response Integration

### 8.1 Alert Routing

#### Critical Alerts → PagerDuty
- Reserve shortfall
- Money multiplier violation
- System compromise

#### Warning Alerts → Slack
- Low reserve ratio
- Vault health low
- Bridge failures

#### Info Alerts → Email
- Daily summaries
- Weekly reports
- Monthly reviews

---

## 9. Monitoring Checklist

### ✅ Setup Checklist

- [ ] Prometheus installed and configured
- [ ] Grafana installed and configured
- [ ] Dashboards created
- [ ] Alerts configured
- [ ] Event monitoring set up
- [ ] Log aggregation configured
- [ ] Alert routing configured
- [ ] Incident response integrated

---

**Last Updated**: Monitoring Setup Complete