SETTLEMENT_RISK_MODEL_LAYER.md
Purpose
Define a deterministic governance-level risk scoring model for settlement decisions without performing execution-layer operations.
Loading module
Resolving locale, route permissions, and workspace projection.
Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 10_normative | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: GOVERNANCE_ADMIN
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
Define a deterministic governance-level risk scoring model for settlement decisions without performing execution-layer operations.
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.
riskScore: integer in [0,100].riskBand: one of LOW, MED, HIGH.requiredControls[]: governance controls required before or during settlement progression.(ledgerHistory, railType, custodyType, providerId, amountValue, assetKind, escrowMode).ACCESS_DECISION gating and policy rules).Each factor contributes integer points in [0,20].
F_cp)F_cu)PLATFORM: 8PARTNER_ESCROW: 12SELF_CUSTODY: 18F_rf)INTERNAL_LEDGER: 4BANK: 10VASP: 14BLOCKCHAIN: 16F_fx)` (asset-kind proxy)F_op)
Derived from ledger history for same subjectId / provider class:F_co)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 <= 33MED if 34 <= riskScore <= 66HIGH if riskScore >= 67Controls set is deterministic by band plus hard triggers.
Baseline by band:
LOW: require milestonesMED: require escrow, require milestones, require 2-person approvalHIGH: require escrow, require milestones, require 2-person approval, require enhanced KYC, require max amount caps, require delayed releaseHard triggers:
SELF_CUSTODY => add require enhanced KYCrequire delayed releaserequire max amount capspolicyHash MAY declare minimum controls per risk band.ACCESS_DECISION for settlement actions SHOULD validate that required controls are satisfied before ALLOW.Inputs:
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=4raw = 0.18*2 + 0.17*8 + 0.20*4 + 0.17*3 + 0.14*4 + 0.14*4 = 4.15riskScore = round(5*4.15)=21, riskBand=LOWRecommended controls:
require milestonesInputs:
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=10raw = 9.14riskScore = round(5*9.14)=46, riskBand=MEDRecommended controls:
require escrowrequire milestonesrequire 2-person approvalInputs:
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=18raw = 16.40riskScore = round(5*16.40)=82, riskBand=HIGHRecommended controls:
require escrowrequire milestonesrequire 2-person approvalrequire enhanced KYCrequire max amount capsrequire delayed releasepackages/core/settlement/verifySettlementAuthorization.ts and verifySettlementEventAuthorization.ts.packages/core/settlement/verifySettlementLifecycle.ts.packages/core/settlement/*.(riskScore, riskBand, requiredControls[]).