180 lines
3.5 KiB
Markdown
180 lines
3.5 KiB
Markdown
# 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`
|
|
|