# Policy System

## Overview

The policy system provides modular, plugin-based governance controls. Policy modules evaluate proposed actions and can approve or deny them.

## Policy Architecture

### PolicyEngine
Central coordinator that:
- Registers policy modules
- Aggregates decisions from all modules
- Returns allow/deny with reason

### Policy Modules

#### 1. PolicyHFTrend
Monitors health factor trends and ensures:
- HF never decreases
- HF improvements meet minimum threshold
- Trend is always improving

**Configuration:**
- `minHFThreshold`: Minimum acceptable HF (default: 1.05)
- `minHFImprovement`: Minimum improvement per cycle (default: 1%)

#### 2. PolicyFlashVolume
Limits flash loan volume per time period:
- Per-asset volume limits
- Global volume limits
- Time-based tracking windows

**Configuration:**
- `periodDuration`: Tracking window (default: 1 day)
- `assetVolumeLimit[asset]`: Per-asset limit
- `globalVolumeLimit`: Global limit

#### 3. PolicyLiquiditySpread
Validates liquidity and spreads:
- Maximum acceptable spread
- Minimum liquidity depth
- Liquidity-to-operation ratio checks

**Configuration:**
- `maxSpreadBps`: Maximum spread in basis points (default: 50 = 0.5%)
- `minLiquidityDepth[asset]`: Minimum liquidity required

#### 4. PolicyProviderConcentration
Prevents over-concentration in single providers:
- Maximum percentage from single provider
- Diversification enforcement
- Time-window tracking

**Configuration:**
- `maxProviderConcentrationBps`: Maximum concentration (default: 5000 = 50%)
- `trackingWindow`: Tracking period (default: 7 days)

## Policy Evaluation Flow

```
Action Proposed
  ↓
PolicyEngine.evaluateAll(actionType, actionData)
  ↓
For each registered module:
  1. Check if enabled
  2. Call module.evaluate()
  3. Get decision
  4. If deny → return deny immediately
  ↓
If all modules approve → return allow
```

## Policy Decision Structure

```solidity
struct PolicyDecision {
    bool allowed;
    string reason;  // Empty if allowed, explanation if denied
}
```

## Adding New Policy Modules

### Step 1: Implement IPolicyModule

```solidity
contract MyPolicyModule is IPolicyModule {
    function evaluate(
        bytes32 actionType,
        bytes memory actionData
    ) external view returns (PolicyDecision memory) {
        // Policy logic
        return PolicyDecision({
            allowed: true,
            reason: ""
        });
    }
    
    function name() external pure returns (string memory) {
        return "MyPolicy";
    }
    
    function isEnabled() external view returns (bool) {
        return _enabled;
    }
    
    function setEnabled(bool enabled) external onlyOwner {
        _enabled = enabled;
    }
}
```

### Step 2: Register with PolicyEngine

```solidity
policyEngine.registerPolicyModule(address(myPolicyModule));
```

### Step 3: Configure Parameters

```solidity
myPolicyModule.setParameter(value);
```

## Policy Enforcement

### Pre-Execution
- GovernanceGuard calls `PolicyEngine.evaluateAll()`
- If denied, transaction reverts before execution

### During Execution
- Some policies monitor state during execution
- Can emit warnings or deny mid-execution

### Post-Execution
- Policies can verify outcomes
- Can trigger alerts if thresholds exceeded

## Configuration Management

### Owner-Only Updates
- Register/unregister modules
- Configure policy parameters
- Enable/disable modules

### Multi-Sig Requirements
Critical policy changes should require multi-sig:
- Adding new policy modules
- Changing volume limits
- Changing HF thresholds

## Testing Policies

### Unit Tests
- Test each policy module independently
- Test allow/deny scenarios
- Test configuration updates

### Integration Tests
- Test policy aggregation
- Test policy conflicts
- Test policy order independence

## Best Practices

1. **Fail-Safe Defaults**: Deny by default if policy unavailable
2. **Clear Reasons**: Provide detailed denial reasons
3. **Modular Design**: Keep policies independent
4. **Upgradeable**: Support parameter updates
5. **Documented**: Document all policy logic

## Monitoring

### Policy Metrics
- Approval/denial rates
- Most common denial reasons
- Policy evaluation latency
- Module usage statistics

### Alerts
- High denial rate
- Policy module failures
- Unusual policy patterns