Initial commit

2025-11-20 15:35:25 -08:00
commit bfbe3ee8b7
59 changed files with 7187 additions and 0 deletions
--- a/docs/POLICY.md
+++ b/docs/POLICY.md
@@ -0,0 +1,185 @@
+# 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
+