ERC-8330 Target linked NAV snapshot oracle (Subject-Linked NAV Snapshot Oracle)
Last Call · Vaults & DeFi · created 2026-07-05
Defines a standard interface for recording and querying on chain who determined the net asset value (NAV) of an asset that is not traded frequently, such as a fund or real estate, as of what point in time, and using what methodology.
Why it is needed
Assets such as funds, private credit, real estate, infrastructure, and commodities do not form prices in real time the way exchange traded assets do, and their value is instead set through periodic appraisal. Consumers of such values need to know what the value means, as of what valuation date, when it was published, who provided it, and whether it is too stale to use now. However, existing price or quote oracle interfaces do not necessarily preserve a way to separately check valuation history, provider identity, references to the appraisal methodology, restatement (correction) records, publication lag, and valuation lag. Individually built NAV contracts also use different stream keys and latest value rules, making them mutually incompatible. This standard unifies the semantics of publishing and querying NAV, but does not address NAV calculation itself, provider qualification, or asset backing guarantees.
In depth
Stream and NAV basis configuration
Every snapshot belongs to a stream identified by the (subjectId, currency) pair, and snapshot indices are numbered independently starting from 0 within each stream. Each stream must set its NAV basis exactly once via setNAVBasis before the first publication. Only three bases are allowed: PER_UNIT, the value of one unit of the underlying asset; PER_SHARE, the value of one share (token); and TOTAL, the value of the entire subject. Once stored, the basis is permanent and cannot change. streamNAVBasis returns the configured basis, or bytes32(0) for an unconfigured stream. publishNAV must reject calls for streams with no basis configured and calls whose basis differs from the configured one. The basis is fixed at the stream level because if each provider chose its own basis, submissions for the same valuation date would become incomparable, blocking aggregation.
Publication rules and numeric limits
publishNAV can only be called by authorized providers, and the implementation defines and must document the authorization method. For an accepted snapshot, provider is recorded as msg.sender, publishedAt as the block timestamp, and an NAVPublished event is emitted. valuationTimestamp cannot exceed block.timestamp, and methodologyHash cannot be bytes32(0). Numeric limits reject values where decimals exceeds 18, nav equals type(int256).min, or the magnitude exceeds uint256(type(int256).max) / (10 ** uint256(18 - decimals)). These limits let aggregation implementations safely normalize all values to 18 decimal places. A single provider can have only one currently valid original snapshot per valuation timestamp within the same stream, and once that slot is filled the correction procedure must be used instead. nav is a signed integer because liabilities can exceed assets, and consumers must explicitly handle zero and negative values.
Correction chain
An original snapshot has its correctsIndex set to NO_CORRECTION (type(uint256).max). A correction snapshot must reference an earlier snapshot in the same stream, the target must be a terminal snapshot with no subsequent correction or invalidation yet, and the correction must be published by the same provider as the target with the same valuationTimestamp and navBasis. Once accepted, the target's correctedByIndex is updated to the new index, while its other fields remain unchanged. A correction can itself be corrected, forming a linear chain. NAV, decimals, and the methodology hash and URI can all be changed by a correction. currentSnapshotIndex follows correctedByIndex to return the terminal, non invalidated index, and isSnapshotCurrent returns true only for a snapshot that is both terminal and not invalidated.
Administrative invalidation
invalidateSnapshot can only be called under a documented administrative or governance policy, and it rejects a zero reasonHash, a nonexistent snapshot, a non terminal snapshot, or an already invalidated snapshot. On success, the record is preserved but permanently marked invalid. It is excluded from the latest value, the provider's latest value, the current chain, quorum, aggregation, and deviation calculations, and affected pointers are recalculated. If an original is invalidated, that provider and timestamp slot can be refilled with a new original, and if a correction is invalidated, the preceding snapshot becomes terminal again and a replacement correction can be submitted. A long chain is unwound by invalidating each newly terminal snapshot in turn. Invalidation does not erase the correctsIndex history, so consumers reconstructing history must also check the NAVSnapshotInvalidated event, and an invalidated snapshot can neither be corrected again nor restored.
Latest value selection and dual freshness
latestNAV returns the current snapshot with the largest valuationTimestamp, regardless of freshness. If the valuation timestamps are equal, it picks the one published more recently; if the publish times are also equal, it picks the one with the larger index. A late correction to an older valuation timestamp must not displace a more recent valuation. latestNAVStatus returns the same snapshot with two additional flags. isPublishStale is block.timestamp > publishedAt + heartbeat, and isValuationStale is block.timestamp > valuationTimestamp + maxValuationAge. At exactly the threshold, it is considered fresh. If either threshold is unset, latestNAVStatus reverts. Even if something was published recently, the valuation itself may be stale, so consumers must check both flags.
Optional Aggregation Extension
Aggregation is an optional feature. setAggregationConfig sets the quorum, the deviation threshold (up to 10,000bps), and maxSubmissionAge, the maximum age for individual submissions. At a given valuation timestamp, only one current snapshot per provider is eligible for aggregation, and latestAggregationTimestamp becomes the latest valuation timestamp at which the number of eligible providers meets or exceeds the quorum. aggregatedNAV uses only fresh submissions whose publishedAt is within maxSubmissionAge; if the count falls short of the quorum, it does not fall back to an older valuation timestamp and instead reverts. The calculation is deterministic: it normalizes every fresh value to the maximum submitted decimal count (nav * 10^(maxDecimals - decimals)), sorts them in ascending order, and picks values[(providerCount - 1) / 2], i.e., the lower median when the count is even. It reverts until both the staleness thresholds and the aggregation configuration are set.
Deviation Detection
In the publish transaction, deviation is calculated only when there is a fresh quorum at the latest aggregation timestamp, using the same set of fresh submissions as aggregatedNAV. The formula is deviationBps = (maxNav - minNav) * 10,000 / abs(medianNav). If the spread is 0, the deviation is also 0; if the median is 0 while there is a spread, or if the calculation overflows, it saturates to type(uint256).max. If the deviation exceeds deviationThresholdBps, the NAVDeviationDetected event fires; it does not fire when the deviation equals the threshold. This event is only an alert; it does not invalidate submissions or block aggregation, and stale submissions must not trigger or affect the deviation calculation.
ERC-165 and Review-Stage Caveats
The core oracle must implement ERC-165 and return true for type(INAVSnapshotOracle).interfaceId, and if it supports aggregation it must also return true for type(INAVAggregation).interfaceId. This Review-stage revision adds fresh-submission query functions and maxSubmissionAge to INAVAggregation, and changes the return tuple of aggregatedNAV. The function selector is unchanged, but the return format is not ABI-compatible, so using a new decoder against an older deployment can misread the previous version's isPublishStale value as isValuationStale. Interface support for this revision must be confirmed via interfaceId before interpreting aggregation responses, and compatibility must not be judged merely by a successful aggregatedNAV call. This proposal is currently in Review status, so the specification may still change.
Things to watch out for
- NAV Is Not an Executable Price: NAV is an accounting or valuation claim. Tokens can trade above or below NAV, and redemptions can be restricted, delayed, or suspended. NAV must not be treated as a market price without separately verifying liquidity and redemption conditions.
- You Must Trust Providers and Configuration Authorities: Providers can submit manipulated or incorrect values and methodologies, and configuration authorities can choose dangerous staleness and quorum settings. Revoking a provider's authorization does not automatically invalidate its existing snapshots, so the configuration authority must separately invalidate any snapshots that should be excluded.
- Staleness Flags Only Protect Consumers Who Check Them: latestNAV intentionally returns raw data without any staleness judgment. aggregatedNAV requires a fresh quorum, but the valuation timestamp itself may still be stale, so pricing and settlement paths must check the valuation staleness flag or use a controlled adapter.
- Negative and Zero NAV Must Be Handled Explicitly: Consuming contracts that assume NAV is positive can suffer underflows, division by zero, or asset mispricing. Behavior for zero and negative values must be explicitly defined.
- Front-Running Risk on Valuation Updates: If a large NAV change becomes visible before it is included in a block, it can be traded against using the previously accepted value. When the economic risk is significant, private submission, commit-reveal publishing, settlement pausing, or delayed activation should be considered.