186 lines
4.2 KiB
Markdown
186 lines
4.2 KiB
Markdown
# 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
|
|
|