SETTLEMENT_RISK_MODEL_LAYER.md

Purpose

Define a deterministic governance-level risk scoring model for settlement decisions without performing execution-layer operations.

Scope

This layer evaluates settlement risk from governance-visible inputs and returns controls that can be required by policy and authorization. It does not execute transfers, escrow, or KYC workflows.

Definitions

• riskScore: integer in [0,100].
• riskBand: one of LOW, MED, HIGH.
• requiredControls[]: governance controls required before or during settlement progression.
• Input tuple: (ledgerHistory, railType, custodyType, providerId, amountValue, assetKind, escrowMode).

Normative Rules

1. Risk scoring MUST be deterministic and reproducible from the same inputs.
2. Scoring MUST NOT use ML models, randomness, wall-clock entropy, or external network calls.
3. Risk outputs MAY guide authorization decisions but MUST NOT mutate ledger state by themselves.
4. Controls MUST be enforced through governance actions (for example via ACCESS_DECISION gating and policy rules).

Risk Factors

Each factor contributes integer points in [0,20].

1. Counterparty Risk (F_cp)

• INTERNAL trusted provider: 2
• known regulated provider: 6
• unknown/unrated provider: 14
• high-risk counterparty flag in history: 20

2. Custody Risk (F_cu)

• PLATFORM: 8
• PARTNER_ESCROW: 12
• SELF_CUSTODY: 18

3. Rail Finality Risk (F_rf)

• INTERNAL_LEDGER: 4
• BANK: 10
• VASP: 14
• BLOCKCHAIN: 16

4. FX/Volatility Risk (F_fx)` (asset-kind proxy)

• stable fiat-like asset: 3
• tokenized fiat/stable asset: 8
• volatile crypto asset: 16

5. Operational Risk (F_op) Derived from ledger history for same subjectId / provider class:

• no recent rail errors: 4
• one recent rail error: 10
• repeated rail errors: 18

6. Compliance Risk (F_co)

• full compliance profile known: 4
• partial profile: 10
• enhanced due diligence required: 18

Deterministic Scoring Formula

Weighted linear score:

raw = 0.18*F_cp + 0.17*F_cu + 0.20*F_rf + 0.17*F_fx + 0.14*F_op + 0.14*F_co

riskScore = round(5 * raw) then clamp to [0,100].

Band mapping:

• LOW if riskScore <= 33
• MED if 34 <= riskScore <= 66
• HIGH if riskScore >= 67

Required Controls Mapping

Controls set is deterministic by band plus hard triggers.

Baseline by band:

• LOW: require milestones
• MED: require escrow, require milestones, require 2-person approval
• HIGH: require escrow, require milestones, require 2-person approval, require enhanced KYC, require max amount caps, require delayed release

Hard triggers:

• SELF_CUSTODY => add require enhanced KYC
• volatile crypto asset + high amount => add require delayed release
• repeated rail errors => add require max amount caps

Policy Binding

• Policy referenced by policyHash MAY declare minimum controls per risk band.
• ACCESS_DECISION for settlement actions SHOULD validate that required controls are satisfied before ALLOW.
• Controls are governance preconditions; they are not execution commands.

Scenarios (Deterministic Examples)

Scenario 1: Low-risk internal settlement

Inputs:

• railType=INTERNAL_LEDGER, custodyType=PLATFORM, provider known internal, asset stable fiat, no rail errors, full compliance.

Factors:

• F_cp=2, F_cu=8, F_rf=4, F_fx=3, F_op=4, F_co=4
• raw = 0.18*2 + 0.17*8 + 0.20*4 + 0.17*3 + 0.14*4 + 0.14*4 = 4.15
• riskScore = round(5*4.15)=21, riskBand=LOW

Recommended controls:

• require milestones

Scenario 2: Medium-risk bank settlement with partner escrow

Inputs:

• railType=BANK, custodyType=PARTNER_ESCROW, known regulated provider, tokenized fiat/stable asset, one recent rail error, partial compliance.

Factors:

• F_cp=6, F_cu=12, F_rf=10, F_fx=8, F_op=10, F_co=10
• raw = 9.14
• riskScore = round(5*9.14)=46, riskBand=MED

Recommended controls:

• require escrow
• require milestones
• require 2-person approval

Scenario 3: High-risk blockchain self-custody flow

Inputs:

• railType=BLOCKCHAIN, custodyType=SELF_CUSTODY, unknown provider, volatile crypto asset, repeated rail errors, enhanced due diligence required.

Factors:

• F_cp=14, F_cu=18, F_rf=16, F_fx=16, F_op=18, F_co=18
• raw = 16.40
• riskScore = round(5*16.40)=82, riskBand=HIGH

Recommended controls:

• require escrow
• require milestones
• require 2-person approval
• require enhanced KYC
• require max amount caps
• require delayed release

Mapping to Code

• Authorization gates conceptually align with settlement authorization verifiers in packages/core/settlement/verifySettlementAuthorization.ts and verifySettlementEventAuthorization.ts.
• Lifecycle-sensitive controls conceptually align with packages/core/settlement/verifySettlementLifecycle.ts.
• Risk model output is governance advisory input; append/build record flows remain in packages/core/settlement/*.

Non-normative Notes

• This model is intentionally arithmetic and policy-driven to preserve auditability.
• Factor scales can evolve only through explicit policy/document/version updates.

Testability

• Unit tests SHOULD verify identical input tuple yields identical (riskScore, riskBand, requiredControls[]).
• Boundary tests MUST verify exact transitions at scores 33/34 and 66/67.
• Scenario tests MUST reproduce the three worked examples exactly.
• Policy-binding tests SHOULD verify insufficient controls produce authorization denial for settlement actions.