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

# 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

# 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

# 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

# Liquidation events
vault_liquidation_total

# Liquidation value
vault_liquidation_value_total

---

2.2 ISO-4217 W Token Metrics

Supply Metrics

# Total supply by token
wtoken_supply_total{token="USDW"}

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

Reserve Metrics

# 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

# 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

# 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

# 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

# Reserve verification success rate
bridge_reserve_verification_success_rate

# Reserve verification failures
bridge_reserve_verification_failures_total

Compliance Metrics

# Compliance check success rate
bridge_compliance_success_rate

# Compliance violations
bridge_compliance_violations_total

---

3. Alert Configuration

3.1 Critical Alerts

Reserve Shortfall

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

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

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

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

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

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

// 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

// 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

// 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

{
  "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

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