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

KeyNameWeightWhat it measuresStatus
smart_contractSmart contract0.20Audit history, contract ownership model, timelock presence, and Webacy’s real-time contract analysisLive
operational_governanceOperational governance0.20Multisig controls, admin key practices, and operational hygieneLive
asset_collateralAsset & collateral0.15Collateral quality, asset integrity, reserve transparency, backing type, and share-price (depeg) stabilityLive
market_liquidityMarket & liquidity0.20On-chain liquidity depth and exit/redemption accessibilityLive
counterpartyCounterparty0.10Exposure to external protocols, custodians, and other dependenciesLive
hack_exploit_historyHack & exploit history0.15Known exploits or security incidentsLive
chain_infrastructureChain infrastructure0.00Underlying-chain risk (reserved — zero weight today)Stub (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.

​
What each category measures

Each criterion resolves to pass, warn, or fail, and the criteria within a category roll up into that category’s 0–100 score; Composite derivation below shows how those category scores combine into the grade. The breakdown here explains what each category covers and names representative live criteria — the framework endpoint is the canonical, always-current source for the full criteria list and each criterion’s live/planned status. For the underlying V2 signal-level breakdown that rolls into these categories, see Vault Ratings → Sub-scores.
Code-level safety of the vault contracts: audit coverage, the contract ownership and admin model, upgradeability, and timelock protection. Complemented by Webacy’s real-time contract analysis — our proprietary scan for reentrancy, unchecked calls, and malicious external calls.Representative live criteria: audited, owner_is_multisig, timelock_present, mint_cap_present.
How the vault is controlled and operated day to day: multisig controls, admin-key practices, monitoring of privileged changes, and operational hygiene.Representative criteria: admin_key_changes, timelock_changes.
Quality and integrity of the vault’s underlying assets: collateral quality, asset integrity, reserve transparency, backing type, and share-price (depeg) stability.Representative criteria: share_price_stable, supply_reserves_reconciliation.Related: for real-time peg monitoring of stablecoins and pegged assets, see the Depeg Monitor; for structural risk scoring of stablecoins and RWA tokens, see RWA Risk.
Whether positions can be entered and exited safely: on-chain liquidity depth, exit and redemption liquidity, holder concentration, and anomalous mint/burn or transfer flow.Representative criteria: large_holder_concentration, mint_burn_anomaly, large_transaction_alerts.
Exposure to external entities the vault depends on: protocol and custodian dependencies, concentration in a single counterparty, and centralized points of failure.The live criteria for this category are listed in the framework endpoint.
Track record of security incidents: known exploits, compromises, or incidents affecting the vault, its protocol, or its dependencies.Representative criteria: no_exploit_history.
Risk inherited from the underlying chain: liveness, validator or sequencer centralization, reorg exposure, and bridge security. This category is reserved and carries zero weight today, so no criteria are live yet.

​
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.
These complementary Webacy products score adjacent risk surfaces independently of the vault composite — use them alongside V3 vault risk for fuller coverage.

Contract Risk

Real-time smart contract security analysis and vulnerability detection.

Depeg Monitor

Real-time peg-deviation risk for 600+ stablecoins and pegged assets.

RWA Risk (v3)

Structural risk scoring for stablecoins and real-world asset tokens.