Contract Interface

On-chain contracts are planned for Base and 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.

Base

Chain

Planned

Status

Pending

Verification

Contracts (Planned) & Live API

BRORegistry

Not yet deployed

Planned stable consumer address. Will route all reads to the current oracle implementation, with timelocked (48h) upgrades and codehash verification.

BROOracle

Not yet deployed

Planned oracle implementation. Will store composite BRI, per-dimension scores (12 for protocols, 6 for prediction markets), and an evidence hash per entry.

REST API

https://oracle.blackhart.io/api/v1

Base URL for all REST endpoints.

Read Interface

Planned read functions for the upcoming on-chain integration. All are view functions, with zero gas for consumers once deployed.

IBROOracle + BRORegistry Interface

// 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

Timelocked upgrades

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.

Registry indirection

Consumers will point to the BRORegistry, which routes reads to the active oracle. The registry address never changes. Only the underlying implementation does.

Interface validation

The registry is designed to validate that any proposed oracle implements the IBROOracle interface before accepting it, preventing pointing to arbitrary contracts.

Evidence pinned

Every score update is designed to include an evidence hash linking to the full analysis that produced it, so every score can be audited against its evidence.

Per-dimension transparency

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.

Emergency downgrade

Any updater will be able to immediately downgrade a compromised target's score with an evidence hash. When paused, only the owner can downgrade, and updaters are locked out.

← MCP View Scores