Skip to main content

​
Overview

The V3 risk framework is a versioned taxonomy of 7 categories and 42 criteria that the scoring pipeline evaluates for every vault. Each criterion resolves to pass, warn, or fail per vault; criteria roll up into category scores; category scores roll up into a single composite, which is then mapped to a letter grade. This page narrates the framework. The framework itself lives at GET /api/v3/framework — that endpoint is the source of truth for the category list, the criteria within each category, and which criteria are live versus planned.
For the endpoint payload format and the polarity / upstream-floor mechanics, see the V3 overview.

​
Why the framework is an API

The framework lives behind a public, cacheable endpoint instead of being maintained as a parallel table in the docs. There’s one reason: the docs cannot drift from the API. When the API adds a criterion or moves a planned criterion to live, the next call to GET /api/v3/framework reflects that change immediately. Clients that fetch the framework get the same view the scoring pipeline used to score their last response. This is the load-bearing claim from RFC-019 § “Framework versioning” — the framework is data, not documentation. You can render it client-side, ship it in your own admin UI, or pin a snapshot for reproducible scoring. The endpoint is public (no API key, no billing) and cacheable for 5 minutes (Cache-Control: public, max-age=300, stale-while-revalidate=60). Hit it freely.

​
Categories at a glance

KeyNameWeightStatus
smart_contractSmart contract0.20Live
operational_governanceOperational governance0.20Live
asset_collateralAsset & collateral0.15Live
market_liquidityMarket & liquidity0.20Live
counterpartyCounterparty0.10Live
hack_exploit_historyHack & exploit history0.15Live
chain_infrastructureChain infrastructure0.00Stub (reserved, zero weight)
chain_infrastructure carries zero weight today and is included so the schema is stable — its weight may become non-zero in a future scheme version, at which point existing clients keep working without any code changes. The weights always sum to 1.00. Today the six live categories carry the full weight (chain_infrastructure is 0.00). If chain_infrastructure gains weight in a future scheme version, the live-category weights are rebalanced downward to make room — so the total stays 1.00 rather than the new category being added on top.

​
Composite derivation

The composite score is a two-step calculation.

​
Step 1 — framework composite

For each category that has live criteria, compute a category score (0–100, higher = worse). Multiply each category score by its weight and sum: 
framework_composite = Σ ( category_score × category_weight )

​
Step 2 — upstream floor

Take the maximum of the framework composite and the upstream risk signal: 
composite.score = max(framework_composite, upstream_risk)
Where upstream_risk is a verbatim copy of risk.overallRisk from the v2 envelope on the same response. When the upstream value wins, composite.clamped_by_upstream is true. See The upstream floor on the overview for why this matters.
Polarity is risk-magnitude direction: higher = worse. Category scores, contributor scores, and the composite all run 0 (lowest risk) to 100 (highest risk). The letter grade then maps in the conventional direction — A+ is best, F is worst. See the polarity warning on the V3 overview for the worked example.

​
Letter grade mapping

The composite score maps through the active grading scheme to a letter grade (A+–F) and a star count (1–5). It is a risk rating: lower risk earns a better grade — A+ is the lowest risk, F is the highest. The grading scheme is versioned independently of the framework via ?grading_scheme. The default is v2, the standard 11-band scale below; v1 is the frozen legacy scale (it uses an E band and has no C+) and stays pinnable.
GradeRisk scoreStarsGradeRisk scoreStars
A+0–5★★★★★C+47–56★★★☆☆
A6–12★★★★★C57–66★★★☆☆
A-13–20★★★★★C-67–77★★★☆☆
B+21–28★★★★☆D78–88★★☆☆☆
B29–37★★★★☆F89–100★☆☆☆☆
B-38–46★★★★☆

​
Coverage disclosure

Every V3 vault detail response includes a coverage block: 
{
  "coverage": {
    "framework_version": "v1",
    "total_criteria": 42,
    "live_criteria": 28,
    "per_category": { /* live + total counts per WebacyCategory */ }
  }
}
This is part of the framework contract, not a side note. A category score where 3 of 6 criteria are live is not the same statement as a category score where all criteria are live, and clients deserve to see the difference. Surface the per-category coverage alongside the score whenever you display category-level risk. The 42-criteria total counts every criterion in the taxonomy, live or not. The 28-criteria live count is what the scoring pipeline actually evaluated. The remaining 14 come online over the next several releases.

​
Pinning the framework

Both the framework version and the grading scheme are pinnable via query parameters:
ParameterDefaultBehavior
?framework_version=v1v1Selects which taxonomy version to score against. Unknown → 400 with { error, supported_versions: ['v1'] }.
?grading_scheme=v2v2Selects which composite-to-letter mapping to use. Unknown → 400 with { error, supported_schemes: ['v1', 'v2'] }.
Both default, but pinning is the contract. Clients that don’t pin will silently re-score when a new framework or scheme version ships. Pin from day one; the migration guide has the full story. The framework endpoint accepts the same ?framework_version=v1 parameter — pass it to get the exact taxonomy that a pinned vault detail call would use.

Framework Taxonomy

The canonical, machine-readable framework. Call this for the current category and criteria list.

Vault Detail (V3)

Request/response reference for the per-vault scoring endpoint.

Vault Risk V3 Overview

Polarity, upstream floor, and the V3 versioning contract in one page.

v2 → V3 Migration

Endpoint mapping, deprecation contract, and pinning guidance.