# wallet_risk

OTP application for fraud/risk scoring orchestration, signal accumulation, case escalation, and risk traceability.

Phase 7 — Compliance, Risk Maturity, Audit Readiness.

## Responsibilities

- Risk signal capture from transfer, auth, and integration events.
- Deterministic risk scoring via rule-based scoring engine.
- Aggregated user risk profiles (per-user score + status band).
- Risk case escalation to investigators and compliance.
- Audit-traceable risk events with correlation IDs.

## Public Interface

### Commands

| Module | Description |
|---|---|
| `WalletRisk.Commands.FlagRiskSignal` | Flag a new risk signal for a user; updates risk profile score. |
| `WalletRisk.Commands.EscalateCase` | Open a risk escalation case; assigns investigator or escalates to compliance. |

### Queries

| Module | Description |
|---|---|
| `WalletRisk.Queries.ScoreTransferRisk` | Compute deterministic risk score for a transfer (read-only). |
| `WalletRisk.Queries.GetRiskProfile` | Get aggregated risk profile for a user. |

## Domain Events

| Event | Trigger |
|---|---|
| `RiskScored.v1` | Risk score computed after signal flagging. |
| `RiskEscalated.v1` | Risk case escalated (to investigator or compliance). |
| `RiskCleared.v1` | Risk case resolved/cleared (emitted by future resolve command). |

## Scoring Engine

Deterministic, stateless — `WalletRisk.ScoringEngine`:
- Score = min(sum of signal contributions, 100).
- Bands: 0..29 = `:normal`, 30..59 = `:flagged`, 60..84 = `:under_review`, 85..100 = `:blocked`.

## Risk Signal Types

| Signal Type | Default Contribution |
|---|---|
| `manual_flag` | 40 |
| `pattern_match` | 35 |
| `failed_auth_spike` | 30 |
| `unusual_velocity` | 25 |
| `high_value_transfer` | 20 |
| `geo_anomaly` | 15 |
| `device_change` | 10 |

## RiskCase State Machine

```
open -> under_investigation -> resolved (terminal)
open -> under_investigation -> escalated_to_compliance (terminal)
open -> escalated_to_compliance (terminal, direct)
```

## Boundary Rules

- `wallet_risk` may depend on: `wallet_shared_kernel`, `wallet_observability`, `wallet_events`.
- `wallet_risk` must NOT depend on: `wallet_ledger`, `wallet_accounts` directly — receive signals via events/commands from `wallet_transfers`.
- `wallet_compliance` is a peer domain; cross-boundary contract is event-based.

## Compliance-Risk Boundary Contract

| Flow | Direction | Mechanism |
|---|---|---|
| High-risk transfer alert → AML case | wallet_risk → wallet_compliance | `RiskScored.v1` event (compliance subscribes) |
| SAR escalation originated from risk case | wallet_risk → wallet_compliance | `EscalateCase` with `auto_escalate_to_compliance: true` |
| KYC approval unlocks transfer risk | wallet_compliance → wallet_risk | `KycCaseApproved.v1` event (risk lowers user score) |

## Tests

```
mix test apps/wallet_risk
```