Decimals & scaling

Claros never stores a floating-point number on-chain. Every feed value is an integer amount plus a per-feed decimals exponent, exactly the model Pyth  uses for prices. The human value is amount / 10^decimals. This page explains why, how the conversion works in both directions, and the one constraint that follows from the integer type: the amount is unsigned.

The model

There are two directions, and they are inverses of each other.

The agent encodes once when it attests. Everyone reading the feed decodes. Most of the reading surfaces decode for you and hand back a ready value, but the raw amount and decimals are always available so you can redo the math yourself with full precision.

What is stored on-chain

The value and its exponent are deliberately split across two registries so a consumer can interpret a number entirely on-chain, the Pyth approach where a price ships with its exponent.

The latest value, in the AttestationRegistry:

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

The exponent and unit, in the FeedRegistry:

#[odra::odra_type]
pub struct Feed {
    pub decimals: u8,        // real value = amount / 10^decimals
    pub unit: String,        // e.g. "$/bbl", "MWh", "percent"
    pub title: String,
    pub source: String,
    pub route: String,
    pub frequency: String,
    pub description: String,
}

A reading pairs one Attestation.amount with one Feed.decimals for the same feed_id.

Worked example: WTI crude

The EIA.PET.PRICE.WTI.DAILY feed reports the Cushing WTI spot price in $/bbl with decimals = 6.

Encode (agent):

amount = round(78.94 * 10^6) = round(78.94 * 1000000) = 78940000

Decode (consumer):

value = 78940000 / 10^6 = 78.94

Why scaled integers, not floats

The encoder splits the source on the decimal point, pads or trims the fractional part to exactly decimals digits, then parses the joined digits as one big integer:

// Scale a decimal string by 10^k without float drift.
function scaleDecimalString(s: string, k: number): bigint {
  let neg = s.startsWith('-');
  if (neg) s = s.slice(1);
  let [int, frac = ''] = s.split('.');
  frac = (frac + '0'.repeat(k)).slice(0, k);
  const v = BigInt((int || '0') + frac);
  return neg ? -v : v;
}

Because decimals is chosen to be at least as precise as the source feed, the fraction always fits and the scaling is exact, with no rounding loss in practice.

decimals is the exponent (Pyth expo)

decimals is a per-feed u8, picked to fit the precision of the metric. It plays the same role as Pyth’s expo for a price. Claros uses a small set of conventions:

A count uses decimals = 0, so its amount equals the value exactly with no scaling at all.

The amount is unsigned

U512 is an unsigned integer, so it cannot represent a negative number. Claros only attests metrics that are non-negative: prices, volumes, counts, revenue, and percentages. The off-chain encoder can represent a negative number (it has a sign branch), but the on-chain type cannot hold one, so the live catalog contains only non-negative feeds.

Reading a value back

Whichever surface you use, you can either take the pre-divided value or take the raw amount plus decimals and divide yourself.

import { ClarosOracle } from 'claros-oracle';
 
const claros = new ClarosOracle();
const wti = await claros.getReading('EIA.PET.PRICE.WTI.DAILY');
 
// wti.value    -> 78.94       (already amount / 10^decimals)
// wti.amount   -> 78940000n   (raw U512, as a BigInt)
// wti.decimals -> 6

curl http://localhost:4030/v1/feeds/EIA.PET.PRICE.WTI.DAILY

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

let a = AttestationRegistryRef::new(env, registry).get_latest(feed_id.clone());
let f = FeedRegistryRef::new(env, feed_registry).get_feed(feed_id);
 
let amount: U512 = a.unwrap().amount;     // raw scaled integer
let decimals: u8 = f.unwrap().decimals;   // exponent
 
// real value = amount / 10^decimals, for example:
let scale = U512::from(10u64).pow(U512::from(decimals));
let whole = amount / scale;               // integer part

Convert an amount by hand

Related