Health Monitoring

Learn how to monitor your position health, set up alerts, and respond to health degradation before liquidation occurs.

Overview

Position health monitoring is critical for managers. A healthy position stays profitable and avoids liquidation. An unhealthy position gets liquidated, losing your bond and potentially more.

Key Principle: Monitor continuously, act preemptively.

---

Health Ratio Fundamentals

What is Health Ratio?

Health Ratio = Total Position Value / True Debt

Components:

• Total Position Value: Current market value of all your assets

• True Debt: Borrowed amount + accrued interest

Health Ratio Zones

Health Ratio	Zone	Status	Action Required
> 2.0	Safe	🟢 Very Healthy	Normal operations
1.5 - 2.0	Good	🟢 Healthy	Monitor regularly
1.3 - 1.5	Caution	🟡 Warning	Consider rebalancing
1.1 - 1.3	Danger	🟠 Critical	Immediate action
< 1.1	Liquidation	🔴 Liquidatable	Emergency response

Liquidation Threshold

Each strategy defines when positions become liquidatable:

// Typical liquidation threshold formula
Liquidation Threshold = 1 + minBondRatio - liquidationBuffer

// Example:
// minBondRatio = 0.2 (20%)
// liquidationBuffer = 0.1 (10%)
// Threshold = 1 + 0.2 - 0.1 = 1.1 (110%)

When health ratio < threshold → Position is liquidatable

---

Monitoring Your Health

Real-Time Health Check

function getHealthMetrics(address vault, address manager)
    public
    view
    returns (
        uint256 healthRatio,
        uint256 positionValue,
        uint256 debt,
        uint256 liquidationThreshold,
        uint256 safetyMargin,
        bool isLiquidatable
    )
{
    IFluxVault v = IFluxVault(vault);
    IStrategy strategy = v.STRATEGY();

    // Get position data
    positionValue = v.getPositionValue(manager);
    debt = v.getDebt(manager);

    // Calculate health ratio
    healthRatio = positionValue * 1e18 / debt;

    // Get liquidation threshold
    liquidationThreshold = strategy.getLiquidationThreshold();

    // Calculate safety margin
    // How much buffer before liquidation
    if (healthRatio > liquidationThreshold) {
        safetyMargin = healthRatio - liquidationThreshold;
    } else {
        safetyMargin = 0;
    }

    // Check if liquidatable
    (, isLiquidatable) = strategy.evaluateLiquidation(
        manager,
        positionValue,
        debt
    );

    return (
        healthRatio,
        positionValue,
        debt,
        liquidationThreshold,
        safetyMargin,
        isLiquidatable
    );
}

Health Dashboard

struct HealthDashboard {
    // Current State
    uint256 healthRatio;
    uint256 positionValue;
    uint256 debt;
    uint256 bond;

    // Thresholds
    uint256 liquidationThreshold;
    uint256 targetHealth;

    // Margins
    uint256 valueToLiquidation;  // $ until liquidation
    uint256 debtCapacity;        // Additional debt possible

    // Trends
    uint256 debtGrowthRate;      // Debt increase per day
    uint256 timeToLiquidation;   // Estimated time

    // Alerts
    bool isLiquidatable;
    bool needsRebalance;
    bool criticalHealth;
}

function getDashboard(address vault, address manager)
    external
    view
    returns (HealthDashboard memory)
{
    // ... implementation
}

---

Debt Dynamics

How Debt Grows

Debt increases continuously via interest:

True Debt = Principal × (1 + InterestRate × TimeElapsed / 365 days)

Tracking Debt Growth

function calculateDebtGrowth(address vault, address manager)
    public
    view
    returns (
        uint256 currentDebt,
        uint256 dailyIncrease,
        uint256 weeklyIncrease,
        uint256 debtIn30Days
    )
{
    IFluxVault v = IFluxVault(vault);
    IStrategy strategy = v.STRATEGY();

    // Current debt
    currentDebt = v.getDebt(manager);

    // Interest rate (annual)
    uint256 annualRate = strategy.interestRate();

    // Daily increase
    dailyIncrease = currentDebt * annualRate / 365 / 1e18;

    // Weekly increase
    weeklyIncrease = dailyIncrease * 7;

    // Projected debt in 30 days (compound interest)
    uint256 dailyRate = annualRate / 365;
    debtIn30Days = currentDebt;
    for (uint i = 0; i < 30; i++) {
        debtIn30Days = debtIn30Days * (1e18 + dailyRate) / 1e18;
    }

    return (currentDebt, dailyIncrease, weeklyIncrease, debtIn30Days);
}

Time to Liquidation

Estimate how long until liquidation if no action taken:

