explorer-monorepo/docs/specs/actions/safety-controls.md

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

{
  "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