Attestation & freshness

Every value Claros publishes is an attestation: a compact record written to the AttestationRegistry contract by the Claros agent, and only by the agent’s authorized attester key. An attestation pins a number to the real-world data period it covers, a provenance hash, the account that wrote it, and the chain time it was committed.

This page covers the record’s fields, how period encodes each cadence, and how to decide whether a reading is fresh enough to use.

The attestation record

On-chain, an attestation is this Odra struct (contracts/src/attestation_registry.rs):

#[odra::odra_type]
pub struct Attestation {
    pub period: u64,
    pub amount: U512,
    pub source_hash: String,
    pub attester: Address,
    pub timestamp: u64,
}

How records are stored

attest(asset_id, period, amount, source_hash) writes three places at once: the latest value for the feed, an append-only history entry keyed "{asset_id}#{index}", and a per-feed count (the total across all feeds is also tracked). Read them back with these view methods:

For most consumers, get_latest (on-chain) or its off-chain equivalents are all you need: see the SDK, the REST API, and cross-contract reads.

Verifying provenance with source_hash

source_hash is computed from the stable source fields only (for EIA: route, frequency, sorted facets, period, value, unit; for civic data: asset, period, amount, count, source URL). Because the formula is deterministic, a consumer can recompute the digest from the raw upstream data and compare it to the on-chain source_hash. A match proves the attested number was derived from that exact source row and was not altered in transit.

What period means

period is an integer that names the interval the value describes. The encoding depends on the feed’s frequency (read it from the feed metadata). The agent strips the separators from the source’s period string, so a calendar period becomes a plain integer:

A length-based decoder handles every cadence:

// period -> the UTC instant the value covers. `frequency` comes from the feed metadata.
function decodePeriod(period: number, frequency: string): Date {
  if (frequency === 'hourly') return new Date(period * 1000); // epoch seconds
  const s = String(period);
  if (s.length === 8) return new Date(Date.UTC(+s.slice(0, 4), +s.slice(4, 6) - 1, +s.slice(6, 8))); // YYYYMMDD
  if (s.length === 6) return new Date(Date.UTC(+s.slice(0, 4), +s.slice(4, 6) - 1, 1));               // YYYYMM
  if (s.length === 4) return new Date(Date.UTC(+s, 0, 1));                                             // YYYY
  throw new Error(`unrecognized period: ${period}`);
}

Checking freshness

A reading carries two independent time signals, and a robust staleness check uses both:

They can diverge. A value written minutes ago can still carry an old period if the upstream source has not published anything new, and a recent period written long ago means nothing has changed since. Check timestamp for write age, and decode period to confirm the underlying data is current for the cadence you expect.

A reasonable default tolerance, before you treat a reading as stale, scales with the cadence and the source’s own publishing lag:

import { ClarosOracle } from 'claros-oracle';
 
const oracle = new ClarosOracle(); // testnet addresses baked in
 
// Suggested wall-clock tolerance per cadence, in ms.
const MAX_AGE: Record<string, number> = {
  hourly: 3 * 3_600_000,
  daily: 3 * 86_400_000,
  weekly: 10 * 86_400_000,
  monthly: 45 * 86_400_000,
  annual: 400 * 86_400_000,
};
 
async function isFresh(feedId: string): Promise<boolean> {
  const r = await oracle.getReading(feedId);
  if (!r) return false;                    // never attested
  const ageMs = Date.now() - r.updated_at; // updated_at is epoch ms
  return ageMs <= (MAX_AGE[r.frequency] ?? 86_400_000);
}

GET /v1/feeds/OP-1

{
  "feed_id": "OP-1",
  "value": 2734.2,
  "amount": "273420",
  "decimals": 2,
  "frequency": "daily",
  "period": 20260623,
  "source_hash": "…",
  "updated_at": 1750680000000
}

// Inside your Odra contract. Trait wiring is covered on the cross-contract page.
let att = match self.registry.get_latest(asset_id.clone()) {
    Some(a) => a,
    None => self.env().revert(Error::NoData),
};
 
let now = self.env().get_block_time(); // epoch ms, same clock the registry stamps with
if now.saturating_sub(att.timestamp) > MAX_AGE_MS {
    self.env().revert(Error::StaleData);
}
 
// att.amount is the integer value; scale by the feed's decimals as needed.

The agent re-attests only on new data

Claros runs an hourly heartbeat (agent/src/loop.ts), but a heartbeat is not an attestation. Each tick the agent checks whether the source has advanced, and runs a full cycle only when it has.

Two consequences for consumers:

• A stale timestamp is itself a signal. Because the agent only writes on a new period, a large gap between now and timestamp means the upstream source has published nothing new, or the agent has paused. Your freshness check catches both.
• New data is necessary, not sufficient. Even on a fresh period, the cycle declines to attest if the ZK eligibility credential is not confirmed or the reading fails the anomaly check. The on-chain value is always the last reading the agent judged eligible and clean.

Related