{ "openapi": "3.1.0", "info": { "title": "CR141 Risk API", "summary": "Pre-execution liquidation risk for Compound governance proposals, replayed against frozen, audited artifacts.", "description": "**API status.** The OpenAPI document is public and stable; the API itself is a self-hosted reference instance. No public API host is bound at this time. Run `docker compose up -d` in the repository to get the same four endpoints on `http://localhost:8000`, with Swagger UI at `/docs`. Nothing in this document requires a live host to be useful: the schemas and the captured examples are complete enough to generate a client.\n\nReplays of executed Compound governance proposals against the block before execution. Four endpoints, all backed by the frozen CR141-001 artifacts. Contract: RISK_API_V1.md. The version string is read from ./VERSION at import, so this document, the dashboard label and the documentation cannot disagree.\n\n**Why this exists.** A governance proposal that lowers collateral factors is a liquidation event scheduled in advance. This API answers, per proposal: which accounts does it push underwater, did the engine's prediction match the chain exactly, and what would have happened under a different collateral factor.\n\n**What makes the answers trustworthy.** The predictions were falsified against 28 executed proposals: 474 predicted flips, 474 observed, difference 0, exact set equality 28/28. The audit is closed and reproducible offline from `rerun_package/`.\n\n**No live RPC.** Every response is computed from frozen artifacts shipped in the image. Nothing here depends on Alchemy, an archive node, or network availability — which is why the endpoints answer in tens of milliseconds and cannot drift.\n\n**Contract discipline.** Responses are declared Pydantic models, so `/docs` shows real field names and real examples rather than an empty schema. Fields that would be invented by guessing are omitted instead of nulled; failures return an error code with the command that fixes them rather than a plausible zero.", "version": "1.3.3" }, "paths": { "/evidence/status": { "get": { "tags": [ "Evidence" ], "summary": "Is the audit closed?", "description": "Returns the frozen audit status for CR141-001. Derived from the audited corpus of 28 proposals and 141 CF changes.\n\nThis is the evidence surface: `audit_closed` is true only when all eight gates pass, and `exactness` states the falsification measurement — predicted vs observed flip counts across the whole corpus (`474 / 474`, difference `0`, exact set equality `28/28`). Those numbers are measured from the verdicts, never asserted from a criteria document.\n\n`cache` says where the gate status came from: `frozen: true` means it was pre-measured at image build time and no evaluator is running in this deployment; `null` means an evaluator ran during this request. A consumer that needs to know how old the verdict is should read `cache.generated_utc` rather than assume `audit_closed` was measured just now.\n\n`reproducible_package` points at the offline rerun kit: the audit can be re-verified on a machine with no network access.", "operationId": "evidence_status_evidence_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceStatus" } } } }, "503": { "description": "audit evaluator unavailable and no baked status cache — the API refuses to return a fabricated 'true'" } } } }, "/proposal/{pid}": { "get": { "tags": [ "Proposal" ], "summary": "One proposal: targets, population, predicted vs observed flips", "description": "Returns the audited impact record for a governance proposal.\n\n`markets` lists every CF change the proposal executed (before/after in both wei and decimal). `population` is every account the proposal could reach; `targets` is the subset that entered a changed market; `predicted_flips` and `observed_flips` are the engine's prediction and the chain's outcome, and `exact_set_equality` says whether the two sets are identical — not merely equal in size. `density_pct` is flips per 100 targets.\n\n`route_a_b` is an object on purpose. It reports how often Route A and Route B agree on a *numerator*, and how often they disagree — but `disagree_is_artefact` is true and the reference is CR141-INV-001: the disagreements come from nested-floor truncation and coexist with identical flip sets. A bare integer here would invite a consumer to read 1,105 disagreements as an error rate. They are not errors.\n\n`block` is the execution block and `block_evaluated` is the block the engine read (`block - 1` by contract).", "operationId": "get_proposal_proposal__pid__get", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string", "title": "Pid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proposal" } } } }, "400": { "description": "pid is not an integer" }, "404": { "description": "pid is not in the CR141-001 corpus" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/proposal/{pid}/flips": { "get": { "tags": [ "Proposal" ], "summary": "Flipped accounts, optionally with driver-market attribution", "description": "Returns all predicted/observed flip accounts, optionally including driver attribution.\n\nOne row per account whose predicted buffer goes negative. `predicted_wei` is the engine's buffer and `observed_wei` the chain's, both as signed wei strings (JSON numbers would lose precision above 2^53); `margin_wei` is the distance to the zero crossing and `agrees` says whether prediction and observation land on the same side.\n\nWith `?attribution=true` each row gains `driver_market` — the market with the largest negative contribution — plus its wei delta and the full `contributions` breakdown. `driver_is_heuristic` is true because the driver is chosen by largest contribution, not proven by counterfactual; `joint_cause` is true when no single market alone flips the account.\n\nWithout attribution those fields are **absent, not null** (`exclude_none`): null would read as 'asked, and there is no driver', which is a claim this endpoint refuses to make. For the same reason `next_cursor` disappears on the last page — its absence means end of set.\n\nAttribution needs the per-market `CONTRIB-*.json` sidecar. A pid without one returns 501 with the exact command to regenerate it, rather than a silently empty driver field.", "operationId": "get_flips_proposal__pid__flips_get", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string", "title": "Pid" } }, { "name": "attribution", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Attribution" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlipPage" } } } }, "400": { "description": "pid not an integer, or cursor past end of set" }, "404": { "description": "pid is not in the CR141-001 corpus" }, "501": { "description": "attribution requested but no CONTRIB sidecar exists" }, "503": { "description": "attribution engine unavailable" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/simulate": { "post": { "tags": [ "Simulation" ], "summary": "What would happen if a collateral factor were different?", "description": "Runs a counterfactual simulation using the audited contribution model.\n\nThis is the only endpoint that answers a question the corpus cannot: it takes a collateral factor the governance proposal did **not** execute and recomputes every account's buffer as if it had. The arithmetic is the audit's own — an account's buffer is `buffer_before + sum(contribution over markets)`, and a CF change replaces exactly that market's term — so no approximation is introduced and multiple simultaneous changes simply add.\n\nRuns entirely on frozen artifacts (`CONTRIB-*.json`). **No RPC call is made**, which is why a full-population sweep over 5,309 affected accounts returns in tens of milliseconds.\n\n**Request shape:** `changes` is a list of `{ctoken, new_cf_wei}`. `ctoken` accepts a 0x address or a symbol (`cETH`, `cUSDC`); `new_cf_wei` accepts a wei string or a decimal. Supply `pid` **or** `block` — a simulation with neither is not reproducible and returns 400.\n\n**Reading the result:** `affected_accounts` is every account whose computed buffer moves at all; `newly_flipped` and `healed` are the directional changes; `potential_flips` is the total count whose buffer ends negative. If `invalid` is true an RPC call failed and the numbers must not be trusted — the API says so rather than returning plausible garbage. `borrow_impact_wei` is always 0 by construction: a CF change moves collateral, not debt.", "operationId": "post_simulate_simulate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResult" } } } }, "400": { "description": "missing pid and block, unknown market, market unchanged by this proposal, or malformed wei" }, "404": { "description": "pid/block outside the CR141-001 corpus" }, "501": { "description": "no CONTRIB sidecar for this proposal; the additive model needs per-market contributions" }, "503": { "description": "simulation engine unavailable" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Change": { "properties": { "ctoken": { "type": "string", "title": "Ctoken", "description": "market address or symbol, e.g. 0x39aa… or cUSDC" }, "new_cf_wei": { "type": "string", "title": "New Cf Wei", "description": "hypothetical collateral factor, wei string or decimal" } }, "type": "object", "required": [ "ctoken", "new_cf_wei" ], "title": "Change" }, "Contribution": { "properties": { "market": { "type": "string", "title": "Market" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Symbol" }, "delta_wei": { "type": "string", "title": "Delta Wei" }, "cf_before": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cf Before" }, "cf_after": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cf After" } }, "type": "object", "required": [ "market", "delta_wei" ], "title": "Contribution", "description": "One market's contribution to an account's buffer change." }, "EvidenceStatus": { "properties": { "audit": { "type": "string", "title": "Audit" }, "audit_closed": { "type": "boolean", "title": "Audit Closed" }, "events_measured": { "type": "integer", "title": "Events Measured" }, "gates": { "additionalProperties": { "$ref": "#/components/schemas/Gate" }, "type": "object", "title": "Gates" }, "exactness": { "$ref": "#/components/schemas/Exactness" }, "reproducible_package": { "$ref": "#/components/schemas/ReproduciblePackage" }, "cache": { "anyOf": [ { "$ref": "#/components/schemas/StatusCache" }, { "type": "null" } ], "description": "null when an evaluator ran in this request; the baked cache otherwise" }, "generated_utc": { "type": "string", "title": "Generated Utc" } }, "type": "object", "required": [ "audit", "audit_closed", "events_measured", "gates", "exactness", "reproducible_package", "generated_utc" ], "title": "EvidenceStatus", "examples": [ { "audit": "CR141-001", "audit_closed": true, "cache": { "age_seconds": 68297.6, "frozen": true, "generated_utc": "2026-11-10T12:08:45Z", "note": "pre-measured at image build time; evaluator not present in this deployment", "source": "audit_status_cache.json", "stale": false }, "events_measured": 28, "exactness": { "difference": 0, "exact_set_equality": "28/28", "observed_flips": 474, "predicted_flips": 474 }, "gates": { "G0_bug_classes": { "note": "manual registry in CR141-AUDIT-CLOSURE.json", "pass": true }, "G1_integrity": { "pass": true }, "G2_coverage": { "pass": true }, "G3_reproducibility": { "note": "44/56/133 identical pre/post; 66 post-fix only", "pass": true }, "G4_prediction": { "pass": true }, "G5_corpus": { "pass": true }, "G6_operations": { "pass": true }, "G7_postmortem": { "pass": true } }, "generated_utc": "2026-11-11T07:07:02Z", "reproducible_package": { "command": "cd rerun_package && python3 verify_hashes.py", "network_required": false, "path": "rerun_package/" } } ] }, "Exactness": { "properties": { "predicted_flips": { "type": "integer", "title": "Predicted Flips" }, "observed_flips": { "type": "integer", "title": "Observed Flips" }, "difference": { "type": "integer", "title": "Difference" }, "exact_set_equality": { "type": "string", "title": "Exact Set Equality", "description": "proposals with exact set equality, e.g. 28/28" } }, "type": "object", "required": [ "predicted_flips", "observed_flips", "difference", "exact_set_equality" ], "title": "Exactness", "description": "The falsification measurement: predicted vs observed flip counts." }, "FlipPage": { "properties": { "pid": { "type": "integer", "title": "Pid" }, "total": { "type": "integer", "title": "Total" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "opaque cursor for the next page; OMITTED (not null) on the last page, because this endpoint serializes with exclude_none" }, "attribution": { "type": "boolean", "title": "Attribution" }, "flips": { "items": { "$ref": "#/components/schemas/FlipRow" }, "type": "array", "title": "Flips" } }, "type": "object", "required": [ "pid", "total", "attribution", "flips" ], "title": "FlipPage", "examples": [ { "attribution": true, "flips": [ { "account": "0x00b466c41109eda7be12406d06b017f77732f065", "agrees": true, "contributions": [ { "cf_after": 0.1, "cf_before": 0.2, "delta_wei": "-18397842767644137056", "market": "0xb3319f5d18bc0d84dd1b4825dcde5d5f7266d407", "symbol": "CZRX" }, { "cf_after": 0.35, "cf_before": 0.4, "delta_wei": "-3693106226491475269", "market": "0x6c8c6b02e7b2be14d4fa6022dfd6d75921d90e4e", "symbol": "CBAT" }, { "cf_after": 0.845, "cf_before": 0.855, "delta_wei": "-576901220158309656", "market": "0x39aa39c021dfbae8fac545936693ac917d5e7563", "symbol": "CUSDC" } ], "driver_delta_wei": "-18397842767644137056", "driver_is_heuristic": true, "driver_market": "CZRX", "joint_cause": false, "margin_wei": "22667850214293921981", "markets_touched": [ "CUSDC", "CBAT", "CZRX" ], "n_markets": 3, "observed_wei": "-11781305311049840994", "predicted_wei": "-11781308056272734877" } ], "next_cursor": "MQ==", "pid": 301, "total": 65 } ] }, "FlipRow": { "properties": { "account": { "type": "string", "title": "Account" }, "markets_touched": { "items": { "type": "string" }, "type": "array", "title": "Markets Touched" }, "predicted_wei": { "type": "string", "title": "Predicted Wei" }, "observed_wei": { "type": "string", "title": "Observed Wei" }, "margin_wei": { "type": "string", "title": "Margin Wei" }, "agrees": { "type": "boolean", "title": "Agrees" }, "driver_market": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Driver Market", "description": "market with the largest negative contribution" }, "driver_delta_wei": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Driver Delta Wei" }, "driver_is_heuristic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Driver Is Heuristic" }, "joint_cause": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Joint Cause", "description": "true when no single market alone flips the account" }, "n_markets": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "N Markets" }, "contributions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Contribution" }, "type": "array" }, { "type": "null" } ], "title": "Contributions" } }, "type": "object", "required": [ "account", "markets_touched", "predicted_wei", "observed_wei", "margin_wei", "agrees" ], "title": "FlipRow", "description": "One flipped account. Attribution fields are null without ?attribution=true." }, "Gate": { "properties": { "pass": { "type": "boolean", "title": "Pass" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "required": [ "pass" ], "title": "Gate", "description": "One gate record from CR141-AUDIT-CLOSURE.json." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "MarketChange": { "properties": { "ctoken": { "type": "string", "title": "Ctoken" }, "symbol": { "type": "string", "title": "Symbol" }, "cf_before_wei": { "type": "string", "title": "Cf Before Wei" }, "cf_after_wei": { "type": "string", "title": "Cf After Wei" }, "cf_before": { "type": "number", "title": "Cf Before" }, "cf_after": { "type": "number", "title": "Cf After" }, "delta_rel": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Delta Rel" }, "exec": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exec" } }, "type": "object", "required": [ "ctoken", "symbol", "cf_before_wei", "cf_after_wei", "cf_before", "cf_after" ], "title": "MarketChange", "description": "One executed CF change in this proposal." }, "Proposal": { "properties": { "pid": { "type": "integer", "title": "Pid" }, "block": { "type": "integer", "title": "Block" }, "block_evaluated": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Block Evaluated", "description": "the block the engine read; block - 1 by contract" }, "markets": { "items": { "$ref": "#/components/schemas/MarketChange" }, "type": "array", "title": "Markets" }, "population": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Population" }, "targets": { "type": "integer", "title": "Targets" }, "predicted_flips": { "type": "integer", "title": "Predicted Flips" }, "observed_flips": { "type": "integer", "title": "Observed Flips" }, "exact_set_equality": { "type": "boolean", "title": "Exact Set Equality" }, "density_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Density Pct", "description": "flips per 100 targets" }, "route_a_b": { "$ref": "#/components/schemas/RouteAB" }, "cf_before_zero_route_b_only": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cf Before Zero Route B Only" }, "rpc_failures": { "type": "integer", "title": "Rpc Failures" }, "completion_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Completion Rate" }, "predicted_subset_of_entered_changed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Predicted Subset Of Entered Changed" } }, "type": "object", "required": [ "pid", "block", "markets", "targets", "predicted_flips", "observed_flips", "exact_set_equality", "route_a_b", "rpc_failures" ], "title": "Proposal", "examples": [ { "block": 20519734, "block_evaluated": 20519733, "cf_before_zero_route_b_only": 0, "completion_rate": 100.0, "density_pct": 1.189, "exact_set_equality": true, "markets": [ { "cf_after": 0.18, "cf_after_wei": "180000000000000000", "cf_before": 0.28, "cf_before_wei": "280000000000000000", "ctoken": "0xe65cdb6479bac1e22340e4e755fae7e509ecd06c", "delta_rel": -0.35714285714285715, "exec": 20519734, "symbol": "CAAVE" }, { "cf_after": 0.845, "cf_after_wei": "845000000000000000", "cf_before": 0.855, "cf_before_wei": "855000000000000000", "ctoken": "0x39aa39c021dfbae8fac545936693ac917d5e7563", "delta_rel": -0.011695906432748537, "exec": 20519734, "symbol": "CUSDC" }, { "cf_after": 0.1, "cf_after_wei": "100000000000000000", "cf_before": 0.2, "cf_before_wei": "200000000000000000", "ctoken": "0xb3319f5d18bc0d84dd1b4825dcde5d5f7266d407", "delta_rel": -0.5, "exec": 20519734, "symbol": "CZRX" } ], "observed_flips": 65, "pid": 301, "population": 8353, "predicted_flips": 65, "predicted_subset_of_entered_changed": true, "route_a_b": { "agree": 2156, "artefact_reference": "CR141-INV-001", "disagree": 1105, "disagree_is_artefact": true, "flip_sets_agree_exactly": true }, "rpc_failures": 0, "targets": 5468 } ] }, "ReproduciblePackage": { "properties": { "path": { "type": "string", "title": "Path" }, "network_required": { "type": "boolean", "title": "Network Required" }, "command": { "type": "string", "title": "Command" } }, "type": "object", "required": [ "path", "network_required", "command" ], "title": "ReproduciblePackage" }, "RouteAB": { "properties": { "agree": { "type": "integer", "title": "Agree" }, "disagree": { "type": "integer", "title": "Disagree" }, "disagree_is_artefact": { "type": "boolean", "title": "Disagree Is Artefact" }, "artefact_reference": { "type": "string", "title": "Artefact Reference" }, "flip_sets_agree_exactly": { "type": "boolean", "title": "Flip Sets Agree Exactly" } }, "type": "object", "required": [ "agree", "disagree", "disagree_is_artefact", "artefact_reference", "flip_sets_agree_exactly" ], "title": "RouteAB", "description": "Route A vs Route B agreement, returned as an object on purpose.\n\nA bare integer invites the reader to treat nested-floor truncation as an error rate.\nCR141-INV-001 documents why 100% A