How it works

Claros is a verifiable real-world-data oracle on Casper testnet. An autonomous agent fetches data from an upstream source, normalizes it to an exact integer, hashes the provenance, and signs an on-chain attestation. Two contracts, keyed by a shared feed_id, hold the result: the AttestationRegistry stores the value, and the FeedRegistry stores the metadata that tells you how to read it. Any consumer reads both by feed_id and reconstructs the human number with one formula:

value = amount / 10^decimals

This is the Pyth model. The price ships with its exponent, so a consumer can interpret the integer entirely on-chain, with no off-chain schema.

Architecture at a glance

  UPSTREAM                       AGENT                          ON-CHAIN (Casper)
  --------                       -----                          -----------------
  EIA API v2          fetch      1. scale to integer
  (energy markets)   ------->    2. hash provenance    attest   ----->  AttestationRegistry
  City of San Diego              3. sign TransactionV1                   (value, by feed_id)
  (parking revenue)              4. submit          register_feed --->   FeedRegistry
                                                                         (metadata, by feed_id)

  CONSUMERS  ----- read both by feed_id ----->   value = amount / 10^decimals
  (REST / SDK / cross-contract / x402)

The agent runs on an hourly heartbeat and only attests when the upstream source publishes a period it has not processed yet, so it never spends gas re-attesting the same reading. The data path below is one step inside a larger autonomous cycle that also clears a zero-knowledge eligibility gate and manages a treasury (see the agent).

The attestation pipeline

Every value on Claros is produced by the same five steps.

// EIA: a decimal string like "78.94" at the feed's fixed decimals (6)
amount = scaleDecimalString('78.94', 6);   // 78940000n  (value * 10^6)
 
// San Diego: parking revenue already arrives as integer cents, so decimals = 2
amount = 273420n;                          // $2,734.20

source_hash = sha256(canonical).slice(0, 32);   // 32 hex chars, deterministic

const tx = new ContractCallBuilder()
  .byPackageHash(ATTESTATION_REGISTRY)
  .entryPoint('attest')
  .runtimeArgs(Args.fromMap({
    asset_id:    CLValue.newCLString('EIA.PET.PRICE.WTI.DAILY'),
    period:      CLValue.newCLUint64(20260623),
    amount:      CLValue.newCLUInt512(78940000),
    source_hash: CLValue.newCLString(sourceHash),
  }))
  .chainName('casper-test')
  .payment(20_000_000_000, 1)   // gas limit in motes
  .from(agentKey.publicKey)
  .build();
 
tx.sign(agentKey);
await rpc.putTransaction(tx);

Two registries, one feed_id

Claros splits a feed into two on-chain records that share a single key. The value changes every period; the metadata describes how to interpret it and rarely changes.

What an attestation stores

AttestationRegistry.get_latest(feed_id) returns an Attestation:

The registry also keeps every historical reading: get_at(feed_id, index) returns a past attestation, get_count(feed_id) is that feed’s history length, and total_attestations() is the global count across all feeds.

What a feed’s metadata stores

FeedRegistry.get_feed(feed_id) returns a Feed:

To browse what is registered, feed_count() returns the number of feeds and get_feed_at(index) returns the feed_id at each position. The mapping from a feed_id to its provider route, frequency, column, and facet filters is covered in the feed model.

Self-describing feeds, and why value = amount / 10^decimals

A consumer should never need to know out-of-band that “WTI is quoted in dollars with six decimals.” That fact lives on-chain in the FeedRegistry, alongside the value in the AttestationRegistry. This is what “self-describing” means: the chain ships the value and the exponent and unit to read it.

Storing the value as a scaled integer (U512) rather than a float is what makes this work:

• Exact. Integers have no floating-point rounding error, so the value is the same byte-for-byte for everyone.
• Deterministic and language-agnostic. A Rust contract, the TypeScript SDK, and a REST client all apply the identical amount / 10^decimals formula.
• Overflow-safe. U512 is a 512-bit unsigned integer, large enough for any feed Claros attests.

The scale is fixed per feed and stored once, so the value is just the raw integer and decimals is the exponent that turns it back into a human number.

Worked examples

Reading a value back

Consumers pull both records by feed_id and divide. There are four ways to do it, depending on whether you want a free off-chain read, a free on-chain read, a hosted REST endpoint, or a metered pay-per-call feed.

import { ClarosOracle } from 'claros-oracle';
 
const oracle = new ClarosOracle();                       // testnet addresses baked in
const r = await oracle.getReading('EIA.PET.PRICE.WTI.DAILY');
// r = { value: 78.94, amount: 78940000n, decimals: 6, unit: '$/bbl', period: 20260623, ... }

GET /v1/feeds/EIA.PET.PRICE.WTI.DAILY

{
  "feed_id": "EIA.PET.PRICE.WTI.DAILY",
  "value": 78.94,
  "amount": "78940000",
  "decimals": 6,
  "unit": "$/bbl",
  "title": "WTI crude spot",
  "source": "EIA",
  "period": 20260623,
  "source_hash": "…",
  "updated_at": 1750636800000
}

let a = attestations.get_latest(feed_id.clone()).unwrap(); // Attestation { amount, .. }
let f = feeds.get_feed(feed_id).unwrap();                  // Feed { decimals, unit, .. }
 
// Keep working in scaled integers for exactness; divide only for a whole-unit figure.
// real value = a.amount / 10^f.decimals

For a paid, per-request feed gated by the HTTP 402 protocol, see pay-per-call with x402.

Where this fits in the agent cycle

The attestation pipeline is steps 1 and 2 of the agent’s autonomous cycle. Before it attests, the agent confirms its on-chain zero-knowledge eligibility credential and anomaly-checks the reading against the feed’s typical range; after it attests, it decides whether to reinvest treasury into a yield venue and records that decision on-chain.

Related