function estimateTimeToLiquidation(address vault, address manager)
    public
    view
    returns (uint256 timeInDays, bool isImmediate)
{
    (
        uint256 healthRatio,
        uint256 positionValue,
        uint256 debt,
        uint256 liquidationThreshold,
        ,
        bool isLiquidatable
    ) = getHealthMetrics(vault, manager);

    // Already liquidatable
    if (isLiquidatable) {
        return (0, true);
    }

    // Safe position
    if (healthRatio > liquidationThreshold * 2) {
        return (type(uint256).max, false);  // Effectively infinite
    }

    // Calculate time until health = threshold
    // Assuming position value stays constant, debt grows

    IStrategy strategy = IFluxVault(vault).STRATEGY();
    uint256 annualRate = strategy.interestRate();
    uint256 dailyRate = annualRate / 365;

    // Solve for time when: positionValue / (debt * (1 + rate)^days) = threshold
    // Simplified calculation:
    uint256 targetDebt = positionValue * 1e18 / liquidationThreshold;
    uint256 debtGrowthNeeded = targetDebt - debt;
    uint256 dailyGrowth = debt * dailyRate / 1e18;

    timeInDays = debtGrowthNeeded / dailyGrowth;

    return (timeInDays, false);
}

---

Alert System

Alert Levels

enum AlertLevel {
    SAFE,        // Health > 2.0
    MONITOR,     // Health 1.5 - 2.0
    WARNING,     // Health 1.3 - 1.5
    CRITICAL,    // Health 1.1 - 1.3
    EMERGENCY    // Health < 1.1
}

function getAlertLevel(uint256 healthRatio) public pure returns (AlertLevel) {
    if (healthRatio > 2.0e18) return AlertLevel.SAFE;
    if (healthRatio > 1.5e18) return AlertLevel.MONITOR;
    if (healthRatio > 1.3e18) return AlertLevel.WARNING;
    if (healthRatio > 1.1e18) return AlertLevel.CRITICAL;
    return AlertLevel.EMERGENCY;
}

Automated Alerts

contract HealthMonitor {
    event HealthAlert(
        address indexed manager,
        address indexed vault,
        AlertLevel level,
        uint256 healthRatio,
        uint256 timestamp
    );

    mapping(address => uint256) public lastAlertTime;
    uint256 public constant ALERT_COOLDOWN = 1 hours;

    function checkAndAlert(address vault, address manager) external {
        // Prevent spam
        require(
            block.timestamp > lastAlertTime[manager] + ALERT_COOLDOWN,
            "Alert cooldown"
        );

        // Get health
        (uint256 healthRatio,,,,,) = getHealthMetrics(vault, manager);

        // Get alert level
        AlertLevel level = getAlertLevel(healthRatio);

        // Only alert if not SAFE
        if (level != AlertLevel.SAFE) {
            emit HealthAlert(manager, vault, level, healthRatio, block.timestamp);
            lastAlertTime[manager] = block.timestamp;

            // Take automatic action if EMERGENCY
            if (level == AlertLevel.EMERGENCY) {
                emergencyRebalance(vault, manager);
            }
        }
    }
}

---

Response Strategies

Health Degradation Response

function respondToHealthDegradation(address vault) external {
    (uint256 healthRatio,,,,,) = getHealthMetrics(vault, msg.sender);

    AlertLevel level = getAlertLevel(healthRatio);

    if (level == AlertLevel.EMERGENCY) {
        // Immediate action: Reduce position by 40%
        reducePosition(vault, 40);
    } else if (level == AlertLevel.CRITICAL) {
        // Urgent: Add collateral or reduce by 20%
        if (hasCollateral()) {
            addCollateral(vault);
        } else {
            reducePosition(vault, 20);
        }
    } else if (level == AlertLevel.WARNING) {
        // Prepare: Start reducing non-performing assets
        optimizeAssets(vault);
    }
}

Proactive Rebalancing

Don't wait for health to degrade:

function proactiveRebalance(address vault) external {
    PositionInfo memory info = getPositionInfo(vault, msg.sender);

    // Target health ratio: 1.8
    uint256 targetHealth = 1.8e18;

    if (info.healthRatio < targetHealth) {
        // Calculate how much to improve
        uint256 currentValue = info.positionValue;
        uint256 targetValue = info.debt * targetHealth / 1e18;
        uint256 valueGap = targetValue - currentValue;

        // Option 1: Add collateral
        if (hasCollateral()) {
            addCollateral(vault, valueGap);
        }
        // Option 2: Repay debt
        else {
            uint256 repayAmount = info.debt - (currentValue * 1e18 / targetHealth);
            partialRepay(vault, repayAmount);
        }
    }
}

---

Monitoring Bot Implementation

Simple Monitoring Bot

contract SimpleHealthBot {
    IFluxVault public vault;
    address public manager;
    uint256 public checkInterval = 1 hours;
    uint256 public lastCheck;

    constructor(address _vault, address _manager) {
        vault = IFluxVault(_vault);
        manager = _manager;
    }

    function monitor() external {
        require(block.timestamp >= lastCheck + checkInterval, "Too soon");

        // Get health
        (uint256 healthRatio,,,,,bool isLiquidatable) =
            getHealthMetrics(address(vault), manager);

        // Alert if unhealthy
        if (healthRatio < 1.5e18) {
            emit HealthWarning(healthRatio);
        }

        // Auto-rebalance if critical
        if (healthRatio < 1.2e18 && !isLiquidatable) {
            autoRebalance();
        }

        lastCheck = block.timestamp;
    }

    function autoRebalance() internal {
        // Simple rebalancing: reduce position by 25%
        // In production, use more sophisticated logic
    }
}

