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, exposes a new phase, 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

KeyNamePhase 1 weightPhase 1 status
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 (lights up in Phase 2B)
chain_infrastructure carries zero weight in Phase 1 and is included so the schema is stable — its weight becomes non-zero in Phase 2B, at which point existing clients keep working without any code changes. The weights always sum to 1.00. In Phase 1 the six live categories carry the full weight (chain_infrastructure is 0.00). In Phase 2B, when chain_infrastructure gains weight, 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 (0–5). The grading scheme is versioned independently of the framework via ?grading_scheme=v1. Phase 1 ships v1 only.

​
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 regardless of phase. The 28-criteria live count is what the scoring pipeline actually evaluated. Phase 2A, 2B, 4, and 5 bring the remaining 14 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=v1v1Selects which composite-to-letter mapping to use. Unknown → 400 with { error, supported_schemes: ['v1'] }.
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.

​
Roadmap

The unlive criteria expose a phase field that tracks when they’re scheduled to ship:
PhaseTheme
Phase 2AReal-world assets (/api/v3/rwa/*)
Phase 2BChain infrastructure category lights up (becomes non-zero weight)
Phase 4Expanded counterparty and hack/exploit signals
Phase 5Formal verification and other long-tail criteria
The roadmap is encoded in the live framework endpoint — calling it gives you the current schedule, not a docs snapshot.

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.