Contract Interface
On-chain contracts are planned for Base — not yet deployed. The free REST API is live and available now. The interface below documents the planned on-chain integration.
Oracle reads will be gas-free (view functions only) once contracts are deployed.
Contracts (Planned) & Live API
Not yet deployedPlanned stable consumer address. Will route all reads to the current oracle implementation, with timelocked (48h) upgrades and codehash verification.
Not yet deployedPlanned oracle implementation. Will store composite BRI, per-dimension scores (12 for protocols, 6 for prediction markets), and an evidence hash per entry.
https://oracle.blackhart.io/api/v1Base URL for all REST endpoints.
Read Interface
Planned read functions for the upcoming on-chain integration. All view functions — zero gas for consumers once deployed.
// IBROOracle — planned Read Interface (not yet deployed)
// Targets are identified by human-readable string slugs (e.g. "aave-v3")
// Dimension count is model-dependent: 12 for DeFi protocols, 6 for prediction markets.
// Composite score + staleness
getScore(string slug)
→ (uint16 bri, uint8 forgeScale, uint64 updatedAt, bool isStale)
// Full score struct (all dimensions + evidence hash)
getFullScore(string slug) → Score
// Single dimension by index
// protocols: 0-11 (D1-D12), prediction markets: 0-5
getDimension(string slug, uint8 dimensionIndex) → uint16
// Batch read for portfolio monitoring
batchGetScores(string[] slugs)
→ (uint16[] bris, uint8[] forgeScales, bool[] stale)
// Convenience staleness check
isStale(string slug) → bool
// Score struct layout (dimension count varies by model):
// bri (uint16) — Composite score, 300-1000
// forgeScale (uint8) — 0=RAW .. 6=ADAMANTINE
// updatedAt (uint64) — Timestamp of last update
// sequenceNumber (uint64)— Monotonic per slug
// exists (bool) — Whether the slug has been scored
// model (uint8) — 0=PROTOCOL (12 dims), 1=PREDICTION_MARKET (6 dims)
// dimensions (uint16[]) — Per-dimension scores, each 0-100
// (12 for protocols: D1-D12, 6 for prediction markets)
// evidenceHash (bytes32) — SHA-256 digest of evidence (IPFS CIDv0 with 0x1220 prefix stripped)
// BRORegistry — Upgrade Management
// Consumers point to the registry, which routes to the active oracle
implementationAddress() → address
implementationCodehash() → bytes32
oracleVersion() → uint16
upgradeTimelock() → uint64 // 172,800 seconds (48 hours)Security Model
Regular oracle upgrades will go through a 48-hour timelock with codehash verification at both proposal and activation. The owner will be able to perform an immediate emergency swap if the active oracle is compromised, and consumers will be able to monitor pending upgrades and exit before activation.
Consumers will point to the BRORegistry, which routes reads to the active oracle. The registry address never changes — only the underlying implementation.
The registry is designed to validate that any proposed oracle implements the IBROOracle interface before accepting it, preventing pointing to arbitrary contracts.
Every score update is designed to include an evidence hash linking to the full analysis that produced it, so scores are auditable rather than trust-me assertions.
All dimension scores will be published on-chain — 12 for DeFi protocols, 6 for prediction markets. Consumers will be able to read individual dimensions or the composite BRI.
Any updater will be able to immediately downgrade a compromised target's score with an evidence hash. When paused, only the owner can downgrade — updaters are locked out.