Advanced Monitoring Bot

contract AdvancedHealthBot {
    struct MonitoringConfig {
        uint256 warningThreshold;    // e.g., 1.5e18
        uint256 criticalThreshold;   // e.g., 1.2e18
        uint256 emergencyThreshold;  // e.g., 1.1e18
        uint256 checkInterval;       // e.g., 10 minutes
        bool autoRebalance;          // Enable auto-rebalancing
        uint256 rebalanceTarget;     // Target health ratio
    }

    mapping(address => MonitoringConfig) public configs;

    function monitor(address vault, address manager) external {
        MonitoringConfig memory config = configs[manager];

        // Get health metrics
        (uint256 healthRatio,,,,,) = getHealthMetrics(vault, manager);

        // Take action based on thresholds
        if (healthRatio < config.emergencyThreshold) {
            handleEmergency(vault, manager);
        } else if (healthRatio < config.criticalThreshold) {
            handleCritical(vault, manager);
        } else if (healthRatio < config.warningThreshold) {
            handleWarning(vault, manager);
        }

        // Log health
        logHealth(vault, manager, healthRatio);
    }

    function handleEmergency(address vault, address manager) internal {
        emit EmergencyAlert(vault, manager);

        // Auto-rebalance if enabled
        if (configs[manager].autoRebalance) {
            // Reduce position significantly
            reducePosition(vault, manager, 50);
        }
    }
}

---

Health Trends

Track Historical Health

struct HealthHistory {
    uint256 timestamp;
    uint256 healthRatio;
    uint256 positionValue;
    uint256 debt;
}

mapping(address => HealthHistory[]) public healthHistory;

function recordHealth(address vault, address manager) external {
    (uint256 healthRatio, uint256 value, uint256 debt,,,) =
        getHealthMetrics(vault, manager);

    healthHistory[manager].push(HealthHistory({
        timestamp: block.timestamp,
        healthRatio: healthRatio,
        positionValue: value,
        debt: debt
    }));
}

function getHealthTrend(address manager, uint256 periods)
    external
    view
    returns (bool improving, uint256 avgHealth)
{
    HealthHistory[] memory history = healthHistory[manager];
    require(history.length >= periods, "Insufficient data");

    uint256 startIdx = history.length - periods;
    uint256 sum = 0;

    for (uint i = startIdx; i < history.length; i++) {
        sum += history[i].healthRatio;
    }

    avgHealth = sum / periods;

    // Trend: compare recent vs earlier
    uint256 recentAvg = (history[history.length - 1].healthRatio +
                        history[history.length - 2].healthRatio) / 2;

    improving = recentAvg > avgHealth;
}

---

Best Practices

Monitoring Frequency

- Critical positions (health < 1.3): Every 10 minutes
- Warning positions (health < 1.5): Every hour
- Healthy positions (health > 1.5): Every 6 hours
- Safe positions (health > 2.0): Daily

Proactive Management

// Don't wait for alerts
function dailyHealthMaintenance(address vault) external {
    (uint256 healthRatio,,,,,) = getHealthMetrics(vault, msg.sender);

    // Keep buffer above liquidation
    uint256 targetHealth = 1.8e18;

    if (healthRatio < targetHealth) {
        // Proactively improve health
        improveHealth(vault, targetHealth - healthRatio);
    }

    // Take partial profits to pay down debt
    if (healthRatio > 2.5e18) {
        takePartialProfit(vault);
    }
}

Multi-Position Monitoring

function monitorAllPositions() external {
    address[] memory vaults = getMyVaults();

    for (uint i = 0; i < vaults.length; i++) {
        (uint256 health,,,,,) = getHealthMetrics(vaults[i], msg.sender);

        // Prioritize unhealthiest positions
        if (health < 1.3e18) {
            handleCriticalPosition(vaults[i]);
        }
    }
}

---

Tools and Integration

Web3 Monitoring

// Example: Monitor with ethers.js
async function monitorHealth(vaultAddress, managerAddress) {
    const vault = new ethers.Contract(vaultAddress, vaultABI, provider);

    // Get position value
    const positionValue = await vault.getPositionValue(managerAddress);

    // Get debt
    const debt = await vault.getDebt(managerAddress);

    // Calculate health
    const healthRatio = positionValue.mul(ethers.utils.parseEther("1")).div(debt);

    if (healthRatio.lt(ethers.utils.parseEther("1.3"))) {
        // Send alert
        await sendAlertToDiscord(healthRatio);
    }
}

Integration with Alerting

• Discord webhooks

• Telegram bots

• Email notifications

• PagerDuty for critical alerts

• Custom dashboards

Related Documentation

• Position Management - Managing positions

• Manager Risk - Avoiding liquidation

• Liquidation - How liquidations work

• Manager Integration - Full integration guide