no_five/docs/POLICY.md

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

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

Adding New Policy Modules

Step 1: Implement IPolicyModule

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

policyEngine.registerPolicyModule(address(myPolicyModule));

Step 3: Configure Parameters

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