# Safety Controls Specification

## Overview

This document specifies safety controls including phishing detection, contract risk scoring, address screening, and transaction simulation warnings.

## Phishing/Contract Risk Scoring

### Risk Factors

**1. Contract Verification**:
- Unverified: Higher risk
- Verified: Lower risk

**2. Reputation**:
- Known malicious addresses: High risk
- Known legitimate addresses: Low risk
- Unknown: Medium risk

**3. Code Analysis**:
- Suspicious functions (self-destruct, delegatecall abuse)
- Honeypot patterns
- Proxy contracts (verify implementation)

**4. Historical Data**:
- Previous scam reports
- User reports
- Security audit results

### Risk Score

**Calculation**:
```
risk_score = (verification_risk * 0.3) + 
             (reputation_risk * 0.3) + 
             (code_risk * 0.2) + 
             (historical_risk * 0.2)
```

**Score Ranges**:
- 0.0-0.3: Low risk (green)
- 0.3-0.6: Medium risk (yellow)
- 0.6-1.0: High risk (red)

## Address Screening

### Screening Sources

**1. Blocklists**:
- Known scam addresses
- Phishing addresses
- Mixer/tumbler addresses

**2. Reputation Services**:
- Etherscan labels
- Community reports
- Security databases

**3. Pattern Detection**:
- Address similarity (homoglyph attacks)
- Known scam patterns

### Screening Result

```json
{
  "address": "0x...",
  "risk_level": "high",
  "reasons": [
    "Address on known phishing list",
    "Unverified contract",
    "Suspicious transaction patterns"
  ],
  "sources": ["etherscan", "community_reports"],
  "confidence": 0.95
}
```

## Transaction Simulation and Warnings

### Simulation Checks

**1. Balance Checks**:
- Sufficient token balance
- Sufficient native balance for gas

**2. Approval Checks**:
- Current allowance
- Approval amount vs transaction amount

**3. State Changes**:
- Simulate transaction
- Detect unexpected state changes
- Check for reentrancy risks

**4. Token Transfers**:
- Unexpected token transfers
- High-value transfers
- Transfers to unknown addresses

### Warning Types

**Critical Warnings** (Block transaction):
- Insufficient balance
- Contract self-destruct
- Known malicious address

**High Warnings** (Strong recommendation to cancel):
- Unverified contract
- High slippage
- Large value transfer to new address

**Medium Warnings** (Informational):
- First interaction with contract
- Unusual transaction pattern
- High gas cost

### Warning Display

**UI Elements**:
- Warning banner with risk level
- Detailed explanation
- Option to proceed or cancel
- Educational content

## User Consent Workflow

### Consent Steps

**1. Transaction Review**:
- Display transaction details
- Show risk assessment
- Highlight warnings

**2. Confirmation**:
- User acknowledges risks
- Explicit confirmation required
- Optional: Additional confirmation for high-risk

**3. Execution**:
- Proceed with transaction
- Log consent for audit

### Consent Logging

**Fields**:
- Transaction hash
- User address
- Risk level
- Warnings shown
- Consent timestamp
- User acknowledgment

## Integration Points

### Transaction Flow Integration

1. User initiates transaction
2. Screen address/contract
3. Simulate transaction
4. Calculate risk score
5. Display warnings
6. Request consent
7. Execute if approved

### API Integration

**Risk Assessment API**:
`POST /api/v1/safety/assess`

**Request**: Transaction details
**Response**: Risk score and warnings

## References

- Swap Engine: See `swap-engine.md`
- Bridge Engine: See `bridge-engine.md`
- Security: See `../security/security-architecture.md`