> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V3 Framework Methodology

> Learn how the Webacy V3 risk framework is structured, how composite vault scores are derived from category contributors, and why the taxonomy is API-driven.

## 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 /v3/framework`](/api-reference/vault-risk-v3/get-framework) — that endpoint is the source of truth for the category list, the criteria within each category, and which criteria are live versus planned.

<Tip>
  For the endpoint payload format and the polarity / upstream-floor mechanics, see the [V3 overview](/api-reference/vault-risk-v3/v3-overview).
</Tip>

***

## 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 /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

| Key                      | Name                   | Weight | What it measures                                                                                           | Status                       |
| ------------------------ | ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `smart_contract`         | Smart contract         | 0.20   | Audit history, contract ownership model, timelock presence, and Webacy's real-time contract analysis       | Live                         |
| `operational_governance` | Operational governance | 0.20   | Multisig controls, admin key practices, and operational hygiene                                            | Live                         |
| `asset_collateral`       | Asset & collateral     | 0.15   | Collateral quality, asset integrity, reserve transparency, backing type, and share-price (depeg) stability | Live                         |
| `market_liquidity`       | Market & liquidity     | 0.20   | On-chain liquidity depth and exit/redemption accessibility                                                 | Live                         |
| `counterparty`           | Counterparty           | 0.10   | Exposure to external protocols, custodians, and other dependencies                                         | Live                         |
| `hack_exploit_history`   | Hack & exploit history | 0.15   | Known exploits or security incidents                                                                       | Live                         |
| `chain_infrastructure`   | Chain infrastructure   | 0.00   | Underlying-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](#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](/api-reference/vault-risk-v3/get-framework) 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](/vault-ratings#sub-scores).

On the vault detail response, each criterion doesn't just report a verdict — it shows its work. Every criterion includes a `name` (a human-readable label for the check) and, when a value is available, an `evidence` object with the actual numbers behind the `pass`/`warn`/`fail` — for example holder concentration or an audit count and auditor tier. This is the per-criterion risk-data breakdown: the same checks described below, annotated with the measurements that produced each verdict.

Above the criteria, `composite.drivers` ranks the penalty-driving subcategories worst-first (descending by weighted contribution), so you can read a grade top-down: which subcategory cost the most points, then the specific criteria inside it and their evidence. This is what answers a question like "why is USDS an `A-` and not an `A`?" — the drivers name the subcategory that took the points, and the criterion-level evidence shows the numbers that drove it. These fields are additive; the response includes them when the data is available. See the [Explainability](/api-reference/vault-risk-v3/v3-overview#explainability) section on the V3 overview for the response shape, and the [Vault Detail (V3) reference](/api-reference/vault-risk-v3/get-vault-risk-detail-v3) for the full field schema.

<AccordionGroup>
  <Accordion title="Smart contract — weight 0.20">
    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](/api-reference/contract-risk/get-a-real-time-analysis-for-a-given-contract-address) — our proprietary scan for reentrancy, unchecked calls, and malicious external calls.

    Representative live criteria: `audited`, `owner_is_multisig`, `timelock_present`, `mint_cap_present`.
  </Accordion>

  <Accordion title="Operational governance — weight 0.20">
    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`.
  </Accordion>

  <Accordion title="Asset & collateral — weight 0.15">
    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](/api-reference/depeg-monitor); for structural risk scoring of stablecoins and RWA tokens, see [RWA Risk](/api-reference/rwa-v3).
  </Accordion>

  <Accordion title="Market & liquidity — weight 0.20">
    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`.
  </Accordion>

  <Accordion title="Counterparty — weight 0.10">
    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](/api-reference/vault-risk-v3/get-framework).
  </Accordion>

  <Accordion title="Hack & exploit history — weight 0.15">
    Track record of security incidents: known exploits, compromises, or incidents affecting the vault, its protocol, or its dependencies.

    Representative criteria: `no_exploit_history`.
  </Accordion>

  <Accordion title="Chain infrastructure — weight 0.00 (reserved)">
    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.
  </Accordion>
