Oracle health

Address identity

Pricing starts where the asset registry starts: the token address is the identity. A feed is only ever attached to a verified canonical address — never looked up by ticker, because tickers can collide and the docs ticker can even differ from the on-chain symbol (see CUSO/USO).

The eight health states

Every price evaluation resolves to exactly one state. Order matters: pause and sequencer problems mask price data entirely, because a "fresh" price during an outage is still untrustworthy.

Staleness: the primary guard

Every Robinhood Chain USD feed publishes on an 86,400-second (24-hour) heartbeat with a 0.5% deviation threshold, so the oracle policy's staleness limit is 90,000 seconds — heartbeat plus a one-hour buffer. A reading is stale when now − updatedAt exceeds that limit (manifests can tighten it via risk.oracleStalenessSeconds). Stock feeds discover prices 24/5, but the heartbeat keeps writing on weekends (verified on a Sunday: observed feed ages stayed at or under 16.7 hours, carrying Friday-close-derived values) — so one threshold covers all days, with no special weekend allowance.

Staleness is the primary guard by policy: the official docs describe the oraclePaused() flag as advisory and not enforced on-chain, so a paused oracle may still return a value. HISS checks the pause flag anyway (strictly more conservative), but never relies on it alone.

Pinned feeds (26 of 27)

Feed proxies were pinned on 2026-07-06 from Chainlink's reference data directory for robinhood-mainnet — the source of truth the official docs point to — and live-verified via eth_call on chain 4663 (spot-checked proxies answered with matching description(), decimals() = 8, positive answers, and fresh timestamps). All pinned feeds: 8 decimals, 86,400s heartbeat, 0.5% deviation, 24/5 market hours. This table renders live from PINNED_FEEDS in @hiss/core:

Total-return drift

Stock Token feeds carry total-return semantics: dividends are reinvested into the token via the multiplier, so as dividends accrue the feed price drifts above the headline share price. Per the official docs, this is expected — the token tracks price changes plus reinvested dividends, not just the share price. Never treat that drift as an error, and never present the feed price as "the share price" (divide by the multiplier for that display).

uiMultiplier: never double-apply

Robinhood Chain Stock Tokens expose a uiMultiplier() that reflects corporate actions (splits, reinvested dividends). The critical rule: the Chainlink feed price is the token price and already includes the multiplier. The multiplier exists only to display share-equivalent units. Applying it to the feed price double-counts corporate actions.

// USD value of a raw token amount — the ONLY valuation formula:
value = rawTokenAmount * feedPrice;

// Share-equivalent units, for DISPLAY only:
shareEquivalent = rawTokenAmount * uiMultiplier;

// WRONG — double-counts corporate actions:
value = rawTokenAmount * uiMultiplier * feedPrice; // never do this

Corporate actions can change uiMultiplier() at any time, so never cache share-equivalent math.

Why live pricing is still off

Pinned feeds are necessary but not sufficient. The live-mode gate also requires the Chainlink L2 sequencer uptime feed for chain 4663, which is not yet published (no entry in the reference data directory, and Robinhood is absent from Chainlink's L2 sequencer feed list). Until it appears, liveFeedsPinned() returns false and assertLivePricingAllowed() throws on every live-pricing code path — live pricing is structurally impossible to enable by flag alone, and all pricing comes from the deterministic mock oracle.