merge: chore/cleanup-remove-bloat-and-secrets into main

app/domain/wallet/__init__.py

@@ -0,0 +1,54 @@
+"""Wallet domain — public API + health check."""
+from __future__ import annotations
+
+from app.core import health as health_mod
+from app.core.health import DomainHealth
+
+
+async def _health_check() -> DomainHealth:
+    """Wallet health: DataBus is importable (we don't call it — that would be slow)."""
+    try:
+        # DataBus is the gateway for all chain data. Verify the module loads.
+        import app.databus  # noqa: F401
+        return DomainHealth(
+            name="wallet",
+            healthy=True,
+            details={"databus": "importable"},
+        )
+    except Exception as e:
+        return DomainHealth(name="wallet", healthy=False, error=str(e))
+
+
+health_mod.register_health_check("wallet", _health_check)
+
+
+# Public API
+from app.domain.wallet.analyzer import WalletAnalyzer
+from app.domain.wallet.models import (
+    Balance,
+    RiskLevel,
+    ScanFlag,
+    ScanRequest,
+    ScanResult,
+    TokenHolding,
+    Transaction,
+    Wallet,
+    WalletAnalysis,
+)
+from app.domain.wallet.repository import WalletRepository
+from app.domain.wallet.service import WalletService
+
+__all__ = [
+    "Balance",
+    "RiskLevel",
+    "ScanFlag",
+    "ScanRequest",
+    "ScanResult",
+    "TokenHolding",
+    "Transaction",
+    "Wallet",
+    "WalletAnalysis",
+    "WalletAnalyzer",
+    "WalletRepository",
+    "WalletService",
+]

app/domain/wallet/analyzer.py

@@ -0,0 +1,132 @@
+"""Pure risk-scoring logic. No I/O, no external calls.
+
+This is the testable, deterministic core. Given a portfolio + recent
+transactions + known labels, return a risk score and flags.
+"""
+from __future__ import annotations
+
+from app.domain.wallet.models import (
+    RiskLevel,
+    ScanFlag,
+    TokenHolding,
+    Transaction,
+    WalletAnalysis,
+)
+
+
+class WalletAnalyzer:
+    """Pure-Python risk analysis. No external dependencies."""
+
+    # Truncation for display: first 6 + "..." + last 4
+    TRUNCATE_PREFIX = 6
+    TRUNCATE_SUFFIX = 4
+
+    def analyze(
+        self,
+        address: str,
+        chain: str,
+        tokens: list[TokenHolding] | None = None,
+        recent_transactions: list[Transaction] | None = None,
+        labels: list[str] | None = None,
+    ) -> WalletAnalysis:
+        """Produce a full WalletAnalysis from raw inputs.
+
+        Pure function of inputs. No I/O. Easily unit-testable.
+        """
+        tokens = tokens or []
+        recent = recent_transactions or []
+        labels = labels or []
+
+        risk_score = self._compute_risk_score(tokens, recent, labels)
+        risk_level = RiskLevel.from_score(risk_score)
+        flags = self._compute_flags(tokens, recent, labels, risk_score)
+        total_value = sum(t.value_usd for t in tokens)
+
+        return WalletAnalysis(
+            address=address,
+            chain=chain,
+            truncated_address=self._truncate(address),
+            risk_score=risk_score,
+            risk_level=risk_level,
+            tokens=tokens,
+            recent_transactions=recent,
+            labels=labels,
+            flags=flags,
+            total_value_usd=round(total_value, 2),
+        )
+
+    @staticmethod
+    def _truncate(address: str) -> str:
+        if len(address) <= WalletAnalyzer.TRUNCATE_PREFIX + WalletAnalyzer.TRUNCATE_SUFFIX + 3:
+            return address
+        return (
+            address[: WalletAnalyzer.TRUNCATE_PREFIX]
+            + "..."
+            + address[-WalletAnalyzer.TRUNCATE_SUFFIX :]
+        )
+
+    @staticmethod
+    def _compute_risk_score(
+        tokens: list[TokenHolding],
+        recent: list[Transaction],
+        labels: list[str],
+    ) -> int:
+        """Score 0-100. Higher = riskier.
+
+        Heuristic:
+        - Each token = +2 (diversification proxy)
+        - Each recent tx = +1 (activity proxy)
+        - Each suspicious label (mixer, drainer, exploit) = +30
+        - Negative balances / huge values = clamp 0-100
+        """
+        score = len(tokens) * 2 + len(recent)
+        suspicious = {"mixer", "drainer", "exploit", "hack", "phishing", "ransomware"}
+        for label in labels:
+            if any(s in label.lower() for s in suspicious):
+                score += 30
+        return max(0, min(100, score))
+
+    @staticmethod
+    def _compute_flags(
+        tokens: list[TokenHolding],
+        recent: list[Transaction],
+        labels: list[str],
+        risk_score: int,
+    ) -> list[ScanFlag]:
+        """Generate human-readable risk flags from inputs."""
+        flags: list[ScanFlag] = []
+
+        if risk_score >= 80:
+            flags.append(ScanFlag(
+                code="critical_risk",
+                severity=RiskLevel.CRITICAL,
+                message="Wallet shows patterns consistent with high-risk activity.",
+            ))
+        elif risk_score >= 50:
+            flags.append(ScanFlag(
+                code="elevated_risk",
+                severity=RiskLevel.HIGH,
+                message="Elevated risk indicators present.",
+            ))
+
+        suspicious = {"mixer", "drainer", "exploit", "hack", "phishing", "ransomware"}
+        for label in labels:
+            if any(s in label.lower() for s in suspicious):
+                flags.append(ScanFlag(
+                    code="flagged_entity",
+                    severity=RiskLevel.CRITICAL,
+                    message=f"Wallet linked to flagged entity: {label}",
+                    evidence={"label": label},
+                ))
+
+        # Dust tokens (many low-value tokens) signal airdrop farming or spam
+        dust_count = sum(1 for t in tokens if 0 < t.value_usd < 1)
+        if dust_count >= 10:
+            flags.append(ScanFlag(
+                code="dust_tokens",
+                severity=RiskLevel.MEDIUM,
+                message=f"{dust_count} dust tokens detected — possible airdrop farm or spam exposure.",
+                evidence={"dust_count": dust_count},
+            ))
+
+        return flags

