Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/specs/actions/safety-controls.md

@@ -0,0 +1,179 @@
+# 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`
+