</AccordionGroup>

***

## 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:

```text theme={null}
framework_composite = Σ ( category_score × category_weight )
```

### Step 2 — upstream floor

Take the maximum of the framework composite and the upstream risk signal:

```text theme={null}
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](/api-reference/vault-risk-v3/v3-overview#the-upstream-floor) on the overview for why this matters.

<Warning>
  **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](/api-reference/vault-risk-v3/v3-overview#score-polarity) on the V3 overview for the worked example.
</Warning>

### 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.

| Grade                           | Risk score | Stars | Grade                           | Risk score | Stars |
| :------------------------------ | :--------- | :---- | :------------------------------ | :--------- | :---- |
| <span class="gb gb-a">A+</span> | 0–5        | ★★★★★ | <span class="gb gb-c">C+</span> | 47–56      | ★★★☆☆ |
| <span class="gb gb-a">A</span>  | 6–12       | ★★★★★ | <span class="gb gb-c">C</span>  | 57–66      | ★★★☆☆ |
| <span class="gb gb-a">A-</span> | 13–20      | ★★★★★ | <span class="gb gb-c">C-</span> | 67–77      | ★★★☆☆ |
| <span class="gb gb-b">B+</span> | 21–28      | ★★★★☆ | <span class="gb gb-d">D</span>  | 78–88      | ★★☆☆☆ |
| <span class="gb gb-b">B</span>  | 29–37      | ★★★★☆ | <span class="gb gb-f">F</span>  | 89–100     | ★☆☆☆☆ |
| <span class="gb gb-b">B-</span> | 38–46      | ★★★★☆ |                                 |            |       |

***

## Coverage disclosure

Every V3 vault detail response includes a `coverage` block:

```jsonc theme={null}
{
  "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:

| Parameter               | Default | Behavior                                                                                                             |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `?framework_version=v1` | `v1`    | Selects which taxonomy version to score against. Unknown → `400` with `{ error, supported_versions: ['v1'] }`.       |
| `?grading_scheme=v2`    | `v2`    | Selects 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](/api-reference/migrations/v2-to-v3#pin-from-day-one) 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.

***

## Related resources

<CardGroup cols={2}>
  <Card title="Framework Taxonomy" icon="sitemap" href="/api-reference/vault-risk-v3/get-framework">
    The canonical, machine-readable framework. Call this for the current category and criteria list.
  </Card>

  <Card title="Vault Detail (V3)" icon="vault" href="/api-reference/vault-risk-v3/get-vault-risk-detail-v3">
    Request/response reference for the per-vault scoring endpoint.
  </Card>

  <Card title="Vault Risk V3 Overview" icon="circle-info" href="/api-reference/vault-risk-v3/v3-overview">
    Polarity, upstream floor, and the V3 versioning contract in one page.
  </Card>

  <Card title="v2 → V3 Migration" icon="arrow-right" href="/api-reference/migrations/v2-to-v3">
    Endpoint mapping, deprecation contract, and pinning guidance.
  </Card>
</CardGroup>

## Related Webacy risk coverage

These complementary Webacy products score adjacent risk surfaces independently of the vault composite — use them alongside V3 vault risk for fuller coverage.

<CardGroup cols={3}>
  <Card title="Contract Risk" icon="file-code" href="/api-reference/contract-risk/get-a-real-time-analysis-for-a-given-contract-address">
    Real-time smart contract security analysis and vulnerability detection.
  </Card>

  <Card title="Depeg Monitor" icon="chart-line" href="/api-reference/depeg-monitor">
    Real-time peg-deviation risk for 600+ stablecoins and pegged assets.
  </Card>

  <Card title="RWA Risk (v3)" icon="magnifying-glass-chart" href="/api-reference/rwa-v3">
    Structural risk scoring for stablecoins and real-world asset tokens.
  </Card>
</CardGroup>