app/domain/wallet/models.py

@@ -0,0 +1,132 @@
+"""Pydantic v2 models for the wallet domain.
+
+No FastAPI imports. Pure data shapes.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class RiskLevel(StrEnum):
+    """Wallet risk classification."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @classmethod
+    def from_score(cls, score: int) -> RiskLevel:
+        if score < 20:
+            return cls.LOW
+        if score < 50:
+            return cls.MEDIUM
+        if score < 80:
+            return cls.HIGH
+        return cls.CRITICAL
+
+
+class Wallet(BaseModel):
+    """A wallet identity (address + chain)."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    address: str = Field(..., min_length=1, max_length=256)
+    chain: str = Field(default="solana", description="solana, ethereum, bsc, base, ...")
+    label: str | None = Field(default=None, description="Human-readable label, e.g. 'Binance Hot Wallet'")
+
+
+class TokenHolding(BaseModel):
+    """A single token holding within a wallet's portfolio."""
+
+    symbol: str
+    address: str = ""
+    amount: float = 0.0
+    price_usd: float = 0.0
+    value_usd: float = 0.0
+
+
+class Transaction(BaseModel):
+    """A wallet transaction summary."""
+
+    hash: str
+    type: str = "transfer"
+    amount_usd: float = 0.0
+    timestamp: int = 0
+    block_time: datetime | None = None
+    direction: str | None = Field(default=None, description="in | out | self")
+
+
+class Balance(BaseModel):
+    """Wallet balance + token holdings."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    address: str
+    chain: str
+    native_balance: float = 0.0
+    native_symbol: str = ""
+    total_value_usd: float = 0.0
+    tokens: list[TokenHolding] = Field(default_factory=list)
+    fetched_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class ScanFlag(BaseModel):
+    """A risk flag raised by a scan."""
+
+    code: str
+    severity: RiskLevel
+    message: str
+    evidence: dict[str, Any] = Field(default_factory=dict)
+
+
+class WalletAnalysis(BaseModel):
+    """Full wallet analysis — risk + tokens + recent activity."""
+
+    address: str
+    chain: str
+    truncated_address: str
+    risk_score: int = Field(default=0, ge=0, le=100)
+    risk_level: RiskLevel
+    tokens: list[TokenHolding] = Field(default_factory=list)
+    recent_transactions: list[Transaction] = Field(default_factory=list)
+    labels: list[str] = Field(default_factory=list, description="Known labels (e.g. 'Binance', 'Vitalik')")
+    flags: list[ScanFlag] = Field(default_factory=list)
+    total_value_usd: float = 0.0
+    analyzed_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class ScanRequest(BaseModel):
+    """Request body for the wallet scan endpoint."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    address: str = Field(..., min_length=1, max_length=256)
+    chain: str = Field(default="solana")
+    tier: str = Field(default="free", description="free | pro | elite | internal")
+
+    @field_validator("chain")
+    @classmethod
+    def _chain_lowercase(cls, v: str) -> str:
+        return v.lower().strip()
+
+    @field_validator("tier")
+    @classmethod
+    def _tier_lowercase(cls, v: str) -> str:
+        return v.lower().strip()
+
+
+class ScanResult(BaseModel):
+    """Threat scan result."""
+
+    address: str
+    chain: str
+    risk_score: int = Field(default=0, ge=0, le=100)
+    risk_level: RiskLevel
+    flags: list[ScanFlag] = Field(default_factory=list)
+    modules_run: list[str] = Field(default_factory=list)
+    scanned_at: datetime = Field(default_factory=datetime.utcnow)

