> For the complete documentation index, see [llms.txt](https://city-protocol.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://city-protocol.gitbook.io/docs/security/security-and-risk/oracle-and-nav-design.md).

# Oracle and NAV design

How a NAV report becomes eligible for settlement, and what happens when an update fails.

The report oracle accepts a NAV report only from authorized reporters under a configurable quorum, with protection against duplicate approvals, a freshness bound, binding to the network and the contract, and epoch-timing checks. Settlement rejects a price that moves beyond the vault's deviation tolerance, and a vault can require several independent signers, for example a three-of-three quorum. When an update fails verification, lacks signer approval, uses incomplete data or breaches the deviation limit, the product pauses subscriptions, redemptions or both until the issue is resolved. For OTPs, each constituent's price source is validated at admission.

<figure><img src="https://3297077862-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJxNp2waFk6hg1G4lEQZu%2Fuploads%2Fsdxtcz92eEK7XKybkuFb%2Ffig-oracle-v21.png?alt=media" alt="Eight gates a NAV report must clear before it can affect settlement accounting"><figcaption><p>Only a report that clears every gate can affect settlement accounting.</p></figcaption></figure>

## Report controls

Settlement depends on versioned NAV reports. `ReportOracle` and `PricingModule` apply the following controls to every report.

| Control              | Rule                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------- |
| Authorized reporters | Only enabled reporters can submit or approve a report.                                       |
| Quorum               | Enough distinct reporters must approve the same report digest.                               |
| No duplicates        | Each reporter can approve a given report only once.                                          |
| Freshness            | A report cannot be computed in the future or be older than `maxReportAge`.                   |
| Binding              | The report digest includes the network identifier and the oracle contract address.           |
| Metadata hash        | A report can link its NAV to offchain valuation materials through an optional metadata hash. |
| Epoch timing         | A report must be computed after the relevant epoch closes.                                   |
| Deviation guard      | Settlement reverts when the price moves beyond the vault's tolerance.                        |

The pricing role sets each vault's settlement price-deviation tolerance, at no more than 10,000 bps.

{% hint style="info" %}
NAV applies to Curated Vaults, which report product-level NAV per share at each settlement. OTPs report the token balances in each participant's account, and each constituent's price source is validated at admission.
{% endhint %}