Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.finwatch.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Understanding FinWatch Actions: A Hybrid Approach to Decision-Making

In FinWatch, determining the final action for a transaction is not based on a single rule’s output. Instead, it uses a sophisticated, multi-layered hybrid model that provides both the immediate certainty of explicit commands and the contextual nuance of an aggregated risk assessment. This document explains how individual rule verdicts and the final consolidated verdict work together. An Action is the operation performed when a rule’s conditions are met. It is defined in the then block and consists of a verdict, a risk score, and a reason. This output is passed to the Risk Consolidator, which uses the information to calculate a final risk profile for the transaction and trigger external workflows.

​
The Two Layers of Decision-Making

When a transaction is processed, decision-making happens in two distinct layers:
  1. The Individual Rule Verdict: Each watchscript .ws rule that triggers against the transaction produces its own verdict (block, review, alert, or approve (useful for whitelisting)) and a corresponding score. This serves as an immediate, self-contained signal from that specific rule.
  2. The Consolidated Verdict: After all rules have been executed, the RiskConsolidator service takes all the individual verdicts and scores as input. It then performs a final calculation to produce a single, authoritative outcome for the transaction, consisting of a FinalRiskScore, FinalVerdict, and RiskLevel.
 This is important because rules are dynamic and multiple rules can apply to a single transaction - in scenarios like this a consolidated verdict is applied. Structure: 
when
    .........
then
    block
    score 0.9
    reason "Transaction originated from a blacklisted IP address.
  • score: A numerical value from 0.0 to 1.0 indicating the severity of the event.
  • reason: A descriptive string explaining why the rule was triggered. All reasons from triggered rules are aggregated by the Risk Consolidator.

​
The Decision-Making Hierarchy

The RiskConsolidator does not simply average the scores. It follows a strict, hierarchical order of operations to determine the FinalVerdict. This ensures that critical, high-confidence signals are never ignored.
  1. The block Override (Highest Priority):
    • The system first checks if any of the triggered rules returned a block verdict.
    • If even one rule has a block verdict, the FinalVerdict is immediately set to block. The process stops here. This is an absolute override for zero-tolerance scenarios like sanction list hits.
  2. Score-Based Escalation:
    • If no rule issued a block verdict, the RiskConsolidator calculates the FinalRiskScore by averaging the scores of all triggered rules.
    • It then checks this score against thresholds:
      • If FinalRiskScore >= 0.7, the FinalVerdict is escalated to block.
      • If FinalRiskScore >= 0.5, the FinalVerdict is escalated to review.
  3. The review Guarantee:
    • After the score-based check, the system checks if any of the triggered rules had a review verdict.
    • If so, and if the FinalVerdict hasn’t already been escalated to block, the FinalVerdict is set to review. This ensures that a transaction flagged for review is never implicitly approved, even if its final score is low.
  4. The approve Default (Lowest Priority):
    • If none of the conditions above are met (i.e., no block override, the score is below 0.5, and no rule forced a review), the FinalVerdict defaults to approve

​
Practical Scenarios

Scenario A: Sanctions Hit
  • A transaction triggers three rules:
    1. SanctionsList: block, score: 1.0
    2. NewAccount: review, score: 0.5
    3. LateNightTxn: alert, score: 0.3
  • Result: The FinalVerdict is block. The block override from the SanctionsList rule is the highest priority and immediately ends the decision process.
Scenario B: Suspicious Combination
  • A transaction triggers two rules:
    1. HighVelocity: review, score: 0.8
    2. UnusualCountry: review, score: 0.6
  • Result: The FinalVerdict is block.
    1. No rule has a block verdict, so the override is skipped.
    2. The FinalRiskScore is calculated: (0.8 + 0.6) / 2 = 0.7.
    3. Since the score is >= 0.7, the verdict is escalated to block.
Scenario C: Low-Risk Anomaly
  • A transaction triggers one rule:
    1. LateNightTxn: alert, score: 0.4
  • Result: The FinalVerdict is approve.
    1. No block override.
    2. The FinalRiskScore is 0.4, which is below the 0.5 threshold for review.
    3. No rule forced a review.
    4. The system falls through to the default case, resulting in approve.