app/domain/wallet/repository.py

@@ -0,0 +1,112 @@
+"""Repository — async data fetch for wallet info.
+
+Backed by:
+  - Databus (chain-agnostic on-chain data) for balances + transactions
+  - Redis (cached labels) for known wallet labels
+
+This is a thin async wrapper. No business logic.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from app.core.logging import get_logger
+from app.domain.wallet.models import (
+    Balance,
+    TokenHolding,
+    Transaction,
+    Wallet,
+)
+
+log = get_logger(__name__)
+
+LABELS_HASH_KEY = "rmi:wallet_labels"
+
+
+class WalletRepository:
+    """Async data access for wallet info."""
+
+    async def get_balance(self, wallet: Wallet) -> Balance:
+        """Fetch native + token balances for a wallet.
+
+        Backed by Databus. Falls back to empty balance on error.
+        """
+        try:
+            from app.databus.client import get_databus_client  # local import to avoid cycles
+
+            client = get_databus_client()
+            holdings = await client.get_wallet_balance(wallet.address, chain=wallet.chain)
+            return self._parse_balance(wallet, holdings)
+        except Exception as e:
+            log.warning("wallet_balance_fetch_failed", address=wallet.address[:12], error=str(e))
+            return Balance(address=wallet.address, chain=wallet.chain)
+
+    async def get_transactions(
+        self,
+        wallet: Wallet,
+        limit: int = 50,
+    ) -> list[Transaction]:
+        """Fetch recent transactions for a wallet."""
+        try:
+            from app.databus.client import get_databus_client
+
+            client = get_databus_client()
+            txs = await client.get_wallet_transactions(wallet.address, chain=wallet.chain, limit=limit)
+            return [self._parse_tx(tx) for tx in (txs or [])]
+        except Exception as e:
+            log.warning("wallet_tx_fetch_failed", address=wallet.address[:12], error=str(e))
+            return []
+
+    async def get_labels(self, wallet: Wallet) -> list[str]:
+        """Look up known labels for a wallet from Redis."""
+        try:
+            from app.core.redis import get_redis_async
+
+            r = get_redis_async()
+            raw: str | None = await r.hget(LABELS_HASH_KEY, wallet.address.lower())
+            if raw is None:
+                return []
+            import json
+            data = json.loads(raw)
+            return data.get("labels", []) if isinstance(data, dict) else []
+        except Exception as e:
+            log.warning("wallet_label_fetch_failed", address=wallet.address[:12], error=str(e))
+            return []
+
+    @staticmethod
+    def _parse_balance(wallet: Wallet, raw: dict[str, Any]) -> Balance:
+        tokens: list[TokenHolding] = []
+        total = 0.0
+        for h in (raw or {}).get("tokens", [])[:20]:
+            token_info = h.get("token", {}) or {}
+            decimals = int(token_info.get("decimals", 0) or 0) or 1
+            amount = float(h.get("amount", 0) or 0) / (10**decimals)
+            price = float(h.get("priceUsdt", h.get("price_usd", 0)) or 0)
+            value = amount * price
+            total += value
+            tokens.append(TokenHolding(
+                symbol=token_info.get("symbol", "?"),
+                address=token_info.get("address", ""),
+                amount=round(amount, 4),
+                price_usd=price,
+                value_usd=round(value, 2),
+            ))
+        return Balance(
+            address=wallet.address,
+            chain=wallet.chain,
+            native_balance=float((raw or {}).get("native_balance", 0) or 0),
+            native_symbol=(raw or {}).get("native_symbol", ""),
+            total_value_usd=round(total, 2),
+            tokens=tokens,
+        )
+
+    @staticmethod
+    def _parse_tx(tx: dict[str, Any]) -> Transaction:
+        block_time = tx.get("block_time")
+        return Transaction(
+            hash=str(tx.get("trans_id") or tx.get("tx_hash") or tx.get("hash", ""))[:64],
+            type=str(tx.get("flow") or tx.get("type") or "transfer"),
+            amount_usd=float(tx.get("change_amount") or tx.get("amount_usd", 0) or 0),
+            timestamp=int(block_time or 0),
+            direction=tx.get("direction"),
+        )

app/domain/wallet/service.py

@@ -0,0 +1,103 @@
+"""Service — business logic for wallet analysis and scans.
+
+Composes the repository (data access) and the analyzer (pure logic).
+This is the only thing the api/ layer should call.
+"""
+from __future__ import annotations
+
+from app.core.logging import get_logger
+from app.domain.wallet.analyzer import WalletAnalyzer
+from app.domain.wallet.models import (
+    Balance,
+    ScanRequest,
+    ScanResult,
+    Transaction,
+    Wallet,
+    WalletAnalysis,
+)
+from app.domain.wallet.repository import WalletRepository
+
+log = get_logger(__name__)
+
+
+class WalletService:
+    """Orchestrates wallet data fetch and analysis."""
+
+    def __init__(
+        self,
+        repo: WalletRepository | None = None,
+        analyzer: WalletAnalyzer | None = None,
+    ) -> None:
+        self._repo = repo or WalletRepository()
+        self._analyzer = analyzer or WalletAnalyzer()
+
+    async def analyze(
+        self,
+        address: str,
+        chain: str = "solana",
+    ) -> WalletAnalysis:
+        """Full wallet analysis: balance + transactions + labels → risk-scored result."""
+        wallet = Wallet(address=address, chain=chain)
+        log.info("wallet_analysis_started", address=address[:12], chain=chain)
+        balance = await self._repo.get_balance(wallet)
+        txs = await self._repo.get_transactions(wallet, limit=10)
+        labels = await self._repo.get_labels(wallet)
+        analysis = self._analyzer.analyze(
+            address=address,
+            chain=chain,
+            tokens=balance.tokens,
+            recent_transactions=txs,
+            labels=labels,
+        )
+        # Override total value with the balance's authoritative value
+        analysis.total_value_usd = balance.total_value_usd
+        log.info(
+            "wallet_analysis_complete",
+            address=address[:12],
+            risk_score=analysis.risk_score,
+            risk_level=analysis.risk_level.value,
+        )
+        return analysis
+
+    async def get_balance(self, address: str, chain: str = "solana") -> Balance:
+        """Just the balance."""
+        return await self._repo.get_balance(Wallet(address=address, chain=chain))
+
+    async def get_transactions(
+        self,
+        address: str,
+        chain: str = "solana",
+        limit: int = 50,
+    ) -> list[Transaction]:
+        """Just the transactions."""
+        return await self._repo.get_transactions(
+            Wallet(address=address, chain=chain),
+            limit=limit,
+        )
+
+    async def scan(self, req: ScanRequest) -> ScanResult:
+        """Threat scan. Multi-module. Returns a ScanResult.
+
+        The legacy /api/v1/wallet/scan does a freemium rate-limit check
+        before calling the scanner. That check lives in the api/ layer
+        (HTTP concern), not here.
+        """
+        log.info("wallet_scan_started", address=req.address[:12], chain=req.chain, tier=req.tier)
+        # For now: the scan reuses analyze() + adds module-level flags.
+        analysis = await self.analyze(req.address, req.chain)
+        result = ScanResult(
+            address=analysis.address,
+            chain=analysis.chain,
+            risk_score=analysis.risk_score,
+            risk_level=analysis.risk_level,
+            flags=analysis.flags,
+            modules_run=["analyzer"],
+        )
+        log.info(
+            "wallet_scan_complete",
+            address=req.address[:12],
+            risk_score=result.risk_score,
+            risk_level=result.risk_level.value,
+            flag_count=len(result.flags),
+        )
+        